# cocreating/song4stem-demucs architecture

> Architecture diagram of the GitHub repository cocreating/song4stem-demucs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cocreating/song4stem-demucs
- Repository: https://github.com/cocreating/song4stem-demucs

## Overview

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: [`src-tauri/src/commands.rs`](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/commands.rs) (Commands), [`src-tauri/src/inference/mod.rs`](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/mod.rs) (Inference), [`src-tauri/src/inference/demucs.rs`](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/demucs.rs) (Demucs), [`src/App.vue`](https://github.com/cocreating/song4stem-demucs/blob/master/src/App.vue) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app["App<br/>Vue shell<br/>[App.vue]"]
  node_uploader["File upload<br/>UI component<br/>[FileUploader.vue]"]
  node_progress["Job progress<br/>UI component<br/>[JobProgress.vue]"]
  node_mixer["Stem mixer<br/>UI component<br/>[StemMixer.vue]"]
  node_tauri_client["Tauri client<br/>IPC client<br/>[tauri-client.ts]"]
  node_job_store["Job store<br/>reactive state<br/>[useJobStore.ts]"]
  node_separator_store["Separator store<br/>reactive state"]
end

subgraph group_backend["Desktop backend"]
  node_commands["Commands<br/>Rust IPC<br/>[commands.rs]"]
  node_state["App state<br/>Rust state<br/>[state.rs]"]
  node_errors["Errors<br/>Rust error<br/>[error.rs]"]
end

subgraph group_inference["Inference"]
  node_inference_mod["Inference<br/>Rust module<br/>[mod.rs]"]
  node_models["Models<br/>metadata<br/>[models.rs]"]
  node_provider["Provider API<br/>trait layer<br/>[provider.rs]"]
  node_registry["Registry<br/>[registry.rs]"]
  node_demucs["Demucs<br/>separator backend<br/>[demucs.rs]"]
end

subgraph group_packaging["Build"]
end

subgraph group_external["External"]
  node_sidecar["Sidecar<br/>local process<br/>[demucs_entry.py]"]
  node_weights[("Model weights<br/>remote model")]
  node_audio_file["Audio file<br/>local input"]
  node_stems["WAV stems<br/>local output"]
end

node_app -->|"renders"| node_uploader
node_app -->|"renders"| node_progress
node_app -->|"renders"| node_mixer
node_uploader -->|"submit file"| node_tauri_client
node_progress -->|"reads"| node_job_store
node_mixer -->|"reads"| node_separator_store
node_tauri_client -->|"invoke"| node_commands
node_commands -->|"mutate"| node_state
node_commands -->|"normalize"| node_errors
node_state -->|"push state"| node_job_store
node_state -->|"push state"| node_separator_store
node_commands -->|"orchestrate"| node_inference_mod
node_inference_mod -->|"uses"| node_models
node_inference_mod -->|"abstracts"| node_provider
node_inference_mod -->|"resolves"| node_registry
node_registry -->|"selects"| node_demucs
node_demucs -->|"spawns"| node_sidecar
node_demucs -->|"downloads"| node_weights
node_audio_file -->|"input"| node_commands
node_demucs -->|"writes"| node_stems
node_stems -->|"consumes"| node_mixer

click node_app "https://github.com/cocreating/song4stem-demucs/blob/master/src/App.vue"
click node_uploader "https://github.com/cocreating/song4stem-demucs/blob/master/src/components/FileUploader.vue"
click node_progress "https://github.com/cocreating/song4stem-demucs/blob/master/src/components/JobProgress.vue"
click node_mixer "https://github.com/cocreating/song4stem-demucs/blob/master/src/components/StemMixer.vue"
click node_tauri_client "https://github.com/cocreating/song4stem-demucs/blob/master/src/services/tauri-client.ts"
click node_job_store "https://github.com/cocreating/song4stem-demucs/blob/master/src/stores/useJobStore.ts"
click node_separator_store "https://github.com/cocreating/song4stem-demucs/blob/master/src/stores/useSeparatorStore.ts"
click node_commands "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/commands.rs"
click node_state "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/state.rs"
click node_errors "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/error.rs"
click node_inference_mod "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/mod.rs"
click node_models "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/models.rs"
click node_provider "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/provider.rs"
click node_registry "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/registry.rs"
click node_demucs "https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/demucs.rs"
click node_sidecar "https://github.com/cocreating/song4stem-demucs/blob/master/scripts/demucs_entry.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_uploader,node_progress,node_mixer,node_tauri_client,node_job_store,node_separator_store toneBlue
class node_commands,node_state,node_errors toneAmber
class node_inference_mod,node_models,node_provider,node_registry,node_demucs toneMint
class node_sidecar,node_weights,node_audio_file,node_stems toneIndigo
```

## Components

### Frontend

Vue 3 presentation layer and client-side state

- [App](https://github.com/cocreating/song4stem-demucs/blob/master/src/App.vue): Vue shell · Top-level UI composition · `src/App.vue`
- [File upload](https://github.com/cocreating/song4stem-demucs/blob/master/src/components/FileUploader.vue): UI component · Selects source audio for separation · `src/components/FileUploader.vue`
- [Job progress](https://github.com/cocreating/song4stem-demucs/blob/master/src/components/JobProgress.vue): UI component · Shows separation status and updates · `src/components/JobProgress.vue`
- [Stem mixer](https://github.com/cocreating/song4stem-demucs/blob/master/src/components/StemMixer.vue): UI component · Plays and blends generated stems · `src/components/StemMixer.vue`
- [Tauri client](https://github.com/cocreating/song4stem-demucs/blob/master/src/services/tauri-client.ts): IPC client · Typed bridge for commands and events · `src/services/tauri-client.ts`
- [Job store](https://github.com/cocreating/song4stem-demucs/blob/master/src/stores/useJobStore.ts): reactive state · Client state for active jobs and progress · `src/stores/useJobStore.ts`
- [Separator store](https://github.com/cocreating/song4stem-demucs/blob/master/src/stores/useSeparatorStore.ts): reactive state · Client state for separator readiness and output · `src/stores/useSeparatorStore.ts`

### Desktop backend

Tauri shell and Rust orchestration

- [Commands](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/commands.rs): Rust IPC · Validates requests and handles app commands · `src-tauri/src/commands.rs`
- [App state](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/state.rs): Rust state · Single source of truth for providers and jobs · `src-tauri/src/state.rs`
- [Errors](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/error.rs): Rust error · Normalizes failures for UI reporting · `src-tauri/src/error.rs`

### Inference

Provider abstraction and Demucs integration

- [Inference](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/mod.rs): Rust module · Coordinates model and provider abstractions · `src-tauri/src/inference/mod.rs`
- [Models](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/models.rs): metadata · Model definitions and capabilities · `src-tauri/src/inference/models.rs`
- [Provider API](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/provider.rs): trait layer · Interface for separator backends · `src-tauri/src/inference/provider.rs`
- [Registry](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/registry.rs): provider registry · Discovers and exposes available engines · `src-tauri/src/inference/registry.rs`
- [Demucs](https://github.com/cocreating/song4stem-demucs/blob/master/src-tauri/src/inference/demucs.rs): separator backend · Runs local source separation work · `src-tauri/src/inference/demucs.rs`

### External

Local and remote runtime dependencies

- [Sidecar](https://github.com/cocreating/song4stem-demucs/blob/master/scripts/demucs_entry.py): local process · Bundled Python/Demucs execution process · `scripts/demucs_entry.py`
- **Model weights**: remote model · Fetched checkpoint data for htdemucs
- **Audio file**: local input · User-selected source track on disk
- **WAV stems**: local output · Separated stem files written to disk

## Connections

- 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
