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

25.7 KB
Raw Blame
import { describe, it, expect, vi } from 'vitest';
import { ServerError } from '../../lib/errorHandler.js';
import { alignProjectLyrics } from './lyricAlign.js';
import {
  alignDirectorWords,
  encodePcm16Wav,
  lyricAlignChunkSec,
  lyricAlignFfmpegArgs,
  mergeChunkWords,
  mergeTranscripts,
  pickAlignmentPath,
  planAudioChunks,
  sliceWav,
  wavDurationSec,
} from './lyricAlignCore.js';
import { STT_TIMEOUT_MS } from '../voice/stt.js';

const round3 = (n) => Math.round(n * 1000) / 1000;

function groundWords(count, origin = 0.2) {
  return Array.from({ length: count }, (_, i) => {
    const startSec = round3(origin + i * 0.5);
    return { w: `w${i}`, startSec, endSec: round3(startSec + 0.4) };
  });
}

function within80(word, truth) {
  return Math.abs(word.startSec - truth.startSec) <= 0.08 && Math.abs(word.endSec - truth.endSec) <= 0.08;
}

describe('alignDirectorWords', () => {
  it('places at least 90% of a synthetic phrase within 80ms and flags the interpolated word', () => {
    const ground = groundWords(20);
    const duration = 12;
    const dropped = 'w7';
    const chunks = planAudioChunks(duration, { chunkSec: 8, overlapSec: 2 });
    expect(chunks.length).toBeGreaterThan(1);
    const recognized = mergeChunkWords(chunks.map((chunk) => ({
      ...chunk,
      words: ground
        .filter((word) => word.w !== dropped)
        .filter((word) => {
          const mid = (word.startSec + word.endSec) / 2;
          return mid >= chunk.startSec && mid < chunk.endSec;
        })
        .map((word) => ({
          text: word.w,
          startSec: word.startSec - chunk.startSec,
          endSec: word.endSec - chunk.startSec,
        })),
    })));
    const [aligned] = alignDirectorWords(
      [{ id: 'lc-1', text: ground.map((word) => word.w).join(' '), startSec: null, endSec: null }],
      recognized,
    );
    const hits = aligned.words.filter((word, index) => within80(word, ground[index]));
    expect(hits.length / aligned.words.length).toBeGreaterThanOrEqual(0.9);
    expect(aligned.words).toHaveLength(ground.length);
    expect(aligned.words.find((word) => word.w === dropped).conf).toBe('interpolated');
    expect(aligned.words.filter((word) => word.w !== dropped).every((word) => word.conf === 'matched')).toBe(true);
    // The line had no director times, so the cue takes its first and last word.
    expect(aligned.startSec).toBe(aligned.words[0].startSec);
    expect(aligned.endSec).toBe(aligned.words.at(-1).endSec);
  });

  it('keeps a skipped line inside its window and leaves the sung lines on the vocal', () => {
    const cues = [
      { id: 'a', text: 'walking home', startSec: 0.4, endSec: 1.6 },
      { id: 'b', text: 'not sung here', startSec: 3, endSec: 4 },
      { id: 'c', text: 'under neon', startSec: 5, endSec: 6.2 },
    ];
    const aligned = alignDirectorWords(cues, [
      { text: 'walking', startSec: 0.5, endSec: 1 },
      { text: 'home', startSec: 1, endSec: 1.5 },
      { text: 'under', startSec: 5.1, endSec: 5.4 },
      { text: 'neon', startSec: 5.4, endSec: 5.9 },
    ]);
    expect(aligned[1].words.every((word) => word.conf === 'interpolated')).toBe(true);
    expect(aligned[1].words.every((word) => word.startSec >= 3 && word.endSec <= 4)).toBe(true);
    expect(aligned[0].words.map((word) => [word.startSec, word.conf])).toEqual([
      [0.5, 'matched'],
      [1, 'matched'],
    ]);
    expect(aligned[2].words[0]).toMatchObject({ w: 'under', startSec: 5.1, conf: 'matched' });
    // Director-set line times stay put.
    expect(aligned[0].startSec).toBe(0.4);
    expect(aligned[2].endSec).toBe(6.2);
  });

  it('matches a repeated chorus to its own occurrence', () => {
    const aligned = alignDirectorWords([
      { id: 'a', text: 'we go', startSec: null, endSec: null },
      { id: 'b', text: 'we go', startSec: null, endSec: null },
    ], [
      { text: 'we', startSec: 1, endSec: 1.2 },
      { text: 'go', startSec: 1.2, endSec: 1.5 },
      { text: 'we', startSec: 8, endSec: 8.2 },
      { text: 'go', startSec: 8.2, endSec: 8.6 },
    ]);
    expect(aligned[0].words.map((word) => word.startSec)).toEqual([1, 1.2]);
    expect(aligned[1].words.map((word) => word.startSec)).toEqual([8, 8.2]);
  });

  it('divides an unmatched run between its matched neighbours by character count', () => {
    const [aligned] = alignDirectorWords(
      [{ id: 'a', text: 'hi ab abcd yo', startSec: null, endSec: null }],
      [
        { text: 'hi', startSec: 0, endSec: 1 },
        { text: 'yo', startSec: 7, endSec: 8 },
      ],
    );
    expect(aligned.words[1]).toMatchObject({ w: 'ab', startSec: 1, endSec: 3, conf: 'interpolated' });
    expect(aligned.words[2]).toMatchObject({ w: 'abcd', startSec: 3, endSec: 7, conf: 'interpolated' });
    expect(aligned.words[0].startSec).toBe(0);
    expect(aligned.words[3].startSec).toBe(7);
  });

  it('does not let a word the recognizer missed latch onto the same word a verse later', () => {
    // "the" in line one was not heard. A next-equal-word matcher would take the
    // "the" of line three for it and strand line two between them.
    const aligned = alignDirectorWords([
      { id: 'a', text: 'into the night', startSec: null, endSec: null },
      { id: 'b', text: 'running far away', startSec: null, endSec: null },
      { id: 'c', text: 'under the moon', startSec: null, endSec: null },
    ], [
      { text: 'into', startSec: 1, endSec: 1.3 },
      { text: 'night', startSec: 1.6, endSec: 2 },
      { text: 'running', startSec: 3, endSec: 3.4 },
      { text: 'far', startSec: 3.4, endSec: 3.7 },
      { text: 'away', startSec: 3.7, endSec: 4.2 },
      { text: 'under', startSec: 6, endSec: 6.3 },
      { text: 'the', startSec: 6.3, endSec: 6.4 },
      { text: 'moon', startSec: 6.4, endSec: 7 },
    ]);
    expect(aligned[0].words.map((word) => word.conf)).toEqual(['matched', 'interpolated', 'matched']);
    expect(aligned[0].words[1].startSec).toBeGreaterThanOrEqual(1.3);
    expect(aligned[0].words[1].endSec).toBeLessThanOrEqual(1.6);
    expect(aligned[1]).toMatchObject({ startSec: 3, endSec: 4.2 });
    expect(aligned[1].words.every((word) => word.conf === 'matched')).toBe(true);
    expect(aligned[2].words[1]).toMatchObject({ w: 'the', startSec: 6.3, conf: 'matched' });
  });

  it('matches a curly-apostrophe sheet word to the recognizer\'s straight one', () => {
    const [aligned] = alignDirectorWords(
      [{ id: 'a', text: 'I’m gonna stay', startSec: null, endSec: null }],
      [
        { text: "I'm", startSec: 1, endSec: 1.2 },
        { text: 'gona', startSec: 1.2, endSec: 1.5 },
        { text: 'stay', startSec: 1.5, endSec: 2 },
      ],
    );
    expect(aligned.words.map((word) => [word.w, word.conf])).toEqual([
      ['I’m', 'matched'], ['gonna', 'matched'], ['stay', 'matched'],
    ]);
  });

  it('gives a one-word line the recognizer timed as an instant a playable span', () => {
    const aligned = alignDirectorWords([
      { id: 'a', text: 'Hush.', startSec: null, endSec: null },
      { id: 'b', text: 'can you feel', startSec: null, endSec: null },
    ], [
      { text: 'Hush.', startSec: 20.5, endSec: 20.5 },
      { text: 'can', startSec: 21, endSec: 21.2 },
      { text: 'you', startSec: 21.2, endSec: 21.4 },
      { text: 'feel', startSec: 21.4, endSec: 21.8 },
    ]);
    expect(aligned[0]).toMatchObject({ startSec: 20.5, endSec: 20.75 });
    expect(aligned[0].words[0]).toMatchObject({ w: 'Hush.', conf: 'matched' });
    expect(aligned[1]).toMatchObject({ startSec: 21, endSec: 21.8 });
  });

  it('fills only the cue times the director left empty', () => {
    const [aligned] = alignDirectorWords(
      [{ id: 'a', text: 'walking home', startSec: 1, endSec: null }],
      [
        { text: 'walking', startSec: 1.2, endSec: 1.5 },
        { text: 'home', startSec: 1.5, endSec: 1.9 },
      ],
    );
    expect(aligned.startSec).toBe(1);
    expect(aligned.endSec).toBe(1.9);
  });
});

