videobook 0.0.0-stage → 0.2.0

package/dist/jobs/index.js

@@ -0,0 +1,18 @@
+import { bookManager } from "../engine.js";
+let pending = null;
+let loadPromise = null;
+export function registerAllJobHandlers(engine, books = bookManager) {
+    pending = { engine, books };
+    loadPromise = null;
+}
+export function ensureJobHandlersLoaded() {
+    if (!pending)
+        return Promise.resolve();
+    if (!loadPromise) {
+        const registration = pending;
+        loadPromise = import("./register-all.js").then((mod) => {
+            mod.registerAllJobHandlers(registration.engine, registration.books);
+        });
+    }
+    return loadPromise;
+}

package/dist/jobs/inject-first-frame.js

@@ -0,0 +1,175 @@
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import { H264_MEDIUM, probeVideo, runFfmpeg } from "../ffmpeg.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+import { registerMediaStreams } from "./process-video.js";
+const LOCK_DURATION_MS = 900_000;
+const STALE_VISUAL_DERIVATIVES = [
+    ".original.analysis.json",
+    ".detect-scenes.json",
+    ".suggest-cuts.json",
+    ".suggest-sfx.json",
+    ".analyze-jokes.json",
+];
+function outputContainer(path) {
+    return extname(path).toLowerCase() === ".mov" ? "mov" : "mp4";
+}
+function buildInjectFirstFrameFilter(width, height) {
+    return `[1:v:0]scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height},setsar=1[still];[0:v:0][still]overlay=0:0:eof_action=repeat:repeatlast=1:enable='eq(n\\,0)'[video]`;
+}
+async function renderInjectedFirstFrame(inputPath, imagePath, outputPath, width, height, signal) {
+    await runFfmpeg([
+        "-y",
+        "-i", inputPath,
+        "-i", imagePath,
+        "-filter_complex", buildInjectFirstFrameFilter(width, height),
+        "-map", "[video]",
+        "-map", "0:a?",
+        ...H264_MEDIUM,
+        "-pix_fmt", "yuv420p",
+        "-c:a", "copy",
+        "-map_metadata", "0",
+        "-map_chapters", "0",
+        "-fps_mode", "passthrough",
+        "-movflags", "+faststart",
+        "-f", outputContainer(outputPath),
+        outputPath,
+    ], { signal });
+}
+async function validateInjectedFirstFrame(inputPath, outputPath, 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("First-frame output has no usable video stream");
+    }
+    if (output.width !== input.width || output.height !== input.height) {
+        throw new Error(`First-frame output dimensions ${output.width}x${output.height} do not match source ${input.width}x${input.height}`);
+    }
+    if (output.hasAudio !== input.hasAudio || output.audioCodec !== input.audioCodec) {
+        throw new Error("First-frame output audio stream layout or codec does not match the source");
+    }
+    const tolerance = Math.max(0.08, 2 / input.fps);
+    if (Math.abs(output.duration - input.duration) > tolerance) {
+        throw new Error(`First-frame output duration ${output.duration.toFixed(3)}s does not match source ${input.duration.toFixed(3)}s`);
+    }
+    if (Math.abs(output.videoDuration - input.videoDuration) > tolerance) {
+        throw new Error("First-frame output video timing does not match the source");
+    }
+    if (input.audioDuration !== null && output.audioDuration !== null
+        && Math.abs(output.audioDuration - input.audioDuration) > tolerance) {
+        throw new Error("First-frame output audio timing does not match the source");
+    }
+    if (Math.abs(output.fps - input.fps) > 0.01) {
+        throw new Error(`First-frame output frame rate ${output.fps} does not match source ${input.fps}`);
+    }
+}
+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 });
+}
+async function replaceAssetFile(engine, assetId, targetFilename, outputPath) {
+    await replaceArtifactFileFromPath(engine, assetId, targetFilename, outputPath);
+}
+async function refreshFinalThumbnail(engine, assetId, assetDir, targetFilename, signal) {
+    const tempDir = await mkdtemp(join(tmpdir(), "videocity-inject-first-frame-"));
+    const thumbnailPath = join(tempDir, "thumbnail.jpg");
+    try {
+        await runFfmpeg([
+            "-y",
+            "-i", join(assetDir, targetFilename),
+            "-frames:v", "1",
+            "-q:v", "2",
+            thumbnailPath,
+        ], { signal });
+        const thumbnailStat = await stat(thumbnailPath).catch(() => null);
+        if (!thumbnailStat || thumbnailStat.size === 0) {
+            throw new Error("Failed to generate final thumbnail");
+        }
+        const written = await engine.files.write(assetId, "original.jpg", await readFile(thumbnailPath));
+        if (!written.ok)
+            throw new Error(`Failed to refresh final thumbnail: ${written.error.message}`);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export function registerInjectFirstFrameJob(engine) {
+    registerJobHandler("inject_first_frame", async (payload, ctx) => {
+        const { assetId, assetDir, targetFilename, inputPath, outputPath, imageAssetId, imagePath, bookId, orientation, } = payload;
+        const artifact = engine.artifacts.get(assetId);
+        const isFinalAsset = artifact.ok && artifact.value.kind === "final";
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "process", { durationMs: LOCK_DURATION_MS, data: { state: "injecting-first-frame" } }, async () => {
+            const source = await probeVideo(inputPath, { signal: ctx.signal });
+            if (source.videoCodec === null || source.width <= 0 || source.height <= 0 || source.fps <= 0) {
+                throw new Error(`No usable video stream found in ${targetFilename}`);
+            }
+            const history = engine.history.artifact(assetId);
+            const restoreCommit = history[0]?.hash;
+            try {
+                await renderInjectedFirstFrame(inputPath, imagePath, outputPath, source.width, source.height, ctx.signal);
+                await validateInjectedFirstFrame(inputPath, outputPath, ctx.signal);
+                await replaceAssetFile(engine, assetId, targetFilename, outputPath);
+                if (isFinalAsset) {
+                    await registerMediaStreams(engine, assetId, targetFilename, await probeVideo(join(assetDir, targetFilename), { signal: ctx.signal }));
+                    await refreshFinalThumbnail(engine, assetId, assetDir, targetFilename, ctx.signal);
+                }
+                else {
+                    for (const filename of STALE_VISUAL_DERIVATIVES) {
+                        await deleteIfPresent(engine, assetId, filename);
+                    }
+                }
+                await engine.history.recordOperation("inject_first_frame", assetId, {
+                    image_asset_id: imageAssetId,
+                    target_filename: targetFilename,
+                    orientation,
+                    audio_preserved: true,
+                    timing_preserved: true,
+                });
+            }
+            catch (error) {
+                await discardTemp(outputPath).catch(() => undefined);
+                if (restoreCommit)
+                    await engine.history.restoreArtifact(assetId, restoreCommit);
+                throw error;
+            }
+            return { videoPath: join(assetDir, targetFilename) };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        if (!isFinalAsset) {
+            await queue.enqueue(`process-video-${assetId}-${Date.now()}`, {
+                type: "process_video",
+                videoPath: result.videoPath,
+                assetId,
+                assetDir,
+                bookId,
+                provenance: {
+                    origin: "inject_first_frame",
+                    image_asset_id: imageAssetId,
+                    injected_at: new Date().toISOString(),
+                },
+                force: true,
+                skipDownstreamJobs: true,
+                preserveAudioArtifacts: true,
+                reviveVisualAnalysis: true,
+            });
+        }
+        return {
+            success: true,
+            target_asset_id: assetId,
+            image_asset_id: imageAssetId,
+            target_filename: targetFilename,
+            orientation,
+            audio_preserved: true,
+            timing_preserved: true,
+        };
+    });
+}

package/dist/jobs/isolate-vocals.js

@@ -0,0 +1,69 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeFile, unlink } from "node:fs/promises";
+import { submitKieTask } from "./kie-paygate.js";
+import { uploadBytesToFreeHost, contentHash } from "../upload.js";
+import { registerJobHandler } from "../queue.js";
+import { requireApiKey } from "../api-key.js";
+import { probeVideo, runFfmpeg } from "../ffmpeg.js";
+const MIN_ISOLATION_DURATION = 4.6;
+const PAD_TARGET_DURATION = 5.0;
+export function registerIsolateVocalsJob(engine) {
+    registerJobHandler("isolate_vocals", async (payload, ctx) => {
+        const { audioFilename, assetId, assetDir, bookId, isAudioAsset, } = payload;
+        requireApiKey("KIE_API_KEY");
+        // Read audio file from asset
+        const readResult = await engine.files.read(assetId, audioFilename);
+        if (!readResult.ok)
+            throw new Error(readResult.error.message);
+        const audioBuffer = Buffer.from(readResult.value);
+        // Check duration and pad if needed
+        const probe = await probeVideo(join(assetDir, audioFilename));
+        let uploadBuffer = audioBuffer;
+        let originalDuration;
+        if (probe.duration < MIN_ISOLATION_DURATION) {
+            originalDuration = probe.duration;
+            const padSeconds = PAD_TARGET_DURATION - probe.duration;
+            const tmpInput = join(tmpdir(), `isolate-pad-in-${Date.now()}.mp3`);
+            const tmpOutput = join(tmpdir(), `isolate-pad-out-${Date.now()}.mp3`);
+            try {
+                await writeFile(tmpInput, audioBuffer);
+                await runFfmpeg([
+                    "-y", "-i", tmpInput,
+                    "-af", `apad=pad_dur=${padSeconds}`,
+                    tmpOutput,
+                ]);
+                const { readFile: readFs } = await import("node:fs/promises");
+                uploadBuffer = await readFs(tmpOutput);
+            }
+            finally {
+                await unlink(tmpInput).catch(() => { });
+                await unlink(tmpOutput).catch(() => { });
+            }
+        }
+        // Upload to KIE with a content-hash filename to avoid collisions with
+        // other assets that share the same local filename (e.g. `original.mp3`).
+        const ext = audioFilename.split(".").pop() ?? "bin";
+        const hashedName = `${contentHash(uploadBuffer)}.${ext}`;
+        const downloadUrl = await uploadBytesToFreeHost(uploadBuffer, hashedName);
+        // Create isolation task
+        const request = {
+            model: "elevenlabs/audio-isolation",
+            input: {
+                audio_url: downloadUrl,
+            },
+        };
+        const taskId = await submitKieTask(engine, ctx, {
+            request,
+            taskType: "isolate_vocals",
+            assetId,
+            assetDir,
+            bookId,
+            meta: {
+                isAudioAsset,
+                ...(originalDuration !== undefined ? { originalDuration } : {}),
+            },
+        });
+        return { success: true, taskId };
+    });
+}

package/dist/jobs/kie-paygate.js

@@ -0,0 +1,177 @@
+import { createKie } from "../usage-providers.js";
+import { submitMediaJob } from "@apicity/kie";
+import { mintOtp } from "@apicity/cost";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { QUEUED_TASK_ID } from "videobook-engine";
+import { requireApiKey } from "../api-key.js";
+import { referenceVideoDuration } from "../reference-video-duration.js";
+import { assertProviderPayload } from "../provider-prompt-transform.js";
+import { assessKieRequestEstimate, logUnavailableCostEstimate, } from "./cost-estimate-assessment.js";
+export const KIE_PAYGATE_DOT_PATH = "api.v1.jobs.createTask";
+function defaultSecretPath() {
+    return join(homedir(), ".videobook", "paygate-secret");
+}
+function writeKey(path, content, mode) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, { encoding: "utf8", mode });
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        return;
+    }
+}
+export function ensurePaygateSecret() {
+    const configuredSecret = process.env.APICITY_PAYGATE_SECRET?.trim();
+    if (configuredSecret)
+        return configuredSecret;
+    const secretPath = process.env.APICITY_PAYGATE_SECRET_PATH ?? defaultSecretPath();
+    if (!existsSync(secretPath)) {
+        writeKey(secretPath, `${randomBytes(32).toString("base64url")}\n`, 0o600);
+    }
+    const secret = readFileSync(secretPath, "utf8").trim();
+    if (!secret) {
+        throw new Error(`APICITY paygate secret is empty: ${secretPath}`);
+    }
+    process.env.APICITY_PAYGATE_SECRET_PATH = secretPath;
+    return secret;
+}
+export function mintKieOtp(request, ttlSeconds = 10 * 60, dotPath = KIE_PAYGATE_DOT_PATH, _costHints = {}) {
+    const payload = request;
+    // The OTP hashes the wire payload verbatim — costHints never enter the hash,
+    // so the request that hits Kie carries only its documented schema fields.
+    // Cost estimation is advisory and must not gate minting.
+    return mintOtp(ensurePaygateSecret(), {
+        provider: "kie",
+        method: "POST",
+        dotPath,
+        request: payload,
+        ttl: ttlSeconds,
+    });
+}
+export async function authorizeKiePaygate(request, options = {}) {
+    const costHints = options.costHints ?? {};
+    const assessment = assessKieRequestEstimate(request, costHints);
+    if (!assessment.available) {
+        const model = typeof request.model === "string"
+            ? request.model
+            : options.correlation?.model;
+        await logUnavailableCostEstimate({
+            assessment,
+            engine: options.engine,
+            correlation: {
+                provider: "kie",
+                ...options.correlation,
+                ...(model ? { model } : {}),
+            },
+        });
+    }
+    return {
+        otp: mintKieOtp(request, options.ttlSeconds, options.dotPath, costHints),
+        assessment,
+    };
+}
+function createKieProvider(apiKey) {
+    return createKie({
+        apiKey,
+        timeout: 60_000,
+        paygate: { secret: ensurePaygateSecret() },
+    });
+}
+export async function submitKieTask(engine, ctx, args) {
+    const request = args.request;
+    assertProviderPayload(request, {
+        toolName: args.taskType,
+        wire: true,
+    });
+    const apiKey = requireApiKey("KIE_API_KEY");
+    await engine.metadata.artifacts.write(args.assetId, "generation-payload", request);
+    const costHints = { ...args.costHints };
+    const requestInput = request.input;
+    const videoUrls = requestInput.reference_video_urls;
+    const sourceVideoIds = args.meta.sourceVideoIds;
+    if (costHints.inputDuration === undefined && Array.isArray(videoUrls) && videoUrls.length > 0
+        && Array.isArray(sourceVideoIds) && sourceVideoIds.length === videoUrls.length
+        && sourceVideoIds.every((id) => typeof id === "string")) {
+        const duration = await referenceVideoDuration(engine, sourceVideoIds);
+        if (duration !== undefined)
+            costHints.inputDuration = duration;
+    }
+    if (Object.keys(costHints).length > 0) {
+        await engine.metadata.artifacts.write(args.assetId, "generation-cost-hints", costHints);
+    }
+    const provider = createKieProvider(apiKey);
+    const { otp } = await authorizeKiePaygate(request, {
+        costHints,
+        engine,
+        correlation: {
+            bookId: args.bookId,
+            artifactId: args.assetId,
+            tool: args.taskType,
+            stage: "submit-kie",
+        },
+    });
+    const taskId = await submitMediaJob(provider, request, { otp });
+    const pendingResult = await engine.jobs.pending.write({
+        taskId,
+        taskType: args.taskType,
+        artifactId: args.assetId,
+        meta: args.meta,
+    }, ctx.getOwnerId());
+    if (!pendingResult.ok)
+        throw new Error(`Failed to write pending-task for ${args.assetId}: ${pendingResult.error.message}`);
+    if (pendingResult.value === null)
+        throw new Error(`Lost local lease while writing pending-task`);
+    await engine.metadata.artifacts.write(args.assetId, "kie-task-id", { taskId });
+    ctx.setLease({ kind: "task", taskId });
+    return taskId;
+}
+export async function submitQueuedKieTask(engine, task) {
+    if (task.taskId !== QUEUED_TASK_ID)
+        throw new Error(`KIE task ${task.artifactId} is not locally queued`);
+    const ownerId = await engine.jobs.pending.getOwner(task.artifactId, QUEUED_TASK_ID);
+    if (!ownerId)
+        throw new Error(`No active queued KIE lease found for ${task.artifactId}`);
+    const payloadResult = await engine.metadata.artifacts.read(task.artifactId, "generation-payload");
+    if (!payloadResult.ok || payloadResult.value === null)
+        throw new Error(`No prepared KIE payload found for ${task.artifactId}`);
+    const request = payloadResult.value;
+    assertProviderPayload(request, {
+        toolName: task.taskType,
+        wire: true,
+    });
+    // Reload persisted cost hints (if any) so the OTP minted on resubmission
+    // sees the same duration the original handler resolved, without leaking it
+    // into the wire payload.
+    const hintsResult = await engine.metadata.artifacts.read(task.artifactId, "generation-cost-hints");
+    const costHints = hintsResult.ok && hintsResult.value ? hintsResult.value : {};
+    const apiKey = requireApiKey("KIE_API_KEY");
+    const provider = createKieProvider(apiKey);
+    const { otp } = await authorizeKiePaygate(request, {
+        costHints,
+        engine,
+        correlation: {
+            artifactId: task.artifactId,
+            tool: task.taskType,
+            stage: "submit-queued-kie",
+        },
+    });
+    const taskId = await submitMediaJob(provider, request, { otp });
+    const meta = { ...task.meta };
+    delete meta.kiePaygate;
+    const writeResult = await engine.jobs.pending.write({
+        taskId,
+        taskType: task.taskType,
+        artifactId: task.artifactId,
+        meta,
+    }, ownerId);
+    if (!writeResult.ok)
+        throw new Error(`Failed to write submitted pending-task for ${task.artifactId}: ${writeResult.error.message}`);
+    if (writeResult.value === null)
+        throw new Error(`Lost queued KIE lease while submitting ${task.artifactId}`);
+    await engine.metadata.artifacts.write(task.artifactId, "kie-task-id", { taskId });
+    return writeResult.value.task;
+}

