videobook 0.0.0-stage → 0.2.0

package/dist/jobs/_transcribe.js

@@ -0,0 +1,245 @@
+import { createElevenLabs } from "../usage-providers.js";
+import { findAudioFile } from "videobook-engine";
+import { requireApiKey } from "../api-key.js";
+import { enqueueAssetTagging } from "./tag-asset.js";
+const ELEVENLABS_TIMEOUT_MS = 5 * 60_000;
+function inferAudioMime(filename) {
+    const ext = filename.toLowerCase().split(".").pop() ?? "";
+    switch (ext) {
+        case "mp3":
+            return "audio/mpeg";
+        case "wav":
+            return "audio/wav";
+        case "m4a":
+            return "audio/mp4";
+        case "ogg":
+            return "audio/ogg";
+        case "weba":
+            return "audio/webm";
+        case "flac":
+            return "audio/flac";
+        case "mp4":
+        case "mov":
+            return "video/mp4";
+        default:
+            return "application/octet-stream";
+    }
+}
+/**
+ * Transcribe an asset's audio with ElevenLabs scribe_v2 and write the result
+ * to `elevenlabs.json` in the asset directory. Lease-agnostic: the caller owns
+ * the asset lease (the transcribe job's local lease, or the render job's render
+ * lease when auto-transcribing). Throws on missing API key, unreadable audio,
+ * or a failed write so the caller can surface the failure.
+ */
+export async function transcribeAssetToElevenLabsJson(engine, assetId, audioFilename, options) {
+    const response = await requestElevenLabsTranscript(engine, assetId, audioFilename, options);
+    await writeElevenLabsTranscript(engine, assetId, response, options);
+}
+export async function requestElevenLabsTranscript(engine, assetId, audioFilename, options) {
+    const apiKey = requireApiKey("ELEVENLABS_API_KEY");
+    const readResult = await engine.files.read(assetId, audioFilename);
+    if (!readResult.ok) {
+        throw new Error(`Failed to read audio for ${assetId}: ${readResult.error.message}`);
+    }
+    const audioBytes = new Uint8Array(readResult.value);
+    const audioBlob = new Blob([audioBytes], { type: inferAudioMime(audioFilename) });
+    const provider = createElevenLabs({ apiKey, timeout: ELEVENLABS_TIMEOUT_MS });
+    const request = {
+        model_id: "scribe_v2",
+        file: audioBlob,
+        tag_audio_events: options.tagAudioEvents,
+        diarize: options.diarize,
+        ...(options.languageCode ? { language_code: options.languageCode } : {}),
+    };
+    return provider.v1.speechToText(request);
+}
+export async function writeElevenLabsTranscript(engine, assetId, response, options) {
+    const transcriptionStr = JSON.stringify(response, null, 2);
+    const writeResult = await engine.files.write(assetId, "elevenlabs.json", transcriptionStr);
+    if (!writeResult.ok) {
+        throw new Error(`Failed to write transcription: ${writeResult.error.message}`);
+    }
+    await importElevenLabsTranscript(engine, assetId, response, options);
+    await engine.history.recordOperation("transcribe", assetId, {
+        ...(options.languageCode ? { language_code: options.languageCode } : {}),
+    });
+}
+export async function importElevenLabsTranscript(engine, assetId, response, options) {
+    const source = normalizedTranscripts(response);
+    if (source.length === 0) {
+        throw new Error("ElevenLabs returned an acknowledgement without transcript content");
+    }
+    const streams = engine.streams.list(assetId);
+    if (!streams.ok) {
+        throw new Error(`Failed to read media streams for ${assetId}: ${streams.error.message}`);
+    }
+    const stream = streams.value.find((candidate) => candidate.kind === "audio");
+    if (!stream)
+        throw new Error(`No audio stream is registered for ${assetId}`);
+    const segments = transcriptSegments(source, stream);
+    const language = options.languageCode
+        ?? [...source].sort((left, right) => right.language_probability - left.language_probability)[0]?.language_code
+        ?? "und";
+    const imported = await engine.transcripts.import({
+        artifactId: assetId,
+        streamId: stream.streamId,
+        objectHash: stream.objectHash,
+        language,
+        provider: "elevenlabs",
+        model: "scribe_v2",
+        state: "current",
+        segments,
+    });
+    if (!imported.ok) {
+        throw new Error(`Failed to import transcript for ${assetId}: ${imported.error.message}`);
+    }
+    // Speech is the evidence audio tagging reads, and it can change what a video
+    // is grouped by too.
+    await enqueueAssetTagging(engine, assetId);
+    return imported.value;
+}
+function normalizedTranscripts(response) {
+    if ("words" in response)
+        return [response];
+    if ("transcripts" in response)
+        return response.transcripts;
+    return [];
+}
+function transcriptSegments(transcripts, stream) {
+    const timedWords = transcripts
+        .flatMap((transcript) => transcript.words.map((word) => ({
+        ...word,
+        channelIndex: transcript.channel_index,
+    })))
+        .filter((word) => word.type !== "spacing"
+        && Number.isFinite(word.start)
+        && Number.isFinite(word.end)
+        && word.end > word.start)
+        .sort((left, right) => left.start - right.start
+        || left.channelIndex - right.channelIndex
+        || left.end - right.end);
+    const drafts = [];
+    for (const word of timedWords) {
+        const kind = word.type === "audio_event"
+            ? audioEventKind(word.text)
+            : "speech";
+        const speaker = speakerLabel(word);
+        const previous = drafts.at(-1);
+        const joinsPrevious = kind === "speech"
+            && previous?.kind === "speech"
+            && previous.speaker === speaker
+            && previous.channelIndex === word.channelIndex
+            && word.start - previous.end <= 1.25
+            && word.end - previous.start <= 15;
+        if (joinsPrevious && previous) {
+            previous.end = Math.max(previous.end, word.end);
+            previous.words.push(word);
+            previous.text = joinedSpeech(previous.words);
+            continue;
+        }
+        drafts.push({
+            kind,
+            ...(speaker ? { speaker } : {}),
+            channelIndex: word.channelIndex,
+            start: word.start,
+            end: word.end,
+            words: kind === "speech" ? [word] : [],
+            text: kind === "speech" ? word.text.trim() : word.text.trim(),
+        });
+    }
+    return drafts.map((draft, ordinal) => {
+        const startTick = secondsToTick(draft.start, stream);
+        const endTick = Math.max(startTick + 1, secondsToTick(draft.end, stream));
+        const confidenceValues = draft.words
+            .map(wordConfidence)
+            .filter((value) => value !== undefined);
+        const confidence = confidenceValues.length > 0
+            ? confidenceValues.reduce((sum, value) => sum + value, 0)
+                / confidenceValues.length
+            : undefined;
+        return {
+            ordinal,
+            range: {
+                streamId: stream.streamId,
+                objectHash: stream.objectHash,
+                startTick,
+                durationTicks: Math.min(stream.durationTicks, endTick) - startTick,
+                timeBase: stream.timeBase,
+            },
+            ...(draft.speaker ? { speaker: draft.speaker } : {}),
+            text: draft.text,
+            ...(confidence !== undefined ? { confidence } : {}),
+            kind: draft.kind,
+            words: draft.words.map((word, wordOrdinal) => {
+                const wordStartTick = secondsToTick(word.start, stream);
+                const wordEndTick = Math.max(wordStartTick + 1, secondsToTick(word.end, stream));
+                const wordConfidenceValue = wordConfidence(word);
+                return {
+                    ordinal: wordOrdinal,
+                    startTick: wordStartTick,
+                    durationTicks: Math.min(stream.durationTicks, wordEndTick) - wordStartTick,
+                    text: word.text.trim(),
+                    ...(wordConfidenceValue !== undefined
+                        ? { confidence: wordConfidenceValue }
+                        : {}),
+                    corrected: false,
+                };
+            }),
+        };
+    });
+}
+function secondsToTick(seconds, stream) {
+    const tick = Math.round(seconds * stream.timeBase.denominator / stream.timeBase.numerator);
+    return Math.max(0, Math.min(stream.durationTicks - 1, tick));
+}
+function speakerLabel(word) {
+    const channel = word.channelIndex > 0 ? `channel-${word.channelIndex + 1}` : "";
+    if (word.speaker_id && channel)
+        return `${channel}:${word.speaker_id}`;
+    return word.speaker_id ?? (channel || undefined);
+}
+function audioEventKind(text) {
+    const normalized = text.toLowerCase();
+    if (normalized.includes("music") || normalized.includes("sing"))
+        return "music";
+    if (normalized.includes("silence") || normalized.includes("pause"))
+        return "silence";
+    return "sound";
+}
+function joinedSpeech(words) {
+    return words
+        .map((word) => word.text.trim())
+        .filter(Boolean)
+        .join(" ")
+        .replace(/\s+([,.;:!?])/g, "$1");
+}
+function wordConfidence(word) {
+    if (word.logprob === undefined || !Number.isFinite(word.logprob))
+        return undefined;
+    return Math.max(0, Math.min(1, Math.exp(word.logprob)));
+}
+/**
+ * Ensure an asset has ElevenLabs word-level timings (elevenlabs.json),
+ * transcribing inline if it's missing. Idempotent — returns immediately when the
+ * file already exists. Lease-agnostic: the caller owns the asset lease (a render
+ * job's render lease, a plan job's analyze lease). Throws on missing audio, a
+ * missing API key, or an API/write failure so the caller surfaces the cause.
+ */
+export async function ensureElevenLabsTranscript(engine, assetId) {
+    if ((await engine.files.read(assetId, "elevenlabs.json")).ok)
+        return;
+    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);
+    if (!audioFile)
+        throw new Error(`auto-transcribe failed: no audio file found in asset ${assetId}`);
+    await transcribeAssetToElevenLabsJson(engine, assetId, audioFile.name, {
+        tagAudioEvents: true,
+        diarize: true,
+    });
+}

