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.4 KB
Raw Blame
// Chiptune score preview (#2911) — turns a track's LLM-generated chiptune
// score into a seamlessly LOOPING WebAudio preview. Companion to the offline
// renderer (server/lib/chiptuneRender.js): same score contract, same timing
// semantics (MIRRORS server/lib/chiptuneScore.js buildScoreEvents — keep the
// two in lockstep), synthesized live with OscillatorNodes + a noise buffer
// instead of offline PCM.
//
// No third-party audio library — built on the shared lookahead transport
// (lookaheadTransport.js, #2493) like the other synth players. The schedule
// build is a pure function (unit-tested without Web Audio); the player loops
// by re-basing its cursor each time it exhausts the event list, so the loop
// boundary is sample-scheduler-exact rather than "restart on a timer".

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

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

// --- Pure schedule build (mirrors server buildScoreEvents) ------------------

export const CHIPTUNE_NOISE_PRESETS = ['kick', 'snare', 'hat', 'open-hat'];

// MIDI number for a scientific-pitch STRING ("C4" = 60), or null — the shared
// server/lib/pitchMath.js parser. Differs from scorePlayback.pitchToMidi, which
// takes a parsed { letter, accidental, octave }.
export const parseChiptunePitch = pitchToMidi;

/**
 * Flatten a chiptune score into absolute-time events + the exact loop length.
 * Same drop/clamp semantics as the server: notes starting past their pattern
 * are dropped, overhang is clamped, unresolvable pitches drop just that note.
 */
export function buildChiptuneSchedule(score) {
  if (
    !score || !Array.isArray(score.channels) || !Array.isArray(score.order)
    || !(score.bpm > 0) || !(score.stepsPerBeat > 0) || !(score.beatsPerBar > 0)
  ) {
    return { events: [], stepSec: 0, totalSec: 0 };
  }
  const stepSec = 60 / (score.bpm * score.stepsPerBeat);
  const channelsById = new Map(score.channels.map((c) => [c.id, c]));
  const events = [];
  let baseStep = 0;
  for (const name of score.order) {
    const pattern = score.patterns?.[name];
    if (!pattern) continue;
    const steps = pattern.bars * score.beatsPerBar * score.stepsPerBeat;
    for (const [channelId, notes] of Object.entries(pattern.notes || {})) {
      const channel = channelsById.get(channelId);
      if (!channel || !Array.isArray(notes)) continue;
      for (const note of notes) {
        if (note.step >= steps) continue;
        const lenSteps = Math.min(note.len, steps - note.step);
        const isNoise = channel.wave === 'noise';
        const noise = isNoise ? (CHIPTUNE_NOISE_PRESETS.includes(note.pitch) ? note.pitch : null) : null;
        const freq = isNoise ? null : midiToFreq(parseChiptunePitch(note.pitch));
        if (isNoise ? !noise : !freq) continue;
        events.push({
          wave: channel.wave,
          duty: channel.duty ?? 0.5,
          gain: channel.gain ?? 0.5,
          freq,
          noise,
          startSec: (baseStep + note.step) * stepSec,
          durSec: lenSteps * stepSec,
          vel: note.vel ?? 0.8,
        });
      }
    }
    baseStep += steps;
  }
  events.sort((a, b) => a.startSec - b.startSec);
  return { events, stepSec, totalSec: baseStep * stepSec };
}

// --- WebAudio voices --------------------------------------------------------

const VOICE_PEAK = 0.22; // per-voice headroom so four channels don't clip

// Band-limited pulse wave for non-50% duty cycles (a 'square' OscillatorNode
// is fixed at 50%). Fourier series of a pulse: a_n ∝ sin(nπ·duty)/n.
const pulseWave = (c, duty) => {
  const N = 32;
  const real = new Float32Array(N);
  const imag = new Float32Array(N);
  for (let n = 1; n < N; n += 1) {
    imag[n] = (2 / (n * Math.PI)) * Math.sin(n * Math.PI * duty);
  }
  return c.createPeriodicWave(real, imag, { disableNormalization: false });
};

// Noise voices read the app-wide buffer from audioContext.js via offset 0 — the
// LFSR aesthetic matters less in preview than in the deterministic render.

const NOISE_VOICES = {
  kick: { decaySec: 0.11 },
  snare: { decaySec: 0.12, rate: 0.45 },
  hat: { decaySec: 0.04, rate: 1 },
  'open-hat': { decaySec: 0.2, rate: 1 },
};

