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.6 KB
Raw Blame
// Melody synth playback for the lead-sheet notation — turns a parsed score
// (see scoreNotation.js) into a soft "reference tone" you can hear before you
// sing it. Companion to songPlayback.js: that mixer stacks RECORDED vocal takes,
// this one synthesizes the WRITTEN melody as oscillator tones so a singer can
// preview the intended pitch line.
//
// No third-party audio/MIDI library — Web Audio OscillatorNodes only, mirroring
// the lazy shared-AudioContext + lookahead-scheduler idiom in songPlayback.js.
// The schedule-building math (notes → { freq, startSec, durSec }) is a pure
// function so it can be unit-tested without Web Audio; the player wires that
// schedule onto the audio clock and emits a per-note "now sounding" callback so
// the UI can move a playhead. Pure (no React) — ScoreSheet wraps it in a hook.

import { getAudioContext as ctx } from './audioContext.js';
import { createLookaheadTransport, SYNTH_TIMING } from './lookaheadTransport.js';
import { midiToFreq } from '../../../server/lib/pitchMath.js';

// --- Pitch → frequency ------------------------------------------------------
// Equal-tempered, A4 = 440 Hz. MIDI 69 == A4, so f = 440 · 2^((midi−69)/12).
const PITCH_CLASS = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
const ACCIDENTAL_SHIFT = { '': 0, '#': 1, '##': 2, b: -1, bb: -2, n: 0 };

// MIDI note number for a parsed pitch ({ letter, accidental, octave }). C4 = 60,
// A4 = 69. Returns null for anything that isn't a pitch.
export const pitchToMidi = (pitch) => {
  if (!pitch) return null;
  const pc = PITCH_CLASS[String(pitch.letter || '').toUpperCase()];
  const shift = ACCIDENTAL_SHIFT[pitch.accidental || ''];
  if (pc == null || shift == null || !Number.isFinite(pitch.octave)) return null;
  return (pitch.octave + 1) * 12 + pc + shift;
};

// Frequency (Hz) for a MIDI note number. A4 (69) → 440. The shared
// server/lib/pitchMath.js math, re-exported for the client playback stack.
export { midiToFreq };

// Frequency (Hz) for a parsed pitch, or null when it isn't a pitch.
export const noteToFrequency = (pitch) => {
  const midi = pitchToMidi(pitch);
  return midi == null ? null : midiToFreq(midi);
};

// --- Schedule building (pure) -----------------------------------------------
// Walk the parsed score in render order (measures → notes) and assign each note
// a global index, an onset, and a duration in seconds. The note index matches
// the order <ScoreSheet> flattens notes, so the player's onNote(index) lines up
// with the rendered notehead for the playhead highlight.
//
// Timing: scoreNotation durations are in QUARTER-NOTE beats. The score's tempo
// counts beats where one beat = the time-signature denominator note, so a
// quarter-note beat lasts (60/bpm)·(beatValue/4) seconds. That makes 4/4 read as
// quarter=bpm and 6/8 read as eighth=bpm (the conventional interpretation),
// using the time signature rather than ignoring it.
export const DEFAULT_BPM = 90;

export const buildSchedule = (score, bpmOverride) => {
  const beatValue = score?.time?.beatValue || 4;
  const bpm = Number.isFinite(bpmOverride) && bpmOverride > 0
    ? bpmOverride
    : (Number.isFinite(score?.tempo) && score.tempo > 0 ? score.tempo : DEFAULT_BPM);
  const secPerQuarter = (60 / bpm) * (beatValue / 4);

  const events = [];
  let beat = 0;
  let index = 0;
  for (const measure of score?.measures || []) {
    for (const note of measure.notes || []) {
      const durBeats = note.duration?.beats || 0;
      events.push({
        index,
        rest: !!note.rest,
        midi: note.rest ? null : pitchToMidi(note.pitch),
        freq: note.rest ? null : noteToFrequency(note.pitch),
        startBeat: beat,
        durBeats,
        startSec: beat * secPerQuarter,
        durSec: durBeats * secPerQuarter,
      });
      beat += durBeats;
      index += 1;
    }
  }
  return { events, bpm, secPerQuarter, totalSec: beat * secPerQuarter };
};

