In an age drowning in things that merely work, what's worth using is what earns the name of a real work. True craft lives in the hours no one sees.
- LINUX DO - A new ideal community
Southside Music is a Windows-only third-party NetEase CloudMusic desktop client. It combines a focused music library with a custom audio engine, word-by-word lyrics, desktop lyrics, local favorites, song and lyric-video export, Onerad assistant support, and SouthsideClient integration.
For the story behind the project, read SouthsideMusic Story.
Southside Music is built for people who want NetEase CloudMusic on the desktop without giving up control of playback. After logging in, you can search the catalog, browse cloud playlists, play daily recommendations, and organize songs into local favorite folders.
The player uses its own audio pipeline instead of delegating the listening experience to a web view. Loudness, speed, pitch, stereo width, reverb, transitions, silence detection, preloading, lyrics, and visualization are all handled directly by the application.
Southside Music is an independent, non-commercial project and is not an official NetEase CloudMusic client.
- Loudness normalization with an adjustable target LUFS
- Playback speed from
0.1xto3.0xwith pitch-preserving time stretching - Independent pitch shift from
-12to+12semitones - Optional stereo Haas widening and reverb
- Smart crossfade with adaptive duration, transition curves, tempo and key matching, and automatic gain control
- Silent-ending detection with configurable threshold and detection window
- Current-track and next-track preloading for smoother seeking and switching
- Selectable audio output device
- LRC line timing and YRC word-level timing
- Word-by-word highlighting when YRC data is available
- Translated lyrics with an immediate display toggle
- Always-on-top desktop lyrics with saved position and top-edge anchoring
- Real-time FFT spectrum visualization
- Theme-aware background color mixed from the current cover
- Lyric-video export with configurable format, bitrate, alignment, line count, background, animation, translation, and audio
- Dark and light themes with English and Simplified Chinese UI
- NetEase song and playlist search with incremental loading
- Daily recommended songs and playlists
- Local favorite folders and NetEase cloud playlists in one sidebar
- Batch selection, playlist replacement, queue append, removal, and local reordering
- A Library view that gathers every locally favorited song
- Song export with cover art, lyrics, album, artist, and track metadata
- Queue-after-current actions across Home, Search, Library, and Favorites
- Onerad assistant panel with streaming output and explicit tool-call confirmation
- OpenAI-compatible Chat Completions, OpenAI Responses, and Anthropic providers
- API keys encrypted with Windows Data Protection API
- SouthsideClient WebSocket bridge on port
15489 - Lyrics, cover, song information, position, play state, and FFT streaming to SouthsideClient
- Play/pause, seek, next, and previous commands from SouthsideClient
- In-app GitHub release checking and update handling
- Startup checks for FFmpeg, Python runtime, audio output, network, and OpenGL
- Guided FFmpeg download when the dependency is missing
- Automatic cleanup of old or oversized downloadable caches
- Unhandled-exception dialog with traceback details
- Runtime debug overlay available with
F3
- Open the Releases page.
- Download the latest
SouthsideMusic_<version>_win64_setup.exe. - Run the installer and launch Southside Music.
The first launch performs a dependency check. If FFmpeg is missing, the dependency window can download and install it for you.
Southside Music currently supports Windows only.
Use the account area on the Home page or in the sidebar:
- Cell Phone - Enter your phone number and verification code.
- QR Code - Scan the code with the NetEase CloudMusic app and confirm the login.
- Cookie - Paste your
MUSIC_Ucookie value from the browser DevTools (F12 → Application → Cookies → music.163.com).
The app can start with an anonymous session, but recommendations, cloud playlists, and most account features require a NetEase CloudMusic login.
Select the title-bar search box, enter a keyword, and press Enter. Switch between Songs and Playlists on the Search page. Results continue loading as you scroll.
Select a song to play it immediately. On supported song cards, select the cover to queue that song after the current track. A folder or playlist can replace the active queue or be appended to it.
Use Add folder in the Local section to create an app-managed favorite folder. Song actions let you add, remove, export, or reorder tracks. Cloud playlists remain available separately under Cloud.
Select the bottom playback bar to open the full playing view. It contains the cover, song information, synchronized lyrics, translation controls, and lyric-video export. The compact controller remains available for progress, current lyrics, FFT, previous/play/next, and queue access.
Drag the progress line to seek after the track is ready. Open the queue panel to play, reorder, export, repeat, remove, or clear queued tracks.
Crossfade analyzes adjacent tracks and prepares a transition near the current song's ending. Advanced settings expose transition strength, curve, maximum duration, BPM window, tempo matching, key matching, and automatic gain control. Disable crossfade when exact track boundaries are preferred.
YRC lyrics use word-level highlighting; tracks without YRC timing fall back to line-level LRC display. Translation can be shown when NetEase provides it.
The export button in Now Playing renders synchronized lyrics as .mp4, .av1, .mkv, or .webm. Export options include bitrate, visible line count, word-level timing, translation, alignment, solid-color background, scroll animation, and whether the original audio is included.
Enable Desktop Lyrics in Settings to open a floating always-on-top lyrics window. Its position is persisted between launches. Drag it to the top edge to anchor it, or use Reset Position in Settings.
Favorites can display either a local folder or a NetEase cloud playlist. Local folders support reordering and removal; both views support queue replacement, queue append, and batch operations where available.
Song export supports .mp3, .m4a, .flac, .wav, .ogg, and .opus. Southside Music writes available cover art, lyrics, album, artist, and track metadata into the exported file.
Configure a provider in Settings, then select the chat button in the title bar. Onerad supports streaming responses and can request app actions such as searching, opening folders, controlling playback, or changing settings. Tool calls that affect the app require confirmation.
Southside Music exposes a local WebSocket server on port 15489. The connection sends playback state, song data, lyrics, cover, position, and FFT packets to SouthsideClient, and accepts basic playback controls in return. Connection status, traffic, latency, and connect/disconnect controls are available in Settings.
Settings use a compact default view. Enable Advanced Settings to expose detailed audio, FFT, LLM, storage, and transition controls.
| Section | Main options |
|---|---|
| App | Language and download concurrency |
| Cache Storage | Automatic cleanup, cache age, and space limit |
| Playback | Play order, smart skip, stereo, reverb, output device |
| Crossfade | Strength, curve, duration, BPM, tempo, key, and gain matching |
| Playback Effects | Speed, pitch, silence threshold, and detection window |
| LLM | Providers, API format, key, base URL, and models |
| Window | Cover-color background mixing |
| Lyrics | Animation smoothing |
| Desktop Lyrics | Visibility and position reset |
| FFT | Spectrum, smoothing, buffer, size, and client scaling |
| Loudness | Target LUFS |
| Connection | SouthsideClient status, traffic, latency, and controls |
- Press Space to toggle play/pause.
- Press F3 to toggle the debug overlay.
- Select the lower part of the playback bar to expand or collapse Now Playing.
- Drag the progress line to seek after the song has loaded.
- Select a song cover in supported lists to queue it after the current track.
- Open Library to view songs from all local favorite folders together.
- Change Language in Settings to switch English and Simplified Chinese immediately.
- Adjust Target LUFS if tracks feel inconsistent in perceived volume.
- Windows
- Python
>=3.13 uv- Internet access for initial environment and dependency downloads
git clone https://github.com/Adreno5/SouthsideMusic.git
cd SouthsideMusic
python setup_workspace.pyThe setup script synchronizes the uv environment, prepares the Python 3.14.2 embedded runtime, installs a free-threaded 3.14t worker environment, creates the isolated Nuitka build environment, validates the runtime, and can install Inno Setup.
uv run src/main.pyIf the project environment is already active:
python src/main.pypython -m py_compile src/main.py
uv run ruff check .
uv run ruff format --check .
uv run mypy src/There is no formal automated test suite yet. src/test.py is a manual API exploration script, not a pytest suite.
build.batThe build compiles launcher.py with Nuitka, assembles the embedded runtimes and application resources, then invokes Inno Setup when ISCC.exe is available.
build.result\
├── raw\ Runnable portable directory
└── installer\ Versioned installer, when Inno Setup is available
If Inno Setup is unavailable, the portable build remains in build.result\raw\.
src/
main.py Application entry and startup lifecycle
imports.py Shared Qt, typing, and event imports
core/ Audio, configuration, models, lyrics, themes, backends
services/ Event bus, updates, and application services
views/ Pages, cards, panels, windows, and widgets
pyncm/ Bundled NetEase CloudMusic API client
docs/ English and Chinese documentation
data/ Runtime caches and local favorite data
fonts/ Bundled HarmonyOS Sans SC fonts
icons/, images/ Packaged interface resources
config.json Persistent user configuration
| Layer | Technology |
|---|---|
| GUI | PySide6 + PySide6-Fluent-Widgets |
| Windowing | qframelesswindow + hPyT |
| Audio and DSP | sounddevice + pydub + NumPy + SciPy |
| Metadata | mutagen |
| NetEase API | Bundled pyncm client |
| Networking | requests + Tornado WebSocket server |
| Assistant | OpenAI SDK + Anthropic SDK |
| Packaging | Nuitka + Inno Setup |
- Persistent settings are stored in
config.json. - Local favorites and runtime caches are stored under
data/. - Legacy
config.pkldata is migrated and removed. - LLM API keys are encrypted for the current Windows user with
CryptProtectData. - Downloadable caches can be cleaned automatically by age and total size.
Southside Music is licensed under the PolyForm Noncommercial License 1.0.0.
This software is intended for personal learning, research, and private entertainment. Commercial use is not permitted. Users are responsible for music exported through the application; exported audio must not be redistributed or resold.