How cocreating/song4stem-demucs works
1. Song4Stem is a local desktop app, not a hosted service. Its architecture is a three-layer stack: Vue 3/TypeScript UI, Tauri v2 desktop shell, and a Rust backend that orchestrates audio separation.
2. The main runtime boundary is the Tauri IPC bridge. The Vue frontend sends typed commands into Rust, and Rust sends state/progress back to the UI. The README explicitly says the Rust backend is the single source of truth for provider readiness, active jobs, and separation progress.
3. The frontend is a fairly thin presentation layer. App.vue and the components in src/components appear to cover file upload, job progress, and stem mixing. src/stores holds client-side reactive state, but it is driven by backend state rather than owning the separation logic.
4. The frontend talks to Tauri through src/services/tauri-client.ts, which is the boundary for invoking backend commands and receiving updates. This keeps the UI decoupled from the Rust implementation details.
5. The Rust side is organized around command handling and domain state. src-tauri/src/commands.rs, state.rs, and error.rs form the application orchestration layer: validating requests, tracking job lifecycle, and normalizing failures for the UI.
6. Inference is abstracted behind a provider model. The src-tauri/src/inference modules split responsibilities into model metadata, provider interfaces, a registry, and the Demucs implementation. That suggests the backend can enumerate available separation engines, even though the current repo centers on Demucs.
7. The actual separator is Demucs, packaged as a standalone sidecar rather than embedded Python code. The README says Rust uses the Tauri shell plugin to spawn demucs-cli, so the heavy ML runtime stays outside the Rust binary and is treated as an external local process.
8. Job progress is streamed from the sidecar back into Rust. The backend parses Demucs output into progress events, then forwards those updates to the Vue job UI. This is the core data flow for the “active separation” path.
9. Output files are written to disk as .wav stems, and the frontend later reads them using the Web Audio API. That means separation and playback are separated by a file-system boundary: Rust/Python produces the stems, and the browser-side UI consumes the generated audio files for mixing or preview.
10. Build and packaging are important architectural concerns here. scripts/build_sidecar.sh and scripts/demucs_entry.py build the PyInstaller sidecar; src-tauri/build.rs validates/downloads the htdemucs checkpoint; and Tauri packaging bundles the Rust app plus the sidecar into macOS app/dmg artifacts.
11. From a diagram perspective, the key external dependencies are local-only: the user selects an audio file, the app launches a bundled Demucs sidecar, model weights are fetched from Meta’s public model host if needed, and all results stay on the user’s machine.
12. The architecture is therefore centered on orchestration, not computation: Vue handles interaction, Rust manages state and process control, and the Python/Demucs sidecar performs the compute-heavy source separation.
Main entry points: commands.rs Commands · mod.rs Inference · demucs.rs Demucs · App.vue App
Components 19
Frontend
Vue 3 presentation layer and client-side state
- App · Top-level UI composition
src/App.vue - File upload · Selects source audio for separation
src/components/FileUploader.vue - Job progress · Shows separation status and updates
src/components/JobProgress.vue - Stem mixer · Plays and blends generated stems
src/components/StemMixer.vue - Tauri client · Typed bridge for commands and events
src/services/tauri-client.ts - Job store · Client state for active jobs and progress
src/stores/useJobStore.ts - Separator store · Client state for separator readiness and output
src/stores/useSeparatorStore.ts
Desktop backend
Tauri shell and Rust orchestration
Inference
Provider abstraction and Demucs integration
- Inference · Coordinates model and provider abstractions
src-tauri/src/inference/mod.rs - Models · Model definitions and capabilities
src-tauri/src/inference/models.rs - Provider API · Interface for separator backends
src-tauri/src/inference/provider.rs - Registry · Discovers and exposes available engines
src-tauri/src/inference/registry.rs - Demucs · Runs local source separation work
src-tauri/src/inference/demucs.rs
External
Local and remote runtime dependencies
- Sidecar · Bundled Python/Demucs execution process
scripts/demucs_entry.py - Model weights · Fetched checkpoint data for htdemucs
- Audio file · User-selected source track on disk
- WAV stems · Separated stem files written to disk
Connections 21
- App → File upload: renders · Main screen includes file selection
- App → Job progress: renders · Main screen shows active separation progress
- App → Stem mixer: renders · Main screen exposes stem playback and mixing
- File upload → Tauri client: submit file · UI sends separation request through IPC
- Job progress → Job store: reads · Progress UI consumes reactive job state
- Stem mixer → Separator store: reads · Mixer uses separator output and readiness state
- Tauri client → Commands: invoke · Frontend calls typed Rust commands
- Commands → App state: mutate · Commands update authoritative backend state
- Commands → Errors: normalize · Failures are converted into UI-friendly errors
- App state → Job store: push state · Backend state drives client-side job reactivity
- App state → Separator store: push state · Backend publishes readiness and separator status
- Commands → Inference: orchestrate · Command handlers delegate separation work
- Inference → Models: uses · Inference layer consults model metadata
- Inference → Provider API: abstracts · Providers share a common backend interface
- Inference → Registry: resolves · Registry exposes available engines
- Registry → Demucs: selects · Current architecture centers on Demucs provider
- Demucs → Sidecar: spawns · Rust launches bundled sidecar process
- Demucs → Model weights: downloads · Checkpoint is fetched when missing
- Audio file → Commands: input · User-selected audio enters backend workflow
- Demucs → WAV stems: writes · Separation output is persisted as WAV files
- WAV stems → Stem mixer: consumes · Frontend loads generated stems for playback