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

15.8 KB
Raw Blame
// Chord-sheet play-along for the SongBook `tab` / `chordpro` formats (#4104) —
// the MIDI/score preview `<TabSheetView>` embeds, and the chord-sheet sibling of
// `drumPlayback.js`. Turns the chord tokens a sheet already carries into a
// strummed, tempo-adjustable backing you can practice against, with the sounding
// chord lit in the sheet.
//
// Like every other synth player in this tree it is a thin scheduler over the
// shared `lookaheadTransport.js` (clock, node lifecycle, teardown) and sounds
// through `scheduleTone` from `scorePlayback.js`, so the preview has the same
// voice as the lead-sheet and MIDI previews rather than a fourth synth.
//
// A CHORD SHEET CARRIES NO RHYTHM. Chords-over-lyrics notation says WHICH chords
// and IN WHAT ORDER, never how long each is held — so the schedule reads one
// chord token as one bar, the convention a player falls back on when reading a
// sheet cold. A dash-joined quick change ("Am-Am7") splits its own bar between
// its segments, which is exactly what that notation means. Tab staffs, lyrics
// and prose contribute nothing.
//
// `buildChordSchedule` is PURE (no Web Audio) so the timing math is unit-testable
// in a node env, mirroring `buildDrumSchedule` / `buildSchedule`.

import { getAudioContext as ctx } from './audioContext.js';
import { createLookaheadTransport, SYNTH_TIMING } from './lookaheadTransport.js';
import { makeSafeCall, midiToFreq, scheduleTone } from './scorePlayback.js';
import { chordTones, splitJoinedChords } from './chordShapes.js';

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

// Tempo a sheet with no `tempo:` marking plays at. A chord sheet has no tempo
// field at all, so this is always the reference the percent buttons work off.
export const DEFAULT_CHORD_TEMPO = 90;
// One chord token = one bar of this many beats (see the header note).
export const DEFAULT_CHORD_BEATS_PER_BAR = 4;
export const CHORD_BEATS_MIN = 2;
export const CHORD_BEATS_MAX = 12;
export const CHORD_COUNT_IN_MAX = 4;

// Where the voicing sits. The root lands in the octave starting at MIDI 48 (C3)
// — comfortably under a sung melody — and the bass note an octave and a half
// below that, so the chord reads as a chord rather than a cluster.
const ROOT_BASE_MIDI = 48;
const BASS_BASE_MIDI = 36;

// A strum, not a block chord: each note of the voicing starts this much after
// the one below it. Small enough to still hear as one chord.
const STRUM_SEC = 0.022;
// Per-note gain. Deliberately under `scorePlayback`'s single-voice default —
// four or five tones stack here where the melody synth sounds one.
const CHORD_TONE_PEAK = 0.085;
const BASS_TONE_PEAK = 0.1;
// Count-in / downbeat click: a short high blip, so it cuts through the chords.
const CLICK_FREQ = 1320;
const CLICK_ACCENT_FREQ = 1760;
const CLICK_DUR_SEC = 0.045;
const CLICK_PEAK = 0.14;

const clampInt = (value, min, max, fallback) => {
  const n = Math.trunc(Number(value));
  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
};

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

/**
 * The ordered chord occurrences a parsed sheet holds — the play-along's source
 * material AND the identity the sheet highlights against.
 *
 * `lineIndex` / `chordIndex` address the token in `parseTabSheet(text).lines`,
 * so a renderer can light the exact token that is sounding without the schedule
 * knowing anything about how the sheet is laid out. A dash-joined token yields
 * one occurrence per segment, all pointing at that same token.
 *
 * @param {Array} lines — `parseTabSheet(text).lines`.
 * @returns {Array<{ lineIndex, chordIndex, segment, segments, name }>}
 */
export const sheetChordOccurrences = (lines) => {
  const out = [];
  (Array.isArray(lines) ? lines : []).forEach((line, lineIndex) => {
    (Array.isArray(line?.chords) ? line.chords : []).forEach((chord, chordIndex) => {
      const parts = splitJoinedChords(chord?.name);
      parts.forEach((name, segment) => {
        out.push({ lineIndex, chordIndex, segment, segments: parts.length, name });
      });
    });
  });
  return out;
};

