videobook 0.0.0-stage → 0.2.0

package/dist/jobs/suggest-cuts.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { logger } from "../logger.js";
+import { registerJobHandler } from "../queue.js";
+import { getApiKey } from "../api-key.js";
+import { INTELLIGENCE_MODEL, buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+import { withLocalLease } from "./_lease.js";
+import { TRIM_BUDGET_FRACTION, DEAD_AIR_THRESHOLD_S, TrimSchema, buildCutsContext, extractSilenceCandidates, filterValidTrims, loadAssetForAnalysis, sampleFrames, } from "../tools/_suggest-shared.js";
+const SYSTEM_PROMPT_CUTS = `You are a senior video editor reviewing a short clip. From the timestamped frames, optional transcript, and metadata you receive, return a strict JSON object suggesting sections to cut. Follow the user's editing request when provided.
+
+TRIM RULES (read carefully — most failures come from breaking these):
+
+1. Dead-air trims (severity "high"):
+   - MUST be drawn from the "Silence candidates" list provided in the user message.
+   - You MAY shrink a candidate to be more conservative (e.g., keep 0.2-0.4s of natural pause on each side). You MUST NOT expand a candidate or invent one not in the list.
+   - You MAY merge two adjacent candidates only if they are < 0.5s apart.
+   - If the user message says "no silence candidates", do not suggest any "high" severity trims.
+
+2. Filler-cluster trims (severity "med"):
+   - Require a word-timed transcript. Without word timings, do not suggest any "med" trims.
+   - The transcript MUST contain the filler verbatim ("um", "uh", "like", "you know") at the proposed timestamp range.
+   - Range MUST be tight around the filler word(s), typically < 1.5s.
+   - Do not propose a "med" trim spanning meaningful content.
+
+3. Visual pacing / minor trims (severity "low"):
+   - Use timestamped frames to identify clearly redundant visual holds or awkward lead-ins and tails. Explain the visible evidence and keep the ranges conservative.
+   - Without a transcript, only these visually supported "low" trims are allowed. Missing transcription is not evidence of silence or absence of dialogue. State in the summary that dialogue and audio timing were not assessed.
+   - Sparse frames do not prove what happens between them. Do not invent precise action boundaries; omit uncertain cuts.
+
+4. Hard limits:
+   - Total trim duration (sum of all cut_end - cut_start) MUST be <= the budget given in the user message.
+   - Never overlap trim ranges. cut_start < cut_end. Both within [0, duration].
+   - Do not cut spoken dialogue that completes a sentence. Do not cut audible chants, laughter, or other deliberate audio events.
+   - If unsure, omit. Empty trims is a valid answer.
+
+OUTPUT:
+- Decimal seconds (e.g. 12.4).
+- Do not invent content. Use what is visible in the frames or quoted in the transcript.
+- Prefer fewer high-confidence suggestions over noisy lists.
+- Output JSON only.`;
+const SUGGEST_CUTS_JSON_SCHEMA = {
+    type: "object",
+    required: ["trims", "summary"],
+    additionalProperties: false,
+    properties: {
+        trims: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["cut_start", "cut_end", "reason", "severity"],
+                additionalProperties: false,
+                properties: {
+                    cut_start: { type: "number" },
+                    cut_end: { type: "number" },
+                    reason: { type: "string" },
+                    severity: { type: "string", enum: ["low", "med", "high"] },
+                },
+            },
+        },
+        summary: { type: "string" },
+    },
+};
+const ModelOutputSchema = z.object({
+    trims: z.array(TrimSchema),
+    summary: z.string(),
+});
+export function registerSuggestCutsJob(engine) {
+    registerJobHandler("suggest_cuts", async (payload, ctx) => {
+        const { assetId, instructions } = payload;
+        return withLocalLease(engine, assetId, ctx, "analyze", async () => {
+            const apiKey = getApiKey("OPENAI_API_KEY");
+            if (!apiKey)
+                throw new Error("OPENAI_API_KEY environment variable is not set");
+            const loaded = await loadAssetForAnalysis(engine, assetId, { requireTranscript: false });
+            if (!loaded.ok)
+                throw new Error(loaded.error.message);
+            const { frameNames, transcript, meta, prior } = loaded.value;
+            const candidates = transcript.source === "elevenlabs"
+                ? extractSilenceCandidates(transcript.words, DEAD_AIR_THRESHOLD_S)
+                : [];
+            const duration = typeof meta?.duration === "number" && Number.isFinite(meta.duration) && meta.duration > 0
+                ? meta.duration : null;
+            const trimBudgetS = duration !== null ? duration * TRIM_BUDGET_FRACTION : Infinity;
+            const sampled = sampleFrames(frameNames);
+            const frameParts = [];
+            for (const file of sampled) {
+                const frameRead = await engine.files.read(assetId, `original_frames/${file}`);
+                if (!frameRead.ok)
+                    throw new Error(frameRead.error.message);
+                frameParts.push({ type: "input_text", text: `Frame timestamp: ${parseFloat(file).toFixed(3)}s` }, {
+                    type: "input_image",
+                    image_url: `data:image/jpeg;base64,${Buffer.from(frameRead.value).toString("base64")}`,
+                    detail: "high",
+                });
+            }
+            const contextString = buildCutsContext(meta, prior, transcript, sampled.length, candidates, trimBudgetS, instructions);
+            const userContent = [
+                { type: "input_text", text: contextString },
+                ...frameParts,
+            ];
+            const responses = buildIntelligenceResponses(apiKey);
+            const response = await responses(intelligenceRequest({
+                instructions: SYSTEM_PROMPT_CUTS,
+                input: [{ role: "user", content: userContent }],
+                text: {
+                    format: {
+                        type: "json_schema",
+                        name: "suggested_cuts",
+                        schema: SUGGEST_CUTS_JSON_SCHEMA,
+                        strict: true,
+                    },
+                },
+                max_output_tokens: 4096,
+            }), ctx.signal);
+            const outputText = firstResponseText(response);
+            let parsed;
+            try {
+                parsed = ModelOutputSchema.parse(JSON.parse(outputText));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Model output failed schema validation: ${msg}`);
+            }
+            const { kept, dropped } = filterValidTrims(parsed.trims, candidates, trimBudgetS, {
+                duration, transcriptSource: transcript.source,
+            });
+            if (dropped.length > 0) {
+                logger.warn("suggest-cuts-dropped", { assetId, count: dropped.length });
+            }
+            const final = {
+                trims: kept,
+                summary: parsed.summary,
+                based_on: {
+                    frames: sampled.length,
+                    transcript_source: transcript.source,
+                    silence_candidates: candidates,
+                    trim_budget_s: Number.isFinite(trimBudgetS) ? trimBudgetS : null,
+                    dropped_trims: dropped.map((d) => ({ trim: d.trim, reason: d.reason })),
+                },
+                model: INTELLIGENCE_MODEL,
+                asset_id: assetId,
+            };
+            const writeResult = await engine.files.write(assetId, ".suggest-cuts.json", JSON.stringify(final, null, 2));
+            if (!writeResult.ok) {
+                throw new Error(`Suggestions generated but failed to persist: ${writeResult.error.message}`);
+            }
+            return { success: true, trims: kept.length, dropped: dropped.length };
+        });
+    });
+}

package/dist/jobs/suggest-sfx.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { logger } from "../logger.js";
+import { registerJobHandler } from "../queue.js";
+import { getApiKey } from "../api-key.js";
+import { INTELLIGENCE_MODEL, buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+import { withLocalLease } from "./_lease.js";
+import { SfxSchema, buildSfxContext, loadAssetForAnalysis, sampleFrames, } from "../tools/_suggest-shared.js";
+const MAX_SFX = 8;
+const TIMESTAMP_END_BUFFER_S = 0.05;
+const SYSTEM_PROMPT_SFX = `You are a senior video editor reviewing a short clip. From the frames, transcript, and metadata you receive, return a strict JSON object suggesting sound effects to add.
+
+SFX RULES:
+- type: short slug ("whoosh", "impact", "pop", "ding", "ambient_room", "transition_swell").
+- Suggest only at clear visual or narrative beats (cuts, reveals, punchlines, scene changes). Cap at ${MAX_SFX}.
+- description: one sentence on what is on screen and why this SFX fits.
+
+OUTPUT:
+- Decimal seconds (e.g. 12.4).
+- Do not invent content. Use what is visible in the frames or quoted in the transcript.
+- Prefer fewer high-confidence suggestions over noisy lists.
+- Output JSON only, max ${MAX_SFX} entries.`;
+const SUGGEST_SFX_JSON_SCHEMA = {
+    type: "object",
+    required: ["sfx", "summary"],
+    additionalProperties: false,
+    properties: {
+        sfx: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["timestamp", "type", "description"],
+                additionalProperties: false,
+                properties: {
+                    timestamp: { type: "number" },
+                    type: { type: "string" },
+                    description: { type: "string" },
+                },
+            },
+        },
+        summary: { type: "string" },
+    },
+};
+const ModelOutputSchema = z.object({
+    sfx: z.array(SfxSchema),
+    summary: z.string(),
+});
+export function registerSuggestSfxJob(engine) {
+    registerJobHandler("suggest_sfx", async (payload, ctx) => {
+        const { assetId } = payload;
+        return withLocalLease(engine, assetId, ctx, "analyze", async () => {
+            const apiKey = getApiKey("OPENAI_API_KEY");
+            if (!apiKey)
+                throw new Error("OPENAI_API_KEY environment variable is not set");
+            const loaded = await loadAssetForAnalysis(engine, assetId);
+            if (!loaded.ok)
+                throw new Error(loaded.error.message);
+            const { frameNames, transcript, meta, prior } = loaded.value;
+            const sampled = sampleFrames(frameNames);
+            const frameParts = [];
+            for (const file of sampled) {
+                const frameRead = await engine.files.read(assetId, `original_frames/${file}`);
+                if (!frameRead.ok)
+                    throw new Error(frameRead.error.message);
+                frameParts.push({ type: "input_text", text: `Frame timestamp: ${parseFloat(file).toFixed(3)}s` }, {
+                    type: "input_image",
+                    image_url: `data:image/jpeg;base64,${Buffer.from(frameRead.value).toString("base64")}`,
+                    detail: "high",
+                });
+            }
+            const contextString = buildSfxContext(meta, prior, transcript, sampled.length);
+            const userContent = [
+                { type: "input_text", text: contextString },
+                ...frameParts,
+            ];
+            const responses = buildIntelligenceResponses(apiKey);
+            const response = await responses(intelligenceRequest({
+                instructions: SYSTEM_PROMPT_SFX,
+                input: [{ role: "user", content: userContent }],
+                text: {
+                    format: {
+                        type: "json_schema",
+                        name: "suggested_sound_effects",
+                        schema: SUGGEST_SFX_JSON_SCHEMA,
+                        strict: true,
+                    },
+                },
+                max_output_tokens: 4096,
+            }), ctx.signal);
+            const outputText = firstResponseText(response);
+            let parsed;
+            try {
+                parsed = ModelOutputSchema.parse(JSON.parse(outputText));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Model output failed schema validation: ${msg}`);
+            }
+            const duration = typeof meta?.duration === "number" ? meta.duration : null;
+            const droppedSfx = [];
+            const validSfx = [];
+            for (const entry of parsed.sfx) {
+                if (duration !== null && entry.timestamp > duration - TIMESTAMP_END_BUFFER_S) {
+                    droppedSfx.push({ sfx: entry, reason: `timestamp ${entry.timestamp.toFixed(2)}s past duration ${duration.toFixed(2)}s` });
+                    continue;
+                }
+                validSfx.push(entry);
+            }
+            const capped = validSfx.slice(0, MAX_SFX);
+            if (validSfx.length > MAX_SFX) {
+                for (const entry of validSfx.slice(MAX_SFX)) {
+                    droppedSfx.push({ sfx: entry, reason: `cap of ${MAX_SFX} entries exceeded` });
+                }
+            }
+            if (droppedSfx.length > 0) {
+                logger.warn("suggest-sfx-dropped", { assetId, count: droppedSfx.length });
+            }
+            const final = {
+                sfx: capped,
+                summary: parsed.summary,
+                based_on: {
+                    frames: sampled.length,
+                    transcript_source: transcript.source,
+                    dropped_sfx: droppedSfx,
+                },
+                model: INTELLIGENCE_MODEL,
+                asset_id: assetId,
+            };
+            const writeResult = await engine.files.write(assetId, ".suggest-sfx.json", JSON.stringify(final, null, 2));
+            if (!writeResult.ok) {
+                throw new Error(`Suggestions generated but failed to persist: ${writeResult.error.message}`);
+            }
+            return { success: true, sfx: capped.length, dropped: droppedSfx.length };
+        });
+    });
+}

