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

21.5 KB
Raw Blame
// @vitest-environment node

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { parseDrumChart } from './drumNotation.js';
import { createDrumPlayer } from './drumPlayback.js';
import { parseScore } from './scoreNotation.js';
import { createScorePlayer } from './scorePlayback.js';
import { acquireAudioSession } from './audioContext.js';
import { createFakeAudio } from '../test/fakeAudioContext.js';

// The AUDIBLE half of drumPlayback.js — buildDrumSchedule's pure math is covered
// in drumPlayback.test.js with no Web Audio at all. This suite drives the real
// lookahead transport against the shared Web Audio fake, so the wiring (voices
// actually scheduled, playhead callbacks, loop rebase, teardown) is pinned.
//
// One fake pair for the whole file — lib/audioContext.js caches the context.
const { FakeAudioContext, audio } = createFakeAudio();

// GainNodes the player builds before any voice: the drum master and the
// metronome's own click bus. Every later gain in `audio.gains` is a voice
// envelope, so tests that reason about voices skip these two.
const BUS_GAINS = 2;

// Metronome blips that actually sounded: CLICK_VOICE is a lone square starting
// at 1600 Hz, a frequency no kit voice uses (noise sources carry no `frequency`).
const clickBlips = () => audio.oscillators.filter((o) => o.frequency?.values[0] === 1600);

// A bus's current level: set outright when the bus is built, then glided with
// setTargetAtTime on a live change (which the fake records into `values`).
const busLevel = (bus) => (bus.gain.values.length ? bus.gain.values.at(-1) : bus.gain.value);

// Advance the audio clock relatively, ticking the lookahead interval alongside.
const drive = (deltaSec) => {
  const target = audio.now + deltaSec;
  for (let t = audio.now + 0.05; t <= target + 1e-9; t += 0.05) {
    audio.now = Number(t.toFixed(4));
    vi.advanceTimersByTime(50);
  }
};

// Invented groove (privacy convention): 2 bars, subdivision 1 (one cell/beat) at
// 240 bpm → 0.25s/beat, 1s/bar, so the whole chart is 2s.
const CHART = parseDrumChart(`time: 4/4
tempo: 240
subdivision: 1

# A
HH: xxxx
K: o-o-

# B
S: x-x-`);