// A chord name → the MIDI notes that sound it, low to high. `null` (an
// unvoiceable token — "N.C.", an exotic quality) is a REST, not silence-shaped
// noise: the bar still passes, so the sheet keeps its place.
export const chordMidiNotes = (name) => {
  const tones = chordTones(name);
  if (!tones) return null;
  const rootMidi = ROOT_BASE_MIDI + tones.rootPc;
  const bassPc = tones.bassPc ?? tones.rootPc;
  return [BASS_BASE_MIDI + bassPc, ...tones.semitones.map((semis) => rootMidi + semis)];
};

/**
 * Flatten a parsed sheet's chords into absolute-time strum events.
 *
 * @param {Array} lines — `parseTabSheet(text).lines`.
 * @param {object} [options]
 * @param {number} [options.bpm] — practice tempo (default 90).
 * @param {number} [options.beatsPerBar] — beats one chord is held for (default 4).
 * @param {number} [options.countInBars] — click-only lead-in bars (0–4).
 * @returns {{ events, clicks, bpm, beatSec, barSec, beatsPerBar, countInSec, totalSec }}
 */
export const buildChordSchedule = (lines, options = {}) => {
  const bpm = Number.isFinite(options.bpm) && options.bpm > 0 ? options.bpm : DEFAULT_CHORD_TEMPO;
  const beatsPerBar = clampInt(options.beatsPerBar, CHORD_BEATS_MIN, CHORD_BEATS_MAX, DEFAULT_CHORD_BEATS_PER_BAR);
  const countInBars = clampInt(options.countInBars, 0, CHORD_COUNT_IN_MAX, 0);
  const beatSec = 60 / bpm;
  const barSec = beatSec * beatsPerBar;
  const countInSec = countInBars * barSec;

  // The count-in is its own list rather than an entry in `events`: `events` is
  // indexed 1:1 with the sheet's chord tokens (that index IS the highlight), and
  // interleaving clicks would make the index mean two different things.
  const clicks = [];
  for (let bar = 0; bar < countInBars; bar += 1) {
    for (let beat = 0; beat < beatsPerBar; beat += 1) {
      clicks.push({
        beat: beat + 1,
        accent: beat === 0,
        startSec: (bar * beatsPerBar + beat) * beatSec,
      });
    }
  }

  let cursor = countInSec;
  const events = sheetChordOccurrences(lines).map((occurrence, index) => {
    // A dash-joined token's segments share the token's one bar.
    const durSec = barSec / occurrence.segments;
    const startSec = cursor;
    cursor += durSec;
    const midis = chordMidiNotes(occurrence.name);
    return { index, ...occurrence, midis: midis || [], rest: !midis, startSec, durSec };
  });

  return {
    events,
    clicks,
    bpm,
    beatSec,
    barSec,
    beatsPerBar,
    countInSec,
    totalSec: events.length ? cursor : 0,
  };
};

/**
 * A built schedule + a live clock position → what the UI should show (pure).
 *
 * Read off the audio clock rather than the player's `onChord` events, for the
 * same reason `resolvePlayhead` exists on the drum side: an event callback
 * stands still through the count-in and through a stretch with no voiceable
 * chord, so anything that has to keep moving reads the clock instead.
 *
 * Returns `null` when there is nothing to place; otherwise
 * `{ countIn: true, beat }` during the lead-in, else
 * `{ countIn: false, index, beat }` — `index` into `schedule.events`.
 */