describe('lyric alignment audio', () => {
  it('decodes to 16 kHz mono PCM and slices a window without shifting the clock', () => {
    expect(lyricAlignFfmpegArgs('/songs/mix.wav', '/tmp/vocal.wav')).toEqual([
      '-v', 'error', '-i', '/songs/mix.wav', '-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le', '-y', '/tmp/vocal.wav',
    ]);
    expect(lyricAlignChunkSec(STT_TIMEOUT_MS)).toBeLessThanOrEqual(STT_TIMEOUT_MS / 1000 - 8);
    const wav = encodePcm16Wav(16000 * 4);
    expect(wavDurationSec(wav)).toBeCloseTo(4, 3);
    expect(wavDurationSec(sliceWav(wav, 1, 2.5))).toBeCloseTo(1.5, 3);
    const truncated = encodePcm16Wav(16000);
    truncated.writeUInt32LE(999999, 40);
    expect(wavDurationSec(sliceWav(truncated, 0, 2))).toBeCloseTo(1, 3);
    const stereo = encodePcm16Wav(100);
    stereo.writeUInt16LE(4, 32);
    expect(() => sliceWav(stereo, 0, 0.01)).toThrow(/16-bit mono/);
  });

  it('uses the vocal stem without needing the mix, and does not fall back when the stem file is missing', async () => {
    const resolveMaster = vi.fn(async () => '/library/mix.wav');
    await expect(pickAlignmentPath({ vocalStemFilename: 'v.wav' }, {
      resolveStem: () => '/library/v.wav',
      resolveMaster,
    })).resolves.toEqual({ path: '/library/v.wav', source: 'vocal-stem', mixPath: null });

    await expect(pickAlignmentPath({}, {
      resolveStem: () => null,
      resolveMaster,
    })).resolves.toEqual({ path: '/library/mix.wav', source: 'master', mixPath: null });

    const missing = new ServerError('missing', { status: 404, code: 'MUSIC_VIDEO_VOCAL_STEM_MISSING' });
    await expect(pickAlignmentPath({ vocalStemFilename: 'gone.wav' }, {
      resolveStem: () => { throw missing; },
      resolveMaster,
    })).rejects.toMatchObject({ code: 'MUSIC_VIDEO_VOCAL_STEM_MISSING' });
  });
});

