Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

30.1 KB
Raw Blame
// Drum-kit playback for the SongBook `drum` format — turns a parsed drum chart
// (see drumNotation.js) into an audible groove you can practice along with at a
// tempo you control. The third consumer of the shared lookahead transport
// (`lookaheadTransport.js`), alongside `createScorePlayer` and `createMidiPlayer`:
// the clock, node lifecycle and teardown semantics are all the shared ones, so
// this module only owns the schedule math and the kit voices.
//
// The kit is SYNTHESIZED — no sampled kit ships with PortOS (repo size + sample
// licensing). The voice recipes live in `drumKits.js` (TR-909 / TR-808 /
// Acoustic, selectable); this module owns the schedule math and the Web Audio
// realization of whichever kit is selected.
//
// `buildDrumSchedule` is PURE (no Web Audio) so the timing math — bpm, time
// signature, subdivision, count-in, loop expansion, per-glyph velocity — is
// unit-testable in a node env, mirroring `buildSchedule` in scorePlayback.js.

import { getAudioContext as ctx, getNoiseBuffer } from './audioContext.js';
import { createLookaheadTransport, SYNTH_TIMING } from './lookaheadTransport.js';
import { makeSafeCall } from './scorePlayback.js';
import { kitPiece, DEFAULT_DRUM_TEMPO } from './drumNotation.js';
import { CLICK_VOICE, kitVoiceLayers, resolveDrumKit } from './drumKits.js';

const { SCHEDULE_AHEAD } = SYNTH_TIMING;
const safeCall = makeSafeCall('drum playback');

// The `sound` name a count-in event carries. It is NOT a kit piece — it sounds
// through `CLICK_VOICE` on the click bus, so a count-in is the same blip as the
// through-music click and follows the same volume. ONE predicate decides both
// the voice and the bus: two (say, `sound` for the voice and `countIn` for the
// bus) would let a future click event get the right blip on the wrong bus, and
// silently stop following the volume control.
const CLICK_SOUND = 'click';
const isClickEvent = (ev) => ev.sound === CLICK_SOUND;

// Metronome-click level, 0 (silent) – 1 (full). Full is the historical level, so
// an install that never touches the new control hears exactly what it did.
export const DEFAULT_CLICK_VOLUME = 1;

// Clamp a click level into 0–1. Returns null for a missing/unparseable value so
// a caller can tell "never set" from a legitimately-clamped 0 (the same
// sentinel contract as `clampBpm`) — `Number('')` is 0, i.e. silence, and must
// not be able to masquerade as a chosen level.
export const clampClickVolume = (value) => {
  if (value == null || value === '') return null;
  const n = Number(value);
  if (!Number.isFinite(n)) return null;
  return Math.min(1, Math.max(0, n));
};

// --- Schedule building (pure) ----------------------------------------------

// Clamp a loop range against the chart's real bar count. Returns null when the
// chart is empty or looping is off, so callers can branch on a single value
// instead of juggling three flags. `from`/`to` are 1-based inclusive bar numbers;
// a reversed pair is normalized rather than rejected (the UI's two selects can
// legitimately cross while the user is picking).
export const resolveLoopRange = (barCount, loop) => {
  if (!loop || !barCount) return null;
  const rawFrom = Number.isFinite(loop.from) ? Math.trunc(loop.from) : 1;
  const rawTo = Number.isFinite(loop.to) ? Math.trunc(loop.to) : barCount;
  const from = Math.min(Math.max(1, Math.min(rawFrom, rawTo)), barCount);
  const to = Math.min(Math.max(from, Math.max(rawFrom, rawTo)), barCount);
  return { from, to };
};

