videobook 0.0.0-stage → 0.2.0

package/dist/jobs/trim-audio.js

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { promisify } from "node:util";
+import { basename, extname } from "node:path";
+import { registerJobHandler } from "../queue.js";
+import { FFPROBE, runFfmpeg } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+import { AUDIO_TRIM_EPSILON_SECONDS, validateAudioTrimRange } from "../audio-trim-range.js";
+const execFileAsync = promisify(execFile);
+const LOCK_DURATION_MS = 300_000;
+async function probeAudioDuration(filePath) {
+    const { stdout } = await execFileAsync(FFPROBE, [
+        "-hide_banner",
+        "-v", "error",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        filePath,
+    ]);
+    const data = JSON.parse(stdout);
+    const audioStream = data.streams?.find((stream) => stream.codec_type === "audio");
+    if (!audioStream)
+        throw new Error("Audio file has no usable audio stream");
+    const formatDuration = Number(data.format?.duration ?? 0);
+    const streamDuration = Number(audioStream.duration ?? formatDuration);
+    const duration = Number.isFinite(streamDuration) && streamDuration > 0
+        ? streamDuration
+        : formatDuration;
+    if (!Number.isFinite(duration) || duration <= 0) {
+        throw new Error(`Audio file has invalid duration (${duration})`);
+    }
+    return duration;
+}
+function audioCodecArgs(inputPath) {
+    const ext = extname(inputPath).toLowerCase();
+    if (ext === ".mp3")
+        return ["-c:a", "libmp3lame", "-q:a", "2"];
+    if (ext === ".ogg")
+        return ["-c:a", "libvorbis", "-q:a", "4"];
+    if (ext === ".flac")
+        return ["-c:a", "flac"];
+    if (ext === ".wav")
+        return ["-c:a", "pcm_s16le"];
+    return ["-c:a", "aac", "-b:a", "192k"];
+}
+function buildKeepArgs(inputPath, outputPath, start, duration) {
+    const args = [];
+    if (start > 0)
+        args.push("-ss", String(start));
+    args.push("-i", inputPath, "-map", "0:a:0", "-vn", "-t", String(duration), ...audioCodecArgs(inputPath), "-y", outputPath);
+    return args;
+}
+function buildTrimAudioArgs(inputPath, outputPath, sourceDuration, mode, trimStart, trimEnd, cutStart, cutEnd) {
+    const expectedDuration = validateAudioTrimRange(sourceDuration, mode, trimStart, trimEnd, cutStart, cutEnd);
+    if (mode === "keep") {
+        return {
+            args: buildKeepArgs(inputPath, outputPath, trimStart ?? 0, expectedDuration),
+            expectedDuration,
+        };
+    }
+    const start = cutStart ?? 0;
+    const end = Math.min(cutEnd ?? sourceDuration, sourceDuration);
+    if (start <= AUDIO_TRIM_EPSILON_SECONDS) {
+        return {
+            args: buildKeepArgs(inputPath, outputPath, end, expectedDuration),
+            expectedDuration,
+        };
+    }
+    if (end >= sourceDuration - AUDIO_TRIM_EPSILON_SECONDS) {
+        return {
+            args: buildKeepArgs(inputPath, outputPath, 0, expectedDuration),
+            expectedDuration,
+        };
+    }
+    const filter = [
+        `[0:a]atrim=0:${start},asetpts=PTS-STARTPTS[a1]`,
+        `[0:a]atrim=start=${end},asetpts=PTS-STARTPTS[a2]`,
+        "[a1][a2]concat=n=2:v=0:a=1[a]",
+    ].join(";");
+    return {
+        args: [
+            "-i", inputPath,
+            "-filter_complex", filter,
+            "-map", "[a]",
+            ...audioCodecArgs(inputPath),
+            "-y", outputPath,
+        ],
+        expectedDuration,
+    };
+}
+async function runTrimAudio(inputPath, outputPath, mode, trimStart, trimEnd, cutStart, cutEnd) {
+    const sourceDuration = await probeAudioDuration(inputPath);
+    const { args, expectedDuration } = buildTrimAudioArgs(inputPath, outputPath, sourceDuration, mode, trimStart, trimEnd, cutStart, cutEnd);
+    await runFfmpeg(args);
+    const outputDuration = await probeAudioDuration(outputPath);
+    const tolerance = Math.max(0.35, expectedDuration * 0.05);
+    if (Math.abs(outputDuration - expectedDuration) > tolerance) {
+        throw new Error(`Trimmed audio duration ${outputDuration.toFixed(3)} did not match expected ${expectedDuration.toFixed(3)}`);
+    }
+}
+export function registerTrimAudioJob(engine) {
+    registerJobHandler("trim_audio", async (payload, ctx) => {
+        const { inputPath, outputPath, mode, trimStart, trimEnd, cutStart, cutEnd, assetId, assetDir, commitParams, } = payload;
+        const inputFilename = basename(inputPath);
+        try {
+            await withLockedLocalLease(engine, assetId, assetDir, ctx, "trim", { durationMs: LOCK_DURATION_MS, data: { state: "trimming-audio", ...commitParams } }, async () => {
+                const original = await engine.files.read(assetId, inputFilename);
+                if (!original.ok)
+                    throw new Error(original.error.message);
+                await runTrimAudio(inputPath, outputPath, mode, trimStart, trimEnd, cutStart, cutEnd);
+                await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+                const provenanceResult = await engine.metadata.artifacts.write(assetId, "original", {
+                    origin: "trim_audio",
+                    source_asset_id: assetId,
+                    ...commitParams,
+                    trimmed_at: new Date().toISOString(),
+                });
+                if (!provenanceResult.ok) {
+                    const rollback = await engine.files.write(assetId, inputFilename, original.value);
+                    if (!rollback.ok) {
+                        throw new Error(`${provenanceResult.error.message}; rollback failed: ${rollback.error.message}`);
+                    }
+                    throw new Error(provenanceResult.error.message);
+                }
+            }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+            return { success: true };
+        }
+        finally {
+            await rm(outputPath, { force: true });
+        }
+    });
+}

package/dist/jobs/trim-video.js

@@ -0,0 +1,291 @@
+import { execFile } from "node:child_process";
+import { mkdir, writeFile as fsWriteFile, rename, rm } from "node:fs/promises";
+import { promisify } from "node:util";
+import { join, basename } from "node:path";
+import { registerJobHandler, queue } from "../queue.js";
+import { runFfmpeg, H264_MEDIUM, AUDIO_OPTS, FFPROBE } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+const execFileAsync = promisify(execFile);
+const LOCK_DURATION_MS = 300_000;
+const CROSSFADE_SECS = 0.03;
+const DURATION_EPSILON_SECS = 0.5;
+// Stream-copy cuts snap to keyframes, so A/V container durations often differ
+// by ~1–2s on long sources. Keep this loose enough to accept those while still
+// rejecting the catastrophic desyncs (e.g. 62s declared with 20s of audio)
+// that prompted this check.
+const AV_DRIFT_TOLERANCE_SECS = 2.0;
+// `ffmpeg -t N` lands on the next frame/sample boundary, so the container's
+// reported format duration is typically 10–50ms longer than N. Pre-shrink by
+// one slack window so the output stays ≤ the requested length — required for
+// downstream caps like Wan 2.7's 10s VideoEdit limit.
+const TRIM_DURATION_SAFETY_SECS = 0.05;
+async function probeStreamDurations(filePath) {
+    const { stdout } = await execFileAsync(FFPROBE, [
+        "-v", "error",
+        "-print_format", "json",
+        "-show_streams",
+        "-show_format",
+        filePath,
+    ]);
+    const data = JSON.parse(stdout);
+    const format = Number(data.format?.duration ?? 0);
+    const videoStream = data.streams?.find((s) => s.codec_type === "video");
+    const audioStream = data.streams?.find((s) => s.codec_type === "audio");
+    const video = videoStream ? Number(videoStream.duration ?? format) : null;
+    const audio = audioStream ? Number(audioStream.duration ?? format) : null;
+    return { format, video, audio };
+}
+export async function assertSaneTrimOutput(inputPath, outputPath) {
+    const [input, output] = await Promise.all([
+        probeStreamDurations(inputPath),
+        probeStreamDurations(outputPath),
+    ]);
+    const video = output.video;
+    if (!Number.isFinite(output.format) || output.format <= 0
+        || video === null || !Number.isFinite(video) || video <= 0) {
+        throw new Error(`Trim output has no usable video stream (format=${output.format}, video=${video})`);
+    }
+    if (output.format > input.format + DURATION_EPSILON_SECS) {
+        throw new Error(`Trim output duration ${output.format.toFixed(3)}s exceeds input ${input.format.toFixed(3)}s — likely a corrupted concat`);
+    }
+    if (output.audio !== null && (!Number.isFinite(output.audio)
+        || Math.abs(video - output.audio) > AV_DRIFT_TOLERANCE_SECS)) {
+        throw new Error(`Trim output audio/video duration mismatch: video=${video.toFixed(3)}s audio=${output.audio.toFixed(3)}s`);
+    }
+}
+// Write to `${outputPath}.tmp` then rename to outputPath, so a partial write
+// (process killed mid-encode, OOM, etc.) never leaves a moov-less file
+// sitting at the canonical asset path. `+faststart` puts moov at the front,
+// which means even a truncated mp4 is partially playable AND surfaces obvious
+// corruption to the user immediately rather than after first probe.
+//
+// Prefer stream-copy: a mid-point split of a multi-minute source must finish in
+// seconds, not re-encode the whole file with libx264 medium (which times out
+// enqueueAndWait and leaves husk assets with original.mp4.tmp). Cuts snap to
+// keyframes. Fall back to re-encode when copy fails or produces a broken file
+// (no mid-GOP keyframes → severe A/V desync).
+const COPY_AV_DRIFT_TOLERANCE_SECS = 2.0;
+const COPY_DURATION_SLACK_SECS = 2.0;
+export async function trimRange(inputPath, outputPath, start, end) {
+    try {
+        await runTrimRange(inputPath, outputPath, start, end, "copy");
+        await assertCopyTrimSane(inputPath, outputPath, start, end);
+    }
+    catch {
+        await rm(outputPath, { force: true });
+        await rm(`${outputPath}.tmp`, { force: true });
+        await runTrimRange(inputPath, outputPath, start, end, "reencode");
+    }
+}
+async function assertCopyTrimSane(inputPath, outputPath, start, end) {
+    const [input, output] = await Promise.all([
+        probeStreamDurations(inputPath),
+        probeStreamDurations(outputPath),
+    ]);
+    const video = output.video;
+    if (!Number.isFinite(output.format) || output.format <= 0
+        || video === null || !Number.isFinite(video) || video <= 0) {
+        throw new Error(`Copy trim has no usable video stream (format=${output.format}, video=${video})`);
+    }
+    if (output.audio !== null
+        && (!Number.isFinite(output.audio)
+            || Math.abs(video - output.audio) > COPY_AV_DRIFT_TOLERANCE_SECS)) {
+        throw new Error(`Copy trim A/V desync: video=${video.toFixed(3)}s audio=${output.audio.toFixed(3)}s`);
+    }
+    let expected;
+    if (start !== undefined && end !== undefined)
+        expected = end - start;
+    else if (end !== undefined)
+        expected = end;
+    else if (start !== undefined)
+        expected = input.format - start;
+    if (expected !== undefined && expected > 0) {
+        const slack = Math.max(COPY_DURATION_SLACK_SECS, expected * 0.05);
+        if (Math.abs(output.format - expected) > slack) {
+            throw new Error(`Copy trim duration ${output.format.toFixed(3)}s off expected ${expected.toFixed(3)}s`);
+        }
+    }
+}
+async function runTrimRange(inputPath, outputPath, start, end, mode) {
+    const args = ["-y"];
+    // Copy: put -ss AFTER -i so the cut lands on/after the requested time
+    // (before -i keyframe-snaps backward and can keep almost the whole source).
+    // Re-encode: put -ss BEFORE -i so the decoder skips work.
+    if (mode === "reencode" && start !== undefined) {
+        args.push("-ss", String(start));
+    }
+    args.push("-i", inputPath);
+    if (mode === "copy" && start !== undefined) {
+        args.push("-ss", String(start));
+    }
+    if (end !== undefined) {
+        const requested = start !== undefined ? end - start : end;
+        // Safety margin only for re-encode: shaving 50ms on copy can drop a GOP.
+        const duration = mode === "reencode"
+            ? Math.max(0.01, requested - TRIM_DURATION_SAFETY_SECS)
+            : Math.max(0.01, requested);
+        args.push("-t", String(duration));
+    }
+    const tmpPath = `${outputPath}.tmp`;
+    if (mode === "copy") {
+        args.push("-c", "copy", "-avoid_negative_ts", "make_zero", "-movflags", "+faststart", "-f", "mp4", tmpPath);
+    }
+    else {
+        args.push(...H264_MEDIUM, ...AUDIO_OPTS, "-movflags", "+faststart", "-f", "mp4", tmpPath);
+    }
+    try {
+        await runFfmpeg(args);
+        await rename(tmpPath, outputPath);
+    }
+    catch (err) {
+        await rm(tmpPath, { force: true });
+        throw err;
+    }
+}
+/**
+ * Cut exactly `durationSec` seconds starting at `startSec`, with the output's
+ * container duration reported as the integer second value (not 9.97 / 10.01).
+ *
+ * The trick: forcing the output framerate to 24 means a 23.976-fps source
+ * (very common — YouTube, most films) becomes 240 frames at 24fps = 10.000s.
+ * Audio gets `-t durationSec` directly. With both streams landing on
+ * the same integer-second boundary, ffprobe reports `format=duration` as
+ * an integer.
+ *
+ * Used by /even-split where the user wants the first chunk to read as
+ * "exactly 10s" / "exactly 9s" — a hard requirement for some video-gen UIs
+ * that match on the duration field. No safety margin: precision is the goal.
+ */
+const EXACT_COPY_TOLERANCE_SECS = 0.05;
+export async function trimRangeExact(inputPath, outputPath, startSec, durationSec) {
+    try {
+        await runTrimRange(inputPath, outputPath, startSec > 0 ? startSec : undefined, startSec + durationSec, "copy");
+        const copied = await probeStreamDurations(outputPath);
+        if (Number.isFinite(copied.format)
+            && copied.format > 0
+            && copied.format <= durationSec
+            && copied.format >= durationSec - EXACT_COPY_TOLERANCE_SECS) {
+            await assertSaneTrimOutput(inputPath, outputPath);
+            return;
+        }
+        throw new Error(`Copy trim ${copied.format.toFixed(3)}s is not exact for ${durationSec}s`);
+    }
+    catch {
+        await rm(outputPath, { force: true });
+        await rm(`${outputPath}.tmp`, { force: true });
+    }
+    const args = ["-y"];
+    if (startSec > 0)
+        args.push("-ss", String(startSec));
+    args.push("-i", inputPath);
+    args.push("-t", String(durationSec));
+    args.push("-r", "24", "-vsync", "cfr");
+    const tmpPath = `${outputPath}.tmp`;
+    args.push(...H264_MEDIUM, ...AUDIO_OPTS, "-movflags", "+faststart", "-f", "mp4", tmpPath);
+    try {
+        await runFfmpeg(args);
+        await rename(tmpPath, outputPath);
+    }
+    catch (err) {
+        await rm(tmpPath, { force: true });
+        throw err;
+    }
+}
+async function cutMiddle(inputPath, outputPath, cutStart, cutEnd) {
+    // Degenerate cuts: if the cut starts at 0 or ends at/past input duration,
+    // one of the two halves would be empty (`-t 0` or seek-past-end) and the
+    // subsequent concat fails with "Output file does not contain any stream".
+    // Delegate to a single trimRange call in those cases.
+    if (cutStart <= 0) {
+        await trimRange(inputPath, outputPath, cutEnd, undefined);
+        return;
+    }
+    const { format: inputDuration } = await probeStreamDurations(inputPath);
+    if (cutEnd >= inputDuration - DURATION_EPSILON_SECS) {
+        await trimRange(inputPath, outputPath, undefined, cutStart);
+        return;
+    }
+    const tempDir = join(outputPath, "..", ".trim_temp");
+    await mkdir(tempDir, { recursive: true });
+    try {
+        const beforePath = join(tempDir, "before.mp4");
+        const afterPath = join(tempDir, "after.mp4");
+        const concatList = join(tempDir, "concat.txt");
+        // The before/after halves read disjoint ranges of the input and write to
+        // different output files, so run them in parallel. Halves cut-middle
+        // wall-clock on multi-core hosts.
+        const fadeOutStart = Math.max(cutStart - CROSSFADE_SECS, 0);
+        await Promise.all([
+            runFfmpeg([
+                "-y", "-i", inputPath,
+                "-t", String(cutStart),
+                "-af", `afade=t=out:st=${fadeOutStart}:d=${CROSSFADE_SECS}`,
+                ...H264_MEDIUM, ...AUDIO_OPTS,
+                beforePath,
+            ]),
+            runFfmpeg([
+                "-y", "-ss", String(cutEnd),
+                "-i", inputPath,
+                "-af", `afade=t=in:d=${CROSSFADE_SECS}`,
+                ...H264_MEDIUM, ...AUDIO_OPTS,
+                afterPath,
+            ]),
+        ]);
+        await fsWriteFile(concatList, `file '${beforePath}'\nfile '${afterPath}'\n`);
+        // Re-encode rather than `-c copy`: the two halves are independently-encoded
+        // libx264/AAC streams, so their SPS/PPS, GOP boundaries, and AAC priming
+        // samples don't line up — a copy-concat produces a container with bogus
+        // duration metadata and a truncated audio stream.
+        await runFfmpeg([
+            "-y", "-f", "concat", "-safe", "0",
+            "-i", concatList,
+            ...H264_MEDIUM, ...AUDIO_OPTS,
+            outputPath,
+        ]);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+export function registerTrimVideoJob(engine) {
+    registerJobHandler("trim_video", async (payload, ctx) => {
+        const { inputPath, outputPath, mode, trimStart, trimEnd, cutStart, cutEnd, assetId, assetDir, bookId, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "trim", { durationMs: LOCK_DURATION_MS, data: { state: "trimming" } }, async () => {
+            if (mode === "cut") {
+                await cutMiddle(inputPath, outputPath, cutStart, cutEnd);
+            }
+            else {
+                await trimRange(inputPath, outputPath, trimStart, trimEnd);
+            }
+            try {
+                await assertSaneTrimOutput(inputPath, outputPath);
+            }
+            catch (err) {
+                await rm(outputPath, { force: true });
+                throw err;
+            }
+            const inputFilename = basename(inputPath);
+            await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+            for (const stale of [
+                ".original.analysis.json",
+                ".analysis.gpt4otrans.json",
+                "elevenlabs.json",
+            ]) {
+                await engine.files.delete(assetId, stale);
+            }
+            const videoPath = join(assetDir, inputFilename);
+            return { videoPath };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        await queue.enqueue(`process-video-${assetId}-${Date.now()}`, {
+            type: "process_video",
+            videoPath: result.videoPath,
+            assetId,
+            assetDir,
+            bookId,
+            provenance: { origin: "trim", trimmed_at: new Date().toISOString() },
+            force: true,
+        });
+        return { success: true };
+    });
+}

package/dist/jobs/xai-paygate.js

@@ -0,0 +1,26 @@
+import { createXai } from "../usage-providers.js";
+import { mintOtp } from "@apicity/cost";
+import { ensurePaygateSecret } from "./kie-paygate.js";
+import { assertProviderPayload } from "../provider-prompt-transform.js";
+export const XAI_IMAGE_GENERATIONS_DOT_PATH = "v1.images.generations";
+export const XAI_VIDEO_GENERATIONS_DOT_PATH = "v1.videos.generations";
+export function createXaiPaygatedProvider(apiKey, timeout) {
+    return createXai({
+        apiKey,
+        timeout,
+        paygate: { secret: ensurePaygateSecret() },
+    });
+}
+export function mintXaiOtp(dotPath, request, ttlSeconds = 10 * 60) {
+    return mintOtp(ensurePaygateSecret(), {
+        provider: "xai",
+        method: "POST",
+        dotPath,
+        request: request,
+        ttl: ttlSeconds,
+    });
+}
+export async function callXaiPaid(method, dotPath, request) {
+    assertProviderPayload(request, { toolName: dotPath, wire: true });
+    return method(request, { otp: mintXaiOtp(dotPath, request) });
+}

package/dist/keyword-placement-cache.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { KEYWORD_FRAME_CACHE_FILENAME, KEYWORD_PLACEMENT_METADATA_KEY, KEYWORD_PLACEMENT_VERSION, keywordCueId, } from "./remotion/keyword-placement.js";
+const regionSchema = z.object({
+    kind: z.enum(["face", "text", "graphic"]),
+    confidence: z.number().min(0).max(1),
+    x: z.number().min(0).max(1),
+    y: z.number().min(0).max(1),
+    width: z.number().positive().max(1),
+    height: z.number().positive().max(1),
+}).strict().refine((region) => region.x + region.width <= 1.001 && region.y + region.height <= 1.001, { message: "occupied region extends beyond the source frame" });
+const cueSchema = z.object({
+    cueId: z.string().min(1),
+    text: z.string().min(1),
+    frameTime: z.number().nonnegative(),
+    regions: z.array(regionSchema),
+}).strict();
+const analysisSchema = z.object({
+    version: z.literal(KEYWORD_PLACEMENT_VERSION),
+    fingerprint: z.string().min(1),
+    sourceWidth: z.number().positive(),
+    sourceHeight: z.number().positive(),
+    frameCacheFilename: z.literal(KEYWORD_FRAME_CACHE_FILENAME),
+    analyzedAt: z.string().min(1),
+    cues: z.array(cueSchema).min(1),
+}).strict();
+export function keywordPlacementFingerprint(videoFile, transcript, graphics) {
+    const transcriptHash = createHash("sha256").update(transcript).digest("hex");
+    const payload = {
+        version: KEYWORD_PLACEMENT_VERSION,
+        video: {
+            name: videoFile.name,
+            size: videoFile.sizeBytes,
+            objectHash: videoFile.objectHash,
+        },
+        transcriptHash,
+        cues: graphics.map((graphic) => ({
+            id: keywordCueId(graphic),
+            text: graphic.text,
+            start: graphic.start,
+            end: graphic.end,
+            frameTime: graphic.frameTime,
+        })),
+    };
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+export function parseKeywordPlacementAnalysis(raw) {
+    return analysisSchema.parse(raw);
+}
+export async function readKeywordPlacementAnalysis(engine, assetId) {
+    const result = await engine.metadata.artifacts.read(assetId, KEYWORD_PLACEMENT_METADATA_KEY);
+    if (!result.ok)
+        return null;
+    const parsed = analysisSchema.safeParse(result.value);
+    return parsed.success ? parsed.data : null;
+}
+export async function writeKeywordPlacementAnalysis(engine, assetId, analysis) {
+    const parsed = parseKeywordPlacementAnalysis(analysis);
+    const result = await engine.metadata.artifacts.write(assetId, KEYWORD_PLACEMENT_METADATA_KEY, parsed);
+    if (!result.ok)
+        throw new Error(`Failed to persist keyword placement analysis: ${result.error.message}`);
+}
+export async function isKeywordPlacementCacheValid(engine, assetId, analysis, fingerprint, graphics) {
+    if (!analysis || analysis.fingerprint !== fingerprint)
+        return false;
+    const expectedCueIds = graphics.map(keywordCueId);
+    const cachedCueIds = analysis.cues.map((cue) => cue.cueId);
+    if (expectedCueIds.length !== cachedCueIds.length)
+        return false;
+    if (expectedCueIds.some((cueId, index) => cueId !== cachedCueIds[index]))
+        return false;
+    const frameCache = await engine.files.read(assetId, KEYWORD_FRAME_CACHE_FILENAME);
+    return frameCache.ok;
+}

package/dist/lazy-render.js

@@ -0,0 +1,142 @@
+import { isSubtitleStyle } from "./remotion/subtitles/styles.js";
+import { isOsgPosition, isOsgSize } from "./osg-assets.js";
+import { queue } from "./queue.js";
+import { readTimeline } from "./timeline-helpers.js";
+import { isLanguageSetting } from "./jobs/_translate-transcript.js";
+import { PLAIN_TRANSCRIPT_FILE, TIMED_TRANSCRIPT_FILE, } from "./transcript-projection.js";
+import { VIDEO_ANALYSIS_FILE } from "./video-analysis-projection.js";
+import { findEligibleRenderActions, readStoredRenderDefaults } from "./tools/reconcile-project-work.js";
+import { DEFAULT_KEYWORD_GRAPHICS_LINGER_SECONDS, DEFAULT_KEYWORD_GRAPHICS_MAX_COUNT, } from "./remotion/keyword-graphics.js";
+function isSubtitlePosition(value) {
+    return value === "top" || value === "middle" || value === "bottom";
+}
+function isFontSizePreset(value) {
+    return value === "small" || value === "medium" || value === "large";
+}
+function isBackgroundMode(value) {
+    return value === "blur" || value === "black";
+}
+function stringOr(value, fallback) {
+    return typeof value === "string" ? value : fallback;
+}
+function numberOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function nullableString(value) {
+    return typeof value === "string" ? value : null;
+}
+function stringArrayOrNull(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+}
+/**
+ * Revive the slot-drop vision analysis for a timeline-assigned video whose
+ * .original.analysis.json is missing — the state a force re-process (trim,
+ * re-download) leaves behind after it invalidates the analysis sidecars.
+ * assign_slot only fires on slot drop, so without this revival the auto
+ * pipeline (analyze_video → ElevenLabs transcribe → lazy render) stays wedged
+ * and render_timeline reports missing_renders until a manual /render.
+ */
+export async function enqueueLazyAnalysisIfSlotted(engine, bookId, assetId) {
+    // Same provider gate as assign_slot's lazy analysis: truthy env check (not
+    // getApiKey) so placeholder keys used in tests pass; the real placeholder
+    // defense lives at the API call inside analyze-video.
+    if (!process.env.OPENAI_API_KEY)
+        return null;
+    const asset = engine.artifacts.get(assetId);
+    if (!asset.ok || asset.value.kind !== "video")
+        return null;
+    const timeline = readTimeline(engine);
+    if (!timeline.slots.some((slot) => slot.artifactId === asset.value.artifactId))
+        return null;
+    const manifestResult = await engine.files.manifest(assetId);
+    if (!manifestResult.ok)
+        return null;
+    const [analysis, plainTranscript, timedTranscript] = await Promise.all([
+        engine.files.read(assetId, VIDEO_ANALYSIS_FILE),
+        engine.files.read(assetId, PLAIN_TRANSCRIPT_FILE),
+        engine.files.read(assetId, TIMED_TRANSCRIPT_FILE),
+    ]);
+    if (analysis.ok)
+        return null;
+    // Stable dedupe key: concurrent triggers collapse onto one queued job.
+    const jobId = `auto-analyze-${assetId}`;
+    await queue.enqueue(jobId, {
+        type: "analyze_video",
+        assetId,
+        assetDir: manifestResult.value.path,
+        bookId,
+        hasTranscription: plainTranscript.ok || timedTranscript.ok,
+    });
+    return { jobId };
+}
+async function isRenderAlreadyQueued(engine, assetId, orientation) {
+    const work = await engine.jobs.artifactWork.read(assetId);
+    if (!work.ok || !work.value)
+        return false;
+    const state = work.value;
+    return state.status !== "ready"
+        && state.meta?.kind === "render"
+        && state.meta.orientation === orientation;
+}
+export async function enqueueLazyTimelineRender(engine, bookId, assetId, knownAsset) {
+    const resolved = engine.artifacts.get(assetId);
+    if (!resolved.ok || resolved.value.kind !== "video")
+        return null;
+    const timeline = readTimeline(engine);
+    if (!timeline.slots.some((slot) => slot.artifactId === resolved.value.artifactId))
+        return null;
+    const orientation = timeline.render;
+    if (await isRenderAlreadyQueued(engine, assetId, orientation))
+        return null;
+    const asset = knownAsset ?? resolved.value;
+    const renderActions = await findEligibleRenderActions(engine, [asset], orientation);
+    if (renderActions.length === 0)
+        return null;
+    const action = renderActions[0];
+    const stored = await readStoredRenderDefaults(engine, assetId, orientation);
+    const subtitlesEnabled = action.hasElevenlabs && stored.subtitlesEnabled === true;
+    // Stable dedupe key: concurrent triggers (job-completion hooks racing a
+    // sync poll) collapse onto one queued render instead of double-rendering.
+    const jobId = `auto-render-${assetId}-${orientation}`;
+    await queue.enqueue(jobId, {
+        type: "render_project",
+        bookId,
+        assetId: action.assetId,
+        orientation,
+        assets: [{
+                assetId: action.assetId,
+                assetDir: action.assetDir,
+                videoPath: action.videoPath,
+                videoFilename: action.videoFilename,
+            }],
+        subtitlesEnabled,
+        subtitleLanguage: isLanguageSetting(stored.subtitleLanguage) ? stored.subtitleLanguage : "original",
+        highlightStyle: isSubtitleStyle(stored.highlightStyle) ? stored.highlightStyle : "highlight",
+        position: isSubtitlePosition(stored.position) ? stored.position : "bottom",
+        fontSize: isFontSizePreset(stored.fontSize) ? stored.fontSize : "medium",
+        textColor: stringOr(stored.textColor, "#FFFFFF"),
+        highlightColor: stringOr(stored.highlightColor, "#991B1B"),
+        audioFadeIn: numberOr(stored.audioFadeIn, 0),
+        audioFadeOut: numberOr(stored.audioFadeOut, 0),
+        audioVolume: numberOr(stored.audioVolume, 100),
+        osgImagePath: nullableString(stored.osgImagePath),
+        osgAssetId: nullableString(stored.osgAssetId),
+        osgPosition: isOsgPosition(stored.osgPosition) ? stored.osgPosition : "top-right",
+        osgSize: isOsgSize(stored.osgSize) ? stored.osgSize : "medium",
+        osgScale: numberOr(stored.osgScale, 1),
+        osgOpacity: numberOr(stored.osgOpacity, 1),
+        osgStartSeconds: typeof stored.osgStartSeconds === "number" ? stored.osgStartSeconds : null,
+        osgEndSeconds: typeof stored.osgEndSeconds === "number" ? stored.osgEndSeconds : null,
+        osgTailSeconds: typeof stored.osgTailSeconds === "number" ? stored.osgTailSeconds : null,
+        keywordGraphicsEnabled: stored.keywordGraphicsEnabled === true,
+        keywordGraphicsMaxCount: numberOr(stored.keywordGraphicsMaxCount, DEFAULT_KEYWORD_GRAPHICS_MAX_COUNT),
+        keywordGraphicsLingerSeconds: numberOr(stored.keywordGraphicsLingerSeconds, DEFAULT_KEYWORD_GRAPHICS_LINGER_SECONDS),
+        keywordGraphicsKeywords: stringArrayOrNull(stored.keywordGraphicsKeywords),
+        backgroundMode: isBackgroundMode(stored.backgroundMode) ? stored.backgroundMode : "blur",
+        strokeWidth: numberOr(stored.strokeWidth, 6),
+        strokeColor: stringOr(stored.strokeColor, "#000000"),
+        shadowBlur: numberOr(stored.shadowBlur, 6),
+        shadowOpacity: numberOr(stored.shadowOpacity, 60),
+    });
+    return { jobId };
+}