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

35.4 KB
Raw Blame
/**
 * Music Video — draft excerpt render (#8986, part of #8966).
 *
 * Renders a director-chosen `[startSec, endSec)` window through the SAME
 * composed pipeline as a full render (`planMusicVideoRender` +
 * `buildMusicVideoFfmpegArgs` in `render.js`), then samples a contact sheet at
 * every cut and typography-cue boundary the window contains
 * (`excerptBoundaryTimes` + `encodeFileContactSheetAtTimes`). A frame check
 * alone can't validate motion/audio sync, so the excerpt file itself is the
 * primary artifact — the contact sheet is a quick-scan companion, and its
 * failure doesn't fail the excerpt.
 *
 * Mirrors render.js's job/SSE/cancel machinery on a SEPARATE job map and
 * per-project mutex: an excerpt draft and a full render are different
 * artifacts writing different output files, so nothing stops a director
 * running both — the mutex here only rejects a duplicate excerpt render on
 * the SAME project while one is already in flight.
 */

import { documentSceneVisualLayer } from '../../lib/musicVideoLayers.js';
import { captureMusicVideoEvidence } from '../../lib/musicVideoDependencies.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { unlink } from 'fs/promises';
import { join } from 'path';
import { tmpdir } from 'os';
import { ensureDir, PATHS } from '../../lib/fileUtils.js';
import { ServerError } from '../../lib/errorHandler.js';
import { spawn } from '../../lib/childProcess.js';
import { safeChildProcessOptions } from '../../lib/processEnv.js';
import { broadcastSse, attachSseClient as attachSse, closeJobAfterDelay } from '../../lib/sseUtils.js';
import { attachFfmpegRenderGuard } from '../../lib/ffmpegRenderGuard.js';
import { cancelMusicVideoRenderJob, isMusicVideoRenderCanceled } from './renderCancellation.js';
import { safeUnder } from '../../lib/ffmpeg.js';
import { filterGraphViaFile } from '../../lib/ffmpegFilterGraph.js';
import { encodeFileContactSheetAtTimes } from '../htmlComposition/encode.js';
import { getProject, listProjects, mutateProjectRecord } from './projects.js';
import { requireProject } from './requireProject.js';
import { assertCurrentPerformanceTakes, withDraftPerformanceFallbacks } from './performanceShot.js';
import { assertCurrentClipDependencies, planMusicVideoRender, buildMusicVideoFfmpegArgs, excerptBoundaryTimes, isLocalRenderMark, resolveMasterAudioPath, resolveSoundBedPath } from './render.js';
import { encodeCodeComposition, prepareCodeRender, writeCodeProofSheet } from './codeRender.js';
import { encodeDocumentComposition, prepareDocumentRender } from './documentRender.js';
import { composedLyricWindows, projectTypographyPlan } from './composition.js';
import { renderTypographyOverlays, removeCompositionScratch } from './compositionRender.js';
import { applyFilmLookFinish, filmLookFinishNeeded } from './filmLookFinish.js';
import { startExcerptOnProject, applyExcerptPatch } from './excerpt.js';
import { markRevisionRendering, settleRevisionRender } from './revision.js';
import { ensureInstanceId } from '../instanceIdentity.js';
import { musicVideoAspect, musicVideoAtAspect } from '../../lib/musicVideoAspect.js';
import { musicVideoEvents } from './events.js';
import { pilotDependencies, productionPilotRenderProject } from './productionPilot.js';
import { musicVideoDependencyChanges } from '../../lib/musicVideoDependencies.js';
import { excerptRangeFits } from '../../lib/musicVideoExcerptRange.js';
import { trackedRenderMap } from '../renderActivity.js';

const jobs = new Map();
const projectExcerptRenders = trackedRenderMap('music-video-excerpt', { noun: 'music video draft render', link: (key) => `/music-video/${encodeURIComponent(key)}` });
const PENDING = Symbol('mv-excerpt-render-pending');

export const attachExcerptRenderSseClient = (jobId, res) => attachSse(jobs, jobId, res);

export function cancelExcerptRender(jobId) {
  return cancelMusicVideoRenderJob(jobs.get(jobId), { label: 'music-video excerpt render' });
}

const round3 = (n) => Math.round(n * 1000) / 1000;
const sheetFilenameFor = (filename) => `${filename.replace(/\.mp4$/, '')}-sheet.png`;
// A filename read back off a (possibly peer-synced) record is only ever
// resolved inside its own media directory.
const unlinkUnder = (root, filename) => {
  const path = safeUnder(root, filename);
  return path ? unlink(path).catch(() => {}) : Promise.resolve();
};