/**
 * Flatten a parsed drum chart into absolute-time hit events.
 *
 * Timing mirrors `scorePlayback.buildSchedule`: the tempo counts beats where one
 * beat is the time-signature denominator, so 4/4 reads as quarter=bpm and 6/8 as
 * eighth=bpm. One grid step is one beat / `subdivision`.
 *
 * @param {object} chart — output of `parseDrumChart`.
 * @param {object} [options]
 * @param {number} [options.bpm] — practice tempo (else the chart's `tempo`, else 90).
 * @param {{from:number,to:number}} [options.loop] — 1-based inclusive bar range;
 *   the schedule covers ONLY those bars (the transport loops by replaying it).
 * @param {number} [options.countInBars] — silent-lead bars of click before bar 1.
 * @returns {{ events, bpm, stepSec, barSec, totalSec, countInSec, bars, loop }}
 */
export const buildDrumSchedule = (chart, options = {}) => {
  const beats = chart?.time?.beats || 4;
  const subdivision = chart?.subdivision || 4;
  const bpm = Number.isFinite(options.bpm) && options.bpm > 0
    ? options.bpm
    : (Number.isFinite(chart?.tempo) && chart.tempo > 0 ? chart.tempo : DEFAULT_DRUM_TEMPO);

  // The tempo counts NOTATED beats (the time-signature denominator), so one beat
  // is simply 60/bpm — 4/4 reads as quarter=bpm and 6/8 as eighth=bpm, the
  // conventional interpretation and the same one scorePlayback.buildSchedule
  // arrives at via its quarter-note durations. One grid step is a beat split
  // `subdivision` ways.
  const beatSec = 60 / bpm;
  const stepSec = beatSec / subdivision;
  const barSec = beatSec * beats;

  const allBars = Array.isArray(chart?.bars) ? chart.bars : [];
  const loop = resolveLoopRange(allBars.length, options.loop);
  const bars = loop ? allBars.slice(loop.from - 1, loop.to) : allBars;

  const countInBars = Math.max(0, Math.min(4, Math.trunc(options.countInBars) || 0));
  const countInSec = countInBars * barSec;

  const events = [];
  // Count-in: one click per notated beat, the downbeat accented. Scheduled as
  // real events (not a second clock) so the transport sounds them through the
  // same voice path, and `countIn: true` + a null bar/step lets the UI tell
  // "counting in" from "bar 1".
  for (let bar = 0; bar < countInBars; bar += 1) {
    for (let beat = 0; beat < beats; beat += 1) {
      events.push({
        bar: null,
        step: null,
        beat: beat + 1,
        piece: null,
        sound: CLICK_SOUND,
        velocity: beat === 0 ? 1 : 0.6,
        countIn: true,
        startSec: (bar * beats + beat) * beatSec,
        durSec: Math.min(0.08, stepSec),
      });
    }
  }

  bars.forEach((bar, barIdx) => {
    const barStart = countInSec + barIdx * barSec;
    for (const row of bar.rows || []) {
      const piece = kitPiece(row.piece);
      row.cells.forEach((cell, step) => {
        if (!cell || cell.rest) return;
        events.push({
          // The chart's own bar number (survives a loop-range slice, so the
          // playhead lights the right bar on the full sheet).
          bar: bar.index,
          step,
          piece: row.piece,
          sound: piece?.sound || 'snare',
          velocity: cell.velocity,
          open: !!cell.open,
          accent: !!cell.accent,
          ghost: !!cell.ghost,
          flam: !!cell.flam,
          countIn: false,
          startSec: barStart + step * stepSec,
          durSec: stepSec,
        });
      });
    }
  });

  events.sort((a, b) => a.startSec - b.startSec);
  return {
    events,
    bpm,
    stepSec,
    barSec,
    beatSec,
    countInSec,
    bars,
    loop,
    totalSec: countInSec + bars.length * barSec,
  };
};