// Schedule one chiptune voice; returns { osc, gain } for transport teardown
// (an AudioBufferSourceNode satisfies the same start/stop/onended surface).
function scheduleChipVoice(c, ev, startAt, destination, waveCache) {
  const gain = c.createGain();
  const peak = Math.max(0.0002, VOICE_PEAK * ev.gain * ev.vel);
  const end = startAt + ev.durSec;
  let osc;

  if (ev.noise) {
    const preset = NOISE_VOICES[ev.noise];
    if (ev.noise === 'kick') {
      // Classic chiptune kick: a fast descending sine sweep, not noise.
      osc = c.createOscillator();
      osc.type = 'sine';
      osc.frequency.setValueAtTime(160, startAt);
      osc.frequency.exponentialRampToValueAtTime(45, startAt + preset.decaySec);
    } else {
      osc = c.createBufferSource();
      osc.buffer = getNoiseBuffer(c);
      osc.loop = true;
      osc.playbackRate.value = preset.rate;
    }
    gain.gain.setValueAtTime(peak, startAt);
    gain.gain.exponentialRampToValueAtTime(0.0001, Math.min(end, startAt + preset.decaySec * 4));
  } else {
    osc = c.createOscillator();
    if (ev.wave === 'triangle') osc.type = 'triangle';
    else if (ev.duty === 0.5) osc.type = 'square';
    else {
      const key = ev.duty.toFixed(3);
      if (!waveCache.has(key)) waveCache.set(key, pulseWave(c, ev.duty));
      osc.setPeriodicWave(waveCache.get(key));
    }
    osc.frequency.setValueAtTime(ev.freq, startAt);
    const attack = Math.min(0.008, ev.durSec * 0.25);
    const release = Math.min(0.05, ev.durSec * 0.3);
    gain.gain.setValueAtTime(0.0001, startAt);
    gain.gain.exponentialRampToValueAtTime(peak, startAt + attack);
    gain.gain.setValueAtTime(peak, Math.max(startAt + attack, end - release));
    gain.gain.exponentialRampToValueAtTime(0.0001, end);
  }

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

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

/**
 * Looping chiptune preview player over the shared lookahead transport.
 * `getScore` is re-read on every play() so the preview always sounds the
 * freshest generation. Loops until stop() — `getTotalSec` is Infinity and the
 * cursor re-bases itself each pass, so the loop boundary is scheduler-exact.
 *
 * @param {() => object|null} getScore — returns the current score (or null)
 * @param {{ onLoop?: (loopCount:number) => void }} [callbacks]
 * @returns {{ play, stop, isPlaying, position, loopSec }} — `position()` is the
 *   elapsed preview time in seconds, MONOTONIC across loop passes (the cursor
 *   re-bases rather than restarting), and `loopSec()` the exact length of one
 *   pass, so a UI renders the per-pass playhead as `position() % loopSec()`.
 */
export function createChiptunePlayer(getScore, { onLoop } = {}) {
  let schedule = null;
  let master = null;
  let waveCache = new Map();
  let cursor = { idx: 0, loopStartSec: 0, loops: 0 };

  const transport = createLookaheadTransport({
    getTotalSec: () => Infinity,
    prepare: () => {
      const built = buildChiptuneSchedule(getScore());
      if (!built.events.length || built.totalSec <= 0) return false;
      schedule = built;
      const c = ctx();
      master = c.createGain();
      master.gain.value = 1;
      master.connect(c.destination);
      waveCache = new Map();
      cursor = { idx: 0, loopStartSec: 0, loops: 0 };
      return true;
    },
    scheduleWindow: (now, startTime, track) => {
      if (!schedule || !master) return;
      const horizon = now + SCHEDULE_AHEAD;
      // Hand every event due inside the window to the audio clock; when the
      // list is exhausted, re-base onto the next loop pass and keep going.
      for (;;) {
        if (cursor.idx >= schedule.events.length) {
          cursor.idx = 0;
          cursor.loopStartSec += schedule.totalSec;
          cursor.loops += 1;
          safeCall(onLoop, cursor.loops);
        }
        const ev = schedule.events[cursor.idx];
        const at = startTime + cursor.loopStartSec + ev.startSec;
        if (at >= horizon) break;
        cursor.idx += 1;
        if (at < now - 0.01) continue; // already past (first tick after a stall)
        track(scheduleChipVoice(ctx(), ev, at, master, waveCache));
      }
    },
    seekCursors: () => { cursor = { idx: 0, loopStartSec: 0, loops: 0 }; },
    // Output-only preview: hold the iOS `playback` session while it loops, or
    // the iPhone's ring/silent switch mutes a page that looks like it is
    // playing. Claimed on play and released on teardown by the transport.
    audioSession: 'playback',
    onTeardown: () => {
      if (master) { try { master.disconnect(); } catch { /* already gone */ } master = null; }
    },
  });

  return {
    play: transport.play,
    stop: transport.stop,
    isPlaying: transport.isPlaying,
    position: transport.position,
    // The length of the schedule that is actually SOUNDING (built at play()),
    // not of the caller's current score — a regeneration mid-preview must not
    // re-scale a playhead against a loop nobody is hearing yet. 0 before the
    // first play.
    loopSec: () => (schedule ? schedule.totalSec : 0),
  };
}