// The encoder wrote the excerpt and its contact sheet in place; the settling
// row that first names them commits under a backup lease (#9982), so a
// snapshot never dumps a row naming bytes its file copy missed.
const settleExcerptRecord = (projectId, excerptId, patch) => withBackupAssetPublication(() => mutateProjectRecord(projectId, (current) => ({
  project: settleRevisionRender(applyExcerptPatch(current, excerptId, { ...patch, partialFilename: null, renderingOn: null }), excerptId, patch),
})));

/**
 * Kick off a draft excerpt render. Returns `{ jobId, excerptId }`.
 * `revisionId` (#8987) links the render to an open selective revision in the
 * same write that creates the excerpt, so its finish settles that revision.
 */
// A code-rendered or composition-document project excerpts the same seekable
// composition, windowed on song time, instead of the footage concat.
const SEEKED_EXCERPTS = Object.freeze({
  eidoverse: {
    label: 'Eidoverse Video',
    prepare: async (project) => {
      const plan = await (await import('./eidoverseRender.js')).prepareEidoverseRender(project);
      return { plan, totalSec: plan.durationSec, songSections: (project.scenes || [])
        .filter(s => s.endSec > s.startSec).map(s => ({ sceneId: s.sceneId, startSec: s.startSec, endSec: s.endSec })) };
    },
    encode: async ({ prepared, startSec, endSec, ...input }) => (await import('./eidoverseRender.js')).encodeEidoverseComposition({
      ...input, plan: prepared.plan, windowStart: startSec, windowEnd: endSec,
    }),
  },
  code: {
    label: 'code',
    prepare: async (project) => {
      const full = prepareCodeRender(project);
      return { full, totalSec: full.durationSec, songSections: full.song.sections.map((s) => ({ sceneId: s.sceneId || s.id, startSec: s.startSec, endSec: s.endSec })) };
    },
    encode: async ({ project, projectId, jobId, audioPath, outputPath, signal, onProgress, startSec, endSec, fade }) => {
      const plan = prepareCodeRender(project, { windowStart: startSec, windowEnd: endSec });
      await encodeCodeComposition({
        ...plan, audioPath, audioStartSec: startSec, outputPath, directory: `compositions/music-video/${projectId}/${jobId}`, signal, onProgress, fade,
      });
      return { width: plan.width, height: plan.height, fps: plan.fps, boundaryTimes: plan.sectionTimes };
    },
  },
  document: {
    label: 'composition document',
    soundBed: true,
    performanceTakes: true,
    prepare: async (project) => {
      const plan = await prepareDocumentRender(project);
      const songSections = (project.scenes || [])
        .filter((s) => s?.sceneId && typeof s.startSec === 'number' && typeof s.endSec === 'number' && s.endSec > s.startSec)
        .map((s) => ({ sceneId: s.sceneId, layer: documentSceneVisualLayer(project, s, { generated: project.composition?.document?.source?.kind === 'generated' }), startSec: s.startSec, endSec: s.endSec }));
      return { plan, totalSec: plan.durationSec, songSections };
    },
    encode: ({ prepared, project, jobId, audioPath, soundBed, outputPath, signal, onProgress, startSec, endSec, fade }) => encodeDocumentComposition({
      project, plan: prepared.plan, jobId, audioPath, soundBed, outputPath, signal, onProgress, windowStart: startSec, windowEnd: endSec, fade, collectFootageVisibility: true,
    }),
  },
});