/**
 * A built schedule + a live clock position → where the playhead sits, as a
 * CONTINUOUS grid coordinate (pure; no Web Audio).
 *
 * THIS is the playhead the UI reads. The `onStep` callback reports the last
 * event that SOUNDED, which is enough to light a column but not to place a
 * position: it stalls across rests and never moves at all through a bar with no
 * hits. Anything that has to keep moving with the music — the sheet's line, the
 * transport's pulse — converts the audio clock here instead.
 *
 * Returns `null` when there's nothing to place. Otherwise:
 * - during the count-in (and the negative pre-roll lead) —
 *   `{ countIn: true, beat }`, the 1-based beat WITHIN the count-in bar;
 * - during the music — `{ countIn: false, bar, stepFloat }`, where `bar` is the
 *   chart's own 1-based bar number (so a loop range still points at the right
 *   bar of the full sheet) and `stepFloat` is a fractional grid step into it.
 *
 * @param {object} schedule — `buildDrumSchedule` output.
 * @param {number} posSec — transport position in piece-seconds (may be negative).
 */
export const resolvePlayhead = (schedule, posSec) => {
  const bars = Array.isArray(schedule?.bars) ? schedule.bars : [];
  const { barSec, stepSec, beatSec, countInSec = 0 } = schedule || {};
  if (!bars.length || !(barSec > 0) || !(stepSec > 0)) return null;
  const pos = Number.isFinite(posSec) ? posSec : 0;

  if (pos < countInSec) {
    const beatsPerBar = beatSec > 0 ? Math.max(1, Math.round(barSec / beatSec)) : 1;
    // The lead-in before t=0 is negative — clamp it to the first beat rather
    // than counting backwards past the start of the count-in.
    const elapsedBeats = Math.floor(Math.max(0, pos) / (beatSec || barSec));
    return { countIn: true, beat: (elapsedBeats % beatsPerBar) + 1 };
  }

  const musicSec = bars.length * barSec;
  let elapsed = pos - countInSec;
  // A looping player runs past the end of its schedule forever, replaying the
  // selected range — fold the position back onto one pass.
  if (schedule.loop && musicSec > 0) elapsed = ((elapsed % musicSec) + musicSec) % musicSec;
  elapsed = Math.min(Math.max(0, elapsed), Math.max(0, musicSec - 1e-6));

  const barIdx = Math.min(bars.length - 1, Math.floor(elapsed / barSec));
  return {
    countIn: false,
    bar: bars[barIdx].index,
    stepFloat: (elapsed - barIdx * barSec) / stepSec,
  };
};

// --- Kit voices -------------------------------------------------------------

// The RECIPES live in drumKits.js (three selectable kits); this section is the
// Web Audio realization of them — one node graph per layer, plus the master bus.

const VOICE_PEAK = 0.42; // per-layer gain ceiling before the per-cell velocity scale
// Headroom into the master soft-clipper: a busy bar stacks a kick, a snare, a hat
// and a click at once, so the sum is deliberately kept under unity and the
// clipper only rounds the peaks that still get through.
const MASTER_GAIN = 0.9;

const CURVE_SAMPLES = 1024;
const buildCurve = (shape) => Float32Array.from(
  { length: CURVE_SAMPLES },
  (_, i) => shape((i * 2) / (CURVE_SAMPLES - 1) - 1),
);

// MASTER soft-clipper: plain tanh, so it is unity-gain for quiet material and
// only rounds off the peaks when several loud voices land on the same downbeat.
// Cheaper and steadier than a compressor for a fixed-level drum bus. NOT the
// same curve as a drive of 1 — this one is deliberately un-normalized, and
// normalizing it would push ~2.4 dB of makeup gain into the clipper.
const CLIP_CURVE = buildCurve(Math.tanh);

// Per-LAYER saturation curve, cached per drive amount (a handful of compiled-in
// values). Normalized so the layer keeps its PEAK level and only gains harmonics
// — that harmonic series is what makes a sub-50Hz kick audible on a phone or
// laptop speaker, which has no driver for the fundamental at all (see the
// drumKits.js header).
const driveCurves = new Map();
const driveCurve = (amount) => {
  const cached = driveCurves.get(amount);
  if (cached) return cached;
  const norm = Math.tanh(amount);
  const curve = buildCurve((x) => Math.tanh(amount * x) / norm);
  driveCurves.set(amount, curve);
  return curve;
};

