Publishing a Show — Owner’s Manual

How a show gets from a whole-show WAV to renedebos.com, what you do by hand, what Claude runs, and what every tool in scripts/ is for. Last updated: 2026-07-17 (matches workflow v7 — fixed the applause-limiter true-peak safety loop so its retry actually moves the peak it's supposed to fix; see Part 5 for the full version history).

Part 1 — Your steps, in order

Stage A · Audacity (all you, all judgment)

1. Set up the Work Folder on Google Drive: DAT Tapes/Work Folder/<Artist> - <Venue> <date>/ (e.g. JerryHannan - 19 Broadway 1999-03-29). Put the whole-show WAV there. Work on the local copy under ~/gdrive-mount/.
2. Import the WAV into Audacity and do the whole show in one project:
   • a label at every song's boundaries (this is the most valuable thing you make — see step 4);
   • fade-in at each song start, studio fade-out on the applause;
   • clip repairs on the loudest peaks where needed.
3. Noise reduction — only when the tape needs it. Apply NR across the whole show (one noise profile for the whole tape), ideally before the fade-outs, or check the faded tails after.

Before you apply NR: export the untreated tracks once into Tracks (pre-NR archive)/. Hand edits without NR can't be regenerated later — this is the only chance to keep them.

4. Export the labels: File → Export → Labels → save as labels.txt in the Work Folder root, next to the WAV. It's a 2 KB text file and it is the raw archive's split recipe: WAV + labels can regenerate untouched per-song files forever, even if Audacity or .aup3 files are long gone. The pipeline checks for this file at both of its stages and nags until it exists — it never blocks a publish, but don't let the nag scroll by.
5. Export the tracks: File → Export → Export Multiple, split by labels, FLAC, numbered filenames (01 Title.flac, 02 Title.flac, …) into:
   • Tracks/ — the normal case;
   • Tracks Noise Reduction/ — if and only if you applied NR.

Rule: exactly one of those two folders may contain audio. The pipeline refuses to run if both do — it never guesses which set is canonical.

6. If you treated the tape (NR or anything else non-standard), drop a one-line notes.txt inside the tracks folder with the settings, e.g. noise reduction 6 dB, sensitivity 5. That exact text flows automatically into the show's provenance record and the Technical data table on the site — nobody has to remember or retype it.
7. Save the .aup3 project in the Work Folder and copy everything up to Google Drive via the ChromeOS Files app (your usual way). Drive is the source of truth; Claude verifies against it, not against your local copy.
8. Tell Claude: "process/publish show X to the website." That's the handoff.

Stage B · The pipeline (Claude, automatic — you just answer questions)

Stage C · Afterwards (optional, whenever)

• Review drafted tags/songwriters in the metadata editor (make edit or the "Hannan Metadata Editor" launcher), save, then tell Claude to rebuild and push.
• Rarity drift warnings from the build (a song tagged rarity that now has 3+ appearances) are yours to adjudicate — untag or keep.
• If you kept a pre-NR archive: the Drive copy stays forever, the local copy gets deleted after publish.
• Reclaim disk space: python3 scripts/publish_show.py cleanup <slug> deletes the local working copies — but only after verifying the show is live on the site, complete on R2, and backed up on Drive. It refuses otherwise.

Loudness normalization

Policy: linear gain only, never dynamic (compressor-style) processing — no exceptions. These are acoustic live recordings with wide, intentional dynamics (quiet fingerpicked verses next to loud strummed choruses, hand-drawn fade-outs); the −20 LUFS target is chosen for comfortable listening, not competitive loudness, so there's never a reason to squash a track's dynamics to hit it exactly. process decides per track, in order:

1. Plain linear — the show's nominal target (−20 LUFS for every artist) fits under the −1 dBTP ceiling with a single constant gain. Most tracks.
2. Linear, reduced target — the nominal target would push true peak past the ceiling by a small margin (≤ 2 dB). Instead the track takes its own honest "max linear target" (the same number diagnose reports as PRED_TP's max linear target) — a few dB quieter than its neighbors, always still one constant gain, dynamics untouched. (Workflow v6: the gain for both of these cases is computed once from a measurement pass and applied with ffmpeg's plain volume filter, never loudnorm at render time — earlier versions asked loudnorm for the target and trusted its own linear/dynamic decision, which past this margin would silently fall back to dynamic normalization and flatten a hand-drawn fade with nothing in the logs to show it. v6 removes that decision from the render step entirely, so it can't happen no matter how close to the margin a track sits.)
3. Applause-limited — some audience tapes had the mic close to the crowd, and a clap can peak louder than anything in the music itself, forcing option 2 several dB quieter than the music needs. When the overshoot is large, the loudest moments are located and classified by behavior, not loudness: a window counts as applause only if it sits within min(30s, track-length/6) of the very start or end (tracks are split from one continuous tape — applause lives at those boundaries, never mid-song) and either towers ≥ 27 dB over its own local average (a clap's signature — sustained music measures 19–22 dB) or beats the loudest moment in the song's body by ≥ 2 dB (catches a final chord ringing out under the applause, which would otherwise hide the clap signature). If applause is what's eating the headroom, the music gets one constant gain sized to the music's own peaks — the limiter is mathematically incapable of touching anything classified as music — with a lookahead limiter engaging only on the applause. Ambiguous cases (a loud moment mid-song, or where limiting would barely help) fall back to option 2 and are flagged for a listen.
4. True-peak safety loop (applause-limited tracks only) — the limiter caps sample peaks, but the archive's −1 dBTP ceiling is a true (oversampled) peak; on hot transients the two can disagree by a few tenths of a dB. So the applause-limited render is measured after the fact, and if the real output overshoots, the retry backs off both the limiter threshold and the gain together (workflow v7) and re-renders (up to 5 attempts) — the ceiling is never trusted to the limiter's math alone. (v6 and earlier only backed off the gain; when applause, not music, sets the ceiling, the limiter clamps to its fixed threshold regardless of pre-gain, so a gain-only retry could measure the identical overshoot on every attempt and exhaust its retries still over ceiling — fixed in v7, see below.)

Every track's processing sidecar (data/processing/<slug>.json) records which of the above it got and why, in plain language — that's the Treatment column (hover for the reasoning) in each show's Technical data table. A python3 scripts/audio_process.py plan <folder> --artist <name> dry run shows every decision for a folder of tracks without writing any audio — useful before committing to a reprocess.

QA gates (workflow v6): output loudness range (LRA) is compared against the source's on every track, not just applause-limited ones — a linear gain can't change dynamic range at all, so any drift is the one thing that would reveal a hidden dynamics change regardless of which mode produced it. The provenance sidecar also records plr (true peak minus integrated loudness) and max_m/max_s (peak momentary/short-term loudness) per track — two tracks can share the same integrated loudness while one has a much louder chorus the average smooths over, which is what actually predicts a track sounding louder next to its neighbors in a playlist. The MP3 derivative gets its own small, independent gain trim (the FLAC master is never touched) if lossy encoding would push its true peak past the ceiling, iterated the same way the applause safety loop is.

Part 2 — The tools

Everything lives in scripts/ in the renedebos.com repo. "Who runs it" tells you whether you ever need to touch it.

The two you actually use

The pipeline (Claude runs these — listed so you know what's happening)

Conventions worth remembering

• Folder meanings: root WAV + labels.txt + .aup3 = raw archive · Tracks/ or Tracks Noise Reduction/ = your hand-edited export (pipeline input) · Tracks (pre-NR archive)/ = untreated export kept when NR was used · Processed/ = pipeline output backup (audio-identical to what's on the site; tags are reproducible from the catalog via retag). Anything suffixed "(… superseded)" is a retired earlier generation — draft exports or old processing runs — kept for the record, never used by the pipeline (archive-wide cleanup 2026-07-10).
• The storage rule: store what hands made; derive what machines can remake. Raw splits are never stored (WAV + labels regenerate them); your edits always are.
• Provenance: every processed show has data/processing/<slug>.json — the exact settings and measurements per track — rendered as the "Technical data" table on the show page. NR shows get a blue noise-reduced badge. A per-track Treatment column (workflow v5+) shows which normalization mode the track got, with the plain-language reasoning on hover; a — means the track predates v5 and hasn't been reprocessed yet.

Drive is the source of truth. ~/gdrive-mount is an ordinary local folder; nothing syncs by itself — you copy up via the Files app, Claude verifies against real Drive.

Part 3 — Metadata: the catalog and the tags inside the files

The archive has two metadata layers. Everything editorial lives in one place; the audio files carry a derived copy so downloads look right in any player.

The catalog is the single source of truth. The embedded tags are a derived copy, written by the pipeline. If the two ever disagree, the catalog wins and a retag makes the files match it.

What's embedded in every track

The technical part

• FLAC files store tags as Vorbis comments (the FLAC-native tag block); MP3 files use ID3v2.3 (chosen over 2.4 for maximum player compatibility). ffmpeg writes both from the same generic keys.
• Tags live in the file’s container (the envelope), not in the audio stream. Retagging is a container rewrite (ffmpeg -c copy): the audio bytes pass through untouched, so the audio MD5 in the provenance sidecar stays valid — verify proves after every retag that the music is bit-identical.
• Every retagged track is MD5-checked before upload; a track whose audio would change is refused.
• Where the tagged copies are: R2 (streams + downloads). The website itself doesn’t read the tags — pages render from the catalog. Drive Processed/ backups from before 2026-07-10 are untagged (deliberate: tags are reproducible in one command, so ~8 GB of Drive re-uploads bought nothing); shows published after that date carry tags everywhere.

Changing metadata, end to end

1. Edit the catalog: make edit → change titles, venue, dates, artist credits, songwriter, tags → Save.
2. Update the site: build + push (or ask Claude) — the pages now show the new values.
3. Update the files: python3 scripts/audio_process.py retag <slug> --force — re-derives every tag for that show from the catalog and rewrites the file envelopes on R2. A few minutes per show; audio provably untouched.

Never edit tags directly in the files (with a tag editor or otherwise). The next retag would overwrite your edit, and the R2 copy would silently disagree with the catalog. Change the catalog; let the pipeline propagate it.

Playlist tags: the controlled vocabulary

Don't confuse these with the embedded file tags above — this is a different tags array, the mood/flavor/format labels (ballad, irish, favorite, …) that power the Playlist filters and site search. Three separate places govern them, each answering a different question:

The vocabulary currently holds 20 tags across five groups (provenance, mood, flavor, content/format, curated picks — see TAGS.md for the full table and definitions); 15 of those are offered as playlist filters. instrumental, medley, banter, improv, and beatles are valid tags you can apply to a track, but aren't in TAG_ORDER, so they stay search-only and don't clutter the filter row.

To add or retire a tag:

1. Edit TAGS.md first — it's the source of truth, and its own rules say new vocabulary needs to land there before anywhere else. Keep the list at roughly 20 tags or fewer.
2. Update TAG_VOCAB in scripts/sitegen/core.py to match, or the next build's integrity check fails on any track already carrying the tag.
3. Decide whether it belongs in TAG_ORDER (scripts/playlist.js) as a playlist filter, or stays search-only.
4. Rebuild + push — assets/tracks.json (the playlist's data source) and every page that surfaces tags are generated from the catalog.

TAG_ORDER filters itself down to tags actually present on at least one track, so a retired tag with no tracks left won't render as a dead chip — but the stale name is still confusing to find in the code later. Remove it from TAG_ORDER too when retiring a tag, not just TAGS.md.

Part 4 — Site operations

Reference facts about how the site itself runs. Nothing here is a per-show step; it matters when something breaks or gets upgraded.

How deploys work

Important: a green Action is not proof the site works. After a deploy, always spot-check a URL only the new deploy can serve, on renedebos.com itself. ?cache-bust query strings and client Cache-Control: no-cache headers don't reliably bypass Cloudflare's edge cache on this site (confirmed 2026-07-13, twice: a /shows/*/ page and, in a later deploy, /history/ both kept serving cf-cache-status: HIT with pre-deploy content through several cache-busted requests, while other pages in the same deploys came back fresh). It isn't tied to one route pattern — any page that already had a cached copy sitting at the edge can keep serving it past a deploy. So: after any deploy, spot-check the pages you actually changed, not a different page in the same deploy — freshness elsewhere doesn't prove anything about the page you care about. If a checked page still shows old content, purge it by hand: dashboard → Caching → Configuration → Purge Cache → Custom Purge, paste the exact URL (or Purge Everything if multiple pages from the same deploy are affected). The deploy Action's CLOUDFLARE_API_TOKEN is scoped to Workers deploy only — it can't purge cache, so this step has to be manual.

Security posture (hardened 2026-07-10)

• Every site response carries security headers (HSTS, CSP, nosniff, frame/referrer policies).
• The WAV download password can't be brute-forced quickly: constant-time comparison, a 1-second delay per wrong guess, and a per-minute attempt budget. The password's strength is still the real defence.
• Playlist short-link creation is capped per IP per day (re-sharing an existing playlist doesn't count against it).
• Lossless files can't be reassembled through the streaming endpoint — it refuses WAV/FLAC keys outright.

If things go wrong

• R2 audio lost or corrupted: every processed file is on Drive under <show>/Processed/. Re-upload, run retag --all --force (pre-2026-07-10 Drive backups have no embedded tags), then verify <slug> per show — zero mismatches required.
• A show sounds wrong on the site: verify <slug> compares the live R2 audio against the provenance MD5s and pinpoints any drifted track.
• The site itself: everything is in the git repo — pages, assets, data, workers. A git push (or wrangler rollback for a bad worker version) restores it.
• Raw archive: whole-show WAVs + labels.txt + .aup3 projects live on Drive; the tapes themselves remain the last resort.

Part 5 — Appendix: audio processing version history

Every processed track records which workflow version produced it (ver in data/processing/<slug>.json) and the literal ffmpeg chain applied (chain) — so one show can hold a mix of versions if a single track is ever reprocessed later on a newer engine. scripts/audio_process.py's WORKFLOW_VERSIONS dict is the source of truth; this appendix is its human-readable decode. To see which workflow version (and every other spec field — loudness, true peak, LRA, tags, damage flags) has actually landed on each track across the whole archive at once, filterable and sortable, see Archive Data — not linked from the main nav, bookmark it directly.

v1 — the linear baseline

Two-pass ffmpeg loudnorm to a fixed per-artist target (I=<target>:LRA=11:TP=-1:linear=true), all artists at −20 LUFS (Mad Hannans moved from −16 to −20 after A/B testing showed −16 forced non-linear processing on band masters with no audible loudness gain). Optional 80 Hz high-pass, 18 kHz low-pass, and a 60 Hz hum notch. Output mirrors the input container plus a derived 320k MP3. Deliberately recommend-only: no automatic limiter, compressor, or denoise — those remain hand-editing territory in Audacity.

v2 — corrective EQ

Same audio engine as v1, plus an optional literal ffmpeg EQ chain (--eq), prepended before the loudnorm stage, for restoring a poor source recording (e.g. de-mud + presence + air shelf on a muffled tape). The exact filter chain is recorded verbatim in the track's chain, so only tracks actually processed with --eq differ from v1's output.

v3 — embedded tags + MP3 true-peak check

Audio processing unchanged from v2. Added embedded metadata tags (title/artist/album/track/date/comment, sourced from recordings.json) into both the FLAC master and the derived MP3, plus a true-peak measurement of the encoded MP3 — lossy encoding can overshoot the original peak, so this is recorded per-track as mp3_tp and flagged above 0 dBTP. retag retrofits tags onto already-published shows via a container rewrite (-c copy) that never touches the audio stream, so the provenance MD5 stays intact.

v4 — the silent-fallback fix

The most consequential fix in the series. linear=true is only a request to ffmpeg's loudnorm filter — if hitting the target would push true peak past the −1 dBTP ceiling, ffmpeg silently falls back to dynamic (frame-adaptive) normalization instead, a compressor-like mode that rides gain up on quiet passages and can flatten a hand-drawn fade-out, with no warning at all in the logs (-loglevel error swallows it). From v4 on, any track whose predicted true peak overshoots the ceiling (the same math diagnose's PRED_TP flag already reports) is processed at its own honest "max linear target" (I − TP − 1) instead — a few dB quieter than its neighbors, but always one constant linear gain. Recorded in the provenance sidecar as target_lufs whenever it differs from the show's nominal target.

v5 — applause-aware headroom recovery

Calibrated on "Butter" (jerry-cafe-java-1999-03-25 track 4): on audience tapes the mic often sat close to the crowd, and a single clap can peak 6+ dB above anything in the music, alone forcing v4's reduced target several dB quieter than the music itself needs. When the predicted overshoot exceeds 2 dB, the loudest windows are classified by behavior, never raw loudness: a window can only be applause if it falls within min(30s, track-length/6) of the track's very start or end (tracks are split from one continuous tape — applause lives at those boundaries, never mid-song), and either towers ≥ 27 dB over its own local RMS (a clap's signature; sustained music measures 19–22 dB) or beats the loudest window in the song's body by ≥ 2 dB (catches a final chord ringing out under the applause). If applause is confirmed as what's eating the headroom, the music gets one constant gain sized to the music's own peaks — the limiter is mathematically incapable of reaching anything classified as music — with a lookahead limiter (alimiter, threshold −1.2 dBTP) engaging only on the applause tail. Because alimiter thresholds sample peaks while the archive's ceiling is a true (oversampled) peak, the render is measured after the fact and, if it overshoots, the gain is backed off and re-rendered (up to 5 attempts) — the limiter's math is never trusted blind. Ambiguous cases (a loud moment mid-song, or where limiting would recover less than 1 dB) fall back to v4's reduced target and are flagged for a listen. QA gate: output LRA must match source LRA within 0.5 LU.

This is a narrow, sanctioned exception to the "never limit the music" rule, not a reversal of it — it caps only the applause transient, never the performance itself. See CLAUDE.md's linear-normalization policy note for the full reasoning.

v6 — explicit-gain rendering and broader QA

Every prior version still handed loudnorm a target LUFS at render time and trusted its own internal choice between linear and dynamic (frame-adaptive) normalization — v4 and v5's whole design is built around engineering that choice so it always lands on linear (the reduced target, the applause-sized gain), but the decision at render time was still ffmpeg's to make. v6 removes that decision from the render step entirely: plan_track's measurement pass computes the exact gain a track needs (the same math v4/v5 already used), and the render applies it with ffmpeg's volume filter — an unconditional multiply with no fallback mode to fall into. loudnorm and ebur128 remain in the pipeline purely as measurement tools. Re-running the two tracks used to validate this (one linear-reduced, one applause-limiter) produced byte-identical applause-limiter output to v5 (that code path is untouched) and a slightly more precise linear-reduced result — the old loudnorm-based render for "Plastic Lemons" landed 0.42 dB under the ceiling it was engineered to just reach; the explicit-gain render lands within 0.02 dB of it, using the headroom the plan already calculated was safe.

Three QA additions ride along with the same change:

• The output LRA-preservation check (source vs. rendered loudness range, 0.5 LU tolerance) now runs on every track, not just applause-limiter ones. A linear gain cannot change dynamic range at all — on any other track, a shift would mean something rode the gain during render, which after this change should be structurally impossible, but a QA gate that only watched the one mode capable of nuance was never really guarding the other two.
• The provenance sidecar gains plr (true peak minus integrated loudness) and max_m/max_s (the loudest 400ms/3s window in the track) alongside the existing lufs/tp/lra. Two tracks can share the same integrated loudness while one has a much louder chorus the average smooths straight over — that's what actually predicts a track sounding louder than its neighbors in a mixed playlist, which integrated loudness alone can't show.
• The MP3 derivative gets its own small, independent gain trim — the FLAC master's gain is never touched — if the lossy encode's true peak would otherwise clip on decode, iterated up to 3 times the same way the applause true-peak loop already re-renders and re-measures rather than trusting a single pass.

v7 — the safety loop's retry actually moves the peak

v5 added the true-peak safety loop specifically because alimiter thresholds sample peaks while the archive's ceiling is a true (oversampled) peak, so on hot transients the two can disagree by a few tenths of a dB — the loop renders, measures the real output, and if it overshoots, backs off and re-renders. From v5 through v6, "backs off" meant reducing gain_db alone, the pre-limiter gain applied to the whole track. That's the right lever when the music is what's driving the overshoot — but on an applause-limiter track it's specifically the applause that's eating the headroom, and alimiter clamps that segment to its limit_db threshold regardless of how much pre-gain feeds it, as long as the input still exceeds that threshold at all. Reducing gain_db only ate into the music's already-safe headroom; the applause's post-limiter level — and therefore its true peak — never moved.

Caught live re-processing sean-19-broadway-1999-11-29: track 21, "Houses of the Holy," came back from the safety loop still at −0.79 dBTP, over the −1 ceiling, after all 5 attempts. The report showed why — every single attempt measured the identical −0.78 dBTP, the tell that nothing was actually changing. The fix backs off limit_db in lockstep with gain_db, so the clamp itself moves down on each retry, while keeping music_peak + gain_db <= limit_db — the invariant from v5 that keeps the limiter mathematically incapable of ever reaching anything classified as music. Re-rendered, track 21 landed at −1.15 dBTP on the first retry.

Scope is narrow: linear and linear-reduced tracks are untouched (they never go through this loop), and any applause-limiter track whose first attempt already met the ceiling never enters the retry path either — this only changes the outcome for a track that previously entered the loop and never actually got fixed by it.