package/dist/jobs/sync-video-to-audio.js

@@ -0,0 +1,329 @@
+import { findAudioFile, findVideoFile } from "videobook-engine";
+import { rm } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { hasTimedSpeechWords, resolveAudioCue } from "../audio-cue.js";
+import { buildAudioSyncVideoFilter, createAudioSyncPlan, } from "../audio-sync.js";
+import { AUDIO_OPTS, H264_MEDIUM, probeVideo, runFfmpeg } from "../ffmpeg.js";
+import { registerJobHandler, queue } from "../queue.js";
+import { requestElevenLabsTranscript, writeElevenLabsTranscript, } from "./_transcribe.js";
+import { claimLockedLease, withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+const LOCK_DURATION_MS = 900_000;
+const AUTO_TRANSCRIBE_OPTIONS = {
+    tagAudioEvents: true,
+    diarize: true,
+};
+const STALE_VISUAL_DERIVATIVES = [
+    ".original.analysis.json",
+    ".detect-scenes.json",
+    ".suggest-cuts.json",
+    ".suggest-sfx.json",
+    ".analyze-jokes.json",
+];
+export function resolveSyncVideoToAudioAnchors(anchors, transcript) {
+    return anchors.map((anchor) => ({
+        videoSeconds: anchor.videoSeconds,
+        audioSeconds: "audioSeconds" in anchor
+            ? anchor.audioSeconds
+            : resolveAudioCue(transcript, anchor.audioCue),
+    }));
+}
+function outputArgs(inputPath, outputPath, plan, audioMode) {
+    return [
+        "-y",
+        "-i", inputPath,
+        "-filter_complex", buildAudioSyncVideoFilter(plan),
+        "-map", "[vout]",
+        "-map", "0:a:0",
+        ...H264_MEDIUM,
+        "-pix_fmt", "yuv420p",
+        ...(audioMode === "copy" ? ["-c:a", "copy"] : AUDIO_OPTS),
+        "-t", plan.audioDuration.toFixed(9),
+        "-movflags", "+faststart",
+        "-f", "mp4",
+        outputPath,
+    ];
+}
+export async function renderAudioSyncedVideo(inputPath, outputPath, plan, signal) {
+    const source = await probeVideo(inputPath, { signal });
+    if (source.audioCodec !== "aac") {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, "aac"), { signal });
+        return "aac";
+    }
+    try {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, "copy"), { signal });
+        return "copy";
+    }
+    catch {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, "aac"), { signal });
+        return "aac";
+    }
+}
+export async function validateAudioSyncOutput(inputPath, outputPath, plan, signal) {
+    const [input, output] = await Promise.all([
+        probeVideo(inputPath, { signal }),
+        probeVideo(outputPath, { signal }),
+    ]);
+    if (output.videoCodec === null || output.width <= 0 || output.height <= 0) {
+        throw new Error("Audio-sync output has no usable video stream");
+    }
+    if (!output.hasAudio || output.audioDuration === null) {
+        throw new Error("Audio-sync output does not contain the original audio stream");
+    }
+    if (output.width !== input.width || output.height !== input.height) {
+        throw new Error(`Audio-sync output dimensions ${output.width}x${output.height} do not match source ${input.width}x${input.height}`);
+    }
+    const tolerance = Math.max(0.08, 2 / plan.sourceFps);
+    if (Math.abs(output.videoDuration - plan.audioDuration) > tolerance) {
+        throw new Error(`Audio-sync video duration ${output.videoDuration.toFixed(3)}s does not match audio ${plan.audioDuration.toFixed(3)}s`);
+    }
+    if (Math.abs(output.audioDuration - plan.audioDuration) > tolerance) {
+        throw new Error(`Audio-sync output audio duration ${output.audioDuration.toFixed(3)}s does not match source audio ${plan.audioDuration.toFixed(3)}s`);
+    }
+}
+async function readUsableTimedTranscript(engine, assetId) {
+    const result = await engine.files.read(assetId, "elevenlabs.json");
+    if (!result.ok) {
+        if (result.error.code === "NOT_FOUND")
+            return null;
+        throw new Error(`Failed to read elevenlabs.json: ${result.error.message}`);
+    }
+    try {
+        const transcript = JSON.parse(result.value.toString("utf8"));
+        return hasTimedSpeechWords(transcript) ? transcript : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function prepareAudioSyncTranscript(engine, assetId) {
+    const existing = await readUsableTimedTranscript(engine, assetId);
+    if (existing !== null)
+        return { transcript: existing, replacement: null };
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        throw new Error(`auto-transcribe failed: ${manifest.error.message}`);
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        throw new Error(`auto-transcribe failed: ${artifact.error.message}`);
+    const audioFile = findAudioFile(manifest.value.files, artifact.value.kind)
+        ?? findVideoFile(manifest.value.files);
+    if (!audioFile)
+        throw new Error(`auto-transcribe failed: no audio file found in asset ${assetId}`);
+    const replacement = await requestElevenLabsTranscript(engine, assetId, audioFile.name, AUTO_TRANSCRIBE_OPTIONS);
+    if (!hasTimedSpeechWords(replacement)) {
+        throw new Error(`Auto-transcription for ${assetId} did not return timed speech words`);
+    }
+    return { transcript: replacement, replacement };
+}
+async function deleteIfPresent(engine, assetId, filename) {
+    const result = await engine.files.delete(assetId, filename);
+    if (!result.ok && result.error.code !== "NOT_FOUND") {
+        throw new Error(`Failed to delete ${filename}: ${result.error.message}`);
+    }
+}
+async function discardTemp(outputPath) {
+    await rm(outputPath, { force: true });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function preserveArtifactState(error) {
+    const preserved = error instanceof Error ? error : new Error(String(error));
+    Object.assign(preserved, { preserveArtifactState: true });
+    return preserved;
+}
+export async function restoreAudioSyncSnapshot(engine, assetId, restoreCommit) {
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok) {
+        throw new Error(`Failed to resolve ${assetId} for restore: ${artifact.error.message}`);
+    }
+    const restored = await engine.history.restoreArtifact(artifact.value.artifactId, restoreCommit);
+    if (!restored.ok) {
+        throw new Error(`Failed to restore ${assetId} to ${restoreCommit}: ${restored.error.message}`);
+    }
+    return restored.value.hash;
+}
+function rollbackError(original, failures) {
+    return new Error(`Audio-sync failed: ${errorMessage(original)}. Rollback failed: ${failures.map(errorMessage).join("; ")}`);
+}
+async function clearAudioSyncFailure(engine, assetId) {
+    const cleared = await engine.jobs.failures.clear(assetId);
+    if (!cleared.ok) {
+        throw new Error(`Failed to clear audio-sync error for ${assetId}: ${cleared.error.message}`);
+    }
+}
+async function rollbackAudioSyncFailure(engine, assetId, outputPath, restoreCommit, original, markFailureHandled) {
+    const failures = [];
+    try {
+        await discardTemp(outputPath);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    try {
+        await clearAudioSyncFailure(engine, assetId);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    try {
+        await restoreAudioSyncSnapshot(engine, assetId, restoreCommit);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    if (failures.length > 0)
+        throw rollbackError(original, failures);
+    markFailureHandled();
+    throw preserveArtifactState(original);
+}
+async function restoreAfterEnqueueFailure(engine, assetId, assetDir, restoreCommit) {
+    const claim = await claimLockedLease(engine, assetId, assetDir, "change_speed", { durationMs: LOCK_DURATION_MS, data: { state: "rolling_back_audio_sync" } }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+    if (!claim.ok)
+        throw new Error(`Could not claim ${assetId} for rollback: ${claim.reason}`);
+    const released = await engine.jobs.locks.release(assetDir);
+    if (!released.ok) {
+        await engine.jobs.artifactWork.fail(assetId, claim.ownerId, {
+            message: released.error.message,
+        }).catch(() => undefined);
+        throw new Error(`Failed to release ${assetId} lock before rollback: ${released.error.message}`);
+    }
+    let restored = false;
+    try {
+        await clearAudioSyncFailure(engine, assetId);
+        await restoreAudioSyncSnapshot(engine, assetId, restoreCommit);
+        restored = true;
+    }
+    catch (error) {
+        await engine.jobs.artifactWork.fail(assetId, claim.ownerId, {
+            message: errorMessage(error),
+        }).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        if (restored) {
+            engine.jobs.artifactWork.complete(assetId, claim.ownerId);
+        }
+    }
+}
+function requestedAnchorMetadata(anchor) {
+    return "audioSeconds" in anchor
+        ? { video_seconds: anchor.videoSeconds, audio_seconds: anchor.audioSeconds }
+        : { video_seconds: anchor.videoSeconds, audio_cue: anchor.audioCue };
+}
+export function registerSyncVideoToAudioJob(engine) {
+    registerJobHandler("sync_video_to_audio", async (payload, ctx) => {
+        const { inputPath, outputPath, anchors, assetId, assetDir, bookId, } = payload;
+        const rollbackState = {
+            enteredLease: false,
+            restoreCommit: null,
+        };
+        let result;
+        try {
+            result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "change_speed", { durationMs: LOCK_DURATION_MS, data: { state: "syncing_audio" } }, async () => {
+                rollbackState.enteredLease = true;
+                const history = engine.history.artifact(assetId);
+                rollbackState.restoreCommit = history[0]?.hash ?? null;
+                if (!rollbackState.restoreCommit) {
+                    throw new Error(`sync_video_to_audio requires revision history for ${assetId}`);
+                }
+                const source = await probeVideo(inputPath, { signal: ctx.signal });
+                if (source.videoCodec === null || source.videoDuration <= 0) {
+                    throw new Error(`sync_video_to_audio requires a usable video stream in ${assetId}`);
+                }
+                if (!source.hasAudio || source.audioDuration === null || source.audioDuration <= 0) {
+                    throw new Error(`sync_video_to_audio requires an audio stream in ${assetId}`);
+                }
+                const preparedTranscript = anchors.some((anchor) => "audioCue" in anchor)
+                    ? await prepareAudioSyncTranscript(engine, assetId)
+                    : null;
+                const resolvedAnchors = resolveSyncVideoToAudioAnchors(anchors, preparedTranscript?.transcript);
+                const plan = createAudioSyncPlan({
+                    videoDuration: source.videoDuration,
+                    audioDuration: source.audioDuration,
+                    sourceFps: source.fps,
+                    anchors: resolvedAnchors,
+                });
+                const audioMode = await renderAudioSyncedVideo(inputPath, outputPath, plan, ctx.signal);
+                await validateAudioSyncOutput(inputPath, outputPath, plan, ctx.signal);
+                const inputFilename = basename(inputPath);
+                await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+                if (preparedTranscript?.replacement) {
+                    await writeElevenLabsTranscript(engine, assetId, preparedTranscript.replacement, AUTO_TRANSCRIBE_OPTIONS);
+                }
+                for (const filename of STALE_VISUAL_DERIVATIVES) {
+                    await deleteIfPresent(engine, assetId, filename);
+                }
+                return {
+                    videoPath: join(assetDir, basename(inputPath)),
+                    plan,
+                    requestedAnchors: anchors,
+                    resolvedAnchors,
+                    audioMode,
+                    restoreCommit: rollbackState.restoreCommit,
+                };
+            }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        }
+        catch (error) {
+            if (!rollbackState.enteredLease)
+                throw error;
+            if (rollbackState.restoreCommit === null) {
+                try {
+                    await clearAudioSyncFailure(engine, assetId);
+                }
+                catch (clearError) {
+                    throw rollbackError(error, [clearError]);
+                }
+                throw error;
+            }
+            return rollbackAudioSyncFailure(engine, assetId, outputPath, rollbackState.restoreCommit, error, () => ctx.markAssetFailureHandled());
+        }
+        try {
+            await queue.enqueue(`process-video-${assetId}-${Date.now()}`, {
+                type: "process_video",
+                videoPath: result.videoPath,
+                assetId,
+                assetDir,
+                bookId,
+                provenance: {
+                    origin: "audio_sync",
+                    requested_anchors: result.requestedAnchors.map(requestedAnchorMetadata),
+                    resolved_anchors: result.plan.anchors.map((anchor) => ({
+                        video_seconds: anchor.videoSeconds,
+                        audio_seconds: anchor.audioSeconds,
+                    })),
+                    video_duration: result.plan.videoDuration,
+                    audio_duration: result.plan.audioDuration,
+                    mapping_method: "monotone_cubic_hermite",
+                    audio_preserved: true,
+                    audio_mode: result.audioMode,
+                    audio_synced_at: new Date().toISOString(),
+                },
+                force: true,
+                skipDownstreamJobs: true,
+                preserveAudioArtifacts: true,
+                reviveVisualAnalysis: true,
+            });
+        }
+        catch (error) {
+            try {
+                await restoreAfterEnqueueFailure(engine, assetId, assetDir, result.restoreCommit);
+            }
+            catch (restoreError) {
+                throw rollbackError(error, [restoreError]);
+            }
+            throw preserveArtifactState(error);
+        }
+        return {
+            success: true,
+            video_duration: result.plan.videoDuration,
+            audio_duration: result.plan.audioDuration,
+            resolved_anchors: result.resolvedAnchors.map((anchor) => ({
+                video_seconds: anchor.videoSeconds,
+                audio_seconds: anchor.audioSeconds,
+            })),
+            audio_mode: result.audioMode,
+        };
+    });
+}