// Flam grace-note lead: the ghost hit lands this far BEFORE the main hit.
const FLAM_LEAD_SEC = 0.032;
// Envelope attack. An instant jump to full scale pops on some speakers, so every
// voice ramps in over this — short enough to stay percussive.
const ATTACK_SEC = 0.0015;
// Pitch-envelope fallback for a recipe that sets `to` without a `pitchDecay`.
// Deliberately NOT the amplitude decay: coupling the two is the weak-kick recipe
// this engine replaced, and a fourth kit must not be able to resurrect it by
// omitting a field.
const PITCH_SNAP_SEC = 0.04;

/**
 * Schedule ONE layer of a voice (see the layer shape in drumKits.js); returns an
 * array of `{ osc, gain }` for the transport's teardown tracking — one per
 * source, so a `metal` cluster's partials are each stoppable (an
 * AudioBufferSourceNode satisfies the same start/stop/onended surface an
 * OscillatorNode does).
 *
 * The pitch envelope runs on `pitchDecay`, NOT on the amplitude `decay` — a
 * drum-machine membrane snaps down to its fundamental in tens of milliseconds
 * and then holds there while the amplitude tail runs on for half a second. The
 * two being the same number is exactly what made the old kick sound weak.
 */
const scheduleLayer = (c, layer, startAt, destination, { velocity, open }) => {
  const gain = c.createGain();
  const decay = Math.max(0.005, (open && layer.openDecay) || layer.decay || 0.1);
  const stopAt = startAt + ATTACK_SEC + decay + 0.02;

  // Build the source(s). A `metal` layer is N square oscillators summed into the
  // ONE filter/envelope below — a biquad is linear, so filtering the sum is
  // identical to summing filtered partials, at a third of the nodes per hit.
  const partials = layer.kind === 'metal' ? layer.partials : [null];
  const sources = partials.map((hz) => {
    if (layer.kind === 'noise') {
      const src = c.createBufferSource();
      src.buffer = getNoiseBuffer(c);
      src.loop = true;
      return src;
    }
    const osc = c.createOscillator();
    osc.type = layer.kind === 'metal' ? 'square' : (layer.wave || 'sine');
    osc.frequency.setValueAtTime(hz ?? layer.from, startAt);
    if (layer.kind !== 'metal' && layer.to > 0 && layer.to !== layer.from) {
      osc.frequency.exponentialRampToValueAtTime(
        layer.to,
        startAt + Math.max(0.004, layer.pitchDecay ?? PITCH_SNAP_SEC),
      );
    }
    return osc;
  });

  // source(s) → [drive] → [filter] → gain → bus. The shaper sits BEFORE the gain
  // so the timbre is the same at every velocity (a drive that only bit on accents
  // would make the kit change character as you play softer).
  let head = null;   // the node the sources feed; null until one is created
  let tail = null;   // the last node before the gain
  const append = (node) => {
    if (!head) head = node;
    else tail.connect(node);
    tail = node;
  };
  if (layer.drive > 0) {
    const shaper = c.createWaveShaper();
    shaper.curve = driveCurve(layer.drive);
    shaper.oversample = '2x';
    append(shaper);
  }
  if (layer.filter) {
    const filter = c.createBiquadFilter();
    filter.type = layer.filter.type;
    filter.frequency.setValueAtTime(layer.filter.freq, startAt);
    filter.Q.value = layer.filter.q ?? 1;
    append(filter);
  }
  if (tail) tail.connect(gain);
  for (const src of sources) src.connect(head || gain);
  gain.connect(destination);

  // Percussive envelope: a sub-millisecond attack ramp into an exponential decay
  // to silence. A cluster's `gain` is the level of the WHOLE voice, so it splits
  // across the partials — that keeps a six-oscillator hat comparable to a
  // one-source noise hat instead of six times louder.
  const peak = Math.max(0.0002, (VOICE_PEAK * (layer.gain ?? 1) * velocity) / sources.length);
  gain.gain.setValueAtTime(0.0001, startAt);
  gain.gain.exponentialRampToValueAtTime(peak, startAt + ATTACK_SEC);
  gain.gain.exponentialRampToValueAtTime(0.0001, stopAt - 0.02);

  // One transport entry PER source, all sharing the single gain node: teardown
  // only ever touches `entry.osc`, and a cluster whose partials weren't each
  // tracked would keep ringing after stop() (up to 1.2s for the 808 crash).
  return sources.map((src) => {
    src.start(startAt);
    src.stop(stopAt);
    return { osc: src, gain };
  });
};