// --- Audio context ----------------------------------------------------------
// The app-wide shared AudioContext (imported at top from audioContext.js).
// Resumed on demand because autoplay policy starts it suspended until a user
// gesture.

// Guard a UI callback that fires from a setInterval tick — an uncaught throw
// there has no request boundary to bubble to and would leave the scheduler
// interval orphaned. (AGENTS.md: wrap non-request-lifecycle callbacks.)
// Exported as a factory so midiPlayback.js shares the guard with its own
// log prefix instead of duplicating the body.
export const makeSafeCall = (label) => (cb, ...args) => {
  if (typeof cb !== 'function') return;
  try { cb(...args); }
  catch (err) { console.error(`🎹 ${label} callback failed: ${err.message}`); }
};
const safeCall = makeSafeCall('score playback');

// Lead-window slack for the scheduler tick — the rest of the lookahead timing
// (LEAD, LOOKAHEAD_MS) is owned by the shared transport (lookaheadTransport.js).
const { SCHEDULE_AHEAD } = SYNTH_TIMING;
const TONE_PEAK = 0.18;     // per-voice gain peak for a single sounding tone

// Schedule one tone with a short attack/release gain envelope so it doesn't
// click. Triangle wave reads as a soft reference tone. Routed into `destination`
// (the context output for the solo player; a per-part gain → master bus for the
// multi-part player). Returns the live { osc, gain } so the caller can track it
// for teardown. Pure of any module state — both players here share it, and
// midiPlayback.js imports it so the MIDI preview sounds like the score synth.
export const scheduleTone = (c, freq, startAt, durSec, destination, peak = TONE_PEAK) => {
  const osc = c.createOscillator();
  const gain = c.createGain();
  osc.type = 'triangle';
  osc.frequency.setValueAtTime(freq, startAt);

  const attack = Math.min(0.012, durSec * 0.25);
  const release = Math.min(0.07, durSec * 0.4);
  const end = startAt + durSec;
  const sustainEnd = Math.max(startAt + attack, end - release);
  gain.gain.setValueAtTime(0.0001, startAt);
  gain.gain.exponentialRampToValueAtTime(peak, startAt + attack);
  gain.gain.setValueAtTime(peak, sustainEnd);
  gain.gain.exponentialRampToValueAtTime(0.0001, end);

  osc.connect(gain).connect(destination);
  osc.start(startAt);
  osc.stop(end + 0.03);
  return { osc, gain };
};

// --- Shared per-voice scheduler ---------------------------------------------
// Both score players are thin schedulers over the same shared transport
// (lookaheadTransport.js): the solo player drives one schedule, the multi player
// drives one schedule per voice. Their scheduler-tick and cursor-positioning
// bodies were byte-for-byte the same walk, differing only in destination (context
// output vs. per-play master bus), the onNote signature, and (for the multi
// player) a per-voice end-notify. The two helpers below own that shared walk so
// each player only wires up its own distinct pieces.

// The mutable scheduling position for one schedule: the next event to hand to the
// oscillator scheduler, the next to fire onNote for, and the last index notified
// (so a repeated tick doesn't re-fire the same playhead).
const makeVoiceCursor = () => ({ nextScheduleIdx: 0, nextNotifyIdx: 0, lastNotified: -1 });

// Position a cursor at a resume `offset` — the first event still sounding at (or
// starting after) offset. Both cursors share this point so the note under the
// playhead at resume is (re)scheduled AND (re)notified, and a fresh play from 0
// still notifies note 0 (stop/finish call this with offset 0 to reset to the top).
const positionVoiceCursor = (cursor, schedule, offset) => {
  const events = schedule.events;
  let idx = events.findIndex((e) => e.startSec + e.durSec > offset + 1e-6);
  if (idx < 0) idx = events.length;
  cursor.nextScheduleIdx = idx;
  cursor.nextNotifyIdx = idx;
  cursor.lastNotified = -1;
};

