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
- 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.
- Never invent identifiers. ISRC, UPC, EAN, IPI/CAE, publisher IDs stay empty
unless supplied. The distributor assigns them.
- 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.
- Never notch a harmonic series. Peak detectors flag musical content. Test
before treating (the pipeline does this automatically and reports the fundamental).
- 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.
- 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.
- 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
- Read
reference/WORKFLOW.md — the full process and what each stage decides.
- 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.
- Read
reference/AGENTIK-STANDING-BRIEF.md for Agentik releases — it is the artist-specific spec and overrides the generic one.
- 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.
- 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.
- 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.
- 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
1---2name: album-mastering3description: >4 Master a finished album from stereo mixes into a distribution-ready release:5 measurement-driven mastering (per-track chain + album coherence pass), 3000x30006 artwork, clean metadata with provenance handling, on-device lyric/explicit7 screening, and full analysis + QA reports. Originals are never touched. Use when8 the user says "master my album", "prepare this release for distribution",9 "mastering", "make these tracks release-ready", or in French "masterise mon album",10 "prépare la sortie", "master pour distribution". NOT for mixing (no stems) and NOT11 for single-track loudness normalisation.12argument-hint: "[project.json] (omit → build one from the user's brief)"13allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "AskUserQuestion"]14domain: audio15read_only: false16triggers: ["master my album", "album mastering", "mastering", "distribution ready",17 "release ready", "masterise", "mastering album", "prepare release",18 "LUFS", "true peak", "dBTP", "masteriser"]19metadata:20 source: https://skillmd.com/skills/agentik-os/album-mastering21---2223# album-mastering — stereo mixes → distribution-ready release2425Turns a folder of finished stereo mixes into a complete, documented release: mastered26WAVs, tagged lossless + reference copies, artwork, distributor metadata, and reports27that disclose every process applied.2829**This is mastering, not mixing.** You get two-track masters, not stems. You cannot30rebalance a vocal or move a kick. When something cannot be fixed safely at the master31stage, **report it — never fake the fix with extreme EQ.**3233## Hard rules34351. **Protect the originals.** Copy → `chmod 444` → verify SHA-256 → only then process.36 Never write to the source files. `prepare.py` enforces this and aborts on mismatch.372. **Never invent identifiers.** ISRC, UPC, EAN, IPI/CAE, publisher IDs stay empty38 unless supplied. The distributor assigns them.393. **Strip vendor metadata; never destroy the audit.** Export-tool junk (encoder40 strings, temp titles, local paths, generator names and IDs) is removed from41 everything shipped — `declare_provenance` defaults to `false`. The raw source tags42 stay verbatim in `metadata_before.json`, which is internal and never distributed,43 so provenance remains traceable. Two things this does **not** do: it does not44 rewrite the audit record, and it does not answer the distributor's AI-content45 question — a human does that at upload.464. **Never notch a harmonic series.** Peak detectors flag musical content. Test47 before treating (the pipeline does this automatically and reports the fundamental).485. **Measure, don't assume.** Every claim in the reports must come from a49 measurement. If a field cannot be verified, say so rather than filling a default.506. **Never hand WAV masters to a media library.** macOS ignores RIFF INFO album51 and track tags, so an album of WAVs imports as one album per track with no cover52 — and Music.app writes its own artwork back into the masters, repeatedly, for as53 long as they stay in the library. The `protect` stage sets them read-only; tell54 the artist to remove the WAVs from the library and import55 `deliverables_tagged/m4a/` (ALAC, lossless, bit-identical) instead.567. **The user's tracklist wins** over source filenames — but surface every57 mismatch, and check it against the lyrics. A title that is never sung in its58 own song is usually a draft name; the source filename is usually the real59 hook. `transcribe.py` flags this automatically. Raise it **before** mastering,60 not after the masters are cut.6162## Setup6364```bash65scripts/setup.sh # venv at ~/.cache/album-mastering/venv66```67Needs `ffmpeg`. Lyric screening additionally needs `whisper-cpp` + a ggml model.6869## Run7071```bash72VENV=~/.cache/album-mastering/venv/bin/python73$VENV scripts/pipeline.py my.project.json # everything74$VENV scripts/pipeline.py my.project.json --from master # resume75$VENV scripts/pipeline.py my.project.json --only qa # one stage76$VENV scripts/master.py my.project.json 7 8 # re-master two tracks77$VENV scripts/audit.py my.project.json --scan ~/dir # recursive source audit78$VENV scripts/transcribe.py my.project.json # lyric screening (opt-in)79```8081Stages: `prepare · audit · master · artwork · tag · deliverables · sidecars ·82measure_masters · qa · reports · protect · checksums`8384## How to drive it85861. **Read `reference/WORKFLOW.md`** — the full process and what each stage decides.872. **Build the project file.** Copy `templates/project.template.json`. Ask the user88 only for what you cannot measure: tracklist with exact titles, release date,89 genre, label, copyright. Reuse an artist profile from `artists/` when one exists.903. **Read `reference/AGENTIK-STANDING-BRIEF.md` for Agentik releases** — it is the artist-specific spec and overrides the generic one.914. **Set the loudness arc deliberately.** Do not give every track the same target.92 Ask what the album's shape is, or derive it: dynamic tracks breathe, heavy tracks93 push, closers pull back. Typical underground electronic: −8.5 to −10.0 LUFS,94 ceiling −1.0 dBTP. Never force a track into a range.955. **Run `prepare` and `audit`, then read the measurements before mastering.**96 The audit walks the whole source tree, not just the declared tracks, and will tell97 you about audio files you did not list. The analysis tells98 you which tracks mask their own kick, which are tonal outliers, and whether the99 sources are bandwidth-limited. Set `target_lufs` and `character` from that. Leave100 `duck`, `side_reduction` and `saturation` on `"auto"` unless you have a reason.1016. **Run the rest**, then **read the generated reports and enrich them.** The scripts102 emit every measured number and the mechanical findings; the narrative judgement103 is yours to add.1047. **Report honestly.** Lead with what you found and what the user must still decide105 (title mismatches, AI-provenance declaration, artwork resolution, explicit flags).106107## Known traps108109`reference/DECISIONS.md` documents the ones that have already cost time —110read it before changing any DSP. The short version:111112- **Chunked resampling inflates true-peak measurements.** Exclude chunk edges or you113 will "fix" a limiter that was already correct. Cross-check against `ffmpeg114 -af ebur128=peak=true`.115- **Compare spectra at equal loudness**, never at equal total energy — bass116 differences otherwise distort every other band and reverse your conclusions.117- **Overlapping EQ bells double-count.** Solve the bell bank as least squares.118- **Whisper collapses into `*Musique*`** on dense instrumentals — chunk it.119- **ffmpeg writes its own `ISFT` encoder tag** unless `+bitexact` is an *output* flag.120- **Don't force artwork into WAV.** Compatibility beats convenience.121122## Output123124```125<output_root>/126├── masters/ 24-bit WAV + cover_distribution.jpg alongside127├── artwork/ cover_original.* · cover_distribution.jpg (3000², sRGB)128├── originals_backup/ read-only, SHA-256 verified129├── deliverables_tagged/ m4a/ (ALAC — the one to import into Apple Music) ·130│ flac/ (lossless archive) · mp3/ (320 reference)131├── metadata/ release_metadata.csv/.json · metadata_before/after.json132├── analysis/ MASTERING_ANALYSIS.md · ALBUM_COHERENCE_REPORT.md133└── documentation/ MASTERING_REPORT.md · RELEASE_QA_REPORT.md ·134 LYRICS_SCREENING.md · CHECKSUMS.sha256135```