package/dist/jobs/label-music-sections.js

@@ -0,0 +1,5 @@
+import { registerJobHandler } from "../queue.js";
+import { labelMusicSections } from "../rhythm/section-labels.js";
+export function registerLabelMusicSectionsJob(engine) {
+    registerJobHandler("label_music_sections", async (payload, context) => labelMusicSections(engine, String(payload.artifactId), String(payload.analysisId), String(payload.streamId), context.signal));
+}

package/dist/jobs/osg-placement.js

@@ -0,0 +1,135 @@
+import { isSubtitleStyle } from "../remotion/subtitles/styles.js";
+import sharp from "sharp";
+import { getApiKey } from "../api-key.js";
+import { sampleEvenly } from "../frame-utils.js";
+import { OSG_PLACEMENT_VERSION, writeOsgPlacementAnalysis, } from "../osg-placement-cache.js";
+import { registerJobHandler } from "../queue.js";
+import { mapSourceRectToTarget, orientationDimensions, subtitleBand, } from "../remotion/keyword-placement.js";
+import { scoreWatermarkCorners } from "../remotion/osg-spec.js";
+import { RENDER_ORIENTATIONS, readStoredRenderDefaults } from "../tools/reconcile-project-work.js";
+import { detectOccupiedRegions } from "../vision-regions.js";
+import { BADGE_ASPECT } from "../watermark-badge.js";
+import { withLockedLocalLease } from "./_lease.js";
+const LOCK_DURATION_MS = 300_000;
+const MAX_FRAMES = 8;
+const SYSTEM_PROMPT = `You are a precise video-layout analyst. Each attached image is a frame sampled evenly across a video clip that will carry a small persistent corner watermark.
+
+For every frame, identify all occupied regions the watermark must not cover:
+- every visible human face, including partial faces and faces in posters or screens
+- every existing visible text block, subtitle, caption, title, logo, watermark, or graphic
+
+Return one entry for every cue_id. Coordinates use a normalized image scale from 0 to 1000: x and y are the top-left corner, followed by width and height. Use tight boxes around the visible occupied content. Do not return boxes for bodies, clothing, scenery, microphones, or ordinary objects. Return an empty occupied_regions array only when none of the listed content is visible. Never omit, rename, or duplicate a cue_id.`;
+function isSubtitlePosition(value) {
+    return value === "top" || value === "middle" || value === "bottom";
+}
+function isFontSizePreset(value) {
+    return value === "small" || value === "medium" || value === "large";
+}
+async function readSourceDimensions(engine, assetId, firstFrame) {
+    const meta = await engine.metadata.artifacts.read(assetId, "original");
+    if (meta.ok
+        && typeof meta.value.width === "number" && meta.value.width > 0
+        && typeof meta.value.height === "number" && meta.value.height > 0) {
+        return { width: meta.value.width, height: meta.value.height };
+    }
+    // Only the aspect matters for mapping onto the render canvas, so the sampled
+    // frame's dimensions are an equivalent fallback.
+    const probed = await sharp(firstFrame).metadata();
+    if (!probed.width || !probed.height) {
+        throw new Error(`Could not determine source dimensions for ${assetId}`);
+    }
+    return { width: probed.width, height: probed.height };
+}
+async function chooseWatermarkPositions(engine, assetId, regions, sourceWidth, sourceHeight, userScale, badgeAspect) {
+    const positions = {};
+    for (const orientation of RENDER_ORIENTATIONS) {
+        const { width, height } = orientationDimensions(orientation);
+        const occupied = regions.map((region) => ({
+            ...mapSourceRectToTarget(region, sourceWidth, sourceHeight, width, height),
+            kind: region.kind,
+            confidence: region.confidence,
+        }));
+        const stored = await readStoredRenderDefaults(engine, assetId, orientation);
+        const band = stored.subtitlesEnabled === true
+            ? subtitleBand(orientation, height, isSubtitlePosition(stored.position) ? stored.position : "bottom", isSubtitleStyle(stored.highlightStyle) ? stored.highlightStyle : "impact", isFontSizePreset(stored.fontSize) ? stored.fontSize : "medium")
+            : null;
+        positions[orientation] = scoreWatermarkCorners(orientation, occupied, {
+            aspect: badgeAspect,
+            userScale,
+            subtitleBand: band,
+        }).position;
+    }
+    return positions;
+}
+/**
+ * Sample frames, ask the vision model for occupied regions, and pick the
+ * least-busy corner per orientation. Writes the analysis cache on success.
+ * Throws when vision is unavailable (no key, no frames) so callers can fall
+ * back to a coarser placement.
+ */
+export async function analyzeOsgPlacement(engine, request) {
+    const { assetId, fingerprint, userScale, badgeAspect = BADGE_ASPECT, signal } = request;
+    const apiKey = getApiKey("OPENAI_API_KEY");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY is not set");
+    const listResult = await engine.files.listSubdir(assetId, "original_frames");
+    const frameFiles = listResult.ok
+        ? listResult.value
+            .filter((f) => f.endsWith(".jpg"))
+            .sort((a, b) => parseFloat(a) - parseFloat(b))
+        : [];
+    if (frameFiles.length === 0) {
+        throw new Error(`no_frames: asset ${assetId} has no original_frames to analyze`);
+    }
+    const sampled = sampleEvenly(frameFiles, MAX_FRAMES);
+    const frames = [];
+    for (const file of sampled) {
+        signal.throwIfAborted();
+        const read = await engine.files.read(assetId, `original_frames/${file}`);
+        if (!read.ok)
+            throw new Error(read.error.message);
+        frames.push({
+            id: file,
+            label: `timestamp=${parseFloat(file).toFixed(3)}s`,
+            buffer: Buffer.from(read.value),
+        });
+    }
+    const source = await readSourceDimensions(engine, assetId, frames[0].buffer);
+    const regionsByFrame = await detectOccupiedRegions(frames, {
+        apiKey,
+        signal,
+        instructions: SYSTEM_PROMPT,
+        schemaName: "osg_placement_analysis",
+        errorLabel: "OSG placement",
+        timeout: 240_000,
+    });
+    const regions = [...regionsByFrame.values()].flat();
+    const positions = await chooseWatermarkPositions(engine, assetId, regions, source.width, source.height, userScale, badgeAspect);
+    const analysis = {
+        version: OSG_PLACEMENT_VERSION,
+        fingerprint,
+        sourceWidth: source.width,
+        sourceHeight: source.height,
+        frameTimes: sampled.map((file) => parseFloat(file)),
+        regions,
+        positions,
+        analyzedAt: new Date().toISOString(),
+    };
+    await writeOsgPlacementAnalysis(engine, assetId, analysis);
+    return analysis;
+}
+export function registerOsgPlacementJob(engine) {
+    registerJobHandler("osg_placement", async (payload, ctx) => {
+        const { assetId, assetDir, fingerprint, userScale, badgeAspect = BADGE_ASPECT, } = payload;
+        return withLockedLocalLease(engine, assetId, assetDir, ctx, "analyze", { durationMs: LOCK_DURATION_MS, data: { state: "analyzing-osg-placement" } }, async () => {
+            const analysis = await analyzeOsgPlacement(engine, {
+                assetId,
+                fingerprint,
+                userScale,
+                badgeAspect,
+                signal: ctx.signal,
+            });
+            return { analysis };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+    });
+}

package/dist/jobs/pad-video.js

@@ -0,0 +1,72 @@
+import { rm } from "node:fs/promises";
+import { logger } from "../logger.js";
+import { registerJobHandler, queue } from "../queue.js";
+import { runFfmpeg, probeVideo, H264_MEDIUM, AUDIO_OPTS } from "../ffmpeg.js";
+import { join, basename } from "node:path";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+const LOCK_DURATION_MS = 300_000;
+export function registerPadVideoJob(engine) {
+    registerJobHandler("pad_video", async (payload, ctx) => {
+        const { sourcePath, assetDir, sourceAssetId, bookId, targetSecs, hasAudio } = payload;
+        logger.debug("pad-video-started", { assetId: sourceAssetId, bookId });
+        const result = await withLockedLocalLease(engine, sourceAssetId, assetDir, ctx, "process", { durationMs: LOCK_DURATION_MS, data: { state: "padding-video" } }, async () => {
+            const outName = `padded-${Date.now()}.mp4`;
+            const outputPath = join(assetDir, outName);
+            try {
+                const source = await probeVideo(sourcePath, { signal: ctx.signal });
+                if (!source.videoStream || source.videoDuration <= 0 || targetSecs <= source.videoDuration) {
+                    throw new Error("Padding must extend a playable video stream");
+                }
+                const args = ["-y", "-i", sourcePath];
+                if (hasAudio) {
+                    args.push("-filter_complex", `[0:v]tpad=stop=-1:color=black[v];[0:a]atrim=duration=${source.videoDuration},asetpts=PTS-STARTPTS,apad[a]`, "-map", "[v]", "-map", "[a]", "-t", targetSecs.toString(), ...H264_MEDIUM, ...AUDIO_OPTS, outputPath);
+                }
+                else {
+                    args.push("-filter_complex", "[0:v]tpad=stop=-1:color=black[v]", "-map", "[v]", "-t", targetSecs.toString(), ...H264_MEDIUM, outputPath);
+                }
+                await runFfmpeg(args, { signal: ctx.signal });
+                const output = await probeVideo(outputPath, { signal: ctx.signal });
+                if (!output.videoStream || Math.abs(output.videoDuration - targetSecs) > 1 / source.fps
+                    || output.hasAudio !== hasAudio) {
+                    throw new Error("Padding produced an invalid video duration or audio stream");
+                }
+                const splitAtIso = new Date().toISOString();
+                const provenance = {
+                    origin: "pad_video",
+                    source_asset_id: sourceAssetId,
+                    target_secs: targetSecs,
+                    has_audio: hasAudio,
+                    split_at_iso: splitAtIso,
+                };
+                const inputFilename = basename(sourcePath);
+                await replaceArtifactFileFromPath(engine, sourceAssetId, inputFilename, outputPath);
+                for (const stale of [
+                    ".original.analysis.json",
+                    ".analysis.gpt4otrans.json",
+                    "elevenlabs.json",
+                ]) {
+                    await engine.files.delete(sourceAssetId, stale);
+                }
+                await engine.metadata.artifacts.write(sourceAssetId, "original", provenance);
+                const videoPath = join(assetDir, inputFilename);
+                return { videoPath, provenance };
+            }
+            catch (err) {
+                await rm(outputPath, { force: true }).catch(() => { });
+                throw err;
+            }
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        await queue.enqueueAndWait(`process-video-${sourceAssetId}-${Date.now()}`, {
+            type: "process_video",
+            videoPath: result.videoPath,
+            assetId: sourceAssetId,
+            assetDir: assetDir,
+            bookId,
+            skipDownstreamJobs: true,
+            force: true,
+            provenance: result.provenance,
+        });
+        return { success: true };
+    });
+}