describe('createDrumPlayer', () => {
  beforeEach(() => {
    audio.reset();
    vi.stubGlobal('AudioContext', FakeAudioContext);
    vi.useFakeTimers();
  });
  afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); });

  it('sounds a voice per hit and finishes with onEnded', async () => {
    const ended = vi.fn();
    const player = createDrumPlayer(CHART, { onEnded: ended });
    await player.play();
    drive(3);
    // 4 hats + 2 kicks + 2 snares = 8 hits. The snare voice layers a body tone,
    // so voices ≥ hits — what matters is that every hit sounded.
    expect(audio.oscillators.length).toBeGreaterThanOrEqual(8);
    expect(ended).toHaveBeenCalledTimes(1);
    expect(player.isPlaying()).toBe(false);
  });

  it('uses filtered noise for the hat and a pitched sweep for the kick', async () => {
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nHH: x---\nK: -o--'), {});
    await player.play();
    drive(2);
    // The hat is a filtered noise burst; the kick's body is a pitched oscillator.
    expect(audio.oscillators.some((o) => o.noise)).toBe(true);
    expect(audio.filters.length).toBeGreaterThan(0);
    const swept = audio.oscillators.filter((o) => !o.noise && o.frequency.values.length > 1);
    expect(swept.length).toBeGreaterThan(0);
    // Every sweep DROPS in pitch — a membrane falling to its fundamental.
    expect(swept.every((o) => o.frequency.values[1] < o.frequency.values[0])).toBe(true);
  });

  it('drops the kick pitch far faster than its amplitude decays', async () => {
    // The punch fix: the pitch envelope and the amplitude envelope are separate.
    // A kick whose sweep runs the full length of its tail is the weak-sounding
    // recipe this replaced, so the two are pinned apart here rather than left to
    // whichever numbers a kit happens to carry.
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nK: o---'), {});
    await player.play();
    drive(0.2);
    const body = audio.oscillators.find((o) => !o.noise && o.frequency.values.length > 1);
    expect(body).toBeDefined();
    // stop() is scheduled at attack + decay + 0.02 — a proxy for the amp tail.
    const ampTail = body.stopped - body.started;
    expect(ampTail).toBeGreaterThan(0.3);
    // …and the sweep lands in the first tenth of it (~30–60ms in every kit).
    expect(body.frequency.values[1]).toBeLessThan(body.frequency.values[0] / 2);
    player.stop();
  });

  it('routes the kick body through a drive shaper, and the bus through a clipper', async () => {
    // A sub-50Hz sine is inaudible on a phone speaker; the drive shaper supplies
    // the harmonics that make it read. Both shapers are load-bearing for the
    // "the kick sounds weak" fix, so both are pinned — structurally, off the
    // fake's recorded connections rather than off node creation order.
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nK: o---'), {});
    await player.play();
    drive(0.2);
    const body = audio.oscillators.find((o) => !o.noise && o.frequency.values.length > 1);
    expect(audio.shapers).toContain(body.connections[0]);
    // The master gain feeds a shaper, which feeds the destination.
    const busShaper = audio.shapers.find((s) => s.connections.some((t) => t?.id === 'destination'));
    expect(busShaper).toBeDefined();
    expect(audio.gains.some((g) => g.connections.includes(busShaper))).toBe(true);
    // Every curve is a real saturation curve: bounded to ±1 and monotonic.
    for (const shaper of audio.shapers) {
      expect(shaper.curve.length).toBeGreaterThan(0);
      expect(Math.max(...shaper.curve)).toBeLessThanOrEqual(1);
      expect(Math.min(...shaper.curve)).toBeGreaterThanOrEqual(-1);
      expect(shaper.curve.every((v, i, a) => i === 0 || v >= a[i - 1])).toBe(true);
    }
    player.stop();
  });

  it('scales voice gain by the glyph velocity (accent louder than ghost)', async () => {
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nHH: X-g-'), {});
    await player.play();
    drive(2);
    // Creation order is [master, click bus, ...accent layers, ...ghost layers] —
    // the two buses are built up front in prepare(), and a voice can be several
    // layers (the 808 hat is a six-oscillator cluster), so compare the two halves
    // rather than two fixed indices.
    const peaks = audio.gains.slice(BUS_GAINS).map((g) => Math.max(...g.gain.values, 0));
    const half = peaks.length / 2;
    expect(Number.isInteger(half)).toBe(true);
    expect(Math.max(...peaks.slice(0, half))).toBeGreaterThan(Math.max(...peaks.slice(half)));
    player.stop();
  });

  it('setKit swaps the voices live, without stopping playback', async () => {
    const player = createDrumPlayer(parseDrumChart('tempo: 120\nsubdivision: 1\n\nHH: xxxx'), {});
    await player.play();
    drive(0.5);
    // The default 909 hat is one noise burst.
    expect(audio.oscillators.every((o) => o.noise)).toBe(true);
    player.setKit('808');
    drive(1);
    // The 808's is a square cluster — so the swap shows up as pitched sources
    // appearing mid-run, and playback never stopped to do it.
    expect(audio.oscillators.some((o) => !o.noise)).toBe(true);
    expect(player.isPlaying()).toBe(true);
    player.stop();
  });

  it('shares one filter and envelope across a square cluster', async () => {
    // The 808 hat is six oscillators; they must sum into ONE filter + gain (a
    // biquad is linear, so per-partial filters would be six times the nodes for
    // an identical signal) while each partial stays individually stoppable.
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nHH: x---'), {
      kit: '808',
    });
    await player.play();
    drive(0.2);
    expect(audio.oscillators.length).toBeGreaterThan(1);
    expect(audio.filters).toHaveLength(1);
    expect(audio.gains).toHaveLength(BUS_GAINS + 1); // the buses + one voice envelope
    for (const osc of audio.oscillators) expect(osc.connections).toEqual([audio.filters[0]]);
    player.stop();
    // Every partial was stopped — one tracked entry per oscillator, so an open
    // hat or a 1.2s crash can't ring on after Stop.
    expect(audio.oscillators.every((o) => o.stopped !== null)).toBe(true);
  });

  it('falls back to the default kit for an unknown id rather than going silent', async () => {
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nK: o---'), {
      kit: 'roland-tr-nope',
    });
    await player.play();
    drive(2);
    expect(audio.oscillators.length).toBeGreaterThan(0);
  });

  it('reports the playhead per grid position, once per bar+step', async () => {
    const steps = [];
    const player = createDrumPlayer(CHART, { onStep: (info) => steps.push(info) });
    await player.play();
    drive(3);
    const positions = steps.filter(Boolean).map((s) => `${s.bar}:${s.step}`);
    // Simultaneous hats+kick at bar 1 step 0 collapse to ONE callback.
    expect(positions[0]).toBe('1:0');
    expect(new Set(positions).size).toBe(positions.length);
    expect(positions).toContain('2:0');
    // The final callback clears the playhead.
    expect(steps.at(-1)).toBeNull();
  });

  it('reports count-in beats as countIn with no bar/step', async () => {
    const steps = [];
    const player = createDrumPlayer(CHART, { countInBars: 1, onStep: (i) => steps.push(i) });
    await player.play();
    drive(0.6); // still inside the 1s count-in bar
    const counted = steps.filter((s) => s?.countIn);
    expect(counted.length).toBeGreaterThan(0);
    expect(counted[0]).toMatchObject({ bar: null, step: null, countIn: true });
    player.stop();
  });

  it('loops a bar range without ending and without re-counting-in', async () => {
    const ended = vi.fn();
    const steps = [];
    const player = createDrumPlayer(CHART, {
      loopBars: { from: 2, to: 2 }, countInBars: 1, onEnded: ended, onStep: (i) => steps.push(i),
    });
    await player.play();
    drive(6); // several passes over a 1-bar loop
    expect(ended).not.toHaveBeenCalled();
    expect(player.isPlaying()).toBe(true);
    // Only bar 2 ever sounds; the count-in happens exactly once.
    const music = steps.filter((s) => s && !s.countIn);
    expect(new Set(music.map((s) => s.bar))).toEqual(new Set([2]));
    expect(music.length).toBeGreaterThan(3); // looped, not a single pass
    player.stop();
  });

  it('layers a click when enabled and not when disabled', async () => {
    const quiet = createDrumPlayer(CHART, {});
    await quiet.play();
    drive(2.5);
    const withoutClick = audio.oscillators.length;
    quiet.stop();

    audio.reset();
    const clicked = createDrumPlayer(CHART, { clickEnabled: true });
    await clicked.play();
    drive(2.5);
    // 8 beats of click over the two bars.
    expect(audio.oscillators.length).toBeGreaterThan(withoutClick);
    clicked.stop();
  });

  it('sounds the click on its own bus, at the level it was built with', async () => {
    const player = createDrumPlayer(CHART, { clickEnabled: true, clickVolume: 0.4 });
    await player.play();
    drive(1);
    const [master, clickBus] = audio.gains;
    // The bus hangs off the drum master (so it still goes through the master
    // soft-clipper) and carries the level.
    expect(clickBus.connections).toEqual([master]);
    expect(busLevel(clickBus)).toBe(0.4);
    // Every click envelope feeds the bus, and no KIT voice does.
    const clickVoices = audio.gains.filter((g) => g.connections.includes(clickBus));
    expect(clickVoices.length).toBeGreaterThan(0);
    // Nothing on the master is also on the click bus — a kit voice riding the
    // click bus would duck with the metronome slider.
    const masterVoices = audio.gains.filter((g) => g.connections.includes(master));
    expect(masterVoices.some((g) => clickVoices.includes(g))).toBe(false);
    player.stop();
  });

  it('setClickVolume moves the bus live, without stopping playback', async () => {
    const player = createDrumPlayer(CHART, { clickEnabled: true });
    await player.play();
    drive(0.5);
    const clickBus = audio.gains[1];
    expect(busLevel(clickBus)).toBe(1); // default: unchanged from before
    // A bus move reaches clicks ALREADY scheduled in the lookahead window — that
    // is the whole reason the level isn't folded into each click's velocity.
    player.setClickVolume(0.25);
    expect(busLevel(clickBus)).toBe(0.25);
    expect(player.isPlaying()).toBe(true);
    // A garbled level is ignored rather than silencing the click.
    player.setClickVolume('nope');
    expect(busLevel(clickBus)).toBe(0.25);
    player.stop();
  });

  it('schedules no click voice at all once the level is zero', async () => {
    // Dragging the slider to 0 deliberately does NOT flip the mute toggle, and
    // the level persists — so a silent click that still built a voice per beat
    // would do that forever, on every chart, for nothing.
    const muted = createDrumPlayer(CHART, { clickEnabled: false });
    await muted.play();
    drive(2.5);
    const kitOnly = audio.oscillators.length;
    muted.stop();

    audio.reset();
    const zeroed = createDrumPlayer(CHART, { clickEnabled: true, clickVolume: 0 });
    await zeroed.play();
    drive(2.5);
    // Level 0 costs exactly what muting costs: not one extra node, and not one
    // click blip.
    expect(audio.oscillators).toHaveLength(kitOnly);
    expect(clickBlips()).toHaveLength(0);
    zeroed.stop();

    // Turning it back up mid-run resumes the click without a restart.
    audio.reset();
    const raised = createDrumPlayer(CHART, { clickEnabled: true, clickVolume: 0 });
    await raised.play();
    drive(0.5);
    expect(clickBlips()).toHaveLength(0);
    raised.setClickVolume(1);
    drive(1);
    expect(clickBlips().length).toBeGreaterThan(0);
    raised.stop();
  });

  it('counts in with the metronome click, not with the kit snare', async () => {
    // `sound: 'click'` is not a kit piece — left to kitVoiceLayers it falls
    // through to the SNARE, which made a count-in four snare hits.
    const player = createDrumPlayer(parseDrumChart('tempo: 240\nsubdivision: 1\n\nK: o---'), {
      countInBars: 1, clickEnabled: false, clickVolume: 0.5,
    });
    await player.play();
    drive(1.2); // the 1s count-in bar, then the kick on bar 1
    const clickBus = audio.gains[1];
    // Four click blips, one per count-in beat, each routed through the bus.
    const blips = clickBlips();
    expect(blips).toHaveLength(4);
    expect(audio.gains.filter((g) => g.connections.includes(clickBus))).toHaveLength(4);
    // The count-in sounds even with the through-music click muted ("just count
    // me in"), and the kick still lands on the kit master.
    expect(audio.oscillators.length).toBeGreaterThan(blips.length);
    player.stop();
  });

  it('stop() clears the interval, silences live voices and clears the playhead', async () => {
    const steps = [];
    const player = createDrumPlayer(CHART, { onStep: (i) => steps.push(i) });
    await player.play();
    drive(0.5);
    const scheduled = audio.oscillators.length;
    expect(scheduled).toBeGreaterThan(0);
    player.stop();
    expect(steps.at(-1)).toBeNull();
    // Every voice was stopped, and nothing further schedules.
    expect(audio.oscillators.every((o) => o.stopped !== null)).toBe(true);
    drive(3);
    expect(audio.oscillators).toHaveLength(scheduled);
    expect(player.isPlaying()).toBe(false);
  });

  it('setBpm while idle re-times the schedule; a faster tempo is shorter', async () => {
    const player = createDrumPlayer(CHART, {});
    expect(player.schedule().totalSec).toBeCloseTo(2, 5); // 240 bpm written
    player.setBpm(120);
    expect(player.schedule().totalSec).toBeCloseTo(4, 5);
    player.setBpm(240);
    expect(player.schedule().totalSec).toBeCloseTo(2, 5);
  });

  it('setLoop while idle narrows the schedule to the range', () => {
    const player = createDrumPlayer(CHART, {});
    expect(player.schedule().bars).toHaveLength(2);
    player.setLoop({ from: 2, to: 2 });
    expect(player.schedule().bars.map((b) => b.index)).toEqual([2]);
    player.setLoop(null);
    expect(player.schedule().bars).toHaveLength(2);
  });

  it('setCountIn while idle prepends the lead-in', () => {
    const player = createDrumPlayer(CHART, {});
    expect(player.schedule().countInSec).toBe(0);
    player.setCountIn(2);
    expect(player.schedule().countInSec).toBeCloseTo(2, 5); // two 1s bars
  });

  it('an empty chart reports ended immediately and schedules nothing', async () => {
    const ended = vi.fn();
    const player = createDrumPlayer(parseDrumChart(''), { onEnded: ended });
    await player.play();
    expect(ended).toHaveBeenCalledTimes(1);
    expect(audio.oscillators).toHaveLength(0);
    expect(player.isPlaying()).toBe(false);
  });

  it('loops a single-bar range without spinning', async () => {
    const player = createDrumPlayer(parseDrumChart('subdivision: 1\n\nHH: x---'), {
      loopBars: { from: 1, to: 1 }, countInBars: 0,
    });
    await player.play();
    drive(2);
    expect(player.isPlaying()).toBe(true);
    player.stop();
  });

  it('finishes (never wedges) when the looped bar is all rests', async () => {
    // Two coupled guards, both keyed on canLoop(): the scheduler must not spin its
    // pass-rebase branch on a range with no music events (a rest-only bar has real
    // duration but nothing to repeat), AND the transport must not report an
    // Infinite length for it — otherwise playback sits "playing" forever after the
    // count-in. The chart's OTHER bar has hits, so Play is enabled.
    const ended = vi.fn();
    const chart = parseDrumChart('tempo: 240\nsubdivision: 1\n\n# A\nK: o---\n\n# B\nK: ----');
    const player = createDrumPlayer(chart, {
      loopBars: { from: 2, to: 2 }, countInBars: 1, onEnded: ended,
    });
    await player.play();
    drive(3); // would never return if the rebase spun
    expect(audio.oscillators.length).toBeGreaterThan(0); // the count-in still sounds
    expect(ended).toHaveBeenCalledTimes(1);
    expect(player.isPlaying()).toBe(false);
  });

  // The two iOS Safari failures that made the whole play-along silent on an
  // iPhone while the transport counted and the playhead scrolled.
  describe('on iOS Safari', () => {
    beforeEach(() => { vi.stubGlobal('navigator', { audioSession: { type: 'auto' } }); });

    it("resumes an 'interrupted' context instead of playing against a dead clock", async () => {
      // A call / Siri / the screen locking parks the context here. The old gate
      // read `state === 'suspended'`, walked past this, and armed the scheduler
      // against a clock that never advanced.
      audio.state = 'interrupted';
      const player = createDrumPlayer(CHART, {});
      const playing = player.play(); // parks on ctx.resume()
      expect(audio.resumeCalls).toBe(1);
      audio.flushResume();
      await playing;

      expect(player.isPlaying()).toBe(true);
      drive(1.5);
      expect(audio.oscillators.length).toBeGreaterThan(0);
      player.stop();
    });

    it('holds the playback audio session while sounding so the silent switch cannot mute it', async () => {
      const player = createDrumPlayer(CHART, {});
      await player.play();
      expect(globalThis.navigator.audioSession.type).toBe('playback');
      player.stop();
    });

    // The declaration is document-wide and marks the page output-only, so
    // holding it past playback would follow the user (SPA — no reload) onto the
    // Songs training views and kill their microphone.
    it('hands the session back on stop', async () => {
      const player = createDrumPlayer(CHART, {});
      await player.play();
      player.stop();
      expect(globalThis.navigator.audioSession.type).toBe('auto');
    });

    // The VoiceWidget is mounted on every page (Layout.jsx), so push-to-talk can
    // open the mic while a chart is playing. `playback` REFUSES capture, so the
    // arbiter has to promote — otherwise the fix for this page's silence would
    // have made the mic dead on it instead.
    it('yields to a mic opened mid-playback, then takes playback back', async () => {
      const player = createDrumPlayer(CHART, {});
      await player.play();
      const releaseMic = acquireAudioSession('play-and-record');
      expect(globalThis.navigator.audioSession.type).toBe('play-and-record');
      releaseMic();
      expect(globalThis.navigator.audioSession.type).toBe('playback');
      player.stop();
      expect(globalThis.navigator.audioSession.type).toBe('auto');
    });

    it('hands the session back when the chart ends on its own', async () => {
      const player = createDrumPlayer(CHART, {});
      await player.play();
      drive(3); // CHART is 2s — runs to its natural end
      expect(player.isPlaying()).toBe(false);
      expect(globalThis.navigator.audioSession.type).toBe('auto');
    });
  });
});

// Players hosted on pages that ALSO record must not declare an output-only
// session — the mic would go dead. Only a player that opts in via the
// transport's `audioSession` option touches it.
describe('players that do not opt into an audio session', () => {
  beforeEach(() => {
    audio.reset();
    vi.stubGlobal('AudioContext', FakeAudioContext);
    vi.stubGlobal('navigator', { audioSession: { type: 'auto' } });
    vi.useFakeTimers();
  });
  afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); });

  it('leaves the document audio session alone', async () => {
    const player = createScorePlayer(parseScore('tempo: 120\n| C4q D4q |'), { bpm: 120 });
    await player.play();
    expect(globalThis.navigator.audioSession.type).toBe('auto');
    player.stop();
  });
});