videobook 0.0.0-stage → 0.2.0

package/dist/jobs/tag-asset.js

@@ -0,0 +1,266 @@
+/**
+ * The queued tagging coordinator.
+ *
+ * One job type tags every kind of asset, because the hard parts — deciding
+ * which content was analyzed, refusing to publish a stale result, and leaving
+ * a user's own tags alone — are the same everywhere. What differs is only
+ * where the evidence lives, and that is a lookup.
+ *
+ * Three properties this job must hold:
+ *
+ * - **Detached from readiness.** Tagging never touches the artifact work row.
+ *   A book whose provider key is missing still plays its media; only its tags
+ *   are absent, and the outcome says so.
+ * - **Fenced to the content.** The fence is the primary media file's hash, not
+ *   the asset's whole-directory fingerprint, which changes whenever a sidecar
+ *   is written — including the analysis and tag writes this job itself causes.
+ *   Fencing on the directory would make every run trigger the next one.
+ * - **Idempotent.** The job id carries book, artifact, source hash and
+ *   analyzer version, so a restart, a duplicate completion event and a second
+ *   enqueue collapse into one run; a forced retry opts out explicitly.
+ */
+import { findAudioFile, findPrimaryMediaFile } from "videobook-engine";
+import { getApiKey } from "../api-key.js";
+import { logger } from "../logger.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { tagsFromImageAnalysis, tagsFromScriptText, tagsFromTranscript, tagsFromVideoAnalysis, } from "../asset-tag-extraction.js";
+import { readTaggingSettings } from "../tag-settings.js";
+import { TAG_ANALYZER_VERSION } from "../tag-vocabulary.js";
+const ANALYSIS_FILENAME = ".original.analysis.json";
+/**
+ * Kinds that carry something automatic tagging can read. A character sheet or
+ * a prompt is not untagged because analysis failed — there is nothing about it
+ * to analyze, and manual tags remain available on every kind.
+ */
+const TAGGABLE_KINDS = new Set([
+    "image",
+    "video",
+    "final",
+    "audio",
+    "script",
+]);
+/**
+ * The bytes a tag describes. Rendered orientations and sidecars are excluded:
+ * a tag is a claim about the content someone sees, and re-rendering does not
+ * change that content.
+ */
+async function primarySourceHash(engine, assetId, kind) {
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return null;
+    const files = manifest.value.files;
+    if (kind === "script") {
+        const document = files.find((file) => !file.name.startsWith("."));
+        return document?.objectHash ?? null;
+    }
+    const primary = kind === "audio"
+        ? findAudioFile(files, kind) ?? findPrimaryMediaFile(files, kind)
+        : findPrimaryMediaFile(files, kind);
+    return primary?.objectHash ?? null;
+}
+async function readAnalysis(engine, assetId) {
+    const read = await engine.files.read(assetId, ANALYSIS_FILENAME);
+    if (!read.ok)
+        return null;
+    try {
+        return JSON.parse(read.value.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function transcriptEvidence(engine, assetId) {
+    const transcripts = await engine.transcripts.list(assetId);
+    const latest = transcripts.ok ? transcripts.value.at(-1) : undefined;
+    if (!latest)
+        return null;
+    const segments = latest.segments ?? [];
+    const wordCount = segments.reduce((total, segment) => total + segment.text.trim().split(/\s+/u).filter(Boolean).length, 0);
+    const speakers = new Set(segments.flatMap((segment) => (segment.speaker ? [segment.speaker] : [])));
+    return { wordCount, speakerCount: speakers.size };
+}
+async function readScriptText(engine, assetId) {
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return null;
+    const document = manifest.value.files.find((file) => /\.(md|txt|fountain)$/iu.test(file.name));
+    if (!document)
+        return null;
+    const read = await engine.files.read(assetId, document.name);
+    return read.ok ? read.value.toString("utf8") : null;
+}
+/**
+ * Which evidence a kind carries. Audio has no frames, images have no
+ * transcript, and a kind with neither is not a failure — it simply has
+ * nothing automatic tagging can read.
+ */
+async function extractForKind(engine, assetId, kind) {
+    if (kind === "image") {
+        return tagsFromImageAnalysis(await readAnalysis(engine, assetId));
+    }
+    if (kind === "video" || kind === "final") {
+        const fromFrames = tagsFromVideoAnalysis(await readAnalysis(engine, assetId));
+        if (fromFrames.outcome === "tagged")
+            return fromFrames;
+        // A video whose analysis said nothing useful can still be grouped by what
+        // its transcript supports.
+        const fromSpeech = tagsFromTranscript(await transcriptEvidence(engine, assetId));
+        return fromSpeech.outcome === "tagged" ? fromSpeech : fromFrames;
+    }
+    if (kind === "audio") {
+        return tagsFromTranscript(await transcriptEvidence(engine, assetId));
+    }
+    if (kind === "script") {
+        return tagsFromScriptText(await readScriptText(engine, assetId));
+    }
+    return { tags: [], outcome: "unsupported_kind" };
+}
+/** Deterministic id: the same content and analyzer never queue twice. */
+export function tagAssetJobId(bookId, assetId, sourceHash) {
+    return `tag-asset-${bookId}-${assetId}-${sourceHash}-${TAG_ANALYZER_VERSION}`;
+}
+/**
+ * Queues tagging for one asset. Callers are completion tails — upload,
+ * processing, generation, analysis — so this must never throw into them: an
+ * asset that cannot be tagged is still a usable asset.
+ */
+export async function enqueueAssetTagging(engine, assetId, options = {}) {
+    try {
+        if (!options.force && !readTaggingSettings(engine).automaticEnabled)
+            return;
+        const bookId = engine.book.get().bookId;
+        const artifact = engine.artifacts.get(assetId);
+        if (!artifact.ok)
+            return;
+        const sourceHash = await primarySourceHash(engine, assetId, artifact.value.kind);
+        if (!sourceHash)
+            return;
+        await queue.enqueue(tagAssetJobId(bookId, assetId, sourceHash), {
+            type: "tag_asset",
+            bookId,
+            assetId,
+            ...(options.force ? { force: true } : {}),
+        });
+    }
+    catch (cause) {
+        logger.warn("tag-asset-failed", { assetId, error: cause });
+    }
+}
+export async function runAssetTagging(engine, payload, control) {
+    const { assetId, force } = payload;
+    const base = { assetId, tagCount: 0, analyzerVersion: TAG_ANALYZER_VERSION };
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok) {
+        return { ...base, outcome: "missing_asset", sourceHash: null };
+    }
+    if (!TAGGABLE_KINDS.has(artifact.value.kind)) {
+        return { ...base, outcome: "unsupported_kind", sourceHash: null };
+    }
+    const sourceHash = await primarySourceHash(engine, assetId, artifact.value.kind);
+    if (!sourceHash) {
+        return { ...base, outcome: "no_source_content", sourceHash: null };
+    }
+    // The engine keeps the last accepted snapshot. Re-running over the same
+    // content with the same analyzer would spend a write to reach the same
+    // state, and would clear nothing a user has since dismissed.
+    const snapshot = engine.tags.automatic.snapshot(assetId);
+    const current = snapshot.ok ? snapshot.value : undefined;
+    if (!force
+        && current
+        && current.sourceHash === sourceHash
+        && current.extractorVersion === TAG_ANALYZER_VERSION
+        && !current.stale) {
+        return { ...base, outcome: "already_current", sourceHash };
+    }
+    const extraction = await extractForKind(engine, assetId, artifact.value.kind);
+    if (extraction.outcome === "unsupported_kind") {
+        return { ...base, outcome: extraction.outcome, sourceHash };
+    }
+    if (extraction.outcome === "no_evidence") {
+        if (payload.cacheOnly) {
+            // Nothing usable is cached. Saying so is the point of a cache-only pass:
+            // the asset is counted as needing analysis rather than claimed current.
+            return { ...base, outcome: "no_evidence", sourceHash };
+        }
+        // Analysis is otherwise gated on dropping an asset into a timeline, which
+        // would leave everything that stays in the Library untagged. Ask for it
+        // here instead; the analysis tail re-queues this job, and the dedupe key
+        // is free again by then because this run has finished.
+        const requested = await requestAnalysis(engine, payload.bookId, assetId, artifact.value.kind, control);
+        return { ...base, outcome: requested, sourceHash };
+    }
+    // Re-read the hash: the content may have been replaced while the evidence
+    // was being read, and publishing against the old bytes would describe media
+    // the asset no longer has.
+    const publishHash = await primarySourceHash(engine, assetId, artifact.value.kind);
+    if (publishHash !== sourceHash) {
+        return { ...base, outcome: "no_source_content", sourceHash: publishHash };
+    }
+    const replaced = await engine.tags.automatic.replace({
+        artifactId: assetId,
+        sourceHash,
+        generator: "videobook-editorial-tagger",
+        extractorVersion: TAG_ANALYZER_VERSION,
+        tags: extraction.tags,
+    });
+    if (!replaced.ok) {
+        logger.warn("tag-asset-failed", { assetId, error: replaced.error });
+        return { ...base, outcome: extraction.outcome, sourceHash };
+    }
+    return {
+        ...base,
+        outcome: extraction.outcome,
+        tagCount: extraction.tags.length,
+        sourceHash,
+    };
+}
+/**
+ * Asks for the evidence this kind needs. Nothing here waits: the analysis job
+ * caches its result and re-queues tagging, so a missing provider key costs an
+ * outcome rather than a failed job on a perfectly good asset.
+ */
+async function requestAnalysis(engine, bookId, assetId, kind, control) {
+    if (control && !control.canRequestAnalysis())
+        return "no_evidence";
+    if (kind !== "image" && kind !== "video" && kind !== "final")
+        return "no_evidence";
+    if (!readTaggingSettings(engine).analysisOnNewAssets)
+        return "no_evidence";
+    if (!getApiKey("OPENAI_API_KEY"))
+        return "analysis_unavailable";
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok)
+        return "no_evidence";
+    if (control && !control.canRequestAnalysis())
+        return "no_evidence";
+    if (kind === "image") {
+        const original = manifest.value.files.find((file) => /^original\.(jpe?g|png|webp)$/iu.test(file.name));
+        if (!original)
+            return "no_evidence";
+        await queue.enqueue(`auto-describe-${assetId}`, {
+            type: "describe_image",
+            bookId,
+            sourceAssetId: assetId,
+            sourceImageFilename: original.name,
+        });
+        return "analysis_requested";
+    }
+    if (kind === "video" || kind === "final") {
+        await queue.enqueue(`auto-analyze-${assetId}`, {
+            type: "analyze_video",
+            bookId,
+            assetId,
+            assetDir: manifest.value.path,
+            hasTranscription: false,
+            // Tagging wants the analysis and nothing else: an asset nobody has put
+            // on a timeline must not pull transcription and rendering along behind
+            // it just because it was tagged.
+            purpose: "tagging",
+        });
+        return "analysis_requested";
+    }
+    return "no_evidence";
+}
+export function registerTagAssetJob(engine) {
+    registerJobHandler("tag_asset", async (payload) => await runAssetTagging(engine, payload));
+}

package/dist/jobs/task-failure.js

@@ -0,0 +1,16 @@
+import { appendDiagnostic } from "../diagnostics.js";
+/**
+ * CAS-fail a pending task by (asset_id, task_id) and log to the project's
+ * action log. Required everywhere that fails a provider task: the task_id
+ * scopes the CAS so a late failure of an old task can't clobber a fresh
+ * retry that already replaced the row.
+ */
+export async function failPendingTaskAndLog(engine, assetId, taskId, info) {
+    const result = await engine.jobs.pending.fail(assetId, taskId, info);
+    if (!result.ok)
+        return;
+    await appendDiagnostic(engine, "job-error", {
+        assetId,
+        error: info,
+    }).catch(() => { });
+}

package/dist/jobs/timewarp-video.js

@@ -0,0 +1,152 @@
+import { rm } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { probeVideo, runFfmpeg, H264_MEDIUM, AUDIO_OPTS } from "../ffmpeg.js";
+import { registerJobHandler, queue } from "../queue.js";
+import { buildTimewarpVideoFilter, createTimewarpPlan, } from "../timewarp.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.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 outputArgs(inputPath, outputPath, plan, hasAudio, audioMode) {
+    return [
+        "-y",
+        "-i", inputPath,
+        "-filter_complex", buildTimewarpVideoFilter(plan),
+        "-map", "[vout]",
+        ...(hasAudio ? ["-map", "0:a:0"] : ["-an"]),
+        ...H264_MEDIUM,
+        "-pix_fmt", "yuv420p",
+        ...(hasAudio ? (audioMode === "copy" ? ["-c:a", "copy"] : AUDIO_OPTS) : []),
+        "-t", plan.sourceDuration.toFixed(9),
+        "-movflags", "+faststart",
+        "-f", "mp4",
+        outputPath,
+    ];
+}
+export async function renderTimewarpedVideo(inputPath, outputPath, plan, hasAudio, signal) {
+    if (!hasAudio) {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, false, "copy"), { signal });
+        return "none";
+    }
+    const source = await probeVideo(inputPath, { signal });
+    if (source.audioCodec !== "aac") {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, true, "aac"), { signal });
+        return "aac";
+    }
+    try {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, true, "copy"), { signal });
+        return "copy";
+    }
+    catch {
+        await runFfmpeg(outputArgs(inputPath, outputPath, plan, true, "aac"), { signal });
+        return "aac";
+    }
+}
+export async function validateTimewarpOutput(inputPath, outputPath, plan) {
+    const [input, output] = await Promise.all([
+        probeVideo(inputPath),
+        probeVideo(outputPath),
+    ]);
+    if (output.videoCodec === null || output.width <= 0 || output.height <= 0) {
+        throw new Error("Timewarp output has no usable video stream");
+    }
+    if (output.width !== input.width || output.height !== input.height) {
+        throw new Error(`Timewarp output dimensions ${output.width}x${output.height} do not match source ${input.width}x${input.height}`);
+    }
+    if (output.hasAudio !== input.hasAudio) {
+        throw new Error("Timewarp output audio stream layout does not match the source");
+    }
+    const tolerance = Math.max(0.08, 2 / plan.sourceFps);
+    if (!Number.isFinite(output.duration)
+        || Math.abs(output.duration - plan.sourceDuration) > tolerance) {
+        throw new Error(`Timewarp output duration ${output.duration.toFixed(3)}s does not match source ${plan.sourceDuration.toFixed(3)}s`);
+    }
+}
+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 });
+}
+export function registerTimewarpVideoJob(engine) {
+    registerJobHandler("timewarp_video", async (payload, ctx) => {
+        const { inputPath, outputPath, startSeconds, endSeconds, stretchFactor, assetId, assetDir, bookId, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "change_speed", { durationMs: LOCK_DURATION_MS, data: { state: "timewarping" } }, async () => {
+            const source = await probeVideo(inputPath, { signal: ctx.signal });
+            const plan = createTimewarpPlan({
+                sourceDuration: source.duration,
+                sourceFps: source.fps,
+                startSeconds,
+                endSeconds,
+                stretchFactor,
+            });
+            let audioMode;
+            try {
+                audioMode = await renderTimewarpedVideo(inputPath, outputPath, plan, source.hasAudio, ctx.signal);
+                await validateTimewarpOutput(inputPath, outputPath, plan);
+            }
+            catch (error) {
+                await discardTemp(outputPath);
+                throw error;
+            }
+            const history = engine.history.artifact(assetId);
+            const restoreCommit = history[0]?.hash;
+            try {
+                const inputFilename = basename(inputPath);
+                await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+                for (const filename of STALE_VISUAL_DERIVATIVES) {
+                    await deleteIfPresent(engine, assetId, filename);
+                }
+            }
+            catch (error) {
+                if (restoreCommit)
+                    await engine.history.restoreArtifact(assetId, restoreCommit);
+                throw error;
+            }
+            return {
+                videoPath: join(assetDir, basename(inputPath)),
+                plan,
+                audioMode,
+            };
+        }, { 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: "timewarp",
+                start_seconds: result.plan.startSeconds,
+                end_seconds: result.plan.endSeconds,
+                stretch_factor: result.plan.stretchFactor,
+                outside_stretch_factor: result.plan.outsideStretchFactor,
+                source_duration: result.plan.sourceDuration,
+                selected_output_duration: result.plan.selectedOutputDuration,
+                audio_preserved: true,
+                audio_mode: result.audioMode,
+                timewarped_at: new Date().toISOString(),
+            },
+            force: true,
+            skipDownstreamJobs: true,
+            preserveAudioArtifacts: true,
+            reviveVisualAnalysis: true,
+        });
+        return {
+            success: true,
+            source_duration: result.plan.sourceDuration,
+            selected_output_duration: result.plan.selectedOutputDuration,
+            outside_stretch_factor: result.plan.outsideStretchFactor,
+            audio_mode: result.audioMode,
+        };
+    });
+}

