TURNCRAFT/src/audio/HANDOFF.md

Lane E — HANDOFF (Audio / FX / UI)

Lane E owns src/audio/**, src/fx/**, src/ui/**, src/demo/audioDemo.ts, demo-audio.html. This is the primary handoff; see also src/fx/HANDOFF.md and src/ui/HANDOFF.md. Everything is done and typechecks clean; the demo runs with zero console errors and previews the full audio-visual arc.

Public API surface (what the integrator constructs)

const audio = new AudioEngine();                 // self-wires to the bus
await audio.init();                              // MUST be a user gesture (autoplay)
audio.updateListener(playerView);                // call per frame
audio.getLevels();                               // { low, mid, high } for FX VU
// also: setStemCount, setChannelGain, setPitch, setPlaybackState, playSfx

const fx = new FxSystem({ scene, setEmissiveBoost, getLevels: () => audio.getLevels() });
fx.update(dt);                                    // call each fixed tick

const hud = new Hud({ onStart, onResume, getHotbar }); // onStart(once)=>audio.init()+lock; onResume=>re-lock only

What's done

• Groove (groove.ts + synth.ts + scheduler.ts): fully synthesized 118 BPM, 8-bar F-minor deep-house loop in 5 stems (drums/bass/chords/lead/ sweeps), scheduled on a drift-free lookahead transport (25 ms tick, notes on AudioContext.currentTime). setStemCount(0..5) stacks them musically; muted stems cost nothing (scheduling is gated). Sidechain-ducked bass.
• Spin-up/brake: setPlaybackState(deck, playing, rpm) eases a rate that scales tempo AND per-voice detune together (rpm/rpm33; 45 = +35% & sharper). setPitch(±1) detunes ±2 semitones. Braked to a stop = silence.
• Positional: mix outputs into two PannerNodes at the deck spindles (LAYOUT), plus an always-on low-passed dry bass bed. updateListener follows the player eye/orientation.
• Beat/bar events: audio:beat {energy} (energy = kick gain) and audio:bar are emitted from the scheduler at the audible time (queued and drained on the ctx clock), so LED pulses stay in sync.
• SFX (sfx.ts): footsteps per surface category, land (impact-scaled), break/place, fader zip, button clunk, RCA "clunk-clunk-CLICK", fuse zap, tonearm cue creak, needle drop. Positional when a world at is given.
• Win audio timeline: on game:win, ducks to silence, then at +1.8 s snaps the platters to speed, drops the needle, and slams the full mix in behind a lowpass that sweeps open — all scheduled on the ctx clock (no timers).
• FX & HUD: see the two sibling HANDOFF files.

Contract friction / assumptions the integrator should confirm

1. fader:move mapping: I map faderId containing pitch → pitch bend, else the first digit N → stem channel N-1. If Lane D uses other faderIds (crossfader, named channels), confirm/extend the map in AudioEngine.wireBus().
2. Channel↔stem mapping: 5 stems vs the mixer's 4 channels + crossfader. setChannelGain(ch, v) treats ch as a stem index 0..4. Reconcile with Lane D's channel model if needed.
3. player:landed has no surface category (and player:step no position); I use the last stepped surface and play footsteps listener-centered. Fine unless you want spatialized steps.
4. setEmissiveBoost semantics: I drive it as an absolute intensity — dead-booth base 0.35, stepping toward 1.0 over the 5 repairs, pulsing to ~1.8 on beats. If Lane A's hook is a multiplier with a different baseline, tune the constants in FxSystem (boostBase, pulseTau).
5. VU tower positions are derived from LAYOUT.mixer (no explicit VU coords in constants). If Lane C placed physical LED-block towers elsewhere, align src/fx/layout.ts VU_TOWERS to them.
6. Hotbar model: no core type exists, so Hud defines HotbarModel/ HotbarSlot and reads it via an injected getHotbar(). Adapt Lane D's hotbar to this shape (or wrap it).
7. game:win forces deck playback in audio. Ensure Lane D also spins the real platters visually at the finale so audio and visuals agree.

Nothing in src/core/ was edited. No setBlock anywhere in Lane E. No rAF loop outside src/demo/. npm run typecheck is clean.

---

Round 2 — Headshell Workshop (Lane E slice)

The workshop machine (Lane D, src/machines/workshop/) is fully decoupled from Lane E via the bus — Lane D emits, Lane E sounds/shows. No direct calls, no shared imports. What Lane E added (all additive):

• src/audio/testSignal.ts — playTestSignal(errors) renders the stage-5 needle-drop diagnostic in true stereo (ChannelMerger), one audible chain per fault: swapLR (hard L/R ping-pong), phaseCancel (channel invert → thin), azimuthTilt (one channel −12 dB + waveshaper), trackingLight (80 ms gate stutter), trackingHeavy (1.2 kHz lowpass), skate (abort zip). errorsFromKeys(string[]) adapts the event payload. Error vocabulary matches Lane D's machines/workshop/types.ts exactly (incl. skate).
• src/audio/sfx.ts — 9 workshop one-shots: crimp, wireOn, wireOff, screwTick, screwClunk, tiltCreak, weightDetent, bubbleLock, skate.
• AudioEngine self-wires these bus reactions:
  • workshop:test {errors, clean} → playTestSignal(errorsFromKeys(errors)).
  • workshop:torque {value} → throttled screwTick ratchet (value null = no-op).
  • machine:interact {action} → workshop action keywords (crimp/wire/screw/tilt/detent/weight/bubble/skate/seat) → the matching one-shot. Public playTestSignal(errors) also exists for direct use.

Integration contract (for Fable / Lane D):

• trackingHeavy — Lane E does the lowpass; Lane D should also sag the platter target rpm ~15% (platter.ts) for the full "drag" effect.
• The scope block is Lane D's (its own drawScopeCanvas); Lane E renders no scope (my earlier src/fx/scope.ts was removed to avoid duplication).
• Screw confetti + torque gauge + diagnostic subtitle: see fx/ui HANDOFFs.

Verified live (demo-audio.html → "Headshell Workshop" panel): every error mode plays without clipping, the subtitle names the fault, the radial torque gauge tracks + hides, screw confetti fires, all 9 SFX distinct. Zero console errors; npm run typecheck clean across the whole tree (with Lane D's Workshop.ts present).