describe('mergeTranscripts', () => {
  const words = (list) => list.map(([text, startSec]) => ({ text, startSec, endSec: startSec + 0.3 }));

  it('keeps the stem where it is clean and takes the mix only where the stem loops', () => {
    const stem = words([
      ['hold', 1], ['me', 1.4], ['close', 1.8],
      ['Na-na-na-na-na-na', 4],
      ['no', 9], ['no', 9.4], ['no', 9.8], ['no', 10.2], ['no', 10.6], ['no', 11],
    ]);
    // The mix mishears the clean stretch, and stretches words across the loop too.
    const mix = words([
      ['old', 1], ['me', 1.4], ['clothes', 1.8],
      ['tonight', 4.1],
      ['never', 9], ['let', 9.4], ['me', 9.8], ['go', 10.2],
    ]);
    const merged = mergeTranscripts(stem, mix, 'hold me close tonight\nnever let me go');
    expect(merged.map((word) => word.text)).toEqual(['hold', 'me', 'close', 'tonight', 'never', 'let', 'me', 'go']);
  });

  it('keeps a repeat the lyrics really sing, and drops a looped run with nothing to replace it', () => {
    const sung = words([['hey', 1], ['hey', 1.4], ['hey', 1.8], ['hey', 2.2]]);
    expect(mergeTranscripts(sung, [], 'hey hey hey hey')).toHaveLength(4);
    expect(mergeTranscripts(sung, [], 'hey there')).toHaveLength(0);
  });
});

