[thcp]

Closes #783.

What changed

• Setting: Settings > Library > Stem files: "Stem storage format" (MP3 or WAV) and, for MP3, "MP3 bitrate" (128 / 192 / 256 kbps, CBR libmp3lame). STEMDECK_STEM_FORMAT and STEMDECK_STEM_MP3_KBPS seed it for Docker and Unraid (template rows added); a saved choice wins, as for separation_quality. Whitelisted server-side, both values checked before either is kept; a non-object body is ignored (200), as Settings endpoints answer 500 when the body is not an object #797. Read when a job finishes: no restart.
• Default is MP3 at 128 kbps (the maintainer's explicit choice), one constant: DEFAULT_STEM_STORAGE in app/core/config.py. An existing install that never saved the setting gets MP3 for new songs only; the helper text says so.
• Storage stage (app/pipeline/stem_storage.py), last in the pipeline, after every stage that reads stems. Separation and all analysis still run on WAV. Per stem: encode to a temp file, then verify: ffmpeg and libsndfile both decode it to the WAV's exact frame count, and its loudest 10 s block lines up at lag 0 (cross-correlation, plus a ratio guard for steady tones). Only when every stem passed: rename into place, then delete the WAVs. Any failure keeps every WAV and records the song as WAV; cancel cleans up and raises; the song never fails over it.
• One resolver (app/core/stem_files.py): stem_path picks <name>.wav, else <name>.mp3, by what is on disk. WAV first, because a WAV song can hold a cached download <name>.mp3 (GET /stems/{name}.mp3) that must never shadow it. decoded_wav hands the vocal split model a decoded WAV. Each job records stem_format / stem_mp3_kbps (state, registry, metadata.json, recovery).
• Player: a song whose stem URLs end in .mp3 opens on the full-decode engine (desktop and phone); the chunked engine only streams WAV. Lane downloads are named .mp3.
• The vocal split's two new stems are stored like the song.

What did not change

• WAV selected: the stage touches nothing (pinned by a byte-and-mtime test); every URL and reader resolves to the same .wav as before.
• Existing songs are not converted. A library can mix WAV and MP3 songs.
• No FLAC, no "convert my library". No new dependency; uv.lock unchanged.
• source.<ext> of an upload is never touched. original.wav in stems/ is the complement backing track, a stem, so it is stored like the others.

Audit of .wav (129 lines in 23 backend files on big-release)

Class	Lines	Handling
(a) writes a stem, or reads it inside the pipeline before storage (collect, sections, beatgrid, key refine, demucs, takes, click, backing caches)	39	unchanged, stays WAV
(b) reads a stem of a finished song	29	through stem_path (stems, region, mixdown, mode lanes, zip, backing/rest, vocal envelope, peaks, take length, loudness, fingerprint, lyrics timing and stamp, vocal split, recovery, the TTL sweep)
(c) URL or name for the browser	11	stem URLs carry the stored extension; /stems/{name}.wav serves either format with its own type and file name
(d) comments, upload whitelist, docs	50	unchanged

static/js: 64 matches, almost all .wave* CSS classes. Real WAV assumptions: the chunked engine (WAV-only by design, routed around) and the lane download name (fixed).

Two real bugs the audit found and this fixes: the TTL sweep's _has_stems_on_disk looked only for .wav, so it would have deleted an unregistered MP3 song; and the desktop app saves a lane download under the page's name, which said .wav over MP3 bytes.

Sample alignment (measured)

Broadband test signal and a real separated job, round trip WAV -> MP3 -> decode, all three bitrates:

Decoder	Length difference	Lag (xcorr)
ffmpeg (file input)	0 samples	0
ffmpeg input seek -ss (region exports), 5 offsets	0	0
libsndfile 1.2.2 (mpg123)	0	0
Chromium decodeAudioData (Playwright, seeded MP3 job)	0	0 (MSD at 0: 1.7e-4, at 576: 3.8e-2, at 1105: 0.25)

No compensation needed: libmp3lame's LAME/Xing header (-write_xing 1, explicit) carries delay and padding and all three decoders trim by it. Tolerance is 0 samples. Guards: test_mp3_storage_is_sample_aligned_in_ffmpeg_and_libsndfile (128/192/256), test_mixdown_from_mp3_stems_lines_up_with_one_from_wavs, test_a_shifted_output_keeps_the_wavs (576/1105/2000), and the Chromium spec.

Not verified: Tauri WebKit on macOS and Linux, Safari (no WebKit project in the suite). The storage stage cannot check the browser's decoder.

One finding: ffmpeg reading an MP3 from a pipe keeps the end padding (+479 samples here; start still aligned). No server reader pipes a stem; all pass a file path.

Real end-to-end (isolated server, 20 s sine upload, Demucs on this Mac)

	No setting (default MP3 128)	WAV selected (live, no restart)
Stems on disk	7 x .mp3, no .wav	7 x .wav
Stem files size	2.2 MB	24.7 MB
Store stage	2.4 s (encode + verify, 7 files)	records WAV, touches nothing

Both: every stem 882000 frames, mixdown wav/mp3, region, zip wav/mp3, master loudness and mastered export, EQ export, click + count-in export, backing and rest, vocal envelope, peaks, a take recorded through the API (length = song, lands on its sample), mixdown with the take. Playback, mixer, click, Karaoke and Performance checked in Chromium on the seeded MP3 song.

Tests

• pytest: 3315 passed; the 5 known ogg failures (no libvorbis on this Mac) only. New: tests/test_stem_storage.py (51), covering settings/env precedence and validation, the resolver, every failure mode (no libmp3lame, full disk, corrupt output, short output, shifted output, failed move, stall, cancel mid-encode, unexpected error), atomicity, and the readers above.
• Changed to pin WAV: tests/test_identify_regressions.py (its stubbed stems are placeholder bytes, so MP3 storage could only take its failure path there).
• Playwright full suite: 689 passed, 5 failed, all on the known-flaky list (footer-time, trash-restore Ctrl+click x3, streamer-media). New stem-storage.spec 9/9. npm run test:js green (new stem-format.test.mjs). ruff, ruff format, bandit, i18n coverage clean.

Risks

• Quality: stems summed again carry each stem's coding noise. On the sine test the summed mix's true peak rose 3.4 dB (loudness unchanged). 128 kbps is the explicit choice; 192 and 256 are one click away.
• Engine: MP3 songs decode in full, so they use more RAM than the chunked engine and take longer to start. Over the 1.2 GB ceiling (about 10 min of 6 stems) they fall back to the streaming <audio> path: no click, no key change, not sample-locked. The phone decodes in full too.
• WebKit decoding not verified (above). Docker env vars not tried in a real container.