package/dist/jobs/_translate-transcript.js

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import { parseSegments } from "../remotion/subtitles/segments.js";
+import { INTELLIGENCE_MODEL, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+const TRANSLATION_MODEL = INTELLIGENCE_MODEL;
+// Subtitle language setting: 'original' (use the source transcript) or an
+// ISO 639-1 code naming the translation target.
+export function isLanguageSetting(value) {
+    return typeof value === "string" && (value === "original" || /^[a-z]{2}$/.test(value));
+}
+export function translatedTranscriptFilename(language) {
+    return `elevenlabs.${language}.json`;
+}
+// ElevenLabs scribe reports language_code in ISO 639-3; the UI setting uses
+// ISO 639-1. Covers the curated language list plus common detection results.
+const ISO3_TO_ISO1 = {
+    eng: "en",
+    zho: "zh",
+    cmn: "zh",
+    yue: "zh",
+    spa: "es",
+    por: "pt",
+    fra: "fr",
+    deu: "de",
+    ita: "it",
+    nld: "nl",
+    pol: "pl",
+    rus: "ru",
+    tur: "tr",
+    ara: "ar",
+    hin: "hi",
+    ind: "id",
+    jpn: "ja",
+    kor: "ko",
+    vie: "vi",
+    tha: "th",
+    ukr: "uk",
+    swe: "sv",
+    dan: "da",
+    nor: "no",
+    fin: "fi",
+    ces: "cs",
+    ell: "el",
+    heb: "he",
+    hun: "hu",
+    ron: "ro",
+};
+const LANGUAGE_NAMES = {
+    en: "English",
+    zh: "Chinese",
+    es: "Spanish",
+    pt: "Portuguese",
+    fr: "French",
+    de: "German",
+    it: "Italian",
+    nl: "Dutch",
+    pl: "Polish",
+    ru: "Russian",
+    tr: "Turkish",
+    ar: "Arabic",
+    hi: "Hindi",
+    id: "Indonesian",
+    ja: "Japanese",
+    ko: "Korean",
+    vi: "Vietnamese",
+    th: "Thai",
+    uk: "Ukrainian",
+};
+export function iso1FromIso3(code) {
+    if (!code)
+        return null;
+    return ISO3_TO_ISO1[code.toLowerCase()] ?? null;
+}
+export function readLanguageCode(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const code = raw.language_code;
+    return typeof code === "string" ? code : null;
+}
+// ── Sentence grouping ──
+//
+// The split exists only to preserve subtitle timing: each sentence carries the
+// time window of its source words, and the translated sentence inherits it.
+// Translation itself always sees the full transcript in one request.
+const SENTENCE_END_RE = /[.!?。！？…]["'"』」)]*$/;
+const MAX_SENTENCE_WORDS = 30;
+const PAUSE_GAP_SECONDS = 0.8;
+const CJK_RE = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uff66-\uff9f]/;
+function joinWordTexts(texts) {
+    let joined = "";
+    for (const text of texts) {
+        if (joined.length === 0) {
+            joined = text;
+            continue;
+        }
+        const cjkBoundary = CJK_RE.test(joined.slice(-1)) && CJK_RE.test(text.charAt(0));
+        joined += cjkBoundary ? text : ` ${text}`;
+    }
+    return joined;
+}
+export function groupIntoSentences(words) {
+    const sentences = [];
+    let current = [];
+    const flush = () => {
+        const texts = current.map((w) => w.word.trim()).filter((t) => t.length > 0);
+        if (texts.length > 0) {
+            sentences.push({
+                start: current[0].start,
+                end: current[current.length - 1].end,
+                text: joinWordTexts(texts),
+            });
+        }
+        current = [];
+    };
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        current.push(word);
+        const next = words[i + 1];
+        const sentenceEnd = SENTENCE_END_RE.test(word.word.trim());
+        const longPause = next !== undefined && next.start - word.end > PAUSE_GAP_SECONDS;
+        if (sentenceEnd || longPause || current.length >= MAX_SENTENCE_WORDS)
+            flush();
+    }
+    flush();
+    return sentences;
+}
+// ── Word-timing synthesis for translated text ──
+function tokenizeForTiming(text) {
+    const tokens = [];
+    for (const rough of text.split(/\s+/)) {
+        if (rough.length === 0)
+            continue;
+        // CJK targets arrive as long unspaced runs; split into bigrams so
+        // word-highlight styles still animate.
+        if (rough.length > 2 && CJK_RE.test(rough)) {
+            for (let i = 0; i < rough.length; i += 2)
+                tokens.push(rough.slice(i, i + 2));
+        }
+        else {
+            tokens.push(rough);
+        }
+    }
+    return tokens;
+}
+export function synthesizeWordTimings(text, start, end) {
+    const tokens = tokenizeForTiming(text);
+    if (tokens.length === 0)
+        return [];
+    const weights = tokens.map((t) => Math.max(1, t.length));
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    const duration = Math.max(0, end - start);
+    const words = [];
+    let consumed = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const wordStart = start + (duration * consumed) / totalWeight;
+        consumed += weights[i];
+        const wordEnd = start + (duration * consumed) / totalWeight;
+        words.push({ text: tokens[i], start: wordStart, end: wordEnd, type: "word" });
+    }
+    return words;
+}
+// ── Cache invalidation hash ──
+export function computeSourceTextHash(segments) {
+    const hash = createHash("sha1");
+    for (const segment of segments) {
+        if (segment.words.length > 0) {
+            for (const word of segment.words)
+                hash.update(`${word.word.trim()}\n`);
+        }
+        else {
+            hash.update(`${segment.text.trim()}\n`);
+        }
+    }
+    return hash.digest("hex").slice(0, 12);
+}
+// ── Translation ──
+function buildInstructions(targetLanguage, lineCount) {
+    const languageName = LANGUAGE_NAMES[targetLanguage] ?? targetLanguage;
+    return ("You translate video subtitles. The user message contains the FULL transcript of one video " +
+        "as a JSON array of numbered lines, in spoken order. Translate the dialog as one coherent " +
+        `whole into ${languageName}: natural conversational phrasing, with names, pronouns, and ` +
+        "terminology kept consistent across lines.\n\n" +
+        `Return ONLY a JSON object {"translations": [...]} containing exactly ${lineCount} strings — ` +
+        "translation i corresponds to line i. Do not merge, split, reorder, or omit lines. " +
+        "No romanization, no notes, no text outside the JSON.");
+}
+async function requestTranslations(sentences, targetLanguage, responses, signal) {
+    const response = await responses(intelligenceRequest({
+        instructions: buildInstructions(targetLanguage, sentences.length),
+        input: [{
+                role: "user",
+                content: `TRANSCRIPT LINES (JSON):\n${JSON.stringify(sentences.map((s, i) => ({ i, text: s.text })))}`,
+            }],
+        text: {
+            format: {
+                type: "json_schema",
+                name: "translated_transcript",
+                schema: {
+                    type: "object",
+                    required: ["translations"],
+                    additionalProperties: false,
+                    properties: {
+                        translations: {
+                            type: "array",
+                            minItems: sentences.length,
+                            maxItems: sentences.length,
+                            items: { type: "string" },
+                        },
+                    },
+                },
+                strict: true,
+            },
+        },
+        max_output_tokens: 4096,
+    }), signal);
+    const content = firstResponseText(response);
+    if (!content) {
+        throw new Error(`Translation provider returned no content (status=${response.status})`);
+    }
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed.translations)) {
+        throw new Error(`Translation model returned no translations array. Got keys: ${Object.keys(parsed).join(",")}`);
+    }
+    const translations = parsed.translations;
+    if (translations.length !== sentences.length || !translations.every((t) => typeof t === "string")) {
+        throw new Error(`Translation model returned ${translations.length} entries for ${sentences.length} lines`);
+    }
+    return translations.map((t) => t.trim());
+}
+function collectSentences(segments) {
+    const sentences = [];
+    for (const segment of segments) {
+        if (segment.words.length > 0) {
+            sentences.push(...groupIntoSentences(segment.words));
+        }
+        else if (segment.text.trim().length > 0) {
+            sentences.push({ start: segment.start, end: segment.end, text: segment.text.trim() });
+        }
+    }
+    return sentences;
+}
+export async function translateTranscript(raw, targetLanguage, responses, signal) {
+    const sourceSegments = parseSegments(raw);
+    const sentences = collectSentences(sourceSegments);
+    if (sentences.length === 0) {
+        throw new Error("Transcript contains no subtitle text to translate");
+    }
+    const translations = await requestTranslations(sentences, targetLanguage, responses, signal);
+    const segments = sentences.map((sentence, i) => ({
+        start: sentence.start,
+        end: sentence.end,
+        text: translations[i],
+        words: synthesizeWordTimings(translations[i], sentence.start, sentence.end),
+    }));
+    return {
+        sourceLanguageCode: readLanguageCode(raw),
+        targetLanguage,
+        model: TRANSLATION_MODEL,
+        translatedAt: new Date().toISOString(),
+        sourceTextHash: computeSourceTextHash(sourceSegments),
+        segments,
+    };
+}
+// True when an existing sidecar was produced from the current transcript and
+// can be served as-is.
+export function sidecarMatchesSource(sidecar, sourceSegments) {
+    if (typeof sidecar !== "object" || sidecar === null)
+        return false;
+    const hash = sidecar.sourceTextHash;
+    return typeof hash === "string" && hash === computeSourceTextHash(sourceSegments);
+}

