Merge pull request #710 from PipFoweraker/fable/music-session-1

feat(music): Fable music session 1 -- composed adaptive score, wired + capture pipeline (carries #682)

Author: PipFoweraker

.pre-commit-config.yaml

@@ -13,6 +13,9 @@ repos:
       - id: check-json
       - id: check-added-large-files
         args: ['--maxkb=1000']
+        # Music tracks are legitimately >1MB; committed game/tool audio is
+        # deliberate (storage-is-cheap policy). Guard stays for everything else.
+        exclude: '^(godot/assets/audio/|tools/music/captures/game/).*\.(ogg|mp3|wav)$'
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: detect-private-key

CLAUDE.md

@@ -45,6 +45,13 @@ runtime — the old Python bridge is gone). Python exists only for CI/tooling in
 - **ASCII-only:** no non-ASCII chars in `.py/.md/.json/.yaml/.txt/.cfg/.sh`
   (no smart quotes, em-dashes as `--`, no emoji in source/docs). `enforce-standards`
   blocks the commit otherwise.
+- **Agents: commit in the FOREGROUND and make zero tool calls while hooks
+  run.** The session harness rewrites `.claude/settings.local.json` on tool
+  activity; pre-commit has that file stashed during the run, sees a tracked
+  file change mid-hook, reports "Stashed changes conflicted with hook
+  auto-fixes... Rolling back", and aborts -- and the rollback also DISCARDS
+  any working-tree edits made during the run. Background commits + parallel
+  work = repeated mystery failures (cost 4 attempts on 2026-07-19).
 
 ## Git workflow
 - Branch from **freshly-fetched** `origin/main`, not a stale local ref:

dev-blog/music-session-1.md