async function launchSeekedExcerpt({ projectId, project: stored, startSec, endSec, revisionId, handOff, renderer, aspect = null, fade = false }) {
  // A social cut renders the same composition at another frame (#9280): the
  // re-framed view drives planning, staging and capture; the record keeps its own aspect.
  const project = musicVideoAtAspect(stored, aspect);
  // A missing master throws before the excerpt is marked rendering.
  const audioPath = await resolveMasterAudioPath(project);
  // A draft draws a stale performance shot as a cutaway; the excerpt still records the real selection.
  const drawn = renderer.performanceTakes ? await withDraftPerformanceFallbacks(project, audioPath) : project;
  const prepared = await renderer.prepare(drawn);
  if (renderer.performanceTakes) {
    assertCurrentClipDependencies(drawn);
    await assertCurrentPerformanceTakes(drawn, audioPath);
  }
  const soundBed = renderer.soundBed ? await resolveSoundBedPath(project) : null;
  if (!excerptRangeFits(startSec, endSec, prepared.totalSec, prepared.plan?.fps ?? prepared.full?.fps)) {
    throw new ServerError(
      `The excerpt range must fall within the project's ${prepared.totalSec.toFixed(2)}s song`,
      { status: 422, code: 'INVALID_EXCERPT_RANGE', context: { totalDuration: prepared.totalSec } },
    );
  }
  const endClamped = Math.min(endSec, prepared.totalSec);
  await ensureDir(PATHS.videos);
  await ensureDir(PATHS.videoThumbnails);
  const filename = `music-video-excerpt-${projectId.slice(0, 8)}-${Date.now()}.mp4`;
  const outputPath = join(PATHS.videos, filename);
  const sections = prepared.songSections
    .filter((section) => section.startSec < endClamped && section.endSec > startSec)
    .map((section) => ({
      sceneId: section.sceneId,
      startSec: round3(Math.max(section.startSec, startSec)),
      endSec: round3(Math.min(section.endSec, endClamped)),
    }));
  const renderingOn = await ensureInstanceId();
  const { excerpt } = await mutateProjectRecord(projectId, (current) => {
    const started = startExcerptOnProject(current, { startSec, endSec: endClamped, sections, performanceProject: project, dependencies: captureMusicVideoEvidence(project, { sceneIds: sections.map((section) => section.sceneId), startSec, endSec: endClamped }), partialFilename: filename, renderingOn, aspect: musicVideoAspect(project), fade });
    return revisionId ? { ...started, project: markRevisionRendering(started.project, revisionId, started.excerpt.id) } : started;
  });
  const excerptId = excerpt.id;
  const jobId = excerptId;
  const totalDuration = endClamped - startSec;
  const job = { id: jobId, projectId, excerptId, status: 'running', clients: [], process: null, totalDuration, overlayAbort: new AbortController() };
  jobs.set(jobId, job);
  projectExcerptRenders.set(projectId, jobId);
  handOff();
  const Label = `${renderer.label[0].toUpperCase()}${renderer.label.slice(1)}`;
  console.log(`🎬 Rendering ${renderer.label} music-video excerpt [${jobId.slice(4, 12)}]: project=${projectId.slice(0, 8)} range=[${startSec.toFixed(2)},${endClamped.toFixed(2)}]s footage=off`);
  const { signal } = job.overlayAbort;
  const finalize = async (patch) => {
    projectExcerptRenders.delete(projectId);
    const persisted = await settleExcerptRecord(projectId, excerptId, patch).then(() => true, (err) => {
      console.error(`❌ Music-video ${renderer.label} excerpt [${jobId.slice(4, 12)}] project ${projectId.slice(0, 8)} status→${patch.status} write failed: ${err.message}`);
      return false;
    });
    closeJobAfterDelay(jobs, jobId);
    if (persisted) musicVideoEvents.emit('excerpt-render', { projectId, excerptId, status: patch.status });
    return persisted;
  };
  Promise.resolve().then(() => renderer.encode({
    prepared, project: drawn, projectId, jobId, audioPath, soundBed, outputPath, signal, startSec, endSec: endClamped, fade,
    onProgress: (fraction) => broadcastSse(job, { type: 'progress', progress: fraction }),
  })).then(async (encoded) => {
    job.overlayAbort = null;
    job.status = 'complete';
    let contactSheetFilename = null;
    try {
      contactSheetFilename = sheetFilenameFor(filename);
      await writeCodeProofSheet(outputPath, join(PATHS.videoThumbnails, contactSheetFilename), encoded.boundaryTimes, {
        width: encoded.width, height: encoded.height, fps: encoded.fps,
      });
    } catch (err) {
      console.warn(`⚠️ Music-video ${renderer.label} excerpt contact sheet failed [${jobId.slice(4, 12)}]: ${err.message}`);
      contactSheetFilename = null;
    }
    const persisted = await finalize({ status: 'complete', filename, contactSheetFilename, error: null, jobId: null, width: encoded.width ?? null, height: encoded.height ?? null, ...(encoded.footageVisibility ? { footageVisibility: encoded.footageVisibility } : {}) });
    if (!persisted) {
      await unlink(outputPath).catch(() => {});
      broadcastSse(job, { type: 'error', error: 'The excerpt rendered, but saving the result failed — reload the project and try again' });
      return;
    }
    console.log(`✅ ${Label} music-video excerpt rendered [${jobId.slice(4, 12)}]: ${filename}`);
    broadcastSse(job, { type: 'complete', result: { excerptId, filename, path: `/data/videos/${filename}`, contactSheetFilename, contactSheetPath: contactSheetFilename ? `/data/video-thumbnails/${contactSheetFilename}` : null } });
  }).catch(async (err) => {
    const canceled = signal.aborted || err?.code === 'CANCELED';
    job.status = canceled ? 'canceled' : 'error';
    const reason = canceled ? 'Render cancelled' : `${Label} excerpt failed: ${err.message}`;
    job.lastError = reason;
    const log = canceled ? console.log : console.error;
    log(`${canceled ? '🛑' : '❌'} Music-video ${renderer.label} excerpt ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(4, 12)}]: ${reason}`);
    await unlink(outputPath).catch(() => {});
    await finalize({ status: canceled ? 'canceled' : 'error', error: canceled ? null : reason, filename: null, jobId: null });
    broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
  });
  return { jobId, excerptId };
}

