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

9.7 KB
Raw Blame
// Sample-accurate metronome — the shared timing grid for the song system.
//
// Why Web Audio and not setInterval: a beat that rides setInterval drifts by
// tens of ms under load (same reason songPlayback.js stacks takes on one
// AudioContext clock rather than N <audio> elements). So we use the classic
// "two clocks" pattern — a coarse setInterval *lookahead* timer wakes every
// LOOKAHEAD_MS and schedules every click that falls inside the next
// SCHEDULE_AHEAD_S window directly on the AudioContext clock, which is
// sample-accurate. The UI/beat callbacks are fired with setTimeout aligned to
// each click's audio time so a visual pulse lands in sync with the click.
//
// This is the first real consumer of the song `tempo` (BPM) field. It exposes a
// beat-clock callback (`onBeat({ beat, bar, accent, countIn, whenAudioTime })`)
// so color-match (#1025) and sing-to-score (#1026) can later subscribe to the
// same grid. Pure-ish: no React; the <Metronome> component wraps it for UI.

import { parseScore } from './scoreNotation.js';
import { getAudioContext as audioContext, resumeAudioContext } from './audioContext.js';
import { TEMPO_MIN, TEMPO_MAX } from '../../../server/lib/roundsBounds.js';

// BPM band — the rounds tempo bounds (server/lib/roundsBounds.js), so the
// metronome and the server's `tempo` validation cannot drift.
export const METRONOME_BPM_MIN = TEMPO_MIN;
export const METRONOME_BPM_MAX = TEMPO_MAX;
export const DEFAULT_BPM = 120;

const DEFAULT_BEATS_PER_BAR = 4;
const LOOKAHEAD_MS = 25;        // how often the lookahead timer wakes
const SCHEDULE_AHEAD_S = 0.12;  // how far ahead of `currentTime` we schedule audio
const START_LEAD_S = 0.1;       // small lead before the first beat absorbs jitter

// The app-wide shared AudioContext (imported at top from audioContext.js) —
// reusing one keeps every click on the same clock as the other playback
// features.

// Clamp a BPM into the supported band. Returns null for non-numbers so a caller
// can distinguish "no/invalid value" from a legitimately-clamped number.
export const clampBpm = (bpm) => {
  // Absent (null / undefined / blank) is distinct from a clamped number — don't
  // let Number('') / Number(null) collapse to 0 and silently become the floor.
  if (bpm == null || bpm === '') return null;
  const n = Number(bpm);
  if (!Number.isFinite(n)) return null;
  return Math.max(METRONOME_BPM_MIN, Math.min(METRONOME_BPM_MAX, Math.round(n)));
};

// One canonical reading of a time-signature numerator: anything not a positive
// finite count — absent, garbled, zero, negative, Infinity — falls back to 4/4
// rather than producing a bar with no beats in it (or, for Infinity, a row of
// dots `Array.from` refuses to build). The scheduler and the visual pulse must
// agree on this or the dots stop matching the clicks.
export const normalizeBeatsPerBar = (beatsPerBar) => {
  const n = Math.floor(Number(beatsPerBar));
  return Number.isFinite(n) && n > 0 ? n : DEFAULT_BEATS_PER_BAR;
};

// Seconds between beats at a given BPM (the beat unit is the time-signature
// denominator, i.e. one click per notated beat).
export const secondsPerBeat = (bpm) => 60 / (clampBpm(bpm) ?? DEFAULT_BPM);

// Derive the time signature from a score. Accepts either the raw lead-sheet
// text or an already-parsed `{ beats, beatValue }` object. Defaults to 4/4 when
// absent (parseScore already falls back to 4/4 for a headerless score).
export const timeSignatureFromScore = (score) => {
  if (score && typeof score === 'object' && Number.isFinite(score.beats)) {
    return { beats: score.beats, beatValue: score.beatValue || 4 };
  }
  const parsed = parseScore(typeof score === 'string' ? score : '');
  return {
    beats: parsed.time?.beats || DEFAULT_BEATS_PER_BAR,
    beatValue: parsed.time?.beatValue || 4,
  };
};

// Pure beat-position math: map a global beat index (count-in beats first, then
// music beats) to its descriptor. `accent` marks the accented beat of the bar
// (default beat 1); `countIn` flags the lead-in bars (bar 0). Exported so the UI
// and tests can reason about positions without driving the audio clock.
export const beatDescriptor = (idx, { beatsPerBar = DEFAULT_BEATS_PER_BAR, countInBars = 0, accentBeat = 1 } = {}) => {
  const perBar = normalizeBeatsPerBar(beatsPerBar);
  const countInBeats = Math.max(0, Math.floor(countInBars) || 0) * perBar;
  if (idx < countInBeats) {
    const beat = (idx % perBar) + 1;
    return { beat, bar: 0, accent: beat === accentBeat, countIn: true };
  }
  const m = idx - countInBeats;
  const beat = (m % perBar) + 1;
  return { beat, bar: Math.floor(m / perBar) + 1, accent: beat === accentBeat, countIn: false };
};