describe('alignProjectLyrics', () => {
  const project = {
    id: 'mv-1',
    trackId: 't1',
    lyricCues: [
      { id: 'lc-1', text: 'walking home', startSec: 1, endSec: null },
      { id: 'lc-2', text: 'not sung here', startSec: 2, endSec: 2.8 },
    ],
  };

  function harness(transcribe, record = project, { resolveAudio } = {}) {
    const updateProject = vi.fn(async (id, patch) => ({ id, ...record, ...patch }));
    const decodeAudio = vi.fn(async () => encodePcm16Wav(16000 * 3));
    const getProject = vi.fn(async () => record);
    const release = vi.fn(async () => {});
    return {
      updateProject,
      decodeAudio,
      transcribe,
      release,
      run: (opts = {}) => alignProjectLyrics(record.id, {
        ...opts,
        deps: {
          getProject,
          updateProject,
          resolveAudio: resolveAudio || (async () => ({ path: 'song.wav', source: 'master', mixPath: null })),
          decodeAudio,
          resolveTranscriber: async () => ({ kind: 'test', transcribe, release }),
          ...opts.deps,
        },
      }),
    };
  }

  it('writes matched and interpolated words, and does not replace a time the director set', async () => {
    const transcribe = vi.fn(async () => [
      { text: 'walking', startSec: 0.5, endSec: 1 },
      { text: 'home', startSec: 1, endSec: 1.5 },
    ]);
    const { run, updateProject, release } = harness(transcribe);
    const saved = await run();
    expect(transcribe).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({ prompt: 'walking home\nnot sung here' }));
    expect(saved.lyricCues[0]).toMatchObject({
      startSec: 1,
      endSec: 1.5,
      words: [
        { w: 'walking', startSec: 0.5, endSec: 1, conf: 'matched' },
        { w: 'home', startSec: 1, endSec: 1.5, conf: 'matched' },
      ],
    });
    expect(saved.lyricCues[1].words.every((word) => word.conf === 'interpolated')).toBe(true);
    expect(saved.lyricCues[1].words.every((word) => word.startSec >= 2 && word.endSec <= 2.8)).toBe(true);
    expect(updateProject).toHaveBeenCalledOnce();
    expect(release).toHaveBeenCalledOnce();
  });

  it('reports stages and stops without saving when cancelled mid-run (#10155)', async () => {
    const stages = [];
    const transcribe = vi.fn(async () => [{ text: 'walking', startSec: 0.5, endSec: 1 }]);
    const done = harness(transcribe);
    await done.run({ onProgress: (frame) => stages.push(frame.stage) });
    expect(stages).toEqual(['decoding', 'loading-model', 'transcribing', 'saving']);

    const stopped = harness(vi.fn(async () => [{ text: 'walking', startSec: 0.5, endSec: 1 }]));
    let cancel = false;
    await expect(stopped.run({
      isCancelled: () => cancel,
      onProgress: (frame) => { if (frame.stage === 'loading-model') cancel = true; },
    })).rejects.toMatchObject({ canceled: true });
    expect(stopped.transcribe).not.toHaveBeenCalled();
    expect(stopped.updateProject).not.toHaveBeenCalled();
    expect(stopped.release).toHaveBeenCalledOnce();
  });

  it('uses CTC word slots for repeated lines after silence, without Whisper or mix decoding', async () => {
    const record = { ...project, vocalStemFilename: 'stem.wav', lyricCues: [
      { id: 'a', text: 'hello morning', startSec: null, endSec: null },
      { id: 'b', text: 'hello morning', startSec: null, endSec: null },
    ] };
    const stem = encodePcm16Wav(16000 * 10);
    for (const [start, end] of [[1, 2], [4, 5]]) {
      for (let i = start * 16000; i < end * 16000; i++) stem.writeInt16LE(5000, 44 + i * 2);
    }
    const transcribe = vi.fn();
    const h = harness(transcribe, record, {
      resolveAudio: async () => ({ path: 'stem.wav', source: 'vocal-stem', mixPath: null }),
    });
    h.decodeAudio.mockResolvedValue(stem);
    const forceAlign = vi.fn(async (_wav, cues) => {
      expect(cues).toEqual(record.lyricCues);
      return [1, 4].map((start) => [
        { w: 'hello', startSec: start, endSec: start + 0.4, conf: 'matched' },
        { w: 'morning', startSec: start + 0.4, endSec: start + 1, conf: 'matched' },
      ]);
    });
    const saved = await h.run({ deps: { forceAlign } });
    expect(h.decodeAudio.mock.calls.map(([path]) => path)).toEqual(['stem.wav']);
    expect(forceAlign).toHaveBeenCalledOnce();
    expect(transcribe).not.toHaveBeenCalled();
    expect(saved.lyricCues.map((cue) => cue.startSec)).toEqual([1, 4]);
    expect(saved.lyricAlignSilentWords).toBe(0);
    expect(saved.lyricAlignSource).toBe('vocal-stem');
  });

  it.each([true, false])('retries only compressed whole-song cues and keeps repairs only when expanded (%s)', async (repaired) => {
    const record = { ...project, vocalStemFilename: 'stem.wav', lyricCues: [
      { id: 'a', text: 'walking home', startSec: null, endSec: null },
      { id: 'b', text: 'under blue skies', startSec: null, endSec: null },
      { id: 'c', text: 'another clear morning', startSec: null, endSec: null },
      { id: 'd', text: 'so fast', startSec: null, endSec: null },
    ] };
    const words = (text, start, step) => text.split(' ').map((w, i) => ({
      w, startSec: round3(start + i * step), endSec: round3(start + (i + 1) * step), conf: 'matched',
    }));
    const whole = record.lyricCues.map((cue, i) => words(cue.text, [1, 3, 7.1, 9][i], [0.5, 0.1, 0.15, 0.1][i]));
    const retry = repaired ? words(record.lyricCues[1].text, 4, 0.6) : whole[1];
    const forceAlign = vi.fn().mockResolvedValueOnce(whole).mockResolvedValueOnce([retry]);
    const h = harness(vi.fn(), record, { resolveAudio: async () => ({ path: 'stem.wav', source: 'vocal-stem' }) });
    const stem = encodePcm16Wav(16000 * 10);
    for (let i = 0; i < 16000 * 10; i++) stem.writeInt16LE(5000, 44 + i * 2);
    h.decodeAudio.mockResolvedValue(stem);
    const saved = await h.run({ deps: { forceAlign } });
    expect(forceAlign).toHaveBeenCalledTimes(2);
    expect(forceAlign).toHaveBeenLastCalledWith(stem, [record.lyricCues[1]], expect.objectContaining({ startSec: 2, endSec: 7.1 }));
    expect(saved.lyricCues[1]).toMatchObject({
      id: 'b', words: retry, startSec: retry[0].startSec, endSec: retry.at(-1).endSec, suspect: !repaired,
    });
    for (const i of [0, 2, 3]) expect(saved.lyricCues[i].words).toEqual(whole[i]);
    expect(h.decodeAudio).toHaveBeenCalledOnce();
    expect(h.updateProject).toHaveBeenCalledOnce();
  });

  it.each(['cancel', 'text', 'audio'])('saves nothing when an automatic repair is interrupted by %s', async (outcome) => {
    const record = { ...project, vocalStemFilename: 'stem.wav', lyricCues: [
      { id: 'a', text: 'under blue skies', startSec: null, endSec: null },
    ] };
    const h = harness(vi.fn(), record, { resolveAudio: async () => ({ path: 'stem.wav', source: 'vocal-stem' }) });
    let cancelled = false;
    const collapsed = ['under', 'blue', 'skies'].map((w, i) => ({ w, startSec: i * 0.1, endSec: (i + 1) * 0.1, conf: 'matched' }));
    const forceAlign = vi.fn().mockResolvedValueOnce([collapsed]).mockImplementationOnce(async () => {
      if (outcome === 'cancel') cancelled = true;
      if (outcome === 'text') record.lyricCues = [{ ...record.lyricCues[0], text: 'changed' }];
      if (outcome === 'audio') record.trackId = 'changed';
      return [collapsed];
    });
    await expect(h.run({ deps: { forceAlign }, isCancelled: () => cancelled })).rejects.toMatchObject(
      outcome === 'cancel' ? { canceled: true } : { code: outcome === 'text' ? 'LYRIC_ALIGN_TEXT_CHANGED' : 'MUSIC_VIDEO_AUDIO_CHANGED' });
    expect(forceAlign).toHaveBeenLastCalledWith(expect.any(Buffer), expect.any(Array), expect.objectContaining({ startSec: 0, endSec: 3 }));
    expect(h.updateProject).not.toHaveBeenCalled();
  });

  it('re-aligns one stem line preserving current director edits and the other occurrence', async () => {
    const record = { ...project, vocalStemFilename: 'stem.wav', lyricCues: [
      { id: 'a', text: 'walking home', startSec: 1, endSec: 2, suspect: true },
      { id: 'b', text: 'walking home', startSec: 4, endSec: 5, suspect: true },
    ] };
    const h = harness(vi.fn(), record, {
      resolveAudio: async () => ({ path: 'stem.wav', source: 'vocal-stem' }),
    });
    const stem = encodePcm16Wav(16000 * 6);
    for (let i = 16000; i < 32000; i++) stem.writeInt16LE(5000, 44 + i * 2);
    h.decodeAudio.mockResolvedValue(stem);
    const forceAlign = vi.fn(async () => {
      record.lyricCues = [{ ...record.lyricCues[0], startSec: 1.2, endSec: 2.5 }, record.lyricCues[1]];
      return [[{ w: 'walking', startSec: 1.2, endSec: 1.5, conf: 'matched' }, { w: 'home', startSec: 1.5, endSec: 2, conf: 'matched' }]];
    });
    const saved = await h.run({ cueId: 'a', deps: { forceAlign } });
    expect(forceAlign).toHaveBeenCalledWith(stem, [expect.objectContaining({ id: 'a' })], expect.objectContaining({ startSec: 1, endSec: 2 }));
    expect(saved.lyricCues[0]).toMatchObject({ startSec: 1.2, endSec: 2.5, matched: 1, suspect: false });
    expect(saved.lyricCues[1]).toEqual(record.lyricCues[1]);
    expect(saved.lyricAlignSource).toBeUndefined();
  });

  it('saves nothing when CTC lands in silence, the song or text changes, or alignment is cancelled', async () => {
    for (const outcome of ['silence', 'audio', 'text', 'cancel']) {
      const record = { ...project, vocalStemFilename: 'stem.wav', lyricCues: [{ id: 'a', text: 'walking', startSec: null, endSec: null }] };
      const h = harness(vi.fn(), record, { resolveAudio: async () => ({ path: 'stem.wav', source: 'vocal-stem' }) });
      const stem = encodePcm16Wav(16000 * 3);
      if (outcome !== 'silence') for (let i = 16000; i < 32000; i++) stem.writeInt16LE(5000, 44 + i * 2);
      h.decodeAudio.mockResolvedValue(stem);
      let cancelled = false;
      const forceAlign = async () => {
        if (outcome === 'audio') record.trackId = 'changed';
        if (outcome === 'text') record.lyricCues = [{ ...record.lyricCues[0], text: 'changed' }];
        if (outcome === 'cancel') cancelled = true;
        return [[{ w: 'walking', startSec: 1, endSec: 2, conf: 'matched' }]];
      };
      await expect(h.run({ deps: { forceAlign }, isCancelled: () => cancelled })).rejects.toMatchObject(
        outcome === 'cancel' ? { canceled: true } : { code: { silence: 'LYRIC_ALIGN_SILENT_WORDS', audio: 'MUSIC_VIDEO_AUDIO_CHANGED', text: 'LYRIC_ALIGN_TEXT_CHANGED' }[outcome] });
      expect(h.updateProject).not.toHaveBeenCalled();
    }
  });

  it('separates a missing stem only with explicit consent, then aligns that stem', async () => {
    const record = { ...project, lyricCues: [{ id: 'a', text: 'walking', startSec: null, endSec: null }] };
    const separated = { ...record, vocalStemFilename: 'stem.wav' };
    const updateProject = vi.fn(async (_id, patch) => ({ ...separated, ...patch }));
    const separateVocals = vi.fn(async () => separated);
    const forceAlign = vi.fn(async () => [[{ w: 'walking', startSec: 1, endSec: 2, conf: 'matched' }]]);
    const stem = encodePcm16Wav(16000 * 3);
    for (let i = 16000; i < 32000; i++) stem.writeInt16LE(5000, 44 + i * 2);
    const saved = await alignProjectLyrics('mv-1', { separateVocals: true, deps: {
      getProject: vi.fn().mockResolvedValueOnce(record).mockResolvedValue(separated), updateProject, separateVocals, forceAlign,
      resolveAudio: async (project) => { expect(project.vocalStemFilename).toBe('stem.wav'); return { path: 'stem.wav', source: 'vocal-stem' }; },
      decodeAudio: async () => stem,
    } });
    expect(separateVocals).toHaveBeenCalledOnce();
    expect(forceAlign).toHaveBeenCalledOnce();
    expect(saved.lyricAlignSilentWords).toBe(0);
    const legacy = harness(vi.fn(async () => [{ text: 'walking', startSec: 1, endSec: 2 }]), record);
    await legacy.run({ deps: { separateVocals } });
    expect(separateVocals).toHaveBeenCalledOnce();
  });

  it('names the analysis sections after the lyric sheet once the lines are timed', async () => {
    const record = {
      ...project,
      lyricCues: [
        { id: 'lc-1', text: 'walking home', startSec: null, endSec: null },
        { id: 'lc-2', text: 'under neon', startSec: null, endSec: null },
      ],
      lyricMarkers: [
        { type: 'section', label: 'Verse 1', kind: 'verse', line: 0 },
        { type: 'section', label: 'Chorus', kind: 'chorus', line: 1 },
      ],
      audioAnalysis: {
        bpm: 120, beats: [], downbeats: [], durationSec: 12,
        sections: [
          { label: 'Section 1', startSec: 0, endSec: 2, energy: 0.2 },
          { label: 'Section 2', startSec: 2, endSec: 5, energy: 0.5 },
          { label: 'Section 3', startSec: 5, endSec: 9, energy: 0.9 },
          { label: 'Section 4', startSec: 9, endSec: 12, energy: 0.3 },
        ],
      },
    };
    const transcribe = vi.fn(async () => [
      { text: 'walking', startSec: 2.2, endSec: 3 }, { text: 'home', startSec: 3, endSec: 4.5 },
      { text: 'under', startSec: 5.1, endSec: 6 }, { text: 'neon', startSec: 6, endSec: 8.8 },
    ]);
    const saved = await harness(transcribe, record).run();
    expect(saved.audioAnalysis.sections.map((section) => [section.label, section.labelSource ?? null])).toEqual([
      ['Intro', 'lyrics'], ['Verse 1', 'lyrics'], ['Chorus', 'lyrics'], ['Outro', 'lyrics'],
    ]);
    expect(saved.audioAnalysis.sections[2]).toMatchObject({ analysisLabel: 'Section 3', startSec: 5, endSec: 9, energy: 0.9 });
  });

  it('re-aligns one windowed line without moving the other line', async () => {
    const record = {
      ...project,
      lyricCues: [
        {
          id: 'lc-1', text: 'walking home', startSec: 0.5, endSec: 1.5,
          words: [
            { w: 'walking', startSec: 0.5, endSec: 1, conf: 'matched' },
            { w: 'home', startSec: 1, endSec: 1.5, conf: 'matched' },
          ],
        },
        { id: 'lc-2', text: 'not sung here', startSec: 2, endSec: 2.8 },
      ],
    };
    const transcribe = vi.fn(async () => []);
    const saved = await harness(transcribe, record).run({ cueId: 'lc-2' });
    expect(transcribe).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({ startSec: 2, endSec: 2.8 }));
    expect(saved.lyricCues[0].words).toEqual(record.lyricCues[0].words);
    expect(saved.lyricCues[1].words.every((word) => word.conf === 'interpolated')).toBe(true);
    expect(saved.lyricCues[1].words.every((word) => word.startSec >= 2 && word.endSec <= 2.8)).toBe(true);
  });

  it('stops the runner and saves nothing when transcription fails', async () => {
    const failure = new ServerError('no whisper', { status: 503, code: 'LYRIC_ALIGN_STT_UNAVAILABLE' });
    const transcribe = vi.fn(async () => { throw failure; });
    const { run, updateProject, release } = harness(transcribe);
    await expect(run()).rejects.toBe(failure);
    expect(updateProject).not.toHaveBeenCalled();
    expect(release).toHaveBeenCalledOnce();
  });

  it('does not transcribe when the project has no lyric lines', async () => {
    const transcribe = vi.fn();
    const { run, decodeAudio } = harness(transcribe, { ...project, lyricCues: [] });
    await expect(run()).rejects.toMatchObject({ code: 'NO_LYRICS' });
    expect(transcribe).not.toHaveBeenCalled();
    expect(decodeAudio).not.toHaveBeenCalled();
  });
});