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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
import { writeFile, mkdtemp, rm, stat, utimes } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';
import {
__analyzeBeatGridPcm,
decodeAudioToPcm,
getBeatGrid,
__clearBeatGridCache,
BEAT_GRID_SAMPLE_RATE,
} from './beatGrid.js';
import { findFfmpeg } from './ffmpeg.js';
/**
* Synthesize a mono click track: a short decaying 1kHz burst on every beat at
* the given BPM, over a quiet noise floor. Mirrors the fixture
* `server/services/musicVideo/audioAnalysis.test.js` uses for the same style
* of pipeline — a known tempo with sharp onsets the envelope/autocorrelation
* path must recover.
*/
function clickTrack({ bpm, durationSec, sampleRate = BEAT_GRID_SAMPLE_RATE, offsetSec = 0 }) {
const n = Math.round(durationSec * sampleRate);
const out = new Float32Array(n);
let seed = 12345;
const rand = () => { seed = (seed * 1103515245 + 12345) & 0x7fffffff; return (seed / 0x7fffffff) * 2 - 1; };
for (let i = 0; i < n; i++) out[i] = rand() * 0.001;
const periodSec = 60 / bpm;
const burstSec = 0.04;
const burstLen = Math.round(burstSec * sampleRate);
for (let t = offsetSec; t < durationSec; t += periodSec) {
const start = Math.round(t * sampleRate);
for (let k = 0; k < burstLen && start + k < n; k++) {
const env = Math.exp(-k / (burstLen / 4));
out[start + k] += env * Math.sin((2 * Math.PI * 1000 * k) / sampleRate);
}
}
return out;
}
// Long beatless noise intro, then a regular pulse: the full-track
// autocorrelation peak falls below the significance floor, so only the
// windowed tempo fallback shared with the Music Video analyzer (#9424) can
// measure it.
function lateClickTrack({ bpm, introSec, rhythmicSec, sampleRate = BEAT_GRID_SAMPLE_RATE }) {
const out = new Float32Array(Math.round((introSec + rhythmicSec) * sampleRate));
let seed = 7;
for (let i = 0; i < introSec * sampleRate; i++) {
seed = (seed * 1103515245 + 12345) & 0x7fffffff;
out[i] = ((seed / 0x7fffffff) * 2 - 1) * 0.15;
}
const burstLen = Math.round(0.025 * sampleRate);
for (let t = introSec; t < introSec + rhythmicSec; t += 60 / bpm) {
const start = Math.round(t * sampleRate);
for (let k = 0; k < burstLen && start + k < out.length; k++) {
out[start + k] += 0.8 * Math.exp(-k / (burstLen / 5)) * Math.sin((2 * Math.PI * 1200 * k) / sampleRate);
}
}
return out;
}
/** Minimal 16-bit PCM mono WAV encoder for the ffmpeg round-trip test. */
function encodeWav(samples, sampleRate) {
const numSamples = samples.length;
const dataSize = numSamples * 2;
const buf = Buffer.alloc(44 + dataSize);
buf.write('RIFF', 0);
buf.writeUInt32LE(36 + dataSize, 4);
buf.write('WAVE', 8);
buf.write('fmt ', 12);
buf.writeUInt32LE(16, 16);
buf.writeUInt16LE(1, 20); // PCM
buf.writeUInt16LE(1, 22); // mono
buf.writeUInt32LE(sampleRate, 24);
buf.writeUInt32LE(sampleRate * 2, 28); // byte rate
buf.writeUInt16LE(2, 32); // block align
buf.writeUInt16LE(16, 34); // bits per sample
buf.write('data', 36);
buf.writeUInt32LE(dataSize, 40);
for (let i = 0; i < numSamples; i++) {
const s = Math.max(-1, Math.min(1, samples[i]));
buf.writeInt16LE(Math.round(s * 32767), 44 + i * 2);
}
return buf;
}
// Tolerance grounded in what this style of pipeline actually measures on a
// synthetic click track (spectral-flux onset envelope + autocorrelation) —
// verified against `server/services/musicVideo/audioAnalysis.js`'s own
// already-shipped, already-tested tempo estimator on the SAME fixture, which
// reports the identical ~1.5-2 BPM offset (audioAnalysis.test.js asserts a
// ±2 window, not ±1). A tighter bound here would just be testing a level of
// precision this class of algorithm doesn't deliver on ~16s of audio.
const BPM_TOLERANCE = 2.5;
describe('__analyzeBeatGridPcm', () => {
it('recovers a 120 BPM click track within tolerance', () => {
const samples = clickTrack({ bpm: 120, durationSec: 16 });
const result = __analyzeBeatGridPcm(samples, BEAT_GRID_SAMPLE_RATE);
expect(result.bpm).toBeGreaterThan(120 - BPM_TOLERANCE);
expect(result.bpm).toBeLessThan(120 + BPM_TOLERANCE);
// Beats are monotonically increasing, spaced ~0.5s apart (60/120), and
// downbeats are every 4th beat.
for (let i = 1; i < result.beats.length; i++) {
expect(result.beats[i]).toBeGreaterThan(result.beats[i - 1]);
const gap = result.beats[i] - result.beats[i - 1];
expect(gap).toBeGreaterThan(0.45);
expect(gap).toBeLessThan(0.55);
}
expect(result.downbeats.length).toBeGreaterThan(0);
for (const downbeat of result.downbeats) expect(result.beats).toContain(downbeat);
for (let i = 1; i < result.downbeats.length; i++) {
const gap = result.downbeats[i] - result.downbeats[i - 1];
expect(gap).toBeGreaterThan(1.8);
expect(gap).toBeLessThan(2.2);
}
});
it('avoids the classic double-tempo octave error on a 90 BPM track', () => {
// 180 BPM (exactly double) is the documented common failure mode for
// autocorrelation-based tempo estimation without preference weighting.
const samples = clickTrack({ bpm: 90, durationSec: 20 });
const result = __analyzeBeatGridPcm(samples, BEAT_GRID_SAMPLE_RATE);
expect(result.bpm).toBeGreaterThan(90 - BPM_TOLERANCE);
expect(result.bpm).toBeLessThan(90 + BPM_TOLERANCE);
});
it('recovers onset hits close to each click', () => {
const samples = clickTrack({ bpm: 120, durationSec: 8 });
const result = __analyzeBeatGridPcm(samples, BEAT_GRID_SAMPLE_RATE);
expect(result.hits.length).toBeGreaterThan(10);
// Every true click (60/120 = 0.5s apart) has a detected hit within one
// onset-envelope frame (~23ms at this hop/sample-rate).
for (let t = 1; t < 8; t += 0.5) {
const nearest = result.hits.reduce((best, h) => (Math.abs(h - t) < Math.abs(best - t) ? h : best), Infinity);
expect(Math.abs(nearest - t)).toBeLessThan(0.06);
}
});
it('measures a tempo after a long beatless intro via the windowed fallback', () => {
const samples = lateClickTrack({ bpm: 108, introSec: 45, rhythmicSec: 30 });
const result = __analyzeBeatGridPcm(samples, BEAT_GRID_SAMPLE_RATE);
expect(result.bpm).toBeGreaterThan(105);
expect(result.bpm).toBeLessThan(111);
expect(result.beats.length).toBeGreaterThan(100);
expect(result.tempoConfidence).toBeGreaterThanOrEqual(0.3);
});
it('reports no tempo for silence/noise rather than a bogus BPM', () => {
const samples = new Float32Array(BEAT_GRID_SAMPLE_RATE * 4);
const result = __analyzeBeatGridPcm(samples, BEAT_GRID_SAMPLE_RATE);
expect(result.bpm).toBeNull();
expect(result.beats).toEqual([]);
expect(result.downbeats).toEqual([]);
});
it('returns a null-shaped result for audio too short to analyze', () => {
// 1000 samples clears the rounding floor (durationSec > 0) but stays
// under the hop*4 minimum the DSP core requires to form a single frame.
const result = __analyzeBeatGridPcm(new Float32Array(1000), BEAT_GRID_SAMPLE_RATE);
expect(result.bpm).toBeNull();
expect(result.beats).toEqual([]);
expect(result.hits).toEqual([]);
expect(result.durationSec).toBeGreaterThan(0);
});
it('tolerates an empty/undefined sample buffer', () => {
expect(__analyzeBeatGridPcm(null, BEAT_GRID_SAMPLE_RATE).bpm).toBeNull();
expect(__analyzeBeatGridPcm(new Float32Array(0), BEAT_GRID_SAMPLE_RATE).durationSec).toBe(0);
});
});
describe('decodeAudioToPcm (ffmpeg round-trip)', () => {
let tmpDir;
let ffmpeg;
beforeAll(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'portos-beatgrid-test-'));
ffmpeg = await findFfmpeg();
});
afterAll(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
it('returns null for a nonexistent file', async () => {
expect(await decodeAudioToPcm('/no/such/file.wav')).toBeNull();
});
it('returns null for an already-aborted signal', async () => {
const controller = new AbortController();
controller.abort();
expect(await decodeAudioToPcm(join(tmpDir, 'whatever.wav'), { signal: controller.signal })).toBeNull();
});
// Issue #9652: a wedged ffmpeg must not hang the caller forever.
it('kills ffmpeg and resolves null when the decode exceeds timeoutMs (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping decode-timeout test'); return; }
const wavSampleRate = 44100;
const wavPath = join(tmpDir, 'timeout.wav');
await writeFile(wavPath, encodeWav(clickTrack({ bpm: 120, durationSec: 10, sampleRate: wavSampleRate }), wavSampleRate));
expect(await decodeAudioToPcm(wavPath, { timeoutMs: 1 })).toBeNull();
});
it('decodes a synthesized WAV to PCM at BEAT_GRID_SAMPLE_RATE (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping beat-grid decode round-trip'); return; }
const wavSampleRate = 44100;
const samples = clickTrack({ bpm: 120, durationSec: 10, sampleRate: wavSampleRate });
const wavPath = join(tmpDir, 'click-120.wav');
await writeFile(wavPath, encodeWav(samples, wavSampleRate));
const decoded = await decodeAudioToPcm(wavPath);
expect(decoded).not.toBeNull();
expect(decoded.sampleRate).toBe(BEAT_GRID_SAMPLE_RATE);
expect(decoded.samples.length).toBeGreaterThan(0);
const result = __analyzeBeatGridPcm(decoded.samples, decoded.sampleRate);
expect(result.bpm).toBeGreaterThan(120 - BPM_TOLERANCE);
expect(result.bpm).toBeLessThan(120 + BPM_TOLERANCE);
});
// Issue #8973: decodeAudioToPcm must bound decoded PCM size regardless of
// source track length, rather than buffering the whole file. Encoding a
// real multi-minute fixture would make this suite slow, so this exercises
// the same ffmpeg `-t` truncation path against a short fixture via the
// `maxDurationSec` test seam.
it('truncates decode to maxDurationSec instead of buffering the whole track (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping truncation round-trip'); return; }
const wavSampleRate = 44100;
const samples = clickTrack({ bpm: 120, durationSec: 10, sampleRate: wavSampleRate });
const wavPath = join(tmpDir, 'click-120-long.wav');
await writeFile(wavPath, encodeWav(samples, wavSampleRate));
const decoded = await decodeAudioToPcm(wavPath, { maxDurationSec: 2 });
expect(decoded).not.toBeNull();
expect(decoded.sampleRate).toBe(BEAT_GRID_SAMPLE_RATE);
// Truncated to ~2s, not the full ~10s the source contains.
expect(decoded.samples.length).toBeGreaterThan(BEAT_GRID_SAMPLE_RATE * 1.5);
expect(decoded.samples.length).toBeLessThan(BEAT_GRID_SAMPLE_RATE * 3);
});
});
describe('getBeatGrid (mtime-keyed cache)', () => {
let tmpDir;
let ffmpeg;
beforeAll(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'portos-beatgrid-cache-test-'));
ffmpeg = await findFfmpeg();
});
afterAll(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
afterEach(() => __clearBeatGridCache());
it('returns null for a missing path', async () => {
expect(await getBeatGrid(join(tmpDir, 'missing.wav'))).toBeNull();
});
it('returns null for an invalid path argument', async () => {
expect(await getBeatGrid('')).toBeNull();
expect(await getBeatGrid(null)).toBeNull();
});
it('caches strictly by mtime, not by content (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping beat-grid cache round-trip'); return; }
const wavSampleRate = 44100;
const wavPath = join(tmpDir, 'cache-track.wav');
await writeFile(wavPath, encodeWav(clickTrack({ bpm: 100, durationSec: 6, sampleRate: wavSampleRate }), wavSampleRate));
const first = await getBeatGrid(wavPath);
expect(first).not.toBeNull();
expect(first.bpm).toBeGreaterThan(100 - BPM_TOLERANCE);
expect(first.bpm).toBeLessThan(100 + BPM_TOLERANCE);
// A repeat call against the unchanged file must be an actual cache HIT,
// not a coincidentally-identical recomputation (the DSP is deterministic,
// so `toEqual` alone can't tell the two apart). `toBe` asserts the same
// object reference, which only a real cache hit can produce — a fresh
// analysis always allocates a new result object.
const second = await getBeatGrid(wavPath);
expect(second).toBe(first);
// Overwrite with a different tempo, then bump mtime forward explicitly
// (rather than relying on write-induced mtime resolution, which can be
// coarser than the gap between two writes on some filesystems — a plain
// write's own timestamp could otherwise land in the same millisecond as
// the original). The cache must invalidate and return a freshly measured,
// distinct result.
await writeFile(wavPath, encodeWav(clickTrack({ bpm: 130, durationSec: 6, sampleRate: wavSampleRate }), wavSampleRate));
const stats = await stat(wavPath);
await utimes(wavPath, stats.atime, new Date(stats.mtime.getTime() + 1000));
const updated = await getBeatGrid(wavPath);
expect(updated).not.toBeNull();
expect(updated).not.toBe(first);
expect(updated.bpm).toBeGreaterThan(130 - BPM_TOLERANCE);
expect(updated.bpm).toBeLessThan(130 + BPM_TOLERANCE);
});
it('shares one in-flight analysis across concurrent calls for the same unmeasured track (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping beat-grid in-flight dedup'); return; }
const wavSampleRate = 44100;
const wavPath = join(tmpDir, 'concurrent-track.wav');
await writeFile(wavPath, encodeWav(clickTrack({ bpm: 120, durationSec: 6, sampleRate: wavSampleRate }), wavSampleRate));
// Two concurrent callers against the same never-yet-cached path must
// resolve to the SAME object — proof they shared one decode+analysis
// rather than each spawning their own ffmpeg process.
const [a, b] = await Promise.all([getBeatGrid(wavPath), getBeatGrid(wavPath)]);
expect(a).not.toBeNull();
expect(b).toBe(a);
});
// Issue #9652: the shared in-flight analysis used to run on the FIRST
// caller's signal, so that caller aborting nulled the grid for every other
// waiter. Caller A is the first to start (it owns the analysis) and aborts
// while B is still waiting; B must still get a real grid.
it('does not let the first caller aborting cancel the shared analysis for another caller (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping abort-isolation test'); return; }
const wavSampleRate = 44100;
const wavPath = join(tmpDir, 'abort-isolation.wav');
await writeFile(wavPath, encodeWav(clickTrack({ bpm: 120, durationSec: 6, sampleRate: wavSampleRate }), wavSampleRate));
const controllerA = new AbortController();
const pA = getBeatGrid(wavPath, { signal: controllerA.signal });
// Let A register the shared analysis (stat resolved, decode starting)
// before B joins, so A is deterministically the analysis owner.
await new Promise((r) => setTimeout(r, 10));
const pB = getBeatGrid(wavPath);
controllerA.abort();
const [a, b] = await Promise.all([pA, pB]);
expect(a).toBeNull();
expect(b).not.toBeNull();
expect(b.bpm).toBeGreaterThan(120 - BPM_TOLERANCE);
expect(b.bpm).toBeLessThan(120 + BPM_TOLERANCE);
});
it('returns null for every caller when all of them abort, and leaves nothing wedged in flight (skipped without ffmpeg)', async () => {
if (!ffmpeg) { console.log('⏭️ ffmpeg not found — skipping all-abort test'); return; }
const wavSampleRate = 44100;
const wavPath = join(tmpDir, 'abort-all.wav');
await writeFile(wavPath, encodeWav(clickTrack({ bpm: 120, durationSec: 6, sampleRate: wavSampleRate }), wavSampleRate));
const c1 = new AbortController();
const c2 = new AbortController();
const p1 = getBeatGrid(wavPath, { signal: c1.signal });
const p2 = getBeatGrid(wavPath, { signal: c2.signal });
c1.abort();
c2.abort();
expect(await Promise.all([p1, p2])).toEqual([null, null]);
// A later, healthy caller measures fresh rather than inheriting the abort.
expect(await getBeatGrid(wavPath)).not.toBeNull();
});
});