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, vi, beforeEach, afterEach, afterAll } from 'vitest';
import { tmpdir, platform as osPlatform, arch as osArch } from 'os';
import { join } from 'path';
import { rm, readdir } from 'fs/promises';
import { writeFileSync, mkdtempSync } from 'fs';
const cuda = vi.hoisted(() => ({ status: 'available', maxVramGb: 40 }));
vi.mock('../../lib/cudaCapability.js', () => ({
getCudaCapability: vi.fn(async () => ({ status: cuda.status, gpus: [], maxVramGb: cuda.maxVramGb, error: null })),
}));
vi.mock('../../lib/hfCache.js', () => ({
inspectModelCache: vi.fn(async () => ({ cached: true })),
}));
// ---- Pure-helper tests (no mocks needed) ---------------------------------
import {
buildMusicGenArgs,
buildSidecarArgs,
buildMinimaxInstrumentalLyrics,
ensureClosingSection,
clampDuration,
getMusicgenModel,
getEngine,
getEngineModel,
isEngineReady,
ENGINES,
DEFAULT_ENGINE_ID,
MUSICGEN_MODELS,
AUDIOLDM2_MODELS,
MINIMAX_MUSIC3_MLX_MODELS,
DEFAULT_MUSICGEN_MODEL_ID,
DEFAULT_AUDIOLDM2_MODEL_ID,
MIN_DURATION_SEC,
MAX_DURATION_SEC,
DEFAULT_DURATION_SEC,
MUSIC_VRAM_READINESS,
resolveVramReadiness,
resolveEngineVramReadiness,
MUSIC_RENDERER_BENCHMARK_GUIDE,
} from './musicGen.js';
describe('MUSICGEN_MODELS registry', () => {
it('has a stable, unique id + repo for each model', () => {
const ids = MUSICGEN_MODELS.map((m) => m.id);
expect(new Set(ids).size).toBe(ids.length);
for (const m of MUSICGEN_MODELS) {
expect(typeof m.id).toBe('string');
expect(m.repo).toMatch(/^facebook\/musicgen-/);
expect(typeof m.name).toBe('string');
}
});
it('default model id resolves to a real entry', () => {
expect(getMusicgenModel(DEFAULT_MUSICGEN_MODEL_ID)).toBeTruthy();
});
it('getMusicgenModel returns null for unknown ids', () => {
expect(getMusicgenModel('nope')).toBeNull();
expect(getMusicgenModel(undefined)).toBeNull();
});
});
describe('AUDIOLDM2_MODELS registry', () => {
it('has a stable, unique id + cvssp repo for each model', () => {
const ids = AUDIOLDM2_MODELS.map((m) => m.id);
expect(new Set(ids).size).toBe(ids.length);
for (const m of AUDIOLDM2_MODELS) {
expect(typeof m.id).toBe('string');
expect(m.repo).toMatch(/^cvssp\/audioldm2/);
expect(typeof m.name).toBe('string');
}
});
it('default model id resolves within the audioldm2 engine', () => {
expect(getEngineModel('audioldm2', DEFAULT_AUDIOLDM2_MODEL_ID)).toBeTruthy();
});
});
describe('ENGINES backend registry', () => {
it('exposes all backends with the fields the route + UI consume', () => {
expect(Object.keys(ENGINES).sort()).toEqual(['acestep', 'acestep15', 'audioldm2', 'minimax-music3', 'minimax-music3-mlx', 'musicgen']);
for (const engine of Object.values(ENGINES)) {
expect(typeof engine.id).toBe('string');
expect(typeof engine.name).toBe('string');
expect(Array.isArray(engine.models)).toBe(true);
expect(engine.models.length).toBeGreaterThan(0);
expect(engine.models.some((m) => m.id === engine.defaultModelId)).toBe(true);
expect(engine.minDurationSec).toBeGreaterThanOrEqual(1);
expect(engine.maxDurationSec).toBeGreaterThanOrEqual(engine.minDurationSec);
expect(engine.defaultDurationSec).toBeGreaterThanOrEqual(engine.minDurationSec);
expect(engine.defaultDurationSec).toBeLessThanOrEqual(engine.maxDurationSec);
expect(typeof engine.resolvePython).toBe('function');
expect(typeof engine.installEnv).toBe('string');
expect(engine.scriptPath).toMatch(/generate_\w+\.py$/);
}
});
it('default engine is musicgen (back-compat)', () => {
expect(DEFAULT_ENGINE_ID).toBe('musicgen');
expect(getEngine(DEFAULT_ENGINE_ID).id).toBe('musicgen');
});
it('audioldm2 has a wider duration window than musicgen (long-form)', () => {
expect(ENGINES.audioldm2.maxDurationSec).toBeGreaterThan(ENGINES.musicgen.maxDurationSec);
});
it('keeps ACE-Step 1.5 separate from v1 and requires its fixed installed snapshot', () => {
expect(ENGINES.acestep15).toMatchObject({
id: 'acestep15', installEnv: 'INSTALL_ACESTEP15', lyrics: true,
customModels: false, fixedModelInstall: true,
});
expect(ENGINES.acestep15.models).toEqual([expect.objectContaining({ repo: 'ACE-Step/Ace-Step1.5' })]);
expect(ENGINES.acestep15.scriptPath).toMatch(/generate_acestep15\.py$/);
expect(ENGINES.acestep.models[0].repo).toBe('ACE-Step/ACE-Step-v1-3.5B');
});
it('offers both pinned MLX MiniMax variants with 8-bit as the default', () => {
expect(ENGINES['minimax-music3-mlx']).toMatchObject({
id: 'minimax-music3-mlx',
name: expect.stringContaining('MiniMax-Music3'),
defaultModelId: 'minimax-music3-mlx-8bit',
installEnv: 'INSTALL_MINIMAX_MUSIC3_MLX',
lyrics: true,
customModels: false,
fixedModelInstall: true,
supportsModelRevision: true,
requiresPlatform: { platform: 'darwin', arch: 'arm64' },
});
expect(MINIMAX_MUSIC3_MLX_MODELS).toEqual([
expect.objectContaining({ id: 'minimax-music3-mlx-8bit', repo: 'mlx-community/MiniMax-Music3-8bit', revision: expect.stringMatching(/^[0-9a-f]{40}$/) }),
expect.objectContaining({ id: 'minimax-music3-mlx-bf16', repo: 'mlx-community/MiniMax-Music3-bf16', revision: expect.stringMatching(/^[0-9a-f]{40}$/) }),
]);
});
it('musicgen window mirrors the legacy module-level constants', () => {
expect(ENGINES.musicgen.minDurationSec).toBe(MIN_DURATION_SEC);
expect(ENGINES.musicgen.maxDurationSec).toBe(MAX_DURATION_SEC);
expect(ENGINES.musicgen.defaultDurationSec).toBe(DEFAULT_DURATION_SEC);
});
it('declares MiniMax VRAM requirements per execution profile', () => {
const engine = ENGINES['minimax-music3'];
expect(engine.executionProfile).toBe('cuda-bf16-auto-experimental');
expect(engine.vramProfiles[engine.executionProfile]).toMatchObject({
label: 'CUDA BF16 (automatic full-residency/offload placement)',
minVramGb: 20,
recommendedVramGb: 24,
});
});
it('records that MiniMax profile support has cleared technical checks plus full-length listening', () => {
expect(ENGINES['minimax-music3']).toMatchObject({
benchmarkGuide: MUSIC_RENDERER_BENCHMARK_GUIDE,
requiresFullLengthListening: false,
});
expect(MUSIC_RENDERER_BENCHMARK_GUIDE).toBe('docs/features/music-renderer-benchmarks.md');
});
});
describe('VRAM readiness', () => {
it('distinguishes sufficient, insufficient, and unknown measurements', () => {
expect(resolveVramReadiness({ cudaStatus: 'available', maxVramGb: 32, minVramGb: 24 }))
.toBe(MUSIC_VRAM_READINESS.SUFFICIENT);
expect(resolveVramReadiness({ cudaStatus: 'available', maxVramGb: 12, minVramGb: 24 }))
.toBe(MUSIC_VRAM_READINESS.INSUFFICIENT);
expect(resolveVramReadiness({ cudaStatus: 'available', maxVramGb: null, minVramGb: 24 }))
.toBe(MUSIC_VRAM_READINESS.UNKNOWN_SIZE);
expect(resolveVramReadiness({ cudaStatus: 'unknown', maxVramGb: 32, minVramGb: 24 }))
.toBe(MUSIC_VRAM_READINESS.UNKNOWN_SIZE);
});
it('reports the measured MiniMax CUDA execution profile as sufficient on a large card', () => {
expect(resolveEngineVramReadiness('minimax-music3', {
status: 'available', maxVramGb: 80,
})).toMatchObject({
state: MUSIC_VRAM_READINESS.SUFFICIENT,
executionProfile: 'cuda-bf16-auto-experimental',
minVramGb: 20,
recommendedVramGb: 24,
maxVramGb: 80,
});
});
it('reports the measured MiniMax CUDA execution profile as insufficient below its measured floor', () => {
expect(resolveEngineVramReadiness('minimax-music3', {
status: 'available', maxVramGb: 12,
})).toMatchObject({
state: MUSIC_VRAM_READINESS.INSUFFICIENT,
executionProfile: 'cuda-bf16-auto-experimental',
minVramGb: 20,
recommendedVramGb: 24,
maxVramGb: 12,
});
});
});
describe('getEngine / getEngineModel', () => {
it('falls back to the default engine for an unknown id', () => {
expect(getEngine('does-not-exist').id).toBe(DEFAULT_ENGINE_ID);
expect(getEngine(undefined).id).toBe(DEFAULT_ENGINE_ID);
});
it('resolves a model within the named engine', () => {
expect(getEngineModel('musicgen', 'musicgen-small').repo).toBe('facebook/musicgen-small');
expect(getEngineModel('audioldm2', 'audioldm2-large').repo).toBe('cvssp/audioldm2-large');
});
it('returns null when the model belongs to a different engine', () => {
// musicgen-small is not an audioldm2 model — selection must not bleed across engines.
expect(getEngineModel('audioldm2', 'musicgen-small')).toBeNull();
expect(getEngineModel('musicgen', 'audioldm2')).toBeNull();
});
});
describe('clampDuration', () => {
it('passes through an in-range value (default engine)', () => {
expect(clampDuration(12)).toBe(12);
});
it('floors at MIN and caps at MAX for musicgen', () => {
expect(clampDuration(0, 'musicgen')).toBe(ENGINES.musicgen.minDurationSec);
expect(clampDuration(-5, 'musicgen')).toBe(ENGINES.musicgen.minDurationSec);
expect(clampDuration(9999, 'musicgen')).toBe(ENGINES.musicgen.maxDurationSec);
});
it('uses the audioldm2 window when that engine is named', () => {
// 90s is over musicgen's 30s ceiling but inside audioldm2's window.
expect(clampDuration(90, 'audioldm2')).toBe(90);
expect(clampDuration(9999, 'audioldm2')).toBe(ENGINES.audioldm2.maxDurationSec);
});
it('falls back to the engine default on non-finite input', () => {
expect(clampDuration(NaN, 'musicgen')).toBe(ENGINES.musicgen.defaultDurationSec);
expect(clampDuration('abc', 'audioldm2')).toBe(ENGINES.audioldm2.defaultDurationSec);
expect(clampDuration(undefined)).toBe(DEFAULT_DURATION_SEC);
});
});
describe('buildSidecarArgs', () => {
it('routes ACE-Step 1.5 to its own sidecar with the fixed model repo and lyrics', () => {
const { args } = buildSidecarArgs({
engineId: 'acestep15', pythonPath: '/venv/python', repo: 'ACE-Step/Ace-Step1.5',
prompt: 'bright pop', lyrics: '[Verse] Example', durationSec: 999, outputPath: '/tmp/out.wav',
});
expect(args[0]).toMatch(/generate_acestep15\.py$/);
expect(args.slice(args.indexOf('--model'), args.indexOf('--model') + 2)).toEqual(['--model', 'ACE-Step/Ace-Step1.5']);
expect(args.slice(args.indexOf('--duration'), args.indexOf('--duration') + 2)).toEqual(['--duration', '240']);
expect(args.slice(args.indexOf('--lyrics'), args.indexOf('--lyrics') + 2)).toEqual(['--lyrics', '[Verse] Example']);
});
it('builds MiniMax Music 3 args with lyrics and clamps to five minutes', () => {
const { args } = buildSidecarArgs({
engineId: 'minimax-music3', pythonPath: '/venv/python', repo: 'MiniMaxAI/MiniMax-Music3',
prompt: 'cinematic synthwave', lyrics: 'Example lyrics', durationSec: 999, outputPath: '/tmp/out.wav',
});
expect(args).toContain('MiniMaxAI/MiniMax-Music3');
expect(args.slice(args.indexOf('--duration'), args.indexOf('--duration') + 2)).toEqual(['--duration', '300']);
// A sheet with no closing section gets an [outro] cue appended so the model
// resolves its ending; the caller's words still lead the sheet.
expect(args.slice(args.indexOf('--lyrics'), args.indexOf('--lyrics') + 2))
.toEqual(['--lyrics', 'Example lyrics\n[outro]']);
});
it('pins the selected MLX checkpoint revision in the sidecar args', () => {
const { args } = buildSidecarArgs({
engineId: 'minimax-music3-mlx', pythonPath: '/venv/python', repo: 'mlx-community/MiniMax-Music3-8bit',
revision: '10aa4ca578d04c6f5256c1bc22fc8405a09602b5', prompt: 'bright pop', lyrics: '[verse] Example',
durationSec: 30, outputPath: '/tmp/out.wav',
});
expect(args.slice(args.indexOf('--revision'), args.indexOf('--revision') + 2)).toEqual([
'--revision', '10aa4ca578d04c6f5256c1bc22fc8405a09602b5',
]);
expect(args[0]).toMatch(/generate_minimax_music3_mlx\.py$/);
// MLX carries ensureOutro too — confirm the flag isn't scoped to the CUDA
// engine only, not just that a --lyrics flag exists.
expect(args.slice(args.indexOf('--lyrics'), args.indexOf('--lyrics') + 2))
.toEqual(['--lyrics', '[verse] Example\n[outro]']);
});
const base = {
pythonPath: '/venv/bin/python3',
repo: 'facebook/musicgen-medium',
prompt: 'tense cinematic synth',
durationSec: 10,
outputPath: '/data/music/music-gen-abc.wav',
};
it('preserves the caption including Markdown and whitespace for every engine', () => {
// Regression: the sidecar must receive the caption shown by prompt preview.
const textArg = (args) => args[args.indexOf('--text') + 1];
for (const engineId of Object.keys(ENGINES)) {
const { args } = buildSidecarArgs({
...base, engineId, repo: 'some/repo',
prompt: ' slow-burning, cinematic instrumental with a **dark** `analog` pulse\n',
});
expect(textArg(args), engineId).toBe(' slow-burning, cinematic instrumental with a **dark** `analog` pulse\n');
}
});
it('routes to the musicgen sidecar script for the musicgen engine', () => {
const { bin, args } = buildSidecarArgs({ ...base, engineId: 'musicgen' });
expect(bin).toBe('/venv/bin/python3');
expect(args[0]).toMatch(/generate_musicgen\.py$/);
const flag = (name) => args[args.indexOf(name) + 1];
expect(flag('--model')).toBe('facebook/musicgen-medium');
expect(flag('--text')).toBe('tense cinematic synth');
expect(flag('--output')).toBe('/data/music/music-gen-abc.wav');
});
it('routes to the audioldm2 sidecar script for the audioldm2 engine', () => {
const { args } = buildSidecarArgs({ ...base, engineId: 'audioldm2', repo: 'cvssp/audioldm2' });
expect(args[0]).toMatch(/generate_audioldm2\.py$/);
expect(args[args.indexOf('--model') + 1]).toBe('cvssp/audioldm2');
});
it('clamps the duration to the engine window', () => {
// 120s clamps to musicgen's 30s but passes through for audioldm2.
const mg = buildSidecarArgs({ ...base, engineId: 'musicgen', durationSec: 120 });
expect(mg.args[mg.args.indexOf('--duration') + 1]).toBe(String(ENGINES.musicgen.maxDurationSec));
const ald = buildSidecarArgs({ ...base, engineId: 'audioldm2', durationSec: 120 });
expect(ald.args[ald.args.indexOf('--duration') + 1]).toBe('120');
});
it('passes the runtime-dir flag (default per engine)', () => {
const { args } = buildSidecarArgs({ ...base, engineId: 'audioldm2' });
expect(args).toContain('--runtime-dir');
});
it('threads --lyrics ONLY for lyric-aware engines (acestep)', () => {
const ace = buildSidecarArgs({ ...base, engineId: 'acestep', repo: 'ACE-Step/ACE-Step-v1-3.5B', lyrics: '[verse]\nhello' });
expect(ace.args[0]).toMatch(/generate_acestep\.py$/);
expect(ace.args).toContain('--lyrics');
expect(ace.args[ace.args.indexOf('--lyrics') + 1]).toBe('[verse]\nhello');
// Non-lyric engines never get the flag, even when lyrics are passed.
const mg = buildSidecarArgs({ ...base, engineId: 'musicgen', lyrics: 'ignored' });
expect(mg.args).not.toContain('--lyrics');
const ald = buildSidecarArgs({ ...base, engineId: 'audioldm2', lyrics: 'ignored' });
expect(ald.args).not.toContain('--lyrics');
});
it('sends an empty --lyrics for acestep when none provided (never undefined)', () => {
const { args } = buildSidecarArgs({ ...base, engineId: 'acestep' });
expect(args).toContain('--lyrics');
expect(args[args.indexOf('--lyrics') + 1]).toBe('');
});
});
describe('acestep engine entry', () => {
it('is lyric-aware, fixed-checkpoint, and uses the acestep sidecar', () => {
expect(ENGINES.acestep.lyrics).toBe(true);
expect(ENGINES.acestep.customModels).toBe(false); // single foundation checkpoint
expect(ENGINES.acestep.scriptPath).toMatch(/generate_acestep\.py$/);
expect(ENGINES.acestep.installEnv).toBe('INSTALL_ACESTEP');
});
it('the other engines are NOT lyric-aware but DO accept custom HF checkpoints', () => {
expect(ENGINES.musicgen.lyrics).toBeUndefined();
expect(ENGINES.audioldm2.lyrics).toBeUndefined();
expect(ENGINES.musicgen.customModels).toBe(true);
expect(ENGINES.audioldm2.customModels).toBe(true);
});
});
describe('buildMusicGenArgs (back-compat wrapper)', () => {
const base = {
pythonPath: '/venv/bin/python3',
repo: 'facebook/musicgen-medium',
prompt: 'tense cinematic synth',
durationSec: 10,
outputPath: '/data/music/music-gen-abc.wav',
runtimeDir: '/home/u/.portos/mlx-examples/musicgen',
};
it('builds the musicgen sidecar argv with every flag the script expects', () => {
const { bin, args } = buildMusicGenArgs(base);
expect(bin).toBe('/venv/bin/python3');
expect(args[0]).toMatch(/generate_musicgen\.py$/);
const flag = (name) => args[args.indexOf(name) + 1];
expect(flag('--model')).toBe('facebook/musicgen-medium');
expect(flag('--text')).toBe('tense cinematic synth');
expect(flag('--output')).toBe('/data/music/music-gen-abc.wav');
expect(flag('--runtime-dir')).toBe('/home/u/.portos/mlx-examples/musicgen');
});
it('passes the clamped duration as a string', () => {
const { args } = buildMusicGenArgs({ ...base, durationSec: 9999 });
const dur = args[args.indexOf('--duration') + 1];
expect(dur).toBe(String(MAX_DURATION_SEC));
expect(typeof dur).toBe('string');
});
it('clamps a sub-minimum duration', () => {
const { args } = buildMusicGenArgs({ ...base, durationSec: 0 });
expect(args[args.indexOf('--duration') + 1]).toBe(String(MIN_DURATION_SEC));
});
});
// ---- generateMusic backend-selection tests (mocked subprocess) -----------
// These exercise the JS plumbing only — they never run Python. The spawn mock
// records which sidecar script was launched and synthesizes a success/failure
// without any model weights.
// Shared mutable state for the mock factories — defined via vi.hoisted so it's
// initialized before the (hoisted) vi.mock factories run.
const h = vi.hoisted(() => ({
testDir: '',
spawnCalls: [],
mockExitCode: 0,
mockStdout: '',
mockWriteOutput: true,
deferClose: false,
child: null,
finishChild: null,
musicgenPython: '/fake/venv-musicgen/bin/python3',
audioldm2Python: '/fake/venv-audioldm2/bin/python3',
minimaxMusic3Python: '/fake/venv-minimax-music3/bin/python3',
minimaxMusic3MlxPython: '/fake/venv-minimax-music3-mlx/bin/python3',
// isEngineHealthy's import probe: which interpreters it ran, and whether the
// import succeeded (a half-built venv exits non-zero).
probeCalls: [],
probeOk: true,
// Host identity, so platform-gated engines (MLX MusicGen) behave the same in
// CI on Linux, on a Windows dev box, and on the Apple Silicon they target.
osPlatform: 'darwin',
osArch: 'arm64',
}));
// Set after the top-level imports resolve; the fileUtils mock reads it through
// a getter so the (eagerly-built) PATHS object always reflects the final value.
h.testDir = mkdtempSync(join(tmpdir(), 'musicgen-test-'));
const TEST_DIR = h.testDir;
const spawnCalls = h.spawnCalls;
// Partial: tmpdir() stays real (the suite writes fake WAVs under it); only the
// host identity is driven by the test.
vi.mock('os', async () => ({
...(await vi.importActual('os')),
platform: () => h.osPlatform,
arch: () => h.osArch,
}));
vi.mock('../../lib/childProcess.js', async () => {
const actual = await vi.importActual('../../lib/childProcess.js');
return {
...actual,
// isEngineHealthy probes the venv with `python -c <import>`; promisify()
// wraps this callback form. h.probeOk drives success vs a broken venv.
execFile: (file, args, opts, cb) => {
h.probeCalls.push({ file, args });
const done = typeof opts === 'function' ? opts : cb;
setImmediate(() => (h.probeOk
? done(null, '', '')
: done(Object.assign(new Error("ModuleNotFoundError: No module named 'torch'"), { code: 1 }))));
},
spawn: (bin, args, _opts) => {
h.spawnCalls.push({ bin, args });
const listeners = {};
const proc = {
pid: 101, exitCode: null, signalCode: null,
stdout: { on: (event, cb) => { if (event === 'data' && h.mockStdout) cb(Buffer.from(h.mockStdout)); } },
stderr: { on: (event, cb) => { if (event === 'data') cb(Buffer.from('STAGE:generate\n')); } },
on: (event, cb) => { listeners[event] = cb; },
emit: (event, ...args) => listeners[event]?.(...args),
kill: () => {},
};
let finished = false;
h.child = proc;
h.finishChild = () => {
if (finished) return;
finished = true;
if (h.mockExitCode === 0 && h.mockWriteOutput) {
const outPath = args[args.indexOf('--output') + 1];
writeFileSync(outPath, Buffer.from('fake-wav-bytes'));
}
proc.exitCode = h.mockExitCode;
listeners.close?.(h.mockExitCode, null);
};
if (!h.deferClose) Promise.resolve().then(h.finishChild);
return proc;
},
};
});
// PATHS.music points at the temp dir so the fake WAV lands somewhere writable.
// `music` is a getter so the value reflects h.testDir even though this factory
// runs (hoisted) before the top-level `h.testDir = mkdtempSync(...)` assignment.
vi.mock('../../lib/fileUtils.js', async () => {
const actual = await vi.importActual('../../lib/fileUtils.js');
return {
...actual,
PATHS: { ...actual.PATHS, get music() { return h.testDir; } },
ensureDir: async () => {},
};
});
vi.mock('../hfToken.js', () => ({ hfChildEnv: async () => ({}) }));
// Venv resolvers — flip readiness per engine per test.
vi.mock('../../lib/pythonSetup.js', async () => {
const actual = await vi.importActual('../../lib/pythonSetup.js');
return {
...actual,
resolveMusicgenPython: () => h.musicgenPython,
resolveAudioldm2Python: () => h.audioldm2Python,
resolveMinimaxMusic3Python: () => h.minimaxMusic3Python,
resolveMinimaxMusic3MlxPython: () => h.minimaxMusic3MlxPython,
};
});
const {
generateMusic, isEngineHealthy, invalidateEngineHealth, isEnginePlatformSupported, enginePlatformLabel,
} = await import('./musicGen.js');
beforeEach(() => {
h.spawnCalls.length = 0;
h.mockExitCode = 0;
h.mockWriteOutput = true;
h.deferClose = false;
h.child = null;
h.finishChild = null;
h.mockStdout = 'STAGE:done\nRESULT:{"output":"x","durationSec":12.5,"sampleRate":32000}\n';
h.musicgenPython = '/fake/venv-musicgen/bin/python3';
h.audioldm2Python = '/fake/venv-audioldm2/bin/python3';
h.minimaxMusic3Python = '/fake/venv-minimax-music3/bin/python3';
h.minimaxMusic3MlxPython = '/fake/venv-minimax-music3-mlx/bin/python3';
h.probeCalls.length = 0;
h.probeOk = true;
h.osPlatform = 'darwin';
h.osArch = 'arm64';
cuda.status = 'available';
cuda.maxVramGb = 40;
invalidateEngineHealth();
});
afterEach(async () => {
for (const f of await readdir(TEST_DIR).catch(() => [])) {
await rm(join(TEST_DIR, f), { force: true }).catch(() => {});
}
});
// TEST_DIR (h.testDir) is a module-scope mkdtemp root reused across every
// test in this file — the per-test afterEach above only empties it, so
// remove the root itself once here (#9032).
afterAll(async () => {
await rm(TEST_DIR, { recursive: true, force: true }).catch(() => {});
});
describe('generateMusic backend selection', () => {
it('keeps music ownership through a live sidecar error until close and partial-file cleanup', async () => {
const { maintenance } = await import('../../lib/maintenanceAdmission.js');
h.deferClose = true;
const outcome = generateMusic({ prompt: 'in-flight audio' }).catch(error => error);
await vi.waitFor(() => expect(h.child).not.toBeNull());
const { hold } = maintenance.begin({ reason: 'Drain live audio', owner: 'Operator' });
try {
h.child.emit('error', new Error('signal transport failed'));
await Promise.resolve();
expect(maintenance.status().state).toBe('draining');
h.finishChild();
expect(await outcome).toMatchObject({ code: 'PIPELINE_MUSIC_GEN_FAILED' });
expect(await readdir(TEST_DIR)).toHaveLength(0);
expect(maintenance.status().state).toBe('ready');
} finally {
h.finishChild();
await outcome;
maintenance.resume({ id: hold.id, revision: hold.revision });
}
});
it('holds new music renders before probes or spawn while an admitted render can continue', async () => {
const { maintenance } = await import('../../lib/maintenanceAdmission.js');
const parent = maintenance.admit('media', 'admitted-audio');
const { hold } = maintenance.begin({ reason: 'Drain audio', owner: 'Operator' });
try {
await expect(generateMusic({ prompt: 'new render' })).rejects.toMatchObject({ code: 'MAINTENANCE_HELD' });
expect(h.probeCalls).toEqual([]);
expect(spawnCalls).toEqual([]);
await expect(parent.run(() => generateMusic({ prompt: 'already admitted' }))).resolves.toMatchObject({ engine: 'musicgen' });
expect(maintenance.status().state).toBe('draining');
await parent.finish();
expect(maintenance.status().state).toBe('ready');
} finally {
await parent.finish();
maintenance.resume({ id: hold.id, revision: hold.revision });
}
});
it('defaults to the musicgen sidecar', async () => {
const res = await generateMusic({ prompt: 'calm piano' });
expect(spawnCalls).toHaveLength(1);
expect(spawnCalls[0].bin).toBe('/fake/venv-musicgen/bin/python3');
expect(spawnCalls[0].args[0]).toMatch(/generate_musicgen\.py$/);
expect(res.engine).toBe('musicgen');
expect(res.modelId).toBe(DEFAULT_MUSICGEN_MODEL_ID);
expect(res.filename).toMatch(/^music-gen-.*\.wav$/);
});
it('returns an optional effective execution profile reported by a sidecar', async () => {
h.mockStdout = 'STAGE:done\nRESULT:{"durationSec":12.5,"executionProfile":"cuda-bf16-component-offload"}\n';
const result = await generateMusic({ prompt: 'warm cinematic pop' });
expect(result.executionProfile).toBe('cuda-bf16-component-offload');
expect(spawnCalls).toHaveLength(1);
});
it('runs MiniMax on a card meeting its measured VRAM floor', async () => {
await generateMusic({
prompt: 'warm cinematic pop',
lyrics: '[verse]\nExample words\n[outro]',
engine: 'minimax-music3',
});
expect(spawnCalls).toHaveLength(1);
});
it('blocks MiniMax on a card below its measured VRAM floor', async () => {
cuda.maxVramGb = 12;
await expect(generateMusic({
prompt: 'warm cinematic pop',
lyrics: '[verse]\nExample words\n[outro]',
engine: 'minimax-music3',
})).rejects.toMatchObject({
status: 503,
code: 'PIPELINE_MUSIC_VRAM_INSUFFICIENT',
});
expect(spawnCalls).toHaveLength(0);
});
it('routes MiniMax Music 3 MLX to its sibling venv and pins the selected checkpoint', async () => {
await generateMusic({
prompt: 'warm cinematic pop',
lyrics: '[verse]\nExample words',
engine: 'minimax-music3-mlx',
modelId: 'minimax-music3-mlx-bf16',
durationSec: 30,
});
expect(spawnCalls).toHaveLength(1);
expect(spawnCalls[0].bin).toBe('/fake/venv-minimax-music3-mlx/bin/python3');
expect(spawnCalls[0].args[0]).toMatch(/generate_minimax_music3_mlx\.py$/);
expect(spawnCalls[0].args.slice(spawnCalls[0].args.indexOf('--model'), spawnCalls[0].args.indexOf('--model') + 2)).toEqual([
'--model', 'mlx-community/MiniMax-Music3-bf16',
]);
expect(spawnCalls[0].args.slice(spawnCalls[0].args.indexOf('--revision'), spawnCalls[0].args.indexOf('--revision') + 2)).toEqual([
'--revision', '83a5f2d365673689df5c8f36e21e108751fd92ea',
]);
});
it('routes to the audioldm2 sidecar + venv when engine=audioldm2', async () => {
const res = await generateMusic({ prompt: 'ambient drone', engine: 'audioldm2', durationSec: 60 });
expect(spawnCalls).toHaveLength(1);
expect(spawnCalls[0].bin).toBe('/fake/venv-audioldm2/bin/python3');
expect(spawnCalls[0].args[0]).toMatch(/generate_audioldm2\.py$/);
// 60s is within audioldm2's window — it passes through, not clamped to 30.
expect(spawnCalls[0].args[spawnCalls[0].args.indexOf('--duration') + 1]).toBe('60');
expect(res.engine).toBe('audioldm2');
expect(res.modelId).toBe(DEFAULT_AUDIOLDM2_MODEL_ID);
});
it('resolves modelId within the selected engine', async () => {
await generateMusic({ prompt: 'jazz', engine: 'audioldm2', modelId: 'audioldm2-music' });
expect(spawnCalls[0].args[spawnCalls[0].args.indexOf('--model') + 1]).toBe('cvssp/audioldm2-music');
});
it('falls back to the engine default for a cross-engine modelId', async () => {
// Passing a musicgen model id to the audioldm2 engine must not leak through.
await generateMusic({ prompt: 'jazz', engine: 'audioldm2', modelId: 'musicgen-small' });
expect(spawnCalls[0].args[spawnCalls[0].args.indexOf('--model') + 1]).toBe('cvssp/audioldm2');
});
it('throws 503 with the engine-specific install hint when that venv is missing', async () => {
h.audioldm2Python = null;
await expect(generateMusic({ prompt: 'x', engine: 'audioldm2' }))
.rejects.toMatchObject({ status: 503, code: 'PIPELINE_MUSIC_RUNTIME_MISSING' });
await expect(generateMusic({ prompt: 'x', engine: 'audioldm2' }))
.rejects.toThrow(/INSTALL_AUDIOLDM2/);
// musicgen still works — readiness is per engine.
const res = await generateMusic({ prompt: 'x' });
expect(res.engine).toBe('musicgen');
});
it('rejects an empty prompt with 400 before spawning anything', async () => {
await expect(generateMusic({ prompt: ' ', engine: 'audioldm2' }))
.rejects.toMatchObject({ status: 400, code: 'PIPELINE_MUSIC_EMPTY_PROMPT' });
expect(spawnCalls).toHaveLength(0);
});
it('fails 500 and unlinks the partial when the sidecar writes no audio', async () => {
h.mockWriteOutput = false;
await expect(generateMusic({ prompt: 'x', engine: 'audioldm2' }))
.rejects.toMatchObject({ status: 500, code: 'PIPELINE_MUSIC_GEN_FAILED' });
expect(await readdir(TEST_DIR)).toHaveLength(0);
});
it('fails 500 when the sidecar exits non-zero', async () => {
h.mockExitCode = 1;
await expect(generateMusic({ prompt: 'x' }))
.rejects.toMatchObject({ status: 500, code: 'PIPELINE_MUSIC_GEN_FAILED' });
});
it('never spawns when the signal is already aborted (cancel raced the call)', async () => {
const controller = new AbortController();
controller.abort();
await expect(generateMusic({ prompt: 'x', signal: controller.signal }))
.rejects.toMatchObject({ status: 500, code: 'PIPELINE_MUSIC_GEN_FAILED' });
expect(spawnCalls).toHaveLength(0);
});
});
describe('isEngineReady', () => {
it('reflects each engine resolver independently', () => {
h.musicgenPython = '/fake/venv-musicgen/bin/python3';
h.audioldm2Python = null;
expect(isEngineReady('musicgen')).toBe(true);
expect(isEngineReady('audioldm2')).toBe(false);
});
});
describe('isEngineHealthy', () => {
it('reports a half-built venv as unhealthy even though the interpreter exists', async () => {
// The exact state a killed/failed install leaves behind: `python` is there,
// the packages are not. isEngineReady says yes; isEngineHealthy must not.
h.probeOk = false;
expect(isEngineReady('musicgen')).toBe(true);
expect(await isEngineHealthy('musicgen')).toBe(false);
});
it('reports a fully-installed venv as healthy', async () => {
expect(await isEngineHealthy('musicgen')).toBe(true);
expect(h.probeCalls[0]).toMatchObject({ file: '/fake/venv-musicgen/bin/python3' });
expect(h.probeCalls[0].args[0]).toBe('-c');
});
it('skips the probe entirely when no interpreter is resolved', async () => {
h.audioldm2Python = null;
expect(await isEngineHealthy('audioldm2')).toBe(false);
expect(h.probeCalls).toHaveLength(0);
});
it('caches the verdict so repeat readiness checks do not respawn python', async () => {
expect(await isEngineHealthy('musicgen')).toBe(true);
expect(await isEngineHealthy('musicgen')).toBe(true);
expect(h.probeCalls).toHaveLength(1);
});
it('re-probes with refresh so a repair install is not blocked by a stale verdict', async () => {
h.probeOk = false;
expect(await isEngineHealthy('musicgen')).toBe(false);
// The install just rebuilt the venv — a cached `false` must not stick.
h.probeOk = true;
expect(await isEngineHealthy('musicgen', { refresh: true })).toBe(true);
expect(h.probeCalls).toHaveLength(2);
});
it('tracks each engine independently', async () => {
expect(await isEngineHealthy('musicgen')).toBe(true);
h.probeOk = false;
expect(await isEngineHealthy('audioldm2')).toBe(false);
expect(await isEngineHealthy('musicgen')).toBe(true);
});
});
describe('ENGINES healthProbe parity', () => {
it('every engine declares an import probe', () => {
// A new engine without one silently falls back to "the interpreter file
// exists", which is the exact check isEngineHealthy was added to replace.
for (const engine of Object.values(ENGINES)) {
expect(typeof engine.healthProbe, `${engine.id} healthProbe`).toBe('string');
expect(engine.healthProbe.length).toBeGreaterThan(0);
}
});
});
describe('generateMusic venv-health gate', () => {
it('returns the install hint instead of spawning into a half-built venv', async () => {
// The interpreter is present, the packages are not — without the health gate
// the sidecar spawns and dies with a raw Python ImportError traceback.
h.probeOk = false;
await expect(generateMusic({ prompt: 'a calm piano bed', engine: 'musicgen' }))
.rejects.toMatchObject({ status: 503, code: 'PIPELINE_MUSIC_RUNTIME_MISSING' });
expect(spawnCalls).toHaveLength(0);
});
it('still generates when the venv is healthy', async () => {
const res = await generateMusic({ prompt: 'a calm piano bed', engine: 'musicgen' });
expect(res.filename).toMatch(/^music-gen-.*\.wav$/);
expect(spawnCalls).toHaveLength(1);
});
});
describe('isEnginePlatformSupported', () => {
it('treats an engine with no requiresPlatform as portable', () => {
expect(ENGINES.audioldm2.requiresPlatform).toBeUndefined();
h.osPlatform = 'win32';
h.osArch = 'x64';
expect(isEnginePlatformSupported('audioldm2')).toBe(true);
expect(enginePlatformLabel('audioldm2')).toBeNull();
});
it('allows MusicGen only on Apple Silicon', () => {
// MLX has no Windows/Linux build, so the setup script skips and exits 0 —
// which the install route used to report as "installer exited 0 but still
// not available", indistinguishable from a broken install.
expect(ENGINES.musicgen.requiresPlatform).toMatchObject({ platform: 'darwin', arch: 'arm64' });
expect(isEnginePlatformSupported('musicgen')).toBe(true);
h.osPlatform = 'win32';
h.osArch = 'x64';
expect(isEnginePlatformSupported('musicgen')).toBe(false);
// Intel Mac: right OS, wrong silicon.
h.osPlatform = 'darwin';
h.osArch = 'x64';
expect(isEnginePlatformSupported('musicgen')).toBe(false);
});
it('exposes a human-readable requirement for the UI', () => {
expect(enginePlatformLabel('musicgen')).toContain('Apple Silicon');
});
it('never reports an unsupported host as healthy, and never spawns a probe there', async () => {
h.osPlatform = 'win32';
h.osArch = 'x64';
h.probeOk = true;
expect(await isEngineHealthy('musicgen')).toBe(false);
expect(h.probeCalls).toHaveLength(0);
});
it('refuses to generate on an unsupported host instead of spawning the sidecar', async () => {
h.osPlatform = 'win32';
h.osArch = 'x64';
await expect(generateMusic({ prompt: 'a calm piano bed', engine: 'musicgen' }))
.rejects.toMatchObject({ status: 503, code: 'PIPELINE_MUSIC_RUNTIME_MISSING' });
expect(spawnCalls).toHaveLength(0);
});
});
describe('instrumental lyrics fallback', () => {
const base = { pythonPath: '/venv/bin/python3', prompt: 'cinematic electronic instrumental', durationSec: 60, outputPath: '/tmp/out.wav' };
const lyricsArg = (args) => args[args.indexOf('--lyrics') + 1];
it('adds a documented structure-tag sheet while preserving whitespace-only MiniMax input', () => {
// The checkpoint's tokenize step raises on an empty string, so an
// instrumental prompt used to die with "`lyrics` must be a non-empty
// string" after the model had already loaded.
for (const lyrics of [undefined, '', ' ', '\n\t ']) {
const { args } = buildSidecarArgs({ ...base, engineId: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3', lyrics });
expect(lyricsArg(args), `lyrics=${JSON.stringify(lyrics)}`).toBe(`${lyrics || ''}${lyrics ? '\n' : ''}${buildMinimaxInstrumentalLyrics(60)}`);
}
});
it('sizes the substituted sheet to the render duration, not a fixed one-tag stub', () => {
// `audio_duration` is only a ceiling for this engine — the global LLM ends
// the piece on its own, paced by the sheet's section count. A single
// [instrumental] tag is one section, which is why a 60s ask returned 25s.
const lyricsFor = (durationSec) => lyricsArg(
buildSidecarArgs({ ...base, engineId: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3', durationSec, lyrics: '' }).args,
);
const sections = (sheet) => sheet.split('\n').length;
expect(sections(lyricsFor(20))).toBeLessThan(sections(lyricsFor(60)));
expect(sections(lyricsFor(60))).toBeLessThan(sections(lyricsFor(240)));
});
it('preserves the caller\'s words but guarantees a closing section', () => {
// A caller sheet that resolves mid-phrase would make the model end abruptly;
// append the [outro] cue without disturbing any content the caller wrote.
const words = '[verse]\nExample words here';
const { args } = buildSidecarArgs({ ...base, engineId: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3', lyrics: words });
expect(lyricsArg(args)).toBe(`${words}\n[outro]`);
});
it('does not duplicate a closing section the caller already supplied', () => {
// The cue is idempotent — a sheet that already ends on [outro] is untouched.
const words = '[intro]\n[verse]\nsing\n[outro]';
const { args } = buildSidecarArgs({ ...base, engineId: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3', lyrics: words });
expect(lyricsArg(args)).toBe(words);
});
it('still guarantees a closing section when the caller\'s outro is not the last one', () => {
// The failure mode this PR exists to fix: an outro earlier in the sheet is
// not a CLOSING section, so the model still resolves on the trailing content.
const words = '[outro]\n[chorus]\nbig finish';
const { args } = buildSidecarArgs({ ...base, engineId: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3', lyrics: words });
expect(lyricsArg(args)).toBe(`${words}\n[outro]`);
});
it('leaves ACE-Step empty — it renders an instrumental from empty lyrics itself', () => {
expect(ENGINES.acestep.instrumentalLyrics).toBeUndefined();
const { args } = buildSidecarArgs({ ...base, engineId: 'acestep', repo: 'ACE-Step/ACE-Step-v1-3.5B', lyrics: '' });
expect(lyricsArg(args)).toBe('');
});
});
describe('buildMinimaxInstrumentalLyrics', () => {
const tags = (sheet) => sheet.split('\n');
it('brackets every line and opens on [intro] / closes on [outro]', () => {
const lines = tags(buildMinimaxInstrumentalLyrics(60));
for (const line of lines) expect(line).toMatch(/^\[[a-z]+\]$/);
expect(lines[0]).toBe('[intro]');
expect(lines.at(-1)).toBe('[outro]');
});
it('uses only tags the model card documents, and none that imply a vocal', () => {
// Section tags are a fixed vocabulary; [verse]/[chorus] would coax the
// model into singing over what the user asked to be an instrumental.
const documented = new Set(['intro', 'instrumental', 'bridge', 'solo', 'outro']);
for (const seconds of [1, 30, 60, 120, 300]) {
for (const line of tags(buildMinimaxInstrumentalLyrics(seconds))) {
expect(documented, `${seconds}s → ${line}`).toContain(line.slice(1, -1));
}
}
});
it('grows monotonically with duration and always keeps a body section', () => {
let previous = 0;
for (const seconds of [1, 20, 60, 120, 240, 300]) {
const count = tags(buildMinimaxInstrumentalLyrics(seconds)).length;
expect(count, `${seconds}s`).toBeGreaterThanOrEqual(previous);
// intro + at least one body + outro
expect(count, `${seconds}s`).toBeGreaterThanOrEqual(3);
previous = count;
}
});
it('clamps into the engine window instead of throwing on junk input', () => {
// Mirrors clampDuration's contract — the route validates shape, this
// guards the math, so a non-finite duration falls back to the default.
for (const bad of [undefined, null, NaN, 'sixty', -5, 1e9]) {
expect(() => buildMinimaxInstrumentalLyrics(bad)).not.toThrow();
expect(tags(buildMinimaxInstrumentalLyrics(bad)).length).toBeGreaterThanOrEqual(3);
}
});
it('caps the sheet so a 5-minute render does not emit an unbounded tag wall', () => {
expect(tags(buildMinimaxInstrumentalLyrics(300)).length).toBeLessThanOrEqual(14);
});
});
describe('ensureClosingSection', () => {
it('appends an [outro] cue to a sheet that has no closing section', () => {
expect(ensureClosingSection('[verse]\nhello world')).toBe('[verse]\nhello world\n[outro]');
});
it('returns a sheet that already closes on [outro] unchanged (idempotent)', () => {
const withOutro = '[intro]\n[verse]\nsing\n[outro]';
expect(ensureClosingSection(withOutro)).toBe(withOutro);
});
it('still appends a cue when an outro tag exists but is not the last section', () => {
// Only the LAST section counts as a closing section — an outro earlier in
// the sheet does not guarantee the model resolves there.
expect(ensureClosingSection('[outro]\n[chorus]\nbig finish')).toBe('[outro]\n[chorus]\nbig finish\n[outro]');
});
it('matches a closing section case-insensitively on the tag name', () => {
expect(ensureClosingSection('[VERSE]\n[OUTRO]')).toBe('[VERSE]\n[OUTRO]');
});
it('treats an outro with trailing words as a closing section', () => {
expect(ensureClosingSection('[verse]\nfinal\n[outro fade out]')).toBe('[verse]\nfinal\n[outro fade out]');
});
it('treats a padded tag as a closing section, matching the hasOutro parity in server/lib/musicDuration.js', () => {
expect(ensureClosingSection('[verse]\nfinal\n[ outro ]')).toBe('[verse]\nfinal\n[ outro ]');
});
it('does not treat a non-boundary lookalike as a closing section', () => {
// "outroduction" has no word boundary after "outro", so it is a different
// tag — matching the hasOutro detection in server/lib/musicDuration.js.
expect(ensureClosingSection('[outroduction]')).toBe('[outroduction]\n[outro]');
expect(ensureClosingSection('\n[final-outro]')).toBe('\n[final-outro]\n[outro]');
});
it('treats a leading bracketed tag as a closing section but not a bare unbracketed word', () => {
expect(ensureClosingSection('no tags at all\n[outro]')).toBe('no tags at all\n[outro]');
expect(ensureClosingSection('outro')).toBe('outro\n[outro]');
});
it('preserves authored whitespace before appending the closing cue', () => {
expect(ensureClosingSection('[verse]\nsing\n\n ')).toBe('[verse]\nsing\n\n \n[outro]');
expect(ensureClosingSection('')).toBe('[outro]');
expect(ensureClosingSection(' \n ')).toBe(' \n \n[outro]');
});
});