/**
 * Render [startSec, endSec) of a seekable composition (document, code, Eidoverse) at `aspect`
 * straight to `outputPath`, with no excerpt record: the publishing kit's native 9:16 cut.
 * Resolves the encode's frame (`{ width, height, … }`), or null when the project has no
 * seekable composition. A document that does not lay itself out at that frame throws
 * COMPOSITION_DOCUMENT_FORMAT, which the caller takes as "not available".
 * `deps` (tests): `renderers` stands in for the seeked renderers, `resolveAudio` for the master lookup.
 */
export async function renderSeekedWindow(stored, { startSec, endSec, aspect, fade = false, outputPath, jobId, signal, onProgress }, { renderers = SEEKED_EXCERPTS, resolveAudio = resolveMasterAudioPath } = {}) {
  const renderer = renderers[stored?.composition?.mode];
  if (!renderer) return null;
  const project = musicVideoAtAspect(stored, aspect);
  const prepared = await renderer.prepare(project);
  const audioPath = await resolveAudio(project);
  if (renderer.performanceTakes) {
    assertCurrentClipDependencies(project);
    await assertCurrentPerformanceTakes(project, audioPath);
  }
  const soundBed = renderer.soundBed ? await resolveSoundBedPath(project) : null;
  return renderer.encode({
    prepared, project, projectId: project.id, jobId, audioPath, soundBed, outputPath, signal,
    startSec, endSec: Math.min(endSec, prepared.totalSec), fade, onProgress,
  });
}