package/dist/jobs/transcribe-video-audio.js

@@ -0,0 +1,117 @@
+import { createOpenAi } from "../usage-providers.js";
+import { appendDiagnostic } from "../diagnostics.js";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import { logger } from "../logger.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { getApiKey } from "../api-key.js";
+import { probeVideo } from "../ffmpeg.js";
+import { DOWNSTREAM_LEASE_WAIT_MS, withLocalLease, } from "./_lease.js";
+import { chunkStarts, chunkLength, extractAudioChunk } from "./_audio-chunks.js";
+import { enqueueLazyAnalysisIfSlotted, enqueueLazyTimelineRender } from "../lazy-render.js";
+const CHUNK_SECONDS = 5 * 60;
+async function transcribeBytes(provider, bytes, filename) {
+    const file = new File([bytes], filename, { type: audioMimeType(filename) });
+    const result = await provider.post.v1.audio.transcriptions({
+        file,
+        model: "gpt-transcribe",
+    });
+    return result.text;
+}
+async function transcribeChunked(provider, mediaPath, duration) {
+    const dir = await mkdtemp(join(tmpdir(), "videocity-transcribe-"));
+    try {
+        const texts = [];
+        const starts = chunkStarts(duration, CHUNK_SECONDS);
+        for (let index = 0; index < starts.length; index++) {
+            const start = starts[index];
+            const length = chunkLength(duration, start, CHUNK_SECONDS);
+            const chunkName = `chunk-${String(index).padStart(3, "0")}.mp3`;
+            const chunkPath = join(dir, chunkName);
+            await extractAudioChunk(mediaPath, start, length, chunkPath);
+            const bytes = await readFile(chunkPath);
+            texts.push(await transcribeBytes(provider, new Uint8Array(bytes), chunkName));
+        }
+        return texts.map((text) => text.trim()).filter(Boolean).join(" ");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export async function runTranscribeVideoAudio(engine, payload, ctx) {
+    const { videoPath, assetId, bookId } = payload;
+    const apiKey = getApiKey("OPENAI_API_KEY");
+    if (!apiKey)
+        return { success: false, reason: "OPENAI_API_KEY not set" };
+    const result = await withLocalLease(engine, assetId, ctx, "transcribe", async () => {
+        try {
+            const provider = createOpenAi({ apiKey, timeout: 120_000 });
+            const probe = await probeVideo(videoPath);
+            let text;
+            let chunkCount = 1;
+            if (probe.duration > CHUNK_SECONDS) {
+                chunkCount = chunkStarts(probe.duration, CHUNK_SECONDS).length;
+                text = await transcribeChunked(provider, videoPath, probe.duration);
+            }
+            else {
+                const sourceFilename = payload.sourceFilename ?? "original.mp3";
+                const readResult = await engine.files.read(assetId, sourceFilename);
+                if (!readResult.ok)
+                    throw new Error(readResult.error.message);
+                text = await transcribeBytes(provider, new Uint8Array(readResult.value), sourceFilename);
+            }
+            const jsonString = JSON.stringify({ text }, null, 2);
+            await engine.files.write(assetId, ".analysis.gpt4otrans.json", jsonString);
+            await queue.enqueue(`semantic-index-${assetId}-transcript-${Date.now()}`, {
+                type: "semantic_index",
+                assetId,
+                bookId,
+            });
+            return { success: true, text, chunk_count: chunkCount };
+        }
+        catch (err) {
+            // Soft-fail: this job is enqueued eagerly after every video with audio
+            // (process-video.ts). A failed transcript must not mark the asset
+            // 'error' — the video itself is fine and the transcript is a sidecar,
+            // same rationale as the waveform soft-fail in process-video.ts.
+            // Returning (instead of throwing) lets withLocalLease complete the
+            // lease, so the asset stays claimable for a later retry.
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.warn("transcribe-soft-fail", { assetId, error: err });
+            await appendDiagnostic(engine, "transcribe-soft-fail", { assetId, error: err }).catch(() => undefined);
+            return { success: false, reason };
+        }
+    }, { waitForActiveMs: DOWNSTREAM_LEASE_WAIT_MS });
+    // A force re-process (trim, re-download) invalidated the vision analysis;
+    // for slotted assets re-run it here — after speech-to-text, so the analyze
+    // prompt includes the fresh transcript — which revives auto-transcribe and
+    // the lazy render below (that call skips while the analysis is missing).
+    try {
+        await enqueueLazyAnalysisIfSlotted(engine, bookId, assetId);
+    }
+    catch (err) {
+        void err;
+    }
+    try {
+        await enqueueLazyTimelineRender(engine, bookId, assetId);
+    }
+    catch (err) {
+        void err;
+    }
+    return result;
+}
+export function registerTranscribeVideoAudioJob(engine) {
+    registerJobHandler("transcribe_video_audio", async (payload, ctx) => runTranscribeVideoAudio(engine, payload, ctx));
+}
+function audioMimeType(filename) {
+    switch (extname(filename).toLowerCase()) {
+        case ".wav": return "audio/wav";
+        case ".ogg": return "audio/ogg";
+        case ".weba": return "audio/webm";
+        case ".m4a": return "audio/mp4";
+        case ".aac": return "audio/aac";
+        case ".flac": return "audio/flac";
+        default: return "audio/mpeg";
+    }
+}

package/dist/jobs/transcribe.js

@@ -0,0 +1,35 @@
+import { queue, registerJobHandler } from "../queue.js";
+import { DOWNSTREAM_LEASE_WAIT_MS, withLocalLease, } from "./_lease.js";
+import { transcribeAssetToElevenLabsJson } from "./_transcribe.js";
+import { enqueueLazyAnalysisIfSlotted, enqueueLazyTimelineRender, } from "../lazy-render.js";
+export function registerTranscribeJob(engine) {
+    registerJobHandler("transcribe", async (payload, ctx) => {
+        const { audioFilename, tagAudioEvents, diarize, languageCode, assetId, bookId, } = payload;
+        const result = await withLocalLease(engine, assetId, ctx, "transcribe", async () => {
+            await transcribeAssetToElevenLabsJson(engine, assetId, audioFilename, {
+                tagAudioEvents,
+                diarize,
+                ...(languageCode ? { languageCode } : {}),
+            });
+            return { success: true, provider: "elevenlabs" };
+        }, { waitForActiveMs: DOWNSTREAM_LEASE_WAIT_MS });
+        await queue.enqueue(`semantic-index-${assetId}-transcript-${Date.now()}`, {
+            type: "semantic_index",
+            assetId,
+            bookId,
+        });
+        try {
+            await enqueueLazyAnalysisIfSlotted(engine, bookId, assetId);
+        }
+        catch (err) {
+            void err;
+        }
+        try {
+            await enqueueLazyTimelineRender(engine, bookId, assetId);
+        }
+        catch (err) {
+            void err;
+        }
+        return result;
+    });
+}

package/dist/jobs/translate-transcript.js

@@ -0,0 +1,55 @@
+import { registerJobHandler } from "../queue.js";
+import { requireApiKey } from "../api-key.js";
+import { buildIntelligenceResponses } from "../openai-intelligence.js";
+import { withLocalLease } from "./_lease.js";
+import { enqueueLazyTimelineRender } from "../lazy-render.js";
+import { parseSegments } from "../remotion/subtitles/segments.js";
+import { iso1FromIso3, readLanguageCode, sidecarMatchesSource, translatedTranscriptFilename, translateTranscript, } from "./_translate-transcript.js";
+export async function runTranslateTranscript(engine, payload, ctx) {
+    const { assetId, bookId, targetLanguage } = payload;
+    // Leased as "transcribe": the engine's ArtifactWorkKind union has no
+    // translate kind, and sharing it serializes translation against
+    // re-transcription of the same asset.
+    const result = await withLocalLease(engine, assetId, ctx, "transcribe", async () => {
+        const readResult = await engine.files.read(assetId, "elevenlabs.json");
+        if (!readResult.ok) {
+            throw new Error(`No transcript for ${assetId}: ${readResult.error.message}. Transcribe the asset first.`);
+        }
+        const raw = JSON.parse(readResult.value.toString());
+        if (iso1FromIso3(readLanguageCode(raw)) === targetLanguage) {
+            return { success: true, targetLanguage, skipped: "matches-source" };
+        }
+        const sidecarFilename = translatedTranscriptFilename(targetLanguage);
+        const existing = await engine.files.read(assetId, sidecarFilename);
+        if (existing.ok) {
+            const sourceSegments = parseSegments(raw);
+            try {
+                const sidecar = JSON.parse(existing.value.toString());
+                if (sidecarMatchesSource(sidecar, sourceSegments)) {
+                    return { success: true, targetLanguage, cached: true };
+                }
+            }
+            catch {
+                // unreadable sidecar — re-translate below
+            }
+        }
+        const responses = buildIntelligenceResponses(requireApiKey("OPENAI_API_KEY"));
+        const sidecar = await translateTranscript(raw, targetLanguage, responses, ctx.signal);
+        const writeResult = await engine.files.write(assetId, sidecarFilename, JSON.stringify(sidecar, null, 2));
+        if (!writeResult.ok) {
+            throw new Error(`Failed to write ${sidecarFilename}: ${writeResult.error.message}`);
+        }
+        await engine.history.recordOperation("translate_transcript", assetId, { targetLanguage });
+        return { success: true, targetLanguage };
+    });
+    try {
+        await enqueueLazyTimelineRender(engine, bookId, assetId);
+    }
+    catch (err) {
+        void err;
+    }
+    return result;
+}
+export function registerTranslateTranscriptJob(engine) {
+    registerJobHandler("translate_transcript", (payload, ctx) => runTranslateTranscript(engine, payload, ctx));
+}