album-mastering

# album-mastering — stereo mixes → distribution-ready release Turns a folder of finished stereo mixes into a complete, documented release: mastered WAVs, tagged lossless + reference copies, artwork, distributor metadata, and reports that disclose every process applied. **This is mastering, not mixing.** You get two-track masters, not stems. You cannot rebalance a vocal or move a kick. When something cannot be fixed safely at the master stage, **report it — never fake the fix with extreme EQ.** ## Hard rules 1. **Protect the originals.** Copy → `chmod 444` → verify SHA-256 → only then process. Never write to the source files. `prepare.py` enforces this and aborts on mismatch. 2. **Never invent identifiers.** ISRC, UPC, EAN, IPI/CAE, publisher IDs stay empty unless supplied. The distributor assigns them. 3. **Strip vendor metadata; never destroy the audit.** Export-tool junk (encoder strings, temp titles, local paths, generator names and IDs) is removed from everything shipped — `declare_provenance` defaults to `false`. The raw source tags stay verbatim in `metadata_before.json`, which is internal and never distributed, so provenance remains traceable. Two things this does **not** do: it does not rewrite the audit record, and it does not answer the distributor's AI-content question — a human does that at upload. 4. **Never notch a harmonic series.** Peak detectors flag musical content. Test before treating (the pipeline does this automatically and reports the fundamental). 5. **Measure, don't assume.** Every claim in the reports must come from a measurement. If a field cannot be verified, say so rather than filling a default. 6. **Never hand WAV masters to a media library.** macOS ignores RIFF INFO album and track tags, so an album of WAVs imports as one album per track with no cover — and Music.app writes its own artwork back into the masters, repeatedly, for as long as they stay in the library. The `protect` stage sets them read-only; tell the artist to remove the WAVs from the library and import `deliverables_tagged/m4a/` (ALAC, lossless, bit-identical) instead. 7. **The user's tracklist wins** over source filenames — but surface every mismatch, and check it against the lyrics. A title that is never sung in its own song is usually a draft name; the source filename is usually the real hook. `transcribe.py` flags this automatically. Raise it **before** mastering, not after the masters are cut. ## Setup ```bash scripts/setup.sh # venv at ~/.cache/album-mastering/venv ``` Needs `ffmpeg`. Lyric screening additionally needs `whisper-cpp` + a ggml model. ## Run ```bash VENV=~/.cache/album-mastering/venv/bin/python $VENV scripts/pipeline.py my.project.json # everything $VENV scripts/pipeline.py my.project.json --from master # resume $VENV scripts/pipeline.py my.project.json --only qa # one stage $VENV scripts/master.py my.project.json 7 8 # re-master two tracks $VENV scripts/audit.py my.project.json --scan ~/dir # recursive source audit $VENV scripts/transcribe.py my.project.json # lyric screening (opt-in) ``` Stages: `prepare · audit · master · artwork · tag · deliverables · sidecars · measure_masters · qa · reports · protect · checksums` ## How to drive it 1. **Read `reference/WORKFLOW.md`** — the full process and what each stage decides. 2. **Build the project file.** Copy `templates/project.template.json`. Ask the user only for what you cannot measure: tracklist with exact titles, release date, genre, label, copyright. Reuse an artist profile from `artists/` when one exists. 3. **Read `reference/AGENTIK-STANDING-BRIEF.md` for Agentik releases** — it is the artist-specific spec and overrides the generic one. 4. **Set the loudness arc deliberately.** Do not give every track the same target. Ask what the album's shape is, or derive it: dynamic tracks breathe, heavy tracks push, closers pull back. Typical underground electronic: −8.5 to −10.0 LUFS, ceiling −1.0 dBTP. Never force a track into a range. 5. **Run `prepare` and `audit`, then read the measurements before mastering.** The audit walks the whole source tree, not just the declared tracks, and will tell you about audio files you did not list. The analysis tells you which tracks mask their own kick, which are tonal outliers, and whether the sources are bandwidth-limited. Set `target_lufs` and `character` from that. Leave `duck`, `side_reduction` and `saturation` on `"auto"` unless you have a reason. 6. **Run the rest**, then **read the generated reports and enrich them.** The scripts emit every measured number and the mechanical findings; the narrative judgement is yours to add. 7. **Report honestly.** Lead with what you found and what the user must still decide (title mismatches, AI-provenance declaration, artwork resolution, explicit flags). ## Known traps `reference/DECISIONS.md` documents the ones that have already cost time — read it before changing any DSP. The short version: - **Chunked resampling inflates true-peak measurements.** Exclude chunk edges or you will "fix" a limiter that was already correct. Cross-check against `ffmpeg -af ebur128=peak=true`. - **Compare spectra at equal loudness**, never at equal total energy — bass differences otherwise distort every other band and reverse your conclusions. - **Overlapping EQ bells double-count.** Solve the bell bank as least squares. - **Whisper collapses into `*Musique*`** on dense instrumentals — chunk it. - **ffmpeg writes its own `ISFT` encoder tag** unless `+bitexact` is an *output* flag. - **Don't force artwork into WAV.** Compatibility beats convenience. ## Output ``` <output_root>/ ├── masters/ 24-bit WAV + cover_distribution.jpg alongside ├── artwork/ cover_original.* · cover_distribution.jpg (3000², sRGB) ├── originals_backup/ read-only, SHA-256 verified ├── deliverables_tagged/ m4a/ (ALAC — the one to import into Apple Music) · │ flac/ (lossless archive) · mp3/ (320 reference) ├── metadata/ release_metadata.csv/.json · metadata_before/after.json ├── analysis/ MASTERING_ANALYSIS.md · ALBUM_COHERENCE_REPORT.md └── documentation/ MASTERING_REPORT.md · RELEASE_QA_REPORT.md · LYRICS_SCREENING.md · CHECKSUMS.sha256 ```