// One scheduler tick for a single schedule: hand any due tones to the audio clock
// (via the transport-supplied `track`, routed to `destination`) and fire
// `onNoteIndex(index)` for the latest note that has started. End-of-voice /
// end-of-piece handling stays in the caller — the solo player leaves it to the
// transport's finish, the multi player adds a per-voice end-notify because voices
// differ in length.
const advanceVoiceWindow = (cursor, schedule, now, startTime, track, destination, onNoteIndex) => {
  const events = schedule.events;

  while (cursor.nextScheduleIdx < events.length) {
    const ev = events[cursor.nextScheduleIdx];
    const at = startTime + ev.startSec;
    if (at > now + SCHEDULE_AHEAD) break;
    if (!ev.rest && ev.freq) {
      track(scheduleTone(ctx(), ev.freq, Math.max(at, now), ev.durSec, destination));
    }
    cursor.nextScheduleIdx += 1;
  }

  let newest = -1;
  while (cursor.nextNotifyIdx < events.length && startTime + events[cursor.nextNotifyIdx].startSec <= now) {
    newest = events[cursor.nextNotifyIdx].index;
    cursor.nextNotifyIdx += 1;
  }
  if (newest >= 0 && newest !== cursor.lastNotified) {
    cursor.lastNotified = newest;
    onNoteIndex(newest);
  }
};

/**
 * Build a melody player over a parsed score.
 *
 * @param {object} score — output of `parseScore`.
 * @param {object} [options]
 * @param {number} [options.bpm] — tempo override (else score.tempo, else 90).
 * @param {(index:number|null)=>void} [options.onNote] — called with the index of
 *   the now-sounding note (null when playback ends / stops) so the UI can move a
 *   playhead.
 * @param {()=>void} [options.onEnded] — called once when the melody finishes.
 * @returns {{ play, pause, stop, isPlaying, setTempo, schedule }}
 */
export const createScorePlayer = (score, options = {}) => {
  const { onNote, onEnded } = options;
  let bpm = Number.isFinite(options.bpm) && options.bpm > 0 ? options.bpm : null;
  let schedule = buildSchedule(score, bpm);

  const cursor = makeVoiceCursor();

  // One scheduler tick over the single schedule, routed to the context output.
  // The transport handles the end-of-piece finish, so there's no per-voice
  // end-notify here (unlike the multi-part player).
  const scheduleWindow = (now, startTime, track) => {
    advanceVoiceWindow(cursor, schedule, now, startTime, track, ctx().destination, (index) => safeCall(onNote, index));
  };

  // Position the schedule/notify cursors at a resume offset (stop/finish call this
  // with 0 to reset to the top). No tails, so it ignores the transport's
  // soundTails/startTime/track args.
  const seekCursors = (offset) => { positionVoiceCursor(cursor, schedule, offset); };

  // Rebuild to pick up a tempo change made while idle, then bail (as ended) on
  // an empty score. Runs after the transport's resume/token recheck.
  const prepare = () => {
    schedule = buildSchedule(score, bpm);
    if (!schedule.events.length || schedule.totalSec <= 0) { safeCall(onEnded); return false; }
    return true;
  };

  const transport = createLookaheadTransport({
    getTotalSec: () => schedule.totalSec,
    scheduleWindow,
    prepare,
    seekCursors,
    onStop: () => { safeCall(onNote, null); },
    onEnded: () => { safeCall(onEnded); },
  });

  const setTempo = (nextBpm) => {
    bpm = Number.isFinite(nextBpm) && nextBpm > 0 ? nextBpm : null;
    if (!transport.isPlaying()) schedule = buildSchedule(score, bpm);
  };

  return {
    play: transport.play,
    pause: transport.pause,
    stop: transport.stop,
    isPlaying: transport.isPlaying,
    setTempo,
    schedule: () => schedule,
  };
};

// Master gain for the multi-part bus: back the level off as more voices stack so
// the summed triangle waves don't clip, while a lone voice still plays at the
// same level as the solo player (1.0 for n=1, ~0.35 for a 4-part stack).
const masterGainFor = (count) => Math.min(1, 1.4 / Math.max(1, count));

