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

scripts/setup.sh                 # venv at ~/.cache/album-mastering/venv

Needs ffmpeg. Lyric screening additionally needs whisper-cpp + a ggml model.

Run

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