videobook 0.0.0-stage → 0.2.0

package/dist/jobs/smooth-scene-concat.js

@@ -0,0 +1,257 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AUDIO_OPTS, FFMPEG, H264_MEDIUM, probeVideo, runFfmpeg, } from "../ffmpeg.js";
+import { registerJobHandler, queue } from "../queue.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { ingestWorkspaceOutputs } from "./_persist-output.js";
+import { fixedTransitionSeconds, MIN_TRANSITION_SECONDS } from "../scene-transition.js";
+const execFileAsync = promisify(execFile);
+const LOCK_DURATION_MS = 1_800_000;
+const PCM_SAMPLE_RATE = 8_000;
+const MIN_AUDIO_OVERLAP_SECONDS = 0.08;
+const MAX_AUDIO_OVERLAP_SECONDS = 3;
+const AUDIO_MATCH_THRESHOLD = 0.8;
+function mediaNumber(value) {
+    return value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+async function decodeMonoPcm(path, startSeconds, durationSeconds, signal) {
+    const { stdout } = await execFileAsync(FFMPEG, [
+        "-hide_banner",
+        "-loglevel", "error",
+        "-i", path,
+        "-ss", mediaNumber(startSeconds),
+        "-t", mediaNumber(durationSeconds),
+        "-map", "0:a:0",
+        "-vn",
+        "-ac", "1",
+        "-ar", String(PCM_SAMPLE_RATE),
+        "-f", "s16le",
+        "pipe:1",
+    ], {
+        encoding: "buffer",
+        maxBuffer: 2 * 1024 * 1024,
+        signal,
+    });
+    const buffer = stdout;
+    return new Int16Array(buffer.buffer, buffer.byteOffset, Math.floor(buffer.byteLength / Int16Array.BYTES_PER_ELEMENT));
+}
+function correlationForOverlap(first, second, overlapSamples) {
+    const firstStart = first.length - overlapSamples;
+    let firstSum = 0;
+    let secondSum = 0;
+    let firstSquares = 0;
+    let secondSquares = 0;
+    let products = 0;
+    for (let index = 0; index < overlapSamples; index++) {
+        const firstSample = first[firstStart + index];
+        const secondSample = second[index];
+        firstSum += firstSample;
+        secondSum += secondSample;
+        firstSquares += firstSample * firstSample;
+        secondSquares += secondSample * secondSample;
+        products += firstSample * secondSample;
+    }
+    const firstVariance = firstSquares - (firstSum * firstSum) / overlapSamples;
+    const secondVariance = secondSquares - (secondSum * secondSum) / overlapSamples;
+    const minimumVariance = overlapSamples * 64 * 64;
+    if (firstVariance < minimumVariance || secondVariance < minimumVariance)
+        return null;
+    const covariance = products - (firstSum * secondSum) / overlapSamples;
+    return covariance / Math.sqrt(firstVariance * secondVariance);
+}
+function bestAudioOverlap(first, second) {
+    const minimumSamples = Math.ceil(MIN_AUDIO_OVERLAP_SECONDS * PCM_SAMPLE_RATE);
+    const maximumSamples = Math.min(first.length, second.length);
+    if (maximumSamples < minimumSamples)
+        return null;
+    const coarseStep = Math.max(1, Math.round(PCM_SAMPLE_RATE / 1_000));
+    let bestSamples = minimumSamples;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    const evaluate = (samples) => {
+        const score = correlationForOverlap(first, second, samples);
+        if (score === null)
+            return;
+        if (score > bestScore || (score === bestScore && samples > bestSamples)) {
+            bestSamples = samples;
+            bestScore = score;
+        }
+    };
+    for (let samples = minimumSamples; samples <= maximumSamples; samples += coarseStep) {
+        evaluate(samples);
+    }
+    evaluate(maximumSamples);
+    const refineStart = Math.max(minimumSamples, bestSamples - coarseStep + 1);
+    const refineEnd = Math.min(maximumSamples, bestSamples + coarseStep - 1);
+    for (let samples = refineStart; samples <= refineEnd; samples++)
+        evaluate(samples);
+    if (!Number.isFinite(bestScore) || bestScore < AUDIO_MATCH_THRESHOLD)
+        return null;
+    return {
+        overlapSeconds: bestSamples / PCM_SAMPLE_RATE,
+        score: bestScore,
+    };
+}
+async function detectSharedAudioOverlap(firstPath, secondPath, firstAudioDuration, secondAudioDuration, signal) {
+    const windowSeconds = Math.min(MAX_AUDIO_OVERLAP_SECONDS, firstAudioDuration - MIN_TRANSITION_SECONDS, secondAudioDuration - MIN_TRANSITION_SECONDS);
+    if (windowSeconds < MIN_AUDIO_OVERLAP_SECONDS)
+        return null;
+    const [first, second] = await Promise.all([
+        decodeMonoPcm(firstPath, Math.max(0, firstAudioDuration - windowSeconds), windowSeconds, signal),
+        decodeMonoPcm(secondPath, 0, windowSeconds, signal),
+    ]);
+    return bestAudioOverlap(first, second);
+}
+async function resolveTransitionTiming(firstPath, secondPath, first, second, requested, signal) {
+    if (requested === undefined &&
+        first.hasAudio &&
+        second.hasAudio &&
+        first.audioDuration !== null &&
+        second.audioDuration !== null) {
+        const match = await detectSharedAudioOverlap(firstPath, secondPath, first.audioDuration, second.audioDuration, signal);
+        if (match) {
+            const secondStartSeconds = first.audioDuration - match.overlapSeconds;
+            const transitionSeconds = first.videoDuration - secondStartSeconds;
+            if (secondStartSeconds >= 0 &&
+                transitionSeconds >= MIN_TRANSITION_SECONDS &&
+                transitionSeconds < first.videoDuration &&
+                transitionSeconds < second.videoDuration) {
+                return {
+                    mode: "audio_match",
+                    transitionSeconds,
+                    secondStartSeconds,
+                    audioOverlapSeconds: match.overlapSeconds,
+                    matchScore: match.score,
+                };
+            }
+        }
+    }
+    const transitionSeconds = fixedTransitionSeconds(first.videoDuration, second.videoDuration, requested);
+    return {
+        mode: "fixed",
+        transitionSeconds,
+        secondStartSeconds: first.videoDuration - transitionSeconds,
+        audioOverlapSeconds: transitionSeconds,
+        matchScore: null,
+    };
+}
+function normalizedVideoFilter(input, label, width, height, fps) {
+    // Keep fps last: some Linux FFmpeg builds report a 1/0 frame rate after
+    // setpts, which xfade correctly rejects as variable-frame-rate input.
+    return `[${input}:v]scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,format=yuv420p,settb=AVTB,setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=${mediaNumber(1 / fps)},fps=${mediaNumber(fps)}[${label}]`;
+}
+function fixedAudioFilter(input, label, duration, hasAudio) {
+    if (!hasAudio) {
+        return `anullsrc=r=48000:cl=stereo:d=${mediaNumber(duration)}[${label}]`;
+    }
+    return `[${input}:a]aresample=48000,aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo,apad,atrim=duration=${mediaNumber(duration)},asetpts=PTS-STARTPTS[${label}]`;
+}
+function matchedAudioFilter(input, label, duration) {
+    return `[${input}:a]aresample=48000,aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo,atrim=duration=${mediaNumber(duration)},asetpts=PTS-STARTPTS[${label}]`;
+}
+async function renderSmoothConcat(options, first, second, timing) {
+    const width = first.width;
+    const height = first.height;
+    const fps = first.fps;
+    const outputDuration = timing.secondStartSeconds + second.videoDuration;
+    const filters = [
+        normalizedVideoFilter(0, "v0", width, height, fps),
+        normalizedVideoFilter(1, "v1", width, height, fps),
+        `[v0][v1]xfade=transition=fade:duration=${mediaNumber(timing.transitionSeconds)}:offset=${mediaNumber(timing.secondStartSeconds)},trim=duration=${mediaNumber(outputDuration)},format=yuv420p[v]`,
+    ];
+    const withAudio = first.hasAudio || second.hasAudio;
+    if (withAudio) {
+        if (timing.mode === "audio_match" &&
+            first.audioDuration !== null &&
+            second.audioDuration !== null) {
+            filters.push(matchedAudioFilter(0, "a0", first.audioDuration));
+            filters.push(matchedAudioFilter(1, "a1", second.audioDuration));
+        }
+        else {
+            filters.push(fixedAudioFilter(0, "a0", first.videoDuration, first.hasAudio));
+            filters.push(fixedAudioFilter(1, "a1", second.videoDuration, second.hasAudio));
+        }
+        filters.push(`[a0][a1]acrossfade=d=${mediaNumber(timing.audioOverlapSeconds)}:c1=tri:c2=tri,apad,atrim=duration=${mediaNumber(outputDuration)}[a]`);
+    }
+    await runFfmpeg([
+        "-y",
+        "-i", options.firstPath,
+        "-i", options.secondPath,
+        "-filter_complex", filters.join(";"),
+        "-map", "[v]",
+        ...(withAudio ? ["-map", "[a]"] : []),
+        ...H264_MEDIUM,
+        ...(withAudio ? AUDIO_OPTS : []),
+        "-movflags", "+faststart",
+        options.outputPath,
+    ], { signal: options.signal });
+    return outputDuration;
+}
+function validateProbe(label, probe) {
+    if (probe.width <= 0 || probe.height <= 0 || probe.videoDuration <= 0 || probe.fps <= 0) {
+        throw new Error(`${label} input is not a valid video`);
+    }
+}
+export async function smoothSceneConcatFiles(options) {
+    const [first, second] = await Promise.all([
+        probeVideo(options.firstPath, { signal: options.signal }),
+        probeVideo(options.secondPath, { signal: options.signal }),
+    ]);
+    validateProbe("First", first);
+    validateProbe("Second", second);
+    const timing = await resolveTransitionTiming(options.firstPath, options.secondPath, first, second, options.transitionSeconds, options.signal);
+    const outputDuration = await renderSmoothConcat(options, first, second, timing);
+    const output = await probeVideo(options.outputPath, { signal: options.signal });
+    validateProbe("Output", output);
+    if (Math.abs(output.videoDuration - outputDuration) > 1 / first.fps + 0.01) {
+        throw new Error(`Scene concat produced ${output.videoDuration.toFixed(3)}s of video instead of ${outputDuration.toFixed(3)}s`);
+    }
+    if ((first.hasAudio || second.hasAudio) && (!output.hasAudio
+        || Math.abs((output.audioDuration ?? output.duration) - outputDuration) > 0.15)) {
+        throw new Error("Scene concat output has missing or incomplete audio");
+    }
+    return { ...timing, outputDuration };
+}
+export function registerSmoothSceneConcatJob(engine) {
+    registerJobHandler("smooth_scene_concat", async (payload, ctx) => {
+        const { firstPath, secondPath, outputPath, firstAssetId, secondAssetId, assetId, assetDir, bookId, transitionSeconds, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "splice", { durationMs: LOCK_DURATION_MS, data: { state: "splicing" } }, async () => {
+            const concat = await smoothSceneConcatFiles({
+                firstPath,
+                secondPath,
+                outputPath,
+                transitionSeconds,
+                signal: ctx.signal,
+            });
+            const provenance = {
+                origin: "smooth_scene_concat",
+                first_asset: firstAssetId,
+                second_asset: secondAssetId,
+                alignment_mode: concat.mode,
+                transition_seconds: concat.transitionSeconds,
+                second_start_seconds: concat.secondStartSeconds,
+                audio_overlap_seconds: concat.audioOverlapSeconds,
+                match_score: concat.matchScore,
+                output_duration: concat.outputDuration,
+                concatenated_at: new Date().toISOString(),
+            };
+            await ingestWorkspaceOutputs(engine, assetId, [outputPath.split("/").pop()], "smooth_scene_concat", provenance);
+            await engine.metadata.artifacts.write(assetId, "original", provenance);
+            return { concat, provenance };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        const processJobId = `process-video-${assetId}-${Date.now()}`;
+        await queue.enqueue(processJobId, {
+            type: "process_video",
+            videoPath: outputPath,
+            assetId,
+            assetDir,
+            bookId,
+            provenance: result.provenance,
+        });
+        return {
+            success: true,
+            alignment_mode: result.concat.mode,
+            transition_seconds: result.concat.transitionSeconds,
+            match_score: result.concat.matchScore,
+        };
+    });
+}

package/dist/jobs/splice-video.js

@@ -0,0 +1,280 @@
+import { execFile, spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, extname, join } from "node:path";
+import { promisify } from "node:util";
+import { registerJobHandler, queue } from "../queue.js";
+import { runFfmpeg, FFMPEG, H264_MEDIUM, AUDIO_OPTS, probeVideo, withQuietFfmpegArgs } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { ingestWorkspaceOutputs } from "./_persist-output.js";
+const execFileAsync = promisify(execFile);
+const LOCK_DURATION_MS = 1_800_000;
+// Downsampled grayscale resolution used for both the target reference frame
+// and the scanned frames in video1. Small enough to keep the inner MAE loop
+// cheap (~4k bytes/frame) and to bound memory; large enough to discriminate
+// between visually distinct frames.
+const MATCH_W = 64;
+const MATCH_H = 64;
+const MATCH_FRAME_BYTES = MATCH_W * MATCH_H;
+async function extractTargetFrame(videoPath) {
+    const { stdout } = await execFileAsync(FFMPEG, withQuietFfmpegArgs([
+        "-y",
+        "-i", videoPath,
+        "-vf", `scale=${MATCH_W}:${MATCH_H},format=gray`,
+        "-frames:v", "1",
+        "-an",
+        "-f", "rawvideo",
+        "-pix_fmt", "gray",
+        "pipe:1",
+    ]), { encoding: "buffer", maxBuffer: 1024 * 1024 });
+    const buf = stdout;
+    if (buf.length < MATCH_FRAME_BYTES) {
+        throw new Error(`Target frame extraction returned ${buf.length} bytes, expected ${MATCH_FRAME_BYTES}`);
+    }
+    return buf.subarray(0, MATCH_FRAME_BYTES);
+}
+async function findBestMatch(videoPath, target, fps, startFrame) {
+    const startTime = startFrame / fps;
+    const proc = spawn(FFMPEG, withQuietFfmpegArgs([
+        ...(startFrame > 0 ? ["-ss", String(startTime)] : []),
+        "-i", videoPath,
+        "-vf", `fps=${fps},scale=${MATCH_W}:${MATCH_H},format=gray`,
+        "-an",
+        "-f", "rawvideo",
+        "-pix_fmt", "gray",
+        "pipe:1",
+    ]), { stdio: ["ignore", "pipe", "ignore"] });
+    let buffer = Buffer.alloc(0);
+    let frameIndex = 0;
+    let bestScore = Number.POSITIVE_INFINITY;
+    let bestIndex = -1;
+    for await (const chunk of proc.stdout) {
+        const incoming = chunk;
+        buffer = buffer.length === 0 ? incoming : Buffer.concat([buffer, incoming]);
+        while (buffer.length >= MATCH_FRAME_BYTES) {
+            let score = 0;
+            for (let i = 0; i < MATCH_FRAME_BYTES; i++) {
+                const d = buffer[i] - target[i];
+                score += d < 0 ? -d : d;
+            }
+            if (score < bestScore) {
+                bestScore = score;
+                bestIndex = frameIndex;
+            }
+            buffer = buffer.subarray(MATCH_FRAME_BYTES);
+            frameIndex++;
+        }
+    }
+    await new Promise((resolve, reject) => {
+        proc.on("close", (code) => {
+            if (code === 0 || code === null)
+                resolve();
+            else
+                reject(new Error(`ffmpeg search exited with code ${code}`));
+        });
+        proc.on("error", reject);
+    });
+    if (bestIndex < 0)
+        throw new Error(`No frames decoded from ${videoPath}`);
+    return {
+        frameIndex: startFrame + bestIndex,
+        timestamp: startTime + bestIndex / fps,
+        score: bestScore / MATCH_FRAME_BYTES,
+    };
+}
+async function spliceConcat(firstPath, secondPath, splicePoint, outputPath, width, height, fps, withAudio) {
+    const scalePad = `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1`;
+    const firstVideo = splicePoint === null
+        ? `[0:v]fps=${fps},${scalePad},setpts=PTS-STARTPTS[v0]`
+        : `[0:v]trim=end=${splicePoint},fps=${fps},${scalePad},setpts=PTS-STARTPTS[v0]`;
+    const filterParts = [
+        firstVideo,
+        `[1:v]fps=${fps},${scalePad},setpts=PTS-STARTPTS[v1]`,
+    ];
+    if (withAudio) {
+        const firstAudio = splicePoint === null
+            ? `[0:a]asetpts=PTS-STARTPTS[a0]`
+            : `[0:a]atrim=end=${splicePoint},asetpts=PTS-STARTPTS[a0]`;
+        filterParts.push(firstAudio);
+        filterParts.push(`[1:a]asetpts=PTS-STARTPTS[a1]`);
+        filterParts.push(`[v0][a0][v1][a1]concat=n=2:v=1:a=1[v][a]`);
+    }
+    else {
+        filterParts.push(`[v0][v1]concat=n=2:v=1:a=0[v]`);
+    }
+    const args = [
+        "-y",
+        "-i", firstPath,
+        "-i", secondPath,
+        "-filter_complex", filterParts.join(";"),
+        "-map", "[v]",
+        ...(withAudio ? ["-map", "[a]"] : []),
+        ...H264_MEDIUM,
+        ...(withAudio ? AUDIO_OPTS : []),
+        outputPath,
+    ];
+    await runFfmpeg(args);
+}
+async function verifySpliceDuration(outputPath, expectedDuration, fps) {
+    const output = await probeVideo(outputPath);
+    const tolerance = Math.max(0.25, 2 / fps);
+    if (Math.abs(output.videoDuration - expectedDuration) <= tolerance)
+        return;
+    throw new Error(`Splice output duration ${output.videoDuration.toFixed(3)}s does not match expected ${expectedDuration.toFixed(3)}s`);
+}
+async function readArtifactFile(engine, artifactId, filename) {
+    const result = await engine.files.read(artifactId, filename);
+    if (!result.ok) {
+        throw new Error(`Failed to snapshot ${artifactId}/${filename}: ${result.error.message}`);
+    }
+    return result.value;
+}
+export async function spliceVideoChain(options) {
+    const { clips, outputPath, workDir, width, height, fps, overlap } = options;
+    if (clips.length < 2) {
+        throw new Error("spliceVideoChain requires at least two clips");
+    }
+    let current = clips[0];
+    let lastResult = null;
+    for (let index = 1; index < clips.length; index += 1) {
+        const next = clips[index];
+        const isLast = index === clips.length - 1;
+        const dest = isLast ? outputPath : join(workDir, `acc-${index}.mp4`);
+        lastResult = await spliceVideoFiles({
+            firstPath: current.path,
+            secondPath: next.path,
+            outputPath: dest,
+            width,
+            height,
+            fps,
+            firstDuration: current.duration,
+            secondDuration: next.duration,
+            withAudio: current.hasAudio && next.hasAudio,
+            overlap,
+        });
+        current = {
+            path: dest,
+            duration: lastResult.timestamp + next.duration,
+            hasAudio: current.hasAudio && next.hasAudio,
+        };
+    }
+    if (!lastResult)
+        throw new Error("spliceVideoChain produced no output");
+    return lastResult;
+}
+export async function spliceVideoFiles(options) {
+    const { firstPath, secondPath, outputPath, width, height, fps, firstDuration, secondDuration, withAudio, overlap, } = options;
+    if (!Number.isFinite(firstDuration) || firstDuration <= 0) {
+        throw new Error(`Invalid first video duration: ${firstDuration}`);
+    }
+    if (!Number.isFinite(fps) || fps <= 0) {
+        throw new Error(`Invalid first video frame rate: ${fps}`);
+    }
+    if (!Number.isFinite(secondDuration) || secondDuration <= 0) {
+        throw new Error(`Invalid second video duration: ${secondDuration}`);
+    }
+    if (!Number.isFinite(overlap) || overlap < 0) {
+        throw new Error(`Overlap must be a non-negative number, got: ${overlap}`);
+    }
+    if (overlap === 0) {
+        await spliceConcat(firstPath, secondPath, null, outputPath, width, height, fps, withAudio);
+        await verifySpliceDuration(outputPath, firstDuration + secondDuration, fps);
+        return { timestamp: firstDuration, frameIndex: null, score: null };
+    }
+    const minimumWindow = 1 / fps;
+    const searchStart = Math.max(0, firstDuration - Math.max(overlap, minimumWindow));
+    const startFrame = Math.floor(searchStart * fps);
+    const target = await extractTargetFrame(secondPath);
+    const match = await findBestMatch(firstPath, target, fps, startFrame);
+    await spliceConcat(firstPath, secondPath, match.timestamp, outputPath, width, height, fps, withAudio);
+    await verifySpliceDuration(outputPath, match.timestamp + secondDuration, fps);
+    return match;
+}
+function clipPayloads(payload) {
+    if (Array.isArray(payload.clips) && payload.clips.length >= 2) {
+        return payload.clips;
+    }
+    return [
+        {
+            assetId: payload.firstAssetId,
+            filename: payload.firstFilename ?? basename(payload.firstPath),
+            duration: payload.firstDuration,
+            hasAudio: payload.firstHasAudio,
+        },
+        {
+            assetId: payload.secondAssetId,
+            filename: payload.secondFilename ?? basename(payload.secondPath),
+            duration: payload.secondDuration,
+            hasAudio: payload.secondHasAudio,
+        },
+    ];
+}
+export function registerSpliceVideoJob(engine) {
+    registerJobHandler("splice_video", async (payload, ctx) => {
+        const typedPayload = payload;
+        const { outputPath, assetId, assetDir, bookId, targetWidth, targetHeight, firstFps, overlap, } = typedPayload;
+        const clips = clipPayloads(typedPayload);
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "splice", { durationMs: LOCK_DURATION_MS, data: { state: "splicing" } }, async () => {
+            const sourceDir = await mkdtemp(join(tmpdir(), "videobook-splice-source-"));
+            try {
+                const snapshots = await Promise.all(clips.map(async (clip, index) => {
+                    const snapshotPath = join(sourceDir, `${index}${extname(clip.filename)}`);
+                    const bytes = await readArtifactFile(engine, clip.assetId, clip.filename);
+                    await writeFile(snapshotPath, bytes);
+                    const probed = typeof clip.duration === "number"
+                        ? null
+                        : await probeVideo(snapshotPath);
+                    return {
+                        path: snapshotPath,
+                        duration: typeof clip.duration === "number"
+                            ? clip.duration
+                            : probed.videoDuration,
+                        hasAudio: clip.hasAudio,
+                    };
+                }));
+                const resolvedOverlap = typeof overlap === "number"
+                    ? overlap
+                    : snapshots.length > 2
+                        ? 0
+                        : snapshots[0].duration;
+                const splice = await spliceVideoChain({
+                    clips: snapshots,
+                    outputPath,
+                    workDir: sourceDir,
+                    width: targetWidth,
+                    height: targetHeight,
+                    fps: firstFps,
+                    overlap: resolvedOverlap,
+                });
+                const additional = clips.slice(2).map((clip) => clip.assetId);
+                const provenance = {
+                    origin: "splice",
+                    first_asset: clips[0].assetId,
+                    second_asset: clips[1].assetId,
+                    ...(additional.length > 0 ? { additional_assets: additional } : {}),
+                    overlap_seconds: resolvedOverlap,
+                    splice_timestamp: splice.timestamp,
+                    match_frame_index: splice.frameIndex,
+                    match_score: splice.score,
+                    spliced_at: new Date().toISOString(),
+                };
+                await ingestWorkspaceOutputs(engine, assetId, [basename(outputPath)], "splice_video", provenance);
+                await engine.metadata.artifacts.write(assetId, "original", provenance);
+                return { provenance, timestamp: splice.timestamp, score: splice.score };
+            }
+            finally {
+                await rm(sourceDir, { recursive: true, force: true });
+            }
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        const processJobId = `process-video-${assetId}-${Date.now()}`;
+        await queue.enqueue(processJobId, {
+            type: "process_video",
+            videoPath: outputPath,
+            assetId,
+            assetDir,
+            bookId,
+            provenance: result.provenance,
+        });
+        return { success: true, splice_timestamp: result.timestamp, match_score: result.score };
+    });
+}

package/dist/jobs/split-video.js

@@ -0,0 +1,127 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerJobHandler, queue } from "../queue.js";
+import { assertSaneTrimOutput } from "./trim-video.js";
+import { AUDIO_OPTS, H264_MEDIUM, probeVideo, runFfmpeg } from "../ffmpeg.js";
+async function buildChunk(engine, args) {
+    const { sourcePath, outputPath, start, end, assetId, provenance } = args;
+    const workspace = await mkdtemp(join(tmpdir(), "videobook-split-video-"));
+    const tempPath = join(workspace, "output.mp4");
+    try {
+        const startTime = start ?? 0;
+        const endTime = end ?? (await probeVideo(sourcePath)).videoDuration;
+        await runFfmpeg([
+            "-y", "-ss", String(startTime), "-i", sourcePath,
+            "-t", String(endTime - startTime),
+            "-map", "0:v:0", "-map", "0:a:0?",
+            ...H264_MEDIUM, ...AUDIO_OPTS, "-movflags", "+faststart", tempPath,
+        ]);
+        await assertSaneTrimOutput(sourcePath, tempPath);
+        const written = await engine.files.writeFromPath(assetId, outputPath.split("/").pop(), tempPath);
+        if (!written.ok)
+            throw new Error(written.error.message);
+        const recorded = await engine.history.recordOperation("split_video", assetId, provenance);
+        if (!recorded.ok)
+            throw new Error(recorded.error.message);
+        const metadata = await engine.metadata.artifacts.write(assetId, "original", provenance);
+        if (!metadata.ok)
+            throw new Error(metadata.error.message);
+    }
+    finally {
+        await rm(workspace, { recursive: true, force: true });
+    }
+}
+export function registerSplitVideoJob(engine) {
+    // The destination assets are brand-new, so no other job can hold a lease on
+    // them; we run the two chunks in parallel against the read-only source.
+    registerJobHandler("split_video", async (payload) => {
+        const { sourcePath, sourceAssetId, chunkAEnd, chunkBStart, assetIdA, assetDirA, outputPathA, assetIdB, assetDirB, outputPathB, bookId, } = payload;
+        const overlapSec = Math.max(0, chunkAEnd - chunkBStart);
+        const splitAt = (chunkAEnd + chunkBStart) / 2;
+        const splitAtIso = new Date().toISOString();
+        const provenanceA = {
+            origin: "split",
+            source_asset_id: sourceAssetId,
+            split_at: splitAt,
+            overlap_sec: overlapSec,
+            chunk: "a",
+            chunk_start: 0,
+            chunk_end: chunkAEnd,
+            split_at_iso: splitAtIso,
+        };
+        const provenanceB = {
+            origin: "split",
+            source_asset_id: sourceAssetId,
+            split_at: splitAt,
+            overlap_sec: overlapSec,
+            chunk: "b",
+            chunk_start: chunkBStart,
+            chunk_end: null,
+            split_at_iso: splitAtIso,
+        };
+        await Promise.all([
+            buildChunk(engine, {
+                sourcePath, outputPath: outputPathA,
+                start: undefined, end: chunkAEnd,
+                assetId: assetIdA,
+                provenance: provenanceA,
+            }),
+            buildChunk(engine, {
+                sourcePath, outputPath: outputPathB,
+                start: chunkBStart, end: undefined,
+                assetId: assetIdB,
+                provenance: provenanceB,
+            }),
+        ]);
+        // Both chunk media files already exist on disk at this point. Enqueue each
+        // process_video job independently (allSettled, not all): if one enqueue
+        // fails we must not abandon the other chunk's already-built media. Any
+        // chunk whose job fails to land is flagged as a recoverable error instead
+        // of being silently orphaned.
+        const chunks = [
+            {
+                label: "a",
+                jobId: `process-video-${assetIdA}-${Date.now()}`,
+                assetId: assetIdA,
+                assetDir: assetDirA,
+                videoPath: outputPathA,
+                provenance: provenanceA,
+            },
+            {
+                label: "b",
+                jobId: `process-video-${assetIdB}-${Date.now() + 1}`,
+                assetId: assetIdB,
+                assetDir: assetDirB,
+                videoPath: outputPathB,
+                provenance: provenanceB,
+            },
+        ];
+        const results = await Promise.allSettled(chunks.map((c) => queue.enqueue(c.jobId, {
+            type: "process_video",
+            videoPath: c.videoPath,
+            assetId: c.assetId,
+            assetDir: c.assetDir,
+            bookId,
+            provenance: c.provenance,
+        })));
+        const failed = [];
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            if (r.status === "rejected") {
+                const c = chunks[i];
+                const reason = r.reason instanceof Error ? r.reason.message : String(r.reason);
+                await engine.jobs.failures.write(c.assetId, {
+                    message: `split chunk ${c.label} was built but could not be queued for processing: ${reason}`,
+                    failCode: "split_enqueue_failed",
+                });
+                failed.push(`chunk ${c.label} (${c.assetId})`);
+            }
+        }
+        if (failed.length > 0) {
+            throw new Error(`split_video: failed to enqueue ${failed.join(", ")} for processing; ` +
+                `affected chunk(s) flagged as recoverable`);
+        }
+        return { success: true, chunk_a: assetIdA, chunk_b: assetIdB };
+    });
+}