/**
 * Build a player that synthesizes MULTIPLE parts at once — the melody plus any
 * checked harmony parts — so any combination of lead-sheet voices sounds
 * together, sample-aligned on the one shared AudioContext. Each part is scheduled
 * through its own gain into a shared master bus whose level backs off as more
 * voices stack so the sum doesn't clip. The transport mirrors `createScorePlayer`
 * (play / pause / stop / setTempo) but iterates every part each tick, and the
 * playhead callback is per-part so a viewer can highlight the staff it's showing.
 *
 * @param {Array<{id:string, score:object}>} parts — parsed scores to play together.
 * @param {object} [options]
 * @param {number} [options.bpm] — tempo override applied to every part.
 * @param {(partId:string, index:number|null)=>void} [options.onNote] — the
 *   now-sounding note index for a part (null for every part when playback ends).
 * @param {()=>void} [options.onEnded] — called once when the longest part finishes.
 * @returns {{ play, pause, stop, isPlaying, setTempo }}
 */
export const createMultiScorePlayer = (parts, options = {}) => {
  const { onNote, onEnded } = options;
  let bpm = Number.isFinite(options.bpm) && options.bpm > 0 ? options.bpm : null;

  // A voice carries its part id, its schedule, and per-voice scheduler cursors.
  // `endNotified` tracks whether this voice's playhead has been cleared at its
  // own end — voices have different lengths, so a short part must clear when IT
  // finishes, not when the longest part does (else its last note stays lit).
  const buildVoices = () => (parts || []).map((p) => ({
    id: p.id,
    schedule: buildSchedule(p.score, bpm),
    ...makeVoiceCursor(),
    endNotified: false,
  }));

  let voices = [];
  let totalSec = 0;        // longest voice (seconds) — cached, refreshed on rebuild
  // Rebuild the voice schedules (and cache totalSec) — on init, on play, and on a
  // tempo change while idle. Cheaper than reducing over voices every 25ms tick.
  const rebuild = () => {
    voices = buildVoices();
    totalSec = voices.reduce((m, v) => Math.max(m, v.schedule.totalSec), 0);
  };
  rebuild();

  let master = null;       // shared bus GainNode (created per play)

  // Position every voice's cursors at `offset` (0 resets to the top for
  // stop/finish). No tails, so it ignores the transport's soundTails/startTime/
  // track args.
  const seekCursors = (offset = 0) => {
    for (const v of voices) {
      positionVoiceCursor(v, v.schedule, offset);
      v.endNotified = false;
    }
  };

  const scheduleWindow = (now, startTime, track) => {
    for (const v of voices) {
      advanceVoiceWindow(v, v.schedule, now, startTime, track, master, (index) => safeCall(onNote, v.id, index));

      // Clear this voice's playhead the moment IT finishes (its last note's
      // duration has elapsed), independent of longer voices still sounding.
      if (!v.endNotified && now - startTime >= v.schedule.totalSec) {
        v.endNotified = true;
        safeCall(onNote, v.id, null);
      }
    }
  };

  // Rebuild to pick up a tempo change made while idle, bail (as ended) on an
  // empty selection, then stand up the per-play master bus.
  const prepare = () => {
    rebuild();
    if (!totalSec) { safeCall(onEnded); return false; }
    const c = ctx();
    master = c.createGain();
    master.gain.setValueAtTime(masterGainFor(voices.length), c.currentTime);
    master.connect(c.destination);
    return true;
  };

  const transport = createLookaheadTransport({
    getTotalSec: () => totalSec,
    scheduleWindow,
    prepare,
    seekCursors,
    onStop: () => { for (const v of voices) safeCall(onNote, v.id, null); },
    onEnded: () => { safeCall(onEnded); },
    onTeardown: () => { master = null; },
  });

  const setTempo = (nextBpm) => {
    bpm = Number.isFinite(nextBpm) && nextBpm > 0 ? nextBpm : null;
    if (!transport.isPlaying()) rebuild();
  };

  return {
    play: transport.play,
    pause: transport.pause,
    stop: transport.stop,
    isPlaying: transport.isPlaying,
    setTempo,
    position: transport.position,
    duration: () => totalSec,
  };
};