@@ -0,0 +1,81 @@
+# Music session 1 -- from hummed leitmotif to a wired adaptive score
+
+> Dev-history capture (2026-07-17/19, the Fable music session). How P(Doom)1
+> went from "no composed music" to a five-tier adaptive score playing in-game,
+> in one long human-AI listening loop. Working artifacts live in `tools/music/`;
+> taste law in `tools/music/DIRECTION_NOTES.md`; raw judgment exports in
+> `tools/music/jukebox_notes*.json`.
+
+## The method: judgment rounds
+
+The whole session ran on one loop: Claude composes Strudel patches (browser
+live-coding, hearable in seconds) -> Pip listens on headphones and writes
+unfiltered notes -> the notes are decoded into RULINGS (logged, append-only)
+-> the rulings drive the next iteration. Pip is the taste authority; the
+model is the instrument-builder and secretariat. Two full jukebox judgment
+rounds happened in a single evening, and the second round's notes were
+audibly more precise than the first -- the listening skill builds with the
+score.
+
+Design rulings that came out of ROUND 1: doom's weight lives in dark and
+middle registers (its heralds may sing anywhere); harsh discordance is an
+EVENT (miniboss flavour), not a bed; the tempo-ratchet (the live-band
+*phwar*, everyone dances faster); victory might not be fanfare at all.
+ROUND 2: layers must taper or ring out, never hard-cut; elements may
+germinate over very long spans ("seeds of my own destruction"); respite
+states need "A-team solidity" -- no stressors, but structural reassurance;
+and M4 grew a metal trajectory ("the bassist catches the train... we all
+gain GRUNGE together") that independently converged on the Mick Gordon
+lineage the design docs had already flagged.
+
+## The discoveries
+
+- **The beloved reference decoded.** Pip's most-listened track ("People Of
+  The Drifting Houses", Master Musicians of Bukkake) hides a 7-beat bar
+  grouped 3+2+2 at ~129 bpm. Found by Demucs drum-stem isolation + folding
+  53 s of onsets at candidate meters: contrast for 7 was double any other
+  grouping. Pip had hummed the groove from memory first; the analysis
+  matched his transcription. That cell now seeds the taiko/catastrophe
+  rhythm vocabulary.
+- **The score is a cast.** Six characters with hard timbre boundaries
+  (CASTING_SHEET.md): humans are organic and micro-timed; the rivals are
+  the ONLY purely synthetic voice and never harmonize with us; doom has no
+  theme of its own -- it corrupts ours. Victory is the green cell allowed
+  to play once, pure.
+- **Pip is a performer.** Deep chanting background -> the math-chant
+  conceit (Greek-letter litanies, Latin machine-liturgy, math-phoneme
+  vocables) has a voice, with a hard respect line: real sutras and personal
+  practice stay out of the game.
+
+## The pipeline surprise: no OBS needed
+
+The plan was OBS system-audio capture. The shipped result is better: a
+Playwright script drives strudel.cc in a muted offscreen browser and records
+the WebAudio graph itself (every connect() to the destination is duplicated
+into a MediaRecorder tap). Captures are digitally clean, and the rig runs
+happily while the machine is being used for a voice call -- nothing leaks in
+either direction. One trap cost a full run: navigating to a strudel URL that
+differs only in the #hash is a same-document navigation, so eleven takes
+silently recorded the same patch. The tell was eleven identical volumedetect
+readings; the fix verifies editor content per take.
+
+Post-processing is exact rather than eyeballed: the WebAudio clock is
+sample-accurate, so a 32-bar loop at 104 bpm is cut to precisely 73.846 s
+from the onset-detected downbeat, the loop tail's reverb spill is baked into
+the loop head with an equal-power crossfade (the file boundary IS the loop
+point, per the drop-in kit), and everything lands at -16 LUFS ogg.
+
+## Where it ended up
+
+`music_manager.gd` now plays composed beds in all five adaptive tier slots
+(C major at 104 souring through C dorian, then D dorian at 96 for the
+endgame), the previously-silent VICTORY slot has "The off switch worked
+(quiet dawn)", DEFEAT has the papers-please trudge Pip loved on first
+listen, and the menu ducks into the "Checkpoint saved" respite cue. The
+engine side (PR #682's AudioStreamInteractive tier crossfades) needed zero
+code changes -- wiring the score was a data edit, as designed.
+
+Still ahead: real stems from real players (COMMISSION_LIST.md -- taiko,
+shakuhachi, upright bass, atarigane, Pip's voice), per-tier BASE/PULSE/
+WEIRD/FIRE layer splits, the trailer long-form, and the metal question:
+when the humans finally go loud, what instrument are they allowed to be?

docs/audio/MUSIC_DESIGN.md

@@ -0,0 +1,140 @@
+# P(Doom)1 -- Music design spec (adaptive doom-band music)
+
+> Music is the AUDIO expression of the existing doom-intensity spec
+> (`docs/art/PALETTE_AND_DOOM_INTENSITY.md`). Same two axes, same five bands, same
+> "cozy competence sliding toward existential dread" arc. This document is the reference
+> for the musicians composing stems and for anyone touching
+> `godot/autoload/music_manager.gd`. Companion docs: `STEM_CATALOGUE.md` (what audio we
+> own today), `TRACK_ANALYSIS.md` (the taste reference method).
+
+## 1. The model in one paragraph
+
+Mick-Gordon / DOOM-style adaptive music: a small set of MUSIC TIERS (moods), each built
+from LAYERED STEMS that add/subtract as doom rises. The game's doom value (0-100) is
+read -- never written -- by the music system, quantized to the canonical doom bands, and
+mapped to a tier. Tier changes crossfade horizontally (mood shift); within a tier, stems
+stack vertically (intensity texture). Players should be able to close their eyes and
+know roughly where the doom meter sits.
+
+## 2. Axes -> music mapping
+
+The art spec defines two independent axes plus combined bands. Each gets a musical
+dimension:
+
+| Axis (art spec) | Visual expression | MUSICAL expression |
+|---|---|---|
+| A. Catastrophe (amber -> red -> fire) | glow sours, strobes, literal fire | RHYTHM: percussive density and drive. Cosy = sparse/ambient pulse; alarmed = insistent percussion; fire = a dedicated "things are on fire" layer (alarm-adjacent textures, driving low end) entering at high tiers only |
+| B. Weirdness (green -> blue -> violet) | clean -> glitchy -> eldritch glow | TIMBRE: clean/tonal instruments -> detuned, bit-crushed, glitch-stuttered -> dissonant clusters, wrong-scale intervals, reversed/smeared textures |
+| Doom bands (0-4) | which register the office renders in | WHICH LAYERS ARE LIVE + overall mood/key territory |
+
+Discipline rule, borrowed from the art spec's lighting rule ("at most ONE ambient +
+ONE weird glow source"): at most ONE rhythmic driver and ONE weird/timbral accent
+prominent at a time. Do not stack every layer at full volume even at terminal doom --
+terminal reads as oppressive SPACE plus the fire layer, not as maximum loudness.
+Purple is expensive; so is dissonance. Reserve overt eldritch harmony for tiers 3-4.
+
+## 3. Music tiers (the five bands, made audible)
+
+The game's canonical thresholds live in `ThemeManager.DOOM_STATUS_BANDS` (7 UI bands).
+Music collapses them onto the art spec's 5 doom-intensity bands:
+
+| Music tier | Name | UI bands (doom %) | Mood target | Rhythm (axis A) | Timbre (axis B) |
+|---|---|---|---|---|---|
+| M0 | cosy | NOMINAL (<15) | warm competence, focus | soft pulse or none | clean, tonal, warm (amber) |
+| M1 | uneasy | ELEVATED + HIGH (15-52) | something is off | pulse gains weight, occasional stumble | faint detune/flicker creeping in |
+| M2 | spooky | SEVERE + EXTREME (52-80) | shadows lengthen | insistent percussion, darker low end | glitch artifacts, blue-arcing synth |
+| M3 | eldritch | CATASTROPHIC (80-92) | it has gone wrong in a wrong way | percussion fractures/polyrhythm | dissonant, wrong-scale, violet |
+| M4 | terminal | TERMINAL (92+) | apocalyptic; the end is audible | FIRE layer in; driving or collapsed | full eldritch smear + alarms |
+
+Numbers come from `ThemeManager` at runtime -- the music system holds NO thresholds of
+its own, only the band->tier table `MUSIC_TIER_BY_BAND = [0,1,1,2,2,3,4]`. If Pip
+retunes the bands, music follows automatically.
+
+## 4. Layer/stem model (what the musicians compose)
+
+Each tier is a STEM GROUP played in sync. Target stems per tier (a tier may omit some):
+
+| Stem slot | Carries | Axis | Notes |
+|---|---|---|---|
+| BASE | harmony/bed, the mood itself | bands | always on within its tier; must loop seamlessly |
+| PULSE | percussion/rhythm | A (catastrophe) | density scales with tier; absent at M0 is fine |
+| WEIRD | timbral accent (detune/glitch/dissonance) | B (weirdness) | the "one weird glow" -- keep it a single identifiable voice |
+| FIRE | the things-are-on-fire topper | A, high end | ONLY M3/M4 (like purple in the palette: expensive) |
+
+Composition constraints so stems can be swapped/stacked mechanically:
+- Every stem in a tier: same tempo, same key (or deliberate fixed relationship), same
+  length or integer multiple, seamless loop, no reverb tails crossing the loop point
+  (bake tails into the loop musically or keep them short).
+- Adjacent tiers should share tempo or have a planned tempo relationship (e.g. M0-M2 at
+  one tempo, M3-M4 at another) so crossfades between tiers do not churn.
+- Deliver as separate files (wav or ogg preferred; mp3 acceptable), loudness roughly
+  matched (about -16 LUFS integrated per stem; final balance happens in-engine).
+- Names stay in the ML/AI-safety pun family (see `STEM_CATALOGUE.md`).
+
+## 5. Runtime architecture (what is built, Godot 4.5.1 native)
+
+No FMOD/Wwise. Two native primitives, already implemented in
+`godot/autoload/music_manager.gd`:
+
+- **Horizontal (tier moods): `AudioStreamInteractive`** -- one clip per tier, named
+  `cosy/uneasy/spooky/eldritch/terminal`, with an any-to-any crossfade transition
+  (8 beats at a nominal 120 BPM = 4 s). Tier changes call
+  `AudioStreamPlaybackInteractive.switch_to_clip()`.
+- **Vertical (stems within a tier): `AudioStreamSynchronized`** -- each clip's stream is
+  a synchronized group of that tier's stems with per-stem volume offsets. Today most
+  tiers hold a single placeholder track; the `terminal` tier already layers two tracks
+  to keep the synchronized path exercised.
+
+Signal flow (read-only, view-layer):
+
+```
+GameManager.game_state_updated(state)          # existing broadcast, emitted per turn
+  -> MusicManager._on_game_state_for_music     # reads state["doom"], nothing else
+    -> ThemeManager.get_doom_band_index(doom)  # canonical band (0..6)
+      -> MUSIC_TIER_BY_BAND[band]              # music tier (0..4)
+        -> switch_to_clip(tier)                # native crossfade if tier changed
+```
+
+### Hard rules (ADR-0006: the replay string is the canonical run artifact)
+- Audio is a PURE view-layer side-effect. `MusicManager` only LISTENS to
+  `game_state_updated`; it never calls into game code, never touches the seeded RNG,
+  the turn loop, replay, or any state that could perturb determinism.
+- Never block or crash on missing audio: a missing stem is skipped, an empty tier
+  inherits its neighbour's stream, a fully-empty build falls back to the legacy
+  playlist, and no music at all is silence, not an error.
+- `randi()` use for playlist shuffle is the GLOBAL RNG, not the seeded game RNG --
+  keep it that way; never "fix" music shuffle by borrowing the game's RNG.
+
+## 6. Transition rules
+
+Current prototype: single any-to-any rule -- switch immediately, crossfade over 8 beats
+(4 s), restart target clip from its start. Deliberately simple; placeholder tracks share
+no tempo grid, so beat-aligned transitions would be false precision.
+
+Target rules once composed stems exist (all native `AudioStreamInteractive` features):
+- UP-tier (doom rose): transition at NEXT BEAT, short crossfade (1-2 bars). Rising dread
+  should feel prompt -- the ratchet.
+- DOWN-tier (doom fell -- rare, earned): transition at NEXT BAR or phrase end, long lazy
+  crossfade. Relief arrives slower than fear.
+- M3 -> M4 (terminal): consider a FILLER CLIP sting (a one-shot "it is happening"
+  hit) via the native filler-clip transition option.
+- Hysteresis: band quantization already gives dead zones; if doom oscillates across one
+  boundary each turn and audibly churns, add a 1-turn dwell before down-transitions
+  (do NOT add one for up-transitions; the ratchet must feel immediate).
+
+## 7. Where composed tracks slot in
+
+One place: `MUSIC_TIER_STEMS` in `godot/autoload/music_manager.gd` -- an array of five
+stem lists, `{"path": ..., "volume_db": ...}` per stem. Replacing a placeholder track
+with real per-tier stems is a data edit, no logic change. Contexts outside GAMEPLAY
+(menu / victory / defeat) stay on the existing `music_library` playlists; a future
+victory track and a composed defeat sting slot in there.
+
+Menu music stays NON-adaptive on purpose: the menu has no doom.
+
+## 8. Out of scope / anti-goals
+
+- No AI-generated finished music (rights are murky; Pip values owning rights).
+- No per-action stingers wired to game logic (would tempt writes into the turn loop;
+  any future stinger hooks must also be listen-only).
+- No rewrite of the audio bus layout; the Music bus (index 2) is the only one touched.