export async function startExcerptRender(projectId, { startSec, endSec, aspect = null, fade = false }, { revisionId = null, pilotSceneId = null, verifyCurrent = null } = {}) {
  const stored = await requireProject(projectId);
  await verifyCurrent?.(stored);
  const project = pilotSceneId ? productionPilotRenderProject(stored, pilotSceneId) : stored;
  const pilotEvidence = pilotSceneId ? pilotDependencies(stored, pilotSceneId) : null;
  if (pilotSceneId) {
    const scene = stored.scenes.find((s) => s.sceneId === pilotSceneId);
    if (startSec !== scene.startSec || endSec !== scene.endSec) throw new ServerError('The pilot must review its exact song window', { status: 422, code: 'INVALID_EXCERPT_RANGE' });
  }

  const existingJob = projectExcerptRenders.get(projectId);
  if (existingJob && (existingJob === PENDING || jobs.has(existingJob))) {
    throw new ServerError('An excerpt render is already in progress for this project', {
      status: 409, code: 'EXCERPT_RENDER_IN_PROGRESS', context: { jobId: existingJob === PENDING ? null : existingJob },
    });
  }
  projectExcerptRenders.set(projectId, PENDING);

  let handedOff = false;
  try {
    const seeked = SEEKED_EXCERPTS[project.composition?.mode];
    if (seeked) {
      return await launchSeekedExcerpt({
        projectId, project, startSec, endSec, revisionId, handOff: () => { handedOff = true; }, renderer: seeked, aspect, fade,
      });
    }
    // A footage (ffmpeg) render has no frame of its own to re-lay-out: cropping
    // the 16:9 cut would slice through its type and cards (#9280).
    if ((aspect && aspect !== musicVideoAspect(project)) || fade) {
      throw new ServerError('Social cuts (another aspect, faded edges) need a composition-document or code-rendered project', {
        status: 422, code: 'EXCERPT_ASPECT_UNSUPPORTED',
      });
    }
    const { ffmpeg, audioPath, composed, clips, audioDurationSec, soundBed, aspect: canvasAspect } = await planMusicVideoRender(project, { draft: true });
    await ensureDir(PATHS.videos);
    await ensureDir(PATHS.videoThumbnails);

    // A probe pass (no `excerpt` option) gets the full-song plan's canonical
    // dims/fps/sections/cues in ABSOLUTE song time — the coordinate space
    // `startSec`/`endSec` and `excerptBoundaryTimes` are given in.
    const probe = buildMusicVideoFfmpegArgs(clips, audioPath, join(PATHS.videos, 'probe.mp4'), { audioDurationSec, frameGrid: composed, aspect: canvasAspect });
    // A range ending on the song's analysed length may overrun the frame-rounded render by under a frame.
    if (!excerptRangeFits(startSec, endSec, probe.totalDuration, probe.fps)) {
      throw new ServerError(
        `The excerpt range must fall within the project's ${probe.totalDuration.toFixed(2)}s render`,
        { status: 422, code: 'INVALID_EXCERPT_RANGE', context: { totalDuration: probe.totalDuration } },
      );
    }
    const endClamped = Math.min(endSec, probe.totalDuration);
    const filename = `music-video-excerpt-${projectId.slice(0, 8)}-${Date.now()}.mp4`;
    const outputPath = join(PATHS.videos, filename);
    // #8987: the sections this draft cuts, in absolute song time and clipped to
    // the window — a flagged review note maps onto one of these when the
    // director asks for a selective revision.
    const sections = probe.sections
      .filter((s) => s.startSec < endClamped && s.endSec > startSec)
      .map((s) => ({ sceneId: s.sceneId, layer: s.layer, startSec: round3(Math.max(s.startSec, startSec)), endSec: round3(Math.min(s.endSec, endClamped)) }));

    // Persist the new `status: 'rendering'` excerpt against the FRESHEST
    // record (not the `project` snapshot planning read above), so a
    // concurrent note/edit on another excerpt can't be clobbered. The output
    // filename is recorded now so a restart mid-encode can delete the partial,
    // and the mark names this instance so a synced peer's boot recovery can't
    // demote it (#9010).
    const renderingOn = await ensureInstanceId();
    await verifyCurrent?.(await getProject(projectId));
    const { excerpt } = await mutateProjectRecord(projectId, (current) => {
      if (pilotEvidence && musicVideoDependencyChanges(current, pilotEvidence).length) throw new ServerError('The selected pilot changed before rendering', { status: 409, code: 'COMPOSITION_DRAFT_STALE' });
      const started = startExcerptOnProject(current, { startSec, endSec: endClamped, sections, performanceProject: stored, dependencies: pilotEvidence || captureMusicVideoEvidence(project, { sceneIds: sections.map((section) => section.sceneId), startSec, endSec: endClamped }), partialFilename: filename, renderingOn, aspect: musicVideoAspect(project) });
      return revisionId ? { ...started, project: markRevisionRendering(started.project, revisionId, started.excerpt.id) } : started;
    });
    const excerptId = excerpt.id;
    const jobId = excerptId;

    // The record and revision are already marked rendering, so a throw before
    // the job takes ownership (e.g. the filter-graph temp write) must settle them,
    // or the revision would refuse to resume until a restart (#11777).
    let cues; let style; let lyricWindows; let composition; let totalDuration; let graphPath; let plainEncode; let job;
    try {
      // Only the cue/card windows overlapping the window are worth capturing —
      // typography outside it never survives the final trim.
      const planned = projectTypographyPlan(project, clips, probe.sections, probe.totalDuration);
      style = planned.style;
      const allCues = composed ? planned.cues : [];
      cues = allCues.filter((c) => c.startSec < endClamped && c.endSec > startSec);
      lyricWindows = (composed ? composedLyricWindows(project, endClamped) : [])
        .filter((w) => w.endSec > startSec).map((w) => ({ ...w, startSec: Math.max(w.startSec, startSec) }));
      composition = cues.length > 0 || lyricWindows.length > 0 ? project.composition : null;

      totalDuration = endClamped - startSec;
      // A long filter graph goes to ffmpeg in this file, removed once ffmpeg exits.
      graphPath = join(tmpdir(), `portos-music-video-${jobId}.filtergraph`);
      plainEncode = composition ? null : await filterGraphViaFile(ffmpeg, buildMusicVideoFfmpegArgs(clips, audioPath, outputPath, { audioDurationSec, frameGrid: composed, excerpt: { startSec, endSec: endClamped }, soundBed, grade: composed ? project.composition?.grade : null, beats: project.audioAnalysis?.beats, aspect: canvasAspect }).args, graphPath);
      job = { id: jobId, projectId, excerptId, status: 'running', clients: [], process: null, totalDuration };
      jobs.set(jobId, job);
      projectExcerptRenders.set(projectId, jobId);
    } catch (err) {
      await settleExcerptRecord(projectId, excerptId, { status: 'error', error: err.message, filename: null, jobId: null }).catch((settleErr) => {
        console.error(`❌ Music-video excerpt [${jobId.slice(4, 12)}] project ${projectId.slice(0, 8)} could not settle after a setup failure: ${settleErr.message}`);
      });
      throw err;
    }
    handedOff = true;

    console.log(`🎬 Rendering music-video excerpt [${jobId.slice(4, 12)}]: project=${projectId.slice(0, 8)} range=[${startSec.toFixed(2)},${endClamped.toFixed(2)}]s clips=${clips.length} cues=${cues.length}`);

    // Returns whether the persistence write succeeded — the success path below
    // gates its 'complete' broadcast on it, so a director is never told an
    // excerpt is ready when the record never actually recorded it (the project
    // would otherwise stay stuck 'rendering' while the client believes it's
    // done). Error/cancel paths attempt persistence before notifying clients
    // to refresh; boot recovery clears a record if that write also fails.
    const finalize = async (patch) => {
      projectExcerptRenders.delete(projectId);
      const persisted = await settleExcerptRecord(projectId, excerptId, patch)
        .then(() => true, (err) => {
          console.error(`❌ Music-video excerpt render [${jobId.slice(4, 12)}] project ${projectId.slice(0, 8)} status→${patch.status} write failed: ${err.message}`);
          return false;
        });
      if (composition) await removeCompositionScratch(jobId).catch((err) => {
        console.warn(`⚠️ Music-video excerpt render [${jobId.slice(4, 12)}] could not remove its overlay scratch: ${err.message}`);
      });
      closeJobAfterDelay(jobs, jobId);
      // #8988: an auto-review run waiting on this draft continues from here.
      if (persisted) musicVideoEvents.emit('excerpt-render', { projectId, excerptId, status: patch.status });
      return persisted;
    };

    // A cut/cue contact sheet is a best-effort companion artifact — its
    // failure never fails an excerpt whose video encoded successfully.
    const buildContactSheet = async () => {
      try {
        const times = excerptBoundaryTimes(probe.sections, cues, startSec, endClamped, { fps: probe.fps });
        const sheetFilename = sheetFilenameFor(filename);
        await encodeFileContactSheetAtTimes(outputPath, join(PATHS.videoThumbnails, sheetFilename), times, { width: probe.canonW, height: probe.canonH, fps: probe.fps });
        return sheetFilename;
      } catch (err) {
        console.warn(`⚠️ Music-video excerpt render [${jobId.slice(4, 12)}] contact sheet failed: ${err.message}`);
        return null;
      }
    };

    // The encode's failure and cancel path, shared with the film look pass.
    const settleFailure = async (canceled, reason) => {
      job.status = canceled ? 'canceled' : 'error';
      job.lastError = reason;
      const log = canceled ? console.log : console.error;
      log(`${canceled ? '🛑' : '❌'} Music-video excerpt render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(4, 12)}]: ${reason}`);
      // #8986 acceptance: cancelling an excerpt removes its partial output.
      await unlink(outputPath).catch(() => {});
      await finalize({ status: canceled ? 'canceled' : 'error', error: canceled ? null : reason, filename: null, jobId: null });
      broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
    };

    // A footage excerpt with a film look re-encodes its finished window through
    // the look after ffmpeg (filmLookFinish.js), on song time so the grain
    // matches the final render's frames.
    const finishing = filmLookFinishNeeded(project);
    const startEncode = (encode, progressBase = 0) => {
      const encodeTop = finishing ? progressBase + (1 - progressBase) / 2 : 1;
      const encodeProgress = (fraction) => progressBase + (encodeTop - progressBase) * fraction;
      const dropGraphFile = () => (encode.file ? unlink(encode.file).catch(() => {}) : null);
      const proc = spawn(ffmpeg, encode.args, safeChildProcessOptions({ stdio: ['ignore', 'ignore', 'pipe'] }));
      job.process = proc;

      let stderrBuf = '';
      proc.stderr.on('data', (chunk) => {
        stderrBuf += chunk.toString();
        const lines = stderrBuf.split('\n');
        stderrBuf = lines.pop();
        for (const raw of lines) {
          const line = raw.trim();
          const eq = line.indexOf('=');
          if (eq <= 0) continue;
          const key = line.slice(0, eq);
          const val = line.slice(eq + 1);
          if (key === 'out_time_us') {
            const us = parseInt(val, 10);
            if (Number.isFinite(us) && totalDuration > 0) {
              broadcastSse(job, { type: 'progress', progress: encodeProgress(Math.min(1, (us / 1_000_000) / totalDuration)) });
            }
          } else if (key === 'progress' && val === 'end') {
            broadcastSse(job, { type: 'progress', progress: encodeTop });
          }
        }
      });

      attachFfmpegRenderGuard(proc, {
        label: `Music-video excerpt render [${jobId.slice(4, 12)}]`,
        onProcessError: (err) => {
          job.lastError = `ffmpeg process error: ${err.message}`;
          console.log(`⚠️ Music-video excerpt render post-spawn error [${jobId.slice(4, 12)}]: ${err.message}`);
        },
        onSpawnError: async (err) => {
          await dropGraphFile();
          job.process = null;
          job.status = 'error';
          const reason = `Failed to spawn ffmpeg: ${err.message}`;
          job.lastError = reason;
          console.error(`❌ Music-video excerpt render spawn error [${jobId.slice(4, 12)}]: ${reason}`);
          // Persist before broadcasting: a client that reloads the instant it
          // sees the terminal frame must not race ahead of the write and read
          // back a stale `status: 'rendering'`.
          await finalize({ status: 'error', error: reason, filename: null, jobId: null });
          broadcastSse(job, { type: 'error', error: reason });
        },
        onClose: async (code, signal) => {
          job.process = null;
          await dropGraphFile();
          if (code !== 0) {
            const canceled = isMusicVideoRenderCanceled(job, signal);
            await settleFailure(canceled, canceled ? 'Render cancelled' : signal ? `Killed by signal ${signal}` : `ffmpeg exit ${code}`);
            return;
          }
          if (finishing) {
            job.overlayAbort = new AbortController();
            const { signal: finishSignal } = job.overlayAbort;
            try {
              await applyFilmLookFinish({ project, path: outputPath, jobId, offsetSec: startSec, signal: finishSignal, label: 'Music-video excerpt film look',
                onProgress: (fraction) => broadcastSse(job, { type: 'progress', progress: encodeTop + (1 - encodeTop) * fraction }) });
            } catch (err) {
              await settleFailure(finishSignal.aborted, finishSignal.aborted ? 'Render cancelled' : `Film look pass failed: ${err.message}`);
              return;
            }
            job.overlayAbort = null;
          }
          try {
            job.status = 'complete';
            const contactSheetFilename = await buildContactSheet();
            const persisted = await finalize({ status: 'complete', filename, contactSheetFilename, error: null, jobId: null });
            if (!persisted) {
              // The record write never landed, so nothing else could have
              // learned these filenames to reference them — clean up rather
              // than leaving them as permanently unreferenced orphans on disk.
              await unlink(outputPath).catch(() => {});
              if (contactSheetFilename) await unlink(join(PATHS.videoThumbnails, contactSheetFilename)).catch(() => {});
              broadcastSse(job, { type: 'error', error: 'The excerpt rendered, but saving the result failed — reload the project and try again' });
              return;
            }
            console.log(`✅ Music-video excerpt rendered [${jobId.slice(4, 12)}]: ${filename}`);
            broadcastSse(job, { type: 'complete', result: { excerptId, filename, path: `/data/videos/${filename}`, contactSheetFilename, contactSheetPath: contactSheetFilename ? `/data/video-thumbnails/${contactSheetFilename}` : null } });
          } catch (err) {
            job.status = 'error';
            job.lastError = `Finalize failed: ${err.message}`;
            console.error(`❌ Music-video excerpt render finalize failed [${jobId.slice(4, 12)}]: ${err.message}`);
            await finalize({ status: 'error', error: 'Finalize failed', filename: null, jobId: null });
            broadcastSse(job, { type: 'error', error: 'Excerpt render finalize failed' });
          }
        },
      });
    };

    if (!composition) {
      startEncode(plainEncode);
      return { jobId, excerptId };
    }

    job.overlayAbort = new AbortController();
    const { signal } = job.overlayAbort;
    // Clamp each cue's capture start to the excerpt window: a title-card cue
    // (#8985) can span a whole song section, and capturing it from its TRUE
    // start would re-render everything before the window too, defeating the
    // point of a fast draft preview. The final `[outv]` trim below discards
    // anything before `startSec` anyway, so nothing visible is lost.
    const captureCues = cues.map((c) => ({ ...c, startSec: Math.max(c.startSec, startSec) }));
    renderTypographyOverlays({
      jobId, cues: captureCues, style, width: probe.canonW, height: probe.canonH, fps: probe.fps, durationSec: endClamped, signal,
      lyrics: lyricWindows.length > 0 ? { project, windows: lyricWindows } : null,
      onProgress: (fraction) => broadcastSse(job, { type: 'progress', progress: 0.5 * fraction }),
    }).then(async (overlays) => {
      signal.throwIfAborted();
      job.overlayAbort = null;
      const layered = buildMusicVideoFfmpegArgs(clips, audioPath, outputPath, { audioDurationSec, overlays, frameGrid: true, excerpt: { startSec, endSec: endClamped }, soundBed, grade: composed ? project.composition?.grade : null, beats: project.audioAnalysis?.beats, aspect: canvasAspect });
      startEncode(await filterGraphViaFile(ffmpeg, layered.args, graphPath), 0.5);
    }).catch(async (err) => {
      const canceled = signal.aborted;
      job.status = canceled ? 'canceled' : 'error';
      const reason = canceled ? 'Render cancelled' : `Typography overlay failed: ${err.message}`;
      job.lastError = reason;
      const log = canceled ? console.log : console.error;
      log(`${canceled ? '🛑' : '❌'} Music-video excerpt render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(4, 12)}]: ${reason}`);
      await finalize({ status: canceled ? 'canceled' : 'error', error: canceled ? null : reason, filename: null, jobId: null });
      broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
    });

    return { jobId, excerptId };
  } finally {
    if (!handedOff) projectExcerptRenders.delete(projectId);
  }
}