export const resolveChordPlayhead = (schedule, posSec) => {
  const events = Array.isArray(schedule?.events) ? schedule.events : [];
  const { beatSec, beatsPerBar, countInSec = 0, totalSec = 0 } = schedule || {};
  if (!events.length || !(beatSec > 0)) return null;
  const pos = Number.isFinite(posSec) ? posSec : 0;

  // `countInSec > 0` is load-bearing, not redundant: the transport's pre-roll
  // lead makes `pos` briefly NEGATIVE, so a bare `pos < countInSec` would report
  // "counting in" for the first ~80ms of a run that has no count-in at all —
  // yellow beat dots and a null highlight before the first chord.
  if (countInSec > 0 && pos < countInSec) {
    // Clamp that negative lead to the first beat rather than counting backwards
    // past the start of the count-in.
    const elapsedBeats = Math.floor(Math.max(0, pos) / beatSec);
    return { countIn: true, beat: (elapsedBeats % Math.max(1, beatsPerBar)) + 1 };
  }

  const elapsed = Math.min(Math.max(0, pos), Math.max(0, totalSec - 1e-6));
  // Events are contiguous and in order, so the last one that has started is the
  // sounding one. A linear scan is fine — a long sheet is a few hundred chords,
  // and this runs once per animation frame.
  let index = 0;
  for (let i = 0; i < events.length; i += 1) {
    if (events[i].startSec > elapsed) break;
    index = i;
  }
  return {
    countIn: false,
    index,
    beat: Math.floor((elapsed - countInSec) / beatSec) % Math.max(1, beatsPerBar) + 1,
  };
};

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

/**
 * Build a chord-sheet play-along over parsed sheet lines.
 *
 * @param {Array} lines — `parseTabSheet(text).lines`.
 * @param {object} [options]
 * @param {number} [options.bpm] — practice tempo.
 * @param {number} [options.beatsPerBar] — beats per chord.
 * @param {number} [options.countInBars] — click-only lead-in bars.
 * @param {boolean} [options.clickEnabled] — a downbeat click under every chord.
 * @param {(index:number|null)=>void} [options.onChord] — the now-sounding chord
 *   index (null when playback ends/stops), for the sheet highlight.
 * @param {()=>void} [options.onEnded] — fired once when the sheet finishes.
 * @returns {{ play, pause, stop, isPlaying, position, setBpm, setBeatsPerBar,
 *   setCountIn, setClick, schedule }}
 */
