NI .stem.mp4
The NI-compatible .stem.mp4 cache: file format, library rows, prepare resolution, and error handling.
Mixar caches generated stems as a single NI-compatible .stem.mp4. User Stem files and Mixar-generated cache share one load path. When a valid Stem is available for a track, that file is the playback source (mixdown + four stems) instead of the original audio.
Cache policy
| Topic | Choice |
|---|---|
| Cache format | Single {stems_root}/{fnv64(track_id)}.stem.mp4 |
| User Stem files | Open in place; never Demucs; never write Mixar cache |
| When stems are prepared | Early only (Generate stems / library worker). No ensure or hot-swap on deck load |
| Deck load if cache missing | Play original only; Stems pads inert |
| Mux mode | Consistent streams: all five streams same codec + sample rate |
| Codecs | Settings stems_format: opus (default) | flac. AAC stays out of the UI until a pure-Rust encoder lands in codec. |
| Tooling | Pure Rust mux/demux in codec (Symphonia for demux/decode; dedicated MP4 writer + STEM atom, no ffmpeg) |
| Stem order (file + engine) | NI: drums, bass, other, vocals (mixdown = stream 0) |
mastering_dsp |
Write disabled defaults in STEM atom; do not implement playback |
File format
- Container: MP4, extension
.stem.mp4 - Five stereo audio streams, identical codec and sample rate
- Stream 0 = mixdown (re-encoded from source PCM for generated files)
- Streams 1–4 = drums, bass, other, vocals
- STEM atom JSON (
version: 1, four{name, color},mastering_dspdisabled): labels/colors match stemgen defaults (Drums/Bass/Other/Vocals) - Detection:
.stem.mp4extension for browse/import; validate on open (≥5 audio streams + STEM atom preferred)
Cache and database
Filesystem (generated): {app_support}/stems/{fnv64(track_id)}.stem.mp4
track_stem (generated cache only):
track_idPKpath: absolute path to the.stem.mp4backend,source_fingerprint,format,sample_rate,generated_at
Native library Stem tracks: no track_stem row; prepare opens source_ref directly.
Stale when: format setting changes, fingerprint mismatches, file missing, or legacy four-file directory layout present without a valid .stem.mp4 row.
Migration: ensure / clear_all_track_stems remove old per-track directories; generate regenerates when requested.
Producing a cache
GenerateStems action / library worker
└─ source is normal audio (not a Stem file)
└─ Demucs → mux consistent .stem.mp4 → track_stem.path
Prepare resolution is summarized in the overview.
Components
| Piece | Responsibility |
|---|---|
codec |
Detect/open .stem.mp4; demux all audio streams; mux consistent-stream .stem.mp4 + STEM JSON atom. Keep single-track AudioDecoder for normal files. |
analyzer-stems |
HTDemucs split → PCM stems; call mux helper. |
library |
track_stem with single path; ensure only from analyze/worker; skip ensure for native Stems; clear-cache deletes .stem.mp4 tree (+ old dirs). |
| Prepare / host | Resolve native Stem or cache hit → StemBundle; else main-only. Never enqueue stem ensure on deck load. |
engine-dsp |
Main buffer + optional four stems; NI index order. Bundle load = mixdown as main + attach stems immediately. |
Error handling
- Corrupt cache
.stem.mp4: drop/invalidate row; fall back to original on prepare. - Corrupt native Stem source: fail loudly (toast / prepare error); do not Demucs.
- Ensure writes to temp then rename; failed temp deleted; no partial DB row on failure.
- Codec inside a user Stem that Symphonia cannot decode: error; no silent fallback to Demucs.
- Clear cache while in use: best-effort delete (see Storage & models).