// Boot recovery: like recoverStuckMusicVideoRenders in render.js, no excerpt
// render survives a restart — the job map is memory-only. Demote any excerpt
// left `status: 'rendering'` with no live job to `error` so it isn't shown as
// perpetually in-flight (and its slot doesn't 409 every later excerpt render
// on that project). #8987: delete the partial video/contact sheet the
// interrupted encode was writing, and return a selective revision that was
// rendering that draft to `open` — resumable from its checkpoint, re-rendering
// without generating anything its sections already hold. #9010: an excerpt
// whose `renderingOn` names another instance is that peer's live render, not
// ours to demote.
export async function recoverStuckMusicVideoExcerpts() {
  const instanceId = await ensureInstanceId();
  const projects = await listProjects();
  let recovered = 0;
  for (const project of projects) {
    const stuck = (project.excerpts || []).filter((e) => e.status === 'rendering'
      && !projectExcerptRenders.has(project.id) && isLocalRenderMark(e.renderingOn, instanceId));
    if (stuck.length === 0) continue;
    // Re-checked against the FRESHEST record under the write lock: a peer sync
    // landing after the list may have finished the draft or handed it to
    // another instance, and only a still-stuck local mark is demoted.
    const stuckIds = new Set(stuck.map((e) => e.id));
    const outcome = await mutateProjectRecord(project.id, (current) => {
      const demoted = (current.excerpts || []).filter((e) => stuckIds.has(e.id) && e.status === 'rendering'
        && !projectExcerptRenders.has(project.id) && isLocalRenderMark(e.renderingOn, instanceId));
      let next = current;
      for (const excerpt of demoted) {
        next = { ...next, excerpts: (next.excerpts || []).map((e) => (e.id === excerpt.id ? { ...e, status: 'error', error: 'Interrupted by a server restart', jobId: null, partialFilename: null, renderingOn: null } : e)) };
        next = settleRevisionRender(next, excerpt.id, { status: 'error', error: 'The draft render was interrupted by a server restart' });
      }
      return { project: next, demoted };
    }).catch((err) => {
      console.error(`❌ Music Video excerpt recovery: project ${project.id.slice(0, 8)} write failed: ${err.message}`);
      return null;
    });
    // Only once the record no longer points at them, so a failed write can't
    // leave a record naming a file that is gone.
    if (!outcome) continue;
    recovered += outcome.demoted.length;
    for (const { partialFilename } of outcome.demoted) {
      if (typeof partialFilename !== 'string' || !partialFilename) continue;
      await unlinkUnder(PATHS.videos, partialFilename);
      await unlinkUnder(PATHS.videoThumbnails, sheetFilenameFor(partialFilename));
    }
  }
  if (recovered > 0) console.log(`🎬 Music Video excerpt boot recovery: demoted ${recovered} stuck excerpt render(s)`);
}