export const createChordPlayer = (lines, options = {}) => {
  const { onChord, onEnded } = options;
  let bpm = Number.isFinite(options.bpm) && options.bpm > 0 ? options.bpm : null;
  let beatsPerBar = options.beatsPerBar;
  let countInBars = options.countInBars || 0;
  // Gates FUTURE scheduling only, so — unlike the timing settings — it applies
  // live without a rebuild.
  let clickEnabled = !!options.clickEnabled;

  const build = () => buildChordSchedule(lines, { bpm, beatsPerBar, countInBars });
  let schedule = build();
  let master = null;

  // Separate cursors for the three walks: the tone scheduler and the click
  // scheduler both run AHEAD of the audio clock (a lookahead window), while the
  // highlight trails BEHIND it. One shared cursor would drag the trailing walk
  // forward and light a chord before you hear it.
  let toneIdx = 0;
  let clickIdx = 0;
  let headIdx = 0;
  let lastNotified = -1;
  const resetCursors = () => {
    toneIdx = 0;
    clickIdx = 0;
    headIdx = 0;
    lastNotified = -1;
  };

  // Every click for the current schedule: the count-in's own beats, then a
  // metronome beat through the music. Derived rather than baked into the
  // schedule so toggling the click mid-play needs no rebuild — the toggle gates
  // whether the MUSIC clicks sound, and the count-in's always do.
  const clickTimes = () => {
    const out = schedule.clicks.map((click) => ({ ...click, countIn: true }));
    const musicSec = Math.max(0, schedule.totalSec - schedule.countInSec);
    const beats = Math.round(musicSec / schedule.beatSec);
    for (let beat = 0; beat < beats; beat += 1) {
      out.push({
        beat: (beat % schedule.beatsPerBar) + 1,
        accent: beat % schedule.beatsPerBar === 0,
        countIn: false,
        startSec: schedule.countInSec + beat * schedule.beatSec,
      });
    }
    return out;
  };
  let clicks = clickTimes();

  const soundChord = (c, ev, at, track) => {
    ev.midis.forEach((midi, i) => {
      const freq = midiToFreq(midi);
      if (!freq) return;
      // The bass note (index 0) is not part of the strum sweep and carries a
      // little more level — it is the chord's foundation, not its top voice.
      const offset = i === 0 ? 0 : STRUM_SEC * (i - 1);
      const durSec = Math.max(0.05, ev.durSec - offset);
      track(scheduleTone(c, freq, at + offset, durSec, master, i === 0 ? BASS_TONE_PEAK : CHORD_TONE_PEAK));
    });
  };

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

    while (toneIdx < schedule.events.length) {
      const ev = schedule.events[toneIdx];
      const at = startTime + ev.startSec;
      if (at >= horizon) break;
      toneIdx += 1;
      if (at < now - 0.05) continue; // already past (first tick after a stall)
      if (!ev.rest) soundChord(c, ev, Math.max(at, now), track);
    }

    while (clickIdx < clicks.length) {
      const click = clicks[clickIdx];
      const at = startTime + click.startSec;
      if (at >= horizon) break;
      // The cursor advances even when the click is muted — skipping the walk
      // wholesale would leave it behind and dump a backlog the moment the
      // toggle came back on.
      clickIdx += 1;
      if (at < now - 0.05) continue;
      // Count-in clicks are NOT gated on `clickEnabled` — "click off, count me
      // in" is the mode that combination means, the same call drumPlayback makes.
      if (!click.countIn && !clickEnabled) continue;
      track(scheduleTone(
        c, click.accent ? CLICK_ACCENT_FREQ : CLICK_FREQ,
        Math.max(at, now), CLICK_DUR_SEC, master, CLICK_PEAK,
      ));
    }

    if (!onChord) return;
    let newest = -1;
    while (headIdx < schedule.events.length
      && startTime + schedule.events[headIdx].startSec <= now) {
      newest = schedule.events[headIdx].index;
      headIdx += 1;
    }
    if (newest >= 0 && newest !== lastNotified) {
      lastNotified = newest;
      safeCall(onChord, newest);
    }
  };

  const transport = createLookaheadTransport({
    // Output-only, so it holds the iOS `playback` session while it sounds —
    // without it the hardware ring/silent switch mutes a pure-synth page.
    audioSession: 'playback',
    getTotalSec: () => schedule.totalSec,
    scheduleWindow,
    prepare: () => {
      schedule = build();
      if (!schedule.events.length || schedule.totalSec <= 0) { safeCall(onEnded); return false; }
      clicks = clickTimes();
      resetCursors();
      const c = ctx();
      master = c.createGain();
      master.gain.value = 1;
      master.connect(c.destination);
      return true;
    },
    seekCursors: (offsetSec) => {
      resetCursors();
      if (offsetSec <= 0) return;
      // Resume (pause → play) positions every cursor past what already sounded.
      // The tone cursor keeps the chord still ringing at the offset so a resume
      // mid-chord re-sounds it rather than dropping into silence.
      while (toneIdx < schedule.events.length
        && schedule.events[toneIdx].startSec + schedule.events[toneIdx].durSec <= offsetSec) toneIdx += 1;
      headIdx = toneIdx;
      while (clickIdx < clicks.length && clicks[clickIdx].startSec < offsetSec) clickIdx += 1;
    },
    onStop: () => { safeCall(onChord, 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.
      if (master) {
        try { master.disconnect(); } catch { /* already gone */ }
      }
      master = null;
    },
  });

  // A timing change rebuilds the schedule while idle; while playing the caller
  // restarts, since already-scheduled audio can't be re-timed.
  const rebuildIfIdle = () => {
    if (transport.isPlaying()) return;
    schedule = build();
    clicks = clickTimes();
    resetCursors();
  };

  return {
    play: transport.play,
    pause: transport.pause,
    stop: transport.stop,
    isPlaying: transport.isPlaying,
    position: transport.position,
    setBpm: (next) => {
      bpm = Number.isFinite(next) && next > 0 ? next : null;
      rebuildIfIdle();
    },
    setBeatsPerBar: (next) => { beatsPerBar = next; rebuildIfIdle(); },
    setCountIn: (bars) => { countInBars = clampInt(bars, 0, CHORD_COUNT_IN_MAX, 0); rebuildIfIdle(); },
    setClick: (enabled) => { clickEnabled = !!enabled; },
    schedule: () => schedule,
  };
};