// Sound every layer of a voice at one time, scaled by a velocity multiplier.
const soundLayers = (c, layers, at, destination, track, { velocity, open }) => {
  for (const layer of layers) {
    for (const entry of scheduleLayer(c, layer, at, destination, { velocity, open })) track(entry);
  }
};

// Sound one chart event — the hit, plus a flam grace note when the glyph calls
// for one. Every created node pair goes through `track` so the transport tears
// all of them down on stop.
//
// A count-in event is the metronome, not a kit piece: it sounds through
// `CLICK_VOICE`. Left to `kitVoiceLayers` it would fall through to the kit's
// SNARE (the "unmapped piece stays audible" fallback), which is why a count-in
// used to be four snare hits instead of four clicks.
const soundEvent = (c, kit, ev, at, destination, track) => {
  const layers = isClickEvent(ev) ? CLICK_VOICE : kitVoiceLayers(kit, ev.sound);
  if (ev.flam) {
    soundLayers(c, layers, Math.max(at - FLAM_LEAD_SEC, 0), destination, track, {
      velocity: ev.velocity * 0.45, open: ev.open,
    });
  }
  soundLayers(c, layers, at, destination, track, { velocity: ev.velocity, open: ev.open });
};

// --- Player -----------------------------------------------------------------

/**
 * Build a drum-kit player over a parsed chart.
 *
 * @param {object} chart — output of `parseDrumChart`.
 * @param {object} [options]
 * @param {number} [options.bpm] — practice tempo (else the chart's `tempo:`).
 * @param {number} [options.countInBars] — click-only lead-in bars.
 * @param {{from:number,to:number}|null} [options.loopBars] — 1-based inclusive
 *   bar range; when set, playback repeats that range until stopped.
 * @param {boolean} [options.clickEnabled] — layer a metronome click on every
 *   notated beat, on the same clock as the kit.
 * @param {number} [options.clickVolume] — click/count-in level, 0–1 (default 1).
 * @param {string} [options.kit] — kit id from `drumKits.js` (`909` / `808` /
 *   `acoustic`); an unknown id falls back to the default rather than to silence.
 * @param {({bar:number|null, step:number|null, countIn:boolean})=>void} [options.onStep]
 *   — the now-sounding grid position (null when playback ends/stops), for the
 *   sheet playhead.
 * @param {()=>void} [options.onEnded] — fired once when a non-looping chart ends.
 * @returns {{ play, pause, stop, isPlaying, setBpm, setLoop, setClick, setClickVolume, setKit, schedule }}
 */