/**
 * Build a metronome over a tempo + time signature.
 *
 * @param {object} opts
 * @param {number} opts.bpm            — beats per minute (clamped 20–320).
 * @param {number} opts.beatsPerBar    — numerator of the time signature.
 * @param {number} opts.beatValue      — denominator (carried for consumers; click cadence is BPM-based).
 * @param {number} opts.countInBars    — lead-in bars before bar 1 (0 = none).
 * @param {number} opts.accentBeat     — which beat of the bar is accented (default 1).
 * @param {(info) => void} opts.onBeat — fired on every beat with { beat, bar, accent, countIn, whenAudioTime }.
 * @param {(info) => void} opts.onCountInComplete — fired once at the first music downbeat.
 * @returns {{ start, stop, setBpm, isRunning, getBpm, getBeatsPerBar }}
 */
export function createMetronome({
  bpm = DEFAULT_BPM,
  beatsPerBar = DEFAULT_BEATS_PER_BAR,
  beatValue: _beatValue = 4,
  countInBars = 0,
  accentBeat = 1,
  onBeat = null,
  onCountInComplete = null,
} = {}) {
  let currentBpm = clampBpm(bpm) ?? DEFAULT_BPM;
  const perBar = normalizeBeatsPerBar(beatsPerBar);
  const countIn = Math.max(0, Math.floor(countInBars) || 0);
  const descriptorOpts = { beatsPerBar: perBar, countInBars: countIn, accentBeat };

  let running = false;
  let tickIndex = 0;       // global beats scheduled so far (count-in + music)
  let nextNoteTime = 0;    // audio time of the next beat to schedule
  let lookahead = null;    // setInterval id for the lookahead scheduler
  const pendingTimeouts = new Set(); // beat-callback timers, cleared on stop()

  // Schedule one short click tone at audio time `when`. The accented beat is a
  // brighter, louder blip so beat 1 is audible without watching the screen.
  const scheduleClick = (when, accent) => {
    const c = audioContext();
    const osc = c.createOscillator();
    const gain = c.createGain();
    osc.frequency.value = accent ? 1500 : 1000;
    const peak = accent ? 0.5 : 0.3;
    // Fast attack, short exponential decay — a click, not a tone.
    gain.gain.setValueAtTime(0.0001, when);
    gain.gain.exponentialRampToValueAtTime(peak, when + 0.001);
    gain.gain.exponentialRampToValueAtTime(0.0001, when + 0.05);
    osc.connect(gain).connect(c.destination);
    osc.start(when);
    osc.stop(when + 0.06);
    osc.onended = () => {
      // Outside the request lifecycle — never let a disconnect throw escape.
      try { osc.disconnect(); gain.disconnect(); } catch { /* already torn down */ }
    };
  };

  // Fire the beat/count-in callbacks aligned to the click's audio time.
  const dispatchBeat = (idx, when) => {
    const info = { ...beatDescriptor(idx, descriptorOpts), whenAudioTime: when };
    const firstMusicBeat = !info.countIn && idx === countIn * perBar;
    const delayMs = Math.max(0, (when - audioContext().currentTime) * 1000);
    const id = setTimeout(() => {
      pendingTimeouts.delete(id);
      // setTimeout runs outside the request lifecycle — a throwing consumer
      // callback must not crash the process (AGENTS.md deferred-work boundary).
      try {
        if (firstMusicBeat && onCountInComplete) onCountInComplete(info);
        if (onBeat) onBeat(info);
      } catch (err) {
        console.error(`❌ Metronome beat callback failed: ${err.message}`);
      }
    }, delayMs);
    pendingTimeouts.add(id);
  };

  // Lookahead scheduler — schedule every beat inside the next window.
  const scheduler = () => {
    const c = audioContext();
    while (nextNoteTime < c.currentTime + SCHEDULE_AHEAD_S) {
      const accent = beatDescriptor(tickIndex, descriptorOpts).accent;
      scheduleClick(nextNoteTime, accent);
      dispatchBeat(tickIndex, nextNoteTime);
      nextNoteTime += secondsPerBeat(currentBpm);
      tickIndex += 1;
    }
  };

  const start = async () => {
    if (running) return;
    const c = audioContext();
    // Autoplay policy starts the context suspended until a user gesture, and on
    // iOS it can also come back `'interrupted'` — see lib/audioContext.js.
    await resumeAudioContext(c);
    running = true;
    tickIndex = 0;
    nextNoteTime = c.currentTime + START_LEAD_S;
    scheduler(); // schedule the first window synchronously
    lookahead = setInterval(() => {
      // Interval callback is outside the request lifecycle — guard it.
      try {
        scheduler();
      } catch (err) {
        console.error(`❌ Metronome scheduler failed: ${err.message}`);
      }
    }, LOOKAHEAD_MS);
  };

  // Cancel all scheduled work: the lookahead interval and every pending beat
  // callback. Already-scheduled audio nodes stop on their own `osc.stop(when)`.
  const stop = () => {
    running = false;
    if (lookahead != null) {
      clearInterval(lookahead);
      lookahead = null;
    }
    for (const id of pendingTimeouts) clearTimeout(id);
    pendingTimeouts.clear();
    tickIndex = 0;
  };

  // Change tempo live — takes effect on the next scheduled beat.
  const setBpm = (next) => {
    const clamped = clampBpm(next);
    if (clamped != null) currentBpm = clamped;
  };

  return {
    start,
    stop,
    setBpm,
    isRunning: () => running,
    getBpm: () => currentBpm,
    getBeatsPerBar: () => perBar,
  };
}