package/dist/jobs/analyze-alive-captions.js

@@ -0,0 +1,10 @@
+import { analyzeAliveCaptions } from "../alive-captions/analyze.js";
+import { registerJobHandler } from "../queue.js";
+import { withLockedLocalLease } from "./_lease.js";
+const LOCK_DURATION_MS = 600_000;
+export function registerAnalyzeAliveCaptionsJob(engine) {
+    registerJobHandler("analyze_alive_captions", async (payload, ctx) => {
+        const { assetId, assetDir, force = false } = payload;
+        return withLockedLocalLease(engine, assetId, assetDir, ctx, "analyze", { durationMs: LOCK_DURATION_MS, data: { state: "analyzing-alive-captions" } }, async () => ({ analysis: await analyzeAliveCaptions(engine, assetId, ctx.signal, force) }), { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+    });
+}

package/dist/jobs/analyze-editing-moments.js

@@ -0,0 +1,104 @@
+import { execFile } from "node:child_process";
+import { findPrimaryMediaFile } from "videobook-engine";
+import { registerJobHandler } from "../queue.js";
+import { FFMPEG } from "../ffmpeg.js";
+import { MOMENTS_CHANGE_THRESHOLD, MOMENTS_EXTRACTOR_ID, MOMENTS_EXTRACTOR_VERSION, MOMENTS_MAX_SCAN_SECONDS, MOMENTS_MIN_MOMENT_SECONDS, MOMENTS_SHOT_THRESHOLD, editingMomentsCacheKey, editingMomentsId, rankedMoments, reuseContext, shotsFromScan, usableRanges, } from "../editing-moments.js";
+import { DOWNSTREAM_LEASE_WAIT_MS, withLocalLease } from "./_lease.js";
+export function registerEditingMomentsJob(engine) {
+    registerJobHandler("analyze_editing_moments", async (payload, ctx) => {
+        const { assetId, startSeconds, endSeconds } = payload;
+        return withLocalLease(engine, assetId, ctx, "analyze", async () => {
+            const artifact = engine.artifacts.get(assetId);
+            if (!artifact.ok)
+                throw new Error(artifact.error.message);
+            if (!["video", "final"].includes(artifact.value.kind))
+                throw new Error("Choose a video source to analyze");
+            const manifest = await engine.files.manifest(assetId);
+            if (!manifest.ok)
+                throw new Error(manifest.error.message);
+            const file = findPrimaryMediaFile(manifest.value.files, artifact.value.kind);
+            const streams = engine.streams.list(assetId);
+            if (!streams.ok)
+                throw new Error(streams.error.message);
+            const stream = streams.value.find((item) => item.kind === "video" && item.sourcePath === file?.name
+                && item.objectHash === file?.objectHash);
+            if (!stream || !file)
+                throw new Error("Wait for the current video source to finish processing");
+            const durationSeconds = stream.durationTicks * stream.timeBase.numerator / stream.timeBase.denominator;
+            if (!(durationSeconds > 0) || durationSeconds > MOMENTS_MAX_SCAN_SECONDS) {
+                throw new Error(`Moment analysis supports video up to ${MOMENTS_MAX_SCAN_SECONDS / 60} minutes`);
+            }
+            const start = Math.min(Math.max(0, startSeconds), Math.max(0, durationSeconds - MOMENTS_MIN_MOMENT_SECONDS));
+            const end = endSeconds === null ? durationSeconds : Math.min(Math.max(start + MOMENTS_MIN_MOMENT_SECONDS, endSeconds), durationSeconds);
+            const momentsId = editingMomentsId({
+                objectHash: stream.objectHash, streamIndex: stream.streamIndex, startSeconds: start, endSeconds: end,
+            });
+            const scan = await scanSceneScores(`${manifest.value.path}/${file.name}`, start, end, ctx.signal);
+            const shots = shotsFromScan(scan, end - start).map((shot) => ({
+                ...shot, startSeconds: shot.startSeconds + start, endSeconds: shot.endSeconds + start,
+                change: shot.change ? { ...shot.change, timeSeconds: shot.change.timeSeconds + start } : null,
+            }));
+            const moments = {
+                schemaVersion: 1,
+                momentsId,
+                artifactId: assetId,
+                objectHash: stream.objectHash,
+                streamId: stream.streamId,
+                durationSeconds,
+                extractor: {
+                    id: MOMENTS_EXTRACTOR_ID,
+                    version: MOMENTS_EXTRACTOR_VERSION,
+                    params: {
+                        shotThreshold: MOMENTS_SHOT_THRESHOLD,
+                        changeThreshold: MOMENTS_CHANGE_THRESHOLD,
+                        minMomentSeconds: MOMENTS_MIN_MOMENT_SECONDS,
+                    },
+                },
+                analyzedRanges: [{ startSeconds: start, endSeconds: end }],
+                createdAt: Date.now(),
+                shots,
+                usable: usableRanges([{ startSeconds: start, endSeconds: end }], shots),
+                moments: rankedMoments(shots),
+                reused: await reuseContext(engine, assetId),
+            };
+            const saved = await engine.metadata.artifacts.write(assetId, editingMomentsCacheKey(momentsId), moments);
+            if (!saved.ok)
+                throw new Error(saved.error.message);
+            return { momentsId, shots: shots.length };
+        }, { waitForActiveMs: DOWNSTREAM_LEASE_WAIT_MS });
+    });
+}
+async function scanSceneScores(inputPath, startSeconds, endSeconds, signal) {
+    const stdout = await new Promise((resolve, reject) => {
+        execFile(FFMPEG, [
+            "-v", "error", "-i", inputPath,
+            ...(startSeconds > 0 ? ["-ss", String(startSeconds)] : []),
+            "-to", String(endSeconds),
+            "-map", "0:v:0",
+            "-vf", "select='gte(scene,0)',metadata=print:file=-",
+            "-an", "-f", "null", "-",
+        ], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024, killSignal: "SIGKILL", signal }, (error, stdout) => {
+            if (error)
+                reject(new Error(`ffmpeg scene scan failed: ${error.message}`));
+            else
+                resolve(stdout);
+        });
+    });
+    const frames = [];
+    let pendingTime = null;
+    for (const line of stdout.split(/\r?\n/)) {
+        const time = /pts_time:([0-9]+(?:\.[0-9]+)?)/.exec(line);
+        if (time) {
+            pendingTime = Number.parseFloat(time[1]);
+            continue;
+        }
+        const score = /lavfi\.scene_score=([0-9]+(?:\.[0-9]+)?(?:e[+-][0-9]+)?)/.exec(line);
+        if (score && pendingTime !== null) {
+            frames.push({ timeSeconds: pendingTime, score: Number.parseFloat(score[1]) });
+            pendingTime = null;
+        }
+    }
+    if (!frames.length)
+        throw new Error("The scene scan returned no frames; check the video source");
+    return frames;
+}