export const createDrumPlayer = (chart, options = {}) => {
  const { onStep, onEnded } = options;
  let bpm = Number.isFinite(options.bpm) && options.bpm > 0 ? options.bpm : null;
  let loopBars = options.loopBars || null;
  let clickEnabled = !!options.clickEnabled;
  let clickVolume = clampClickVolume(options.clickVolume) ?? DEFAULT_CLICK_VOLUME;
  let countInBars = options.countInBars || 0;
  // The kit only affects which voices SOUND, never the schedule — so unlike the
  // timing settings it can change mid-play (the next scheduled hit picks it up).
  let kit = resolveDrumKit(options.kit);

  const build = () => buildDrumSchedule(chart, { bpm, loop: loopBars, countInBars });
  let schedule = build();
  let master = null;
  let masterOut = null;
  // The metronome gets its OWN sub-bus into the drum master. A per-hit velocity
  // scale would only reach clicks scheduled AFTER the change, so a slider drag
  // wouldn't be heard until the lookahead window had drained; a bus moves
  // everything already queued too, which is what makes the control feel live.
  let clickBus = null;

  // Click track for the CURRENT schedule: one marker per notated beat of the
  // music (the count-in carries its own clicks as real events). Derived rather
  // than baked into the schedule, so toggling the click mid-play needs no rebuild.
  const clickTimes = () => {
    const out = [];
    const beats = chart?.time?.beats || 4;
    for (let bar = 0; bar < schedule.bars.length; bar += 1) {
      for (let beat = 0; beat < beats; beat += 1) {
        out.push({
          startSec: schedule.countInSec + bar * schedule.barSec + beat * schedule.beatSec,
          accent: beat === 0,
        });
      }
    }
    return out;
  };
  let clicks = clickTimes();

  // Index of the first music (non-count-in) event. Events are sorted by onset and
  // every count-in event precedes the music, so this is where loop pass 2+ starts
  // — a looped range must not re-count-you-in every time around.
  const firstMusicIdx = () => {
    const i = schedule.events.findIndex((ev) => !ev.countIn);
    return i < 0 ? schedule.events.length : i;
  };
  // Length of one LOOP pass: the music only, since the count-in belongs to pass 0.
  const musicSec = () => schedule.totalSec - schedule.countInSec;
  // A loop pass must have BOTH real duration AND at least one music event to
  // advance past. A rest-only selected bar has duration but no events, so
  // `firstMusicIdx()` would return the exhausted end index and the rebase branch
  // would spin forever (a wedged tab, not just silence) — that's the case this
  // event check exists for, distinct from the duration check.
  const canLoop = () => !!schedule.loop
    && musicSec() > 0
    && schedule.events.some((ev) => !ev.countIn);

  // A cursor walks one list (events or clicks) forward through loop passes. Each
  // walker keeps its OWN `pass` because they advance at different rates: the
  // scheduler runs a lookahead window AHEAD of the audio clock while the playhead
  // trails BEHIND it, so a shared pass counter would drag the trailing walker
  // across a loop boundary early and collapse the loop to one pass.
  //
  // A pass-N onset sits at `pass * musicSec + ev.startSec` — pass 0 covers the
  // count-in plus the music, and pass ≥ 1 starts at `firstMusicIdx`, so the first
  // music event of pass 1 lands exactly at the end of pass 0.
  const makeCursor = () => ({ idx: 0, pass: 0 });
  const cursorTime = (cursor, startSec) => startSec + cursor.pass * musicSec();
  // Advance a cursor onto the next pass, or return false when it must stop.
  const advancePass = (cursor, from) => {
    if (!canLoop()) return false;
    cursor.pass += 1;
    cursor.idx = from;
    return true;
  };

  let hitCursor = makeCursor();     // schedules audio (runs ahead)
  let clickCursor = makeCursor();   // schedules the click layer (runs ahead)
  let headCursor = makeCursor();    // drives the playhead (trails)
  let lastHeadKey = null;
  const resetCursor = () => {
    hitCursor = makeCursor();
    clickCursor = makeCursor();
    headCursor = makeCursor();
    lastHeadKey = null;
  };

  const notify = (info) => safeCall(onStep, info);

  const scheduleWindow = (now, startTime, track) => {
    if (!master) return;
    const c = ctx();
    const horizon = now + SCHEDULE_AHEAD;

    // Hand every due hit to the audio clock; on exhausting the list a looping
    // player rebases onto the next pass and keeps going, while a one-shot player
    // stops scheduling and lets the transport's own end check finish it.
    for (;;) {
      if (hitCursor.idx >= schedule.events.length) {
        if (!advancePass(hitCursor, firstMusicIdx())) break;
        continue;
      }
      const ev = schedule.events[hitCursor.idx];
      const at = startTime + cursorTime(hitCursor, ev.startSec);
      if (at >= horizon) break;
      hitCursor.idx += 1;
      if (at < now - 0.05) continue; // already past (first tick after a stall)
      // Count-in beats are metronome, not kit — they ride the click bus so the
      // volume control governs them too. They are deliberately NOT gated on
      // `clickEnabled`: "click off, count-in on" is the "just count me in" mode.
      soundEvent(c, kit, ev, Math.max(at, now), isClickEvent(ev) ? clickBus : master, track);
    }

    // The click layer walks its own list on the same pass geometry. Its pass ≥ 1
    // restart index is 0: every click belongs to the music (the count-in's clicks
    // are real events on the hit list), so a loop pass replays all of them.
    if (clickEnabled) {
      for (;;) {
        if (clickCursor.idx >= clicks.length) {
          if (!advancePass(clickCursor, 0)) break;
          continue;
        }
        const click = clicks[clickCursor.idx];
        const at = startTime + cursorTime(clickCursor, click.startSec);
        if (at >= horizon) break;
        clickCursor.idx += 1;
        if (at < now - 0.05) continue;
        // A level of 0 is silence, and it PERSISTS — dragging the slider down is
        // the obvious way to shut the click up, so without this a practice loop
        // would build a voice per beat forever to sound nothing. The gate sits
        // after the cursor advance (skipping the loop wholesale would leave the
        // cursor behind and dump a backlog on the tick after you turn it back
        // up); the cost is that raising the level mid-window loses at most one
        // lookahead of clicks.
        if (clickVolume <= 0) continue;
        soundLayers(c, CLICK_VOICE, Math.max(at, now), clickBus, track, {
          velocity: click.accent ? 1 : 0.55, open: false,
        });
      }
    }

    // Playhead: report the LATEST position whose onset has already passed. Keyed
    // by bar+step so a bar's simultaneous hits fire one callback, not one per
    // piece — and the key includes the pass, so a looped single bar re-lights.
    //
    // Event-driven, so it stands still through a rest — a caller that needs a
    // position rather than "the last thing that sounded" reads the clock via
    // `position()` + `resolvePlayhead` and passes no `onStep` at all, which
    // skips this walk entirely.
    if (!onStep) return;
    let latest = null;
    for (;;) {
      if (headCursor.idx >= schedule.events.length) {
        if (!advancePass(headCursor, firstMusicIdx())) break;
        continue;
      }
      const ev = schedule.events[headCursor.idx];
      if (startTime + cursorTime(headCursor, ev.startSec) > now) break;
      latest = ev;
      headCursor.idx += 1;
    }
    if (latest) {
      const key = `${headCursor.pass}:${latest.countIn ? 'c' : 'm'}:${latest.bar}:${latest.step}`;
      if (key !== lastHeadKey) {
        lastHeadKey = key;
        notify({ bar: latest.bar, step: latest.step, countIn: latest.countIn });
      }
    }
  };

  const transport = createLookaheadTransport({
    // A play-along is output-only — there is no capture anywhere on the SongBook
    // — so it holds the iOS `playback` session while it sounds. Without it iOS
    // leaves the page on the ambient session and the hardware ring/silent switch
    // mutes the whole kit AND the metronome: the transport counts, the playhead
    // scrolls, and the phone makes no sound. The transport releases it on
    // teardown, so the declaration can't follow the user to a page that records.
    audioSession: 'playback',
    // A LOOPING player never "ends" on its own, so the transport's end check must
    // not finish it — unbounded until stop(). But `canLoop()` is the same gate the
    // scheduler uses: when a selected range holds no music (a rest-only bar) there
    // is nothing to repeat, so the run must be allowed to finish at its natural
    // length instead of sitting "playing" forever after the count-in.
    getTotalSec: () => (canLoop() ? Infinity : schedule.totalSec),
    scheduleWindow,
    prepare: () => {
      schedule = build();
      if (!schedule.events.length || schedule.totalSec <= 0) { safeCall(onEnded); return false; }
      clicks = clickTimes();
      resetCursor();
      const c = ctx();
      // Drum bus: every voice sums here, then through a soft-clipper so a
      // downbeat stacking kick + crash + click rounds off instead of clipping.
      master = c.createGain();
      master.gain.value = MASTER_GAIN;
      masterOut = c.createWaveShaper();
      masterOut.curve = CLIP_CURVE;
      masterOut.oversample = '2x';
      master.connect(masterOut);
      masterOut.connect(c.destination);
      clickBus = c.createGain();
      clickBus.gain.value = clickVolume;
      clickBus.connect(master);
      return true;
    },
    seekCursors: (offsetSec) => {
      // The sheet has no scrub UI, so in practice this only ever runs with 0
      // (fresh play, and stop/finish resetting to the top). A resume offset
      // (transport.pause → play) positions every cursor past what already sounded.
      resetCursor();
      if (offsetSec <= 0) return;
      const skip = (cursor, list, key) => {
        while (cursor.idx < list.length && list[cursor.idx][key] < offsetSec) cursor.idx += 1;
      };
      skip(hitCursor, schedule.events, 'startSec');
      skip(headCursor, schedule.events, 'startSec');
      skip(clickCursor, clicks, 'startSec');
    },
    onStop: () => { notify(null); },
    onEnded: () => { safeCall(onEnded); },
    onTeardown: () => {
      // Outside the request lifecycle — a disconnect on an already-torn-down
      // node must not throw into the transport's teardown path.
      for (const node of [clickBus, master, masterOut]) {
        if (!node) continue;
        try { node.disconnect(); } catch { /* already gone */ }
      }
      clickBus = null;
      master = null;
      masterOut = null;
    },
  });

  // A live setting change rebuilds the schedule while idle; while playing, the
  // caller restarts (a mid-groove tempo jump would desync the playhead against
  // already-scheduled audio).
  const rebuildIfIdle = () => {
    if (transport.isPlaying()) return;
    schedule = build();
    clicks = clickTimes();
    resetCursor();
  };

  return {
    play: transport.play,
    pause: transport.pause,
    stop: transport.stop,
    isPlaying: transport.isPlaying,
    // Live audio-clock position in piece-seconds. The `onStep` callback only
    // fires on EVENTS (so it stalls across a rest and skips a silent bar
    // entirely) — a continuously-scrolling sheet needs the clock itself, read
    // per animation frame rather than pushed through React state.
    position: transport.position,
    setBpm: (next) => {
      bpm = Number.isFinite(next) && next > 0 ? next : null;
      rebuildIfIdle();
    },
    setLoop: (next) => { loopBars = next || null; rebuildIfIdle(); },
    setCountIn: (bars) => {
      countInBars = Math.max(0, Math.trunc(Number(bars)) || 0);
      rebuildIfIdle();
    },
    setClick: (enabled) => { clickEnabled = !!enabled; },
    // Level of the click layer AND the count-in, live (see the `clickBus`
    // declaration for why it's a bus). `setTargetAtTime` rather than a step
    // assignment so a drag across a ringing blip doesn't pop.
    setClickVolume: (level) => {
      const next = clampClickVolume(level);
      if (next == null) return;
      clickVolume = next;
      if (clickBus) clickBus.gain.setTargetAtTime(next, ctx().currentTime, 0.01);
    },
    // Kit changes touch no timing, so — like the click toggle — they apply live:
    // whatever is already in the lookahead window finishes on the old kit and
    // everything scheduled after this lands on the new one.
    setKit: (id) => { kit = resolveDrumKit(id); },
    schedule: () => schedule,
  };
};