videobook 0.0.0-stage → 0.2.0

package/dist/tools/clean-video-audio.js

@@ -0,0 +1,97 @@
+import { findVideoFile } from "videobook-engine";
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { requireArtifactKind, toolError } from "./_shared.js";
+const DEFAULT_SOURCE_MIX = 0.22;
+const DEFAULT_EDGE_FADE_MS = 250;
+const DEFAULT_MUSIC_VOLUME = 0.08;
+export function cleanVideoAudioDef(engine) {
+    return {
+        name: "clean_video_audio",
+        description: "Clean a video's audio in place with ElevenLabs Voice Isolator: dialogue first, a quiet denoised bed for important sounds, edge fades and optional subtle music. The picture is unchanged.",
+        schema: {
+            asset_id: z.string().describe("Video artifact id (with or without a leading @)"),
+            book_id: z.string().describe("Book id"),
+            source_mix: z
+                .number()
+                .min(0)
+                .max(0.5)
+                .optional()
+                .describe(`Original denoised effects/ambience level from 0 to 0.5 (default ${DEFAULT_SOURCE_MIX})`),
+            edge_fade_ms: z
+                .number()
+                .int()
+                .min(0)
+                .max(2000)
+                .optional()
+                .describe(`Start and end fade length used to suppress boundary noise (default ${DEFAULT_EDGE_FADE_MS}ms)`),
+            add_light_music: z
+                .boolean()
+                .optional()
+                .describe("Generate and mix a light instrumental music bed"),
+            music_prompt: z
+                .string()
+                .min(1)
+                .max(4100)
+                .optional()
+                .describe("Optional ElevenLabs Music direction; providing it also enables music"),
+            music_volume: z
+                .number()
+                .min(0.01)
+                .max(0.25)
+                .optional()
+                .describe(`Music level from 0.01 to 0.25 (default ${DEFAULT_MUSIC_VOLUME})`),
+        },
+        handler: async (args) => {
+            if (!process.env.ELEVENLABS_API_KEY) {
+                return toolError("ELEVENLABS_API_KEY environment variable is not set");
+            }
+            const { asset_id, book_id, source_mix, edge_fade_ms, add_light_music, music_prompt, music_volume, } = args;
+            const assetId = asset_id.replace(/^@/, "");
+            const kindGate = await requireArtifactKind(engine, assetId, ["video"], "clean_video_audio");
+            if (kindGate)
+                return kindGate;
+            const manifestResult = await engine.files.manifest(assetId);
+            if (!manifestResult.ok)
+                return toolError(manifestResult.error.message);
+            const manifest = manifestResult.value;
+            const videoFile = manifest.files.find((file) => file.name.toLowerCase() === "original.mp4")
+                ?? findVideoFile(manifest.files);
+            if (!videoFile)
+                return toolError(`No video file found in asset ${assetId}`);
+            const trimmedMusicPrompt = music_prompt?.trim() || null;
+            const addMusic = add_light_music === true || trimmedMusicPrompt !== null;
+            const jobId = `clean-video-audio-${assetId}-${Date.now()}`;
+            try {
+                await queue.enqueue(jobId, {
+                    type: "clean_video_audio",
+                    assetId,
+                    assetDir: manifest.path,
+                    videoFilename: videoFile.name,
+                    bookId: book_id,
+                    sourceMix: source_mix ?? DEFAULT_SOURCE_MIX,
+                    edgeFadeMs: edge_fade_ms ?? DEFAULT_EDGE_FADE_MS,
+                    addMusic,
+                    musicPrompt: trimmedMusicPrompt,
+                    musicVolume: music_volume ?? DEFAULT_MUSIC_VOLUME,
+                });
+            }
+            catch (error) {
+                return toolError(`Audio cleanup could not be enqueued: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            asset_id: assetId,
+                            job_id: jobId,
+                            status: "enqueued",
+                            source_mix: source_mix ?? DEFAULT_SOURCE_MIX,
+                            edge_fade_ms: edge_fade_ms ?? DEFAULT_EDGE_FADE_MS,
+                            light_music: addMusic,
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/clear-failed-tasks.js

@@ -0,0 +1,66 @@
+import { findAudioFile, findVideoFile } from "videobook-engine";
+import { extname } from "node:path";
+import { z } from "zod";
+const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "webp", "gif", "svg"]);
+// Generation errors are not exclusive to generations: sidecar jobs (e.g. a
+// failed ElevenLabs transcribe) write them onto completed assets too. Deleting
+// is only safe for unmaterialized husks — an asset holding real media must be
+// kept and merely have its error row cleared (the same clear the render tool
+// performs before retrying).
+function hasMediaFile(files, kind) {
+    if (findVideoFile(files))
+        return true;
+    if (findAudioFile(files, kind))
+        return true;
+    return files.some((f) => {
+        const ext = (f.extension ?? extname(f.name)).replace(/^\./, "").toLowerCase();
+        return IMAGE_EXTENSIONS.has(ext);
+    });
+}
+export function clearFailedTasksDef(engine) {
+    return {
+        name: "clean_failed_assets",
+        description: "Clean up assets with a persisted generation error: delete unmaterialized generation husks (returned as 'cleared'), but keep assets that already hold media and only clear their error row (returned as 'error_cleared').",
+        schema: {
+            book_id: z.string().describe("Book id"),
+        },
+        handler: async (args) => {
+            const { book_id: _book_id } = args;
+            const failuresRes = await engine.jobs.failures.findAll();
+            const failures = failuresRes.ok ? failuresRes.value : [];
+            const cleared = [];
+            const errorCleared = [];
+            const errors = [];
+            for (const failure of failures) {
+                const artifact = engine.artifacts.get(failure.artifactId);
+                const manifest = await engine.files.manifest(failure.artifactId);
+                const materialized = artifact.ok
+                    && manifest.ok
+                    && hasMediaFile(manifest.value.files, artifact.value.kind);
+                if (materialized) {
+                    const clearResult = await engine.jobs.failures.clear(failure.artifactId);
+                    if (clearResult.ok) {
+                        errorCleared.push(failure.artifactId);
+                    }
+                    else {
+                        errors.push({ assetId: failure.artifactId, message: clearResult.error.message });
+                    }
+                    continue;
+                }
+                const result = await engine.artifacts.delete(failure.artifactId);
+                if (result.ok) {
+                    cleared.push(failure.artifactId);
+                }
+                else {
+                    errors.push({ assetId: failure.artifactId, message: result.error.message });
+                }
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ cleared, error_cleared: errorCleared, errors }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/cold-open.js

@@ -0,0 +1,114 @@
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { getApiKey } from "../api-key.js";
+import { checkColdOpenNotebook, coldOpenCacheKey, coldOpenSource, readColdOpenSuggestion } from "../cold-open.js";
+import { coldOpenRangeError } from "../cold-open-model.js";
+import { withNotebookMutation } from "../notebook-mutations.js";
+import { queue } from "../queue.js";
+import { resolveVideoAssetReference } from "./video-source-reference.js";
+import { parseVideoTimestamp, videoTimestampSchema } from "./video-time-input.js";
+const sourceSchema = z.object({
+    book_id: z.string().uuid(),
+    asset_id: z.string().min(1).describe("Source video artifact UUID or notebook address such as @a1"),
+    notebook_id: z.string().uuid().optional(),
+});
+const editSchema = sourceSchema.extend({
+    source_object_hash: z.string().min(1).describe("Source hash returned by prepare_cold_open"),
+    start_time: videoTimestampSchema,
+    end_time: videoTimestampSchema,
+    request_id: z.string().uuid().describe("Stable request UUID; reuse when retrying this exact reviewed edit"),
+});
+const json = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });
+const failure = (error) => ({ isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] });
+export function coldOpenDefs(engine) {
+    return [{
+            name: "prepare_cold_open",
+            description: "Suggest an exciting 2-5 second highlight of a video for a cold open (cached, or an analysis job to read with list_jobs). Start here for cold opens: review the range, then create the copy with edit_cold_open.",
+            schema: sourceSchema.shape,
+            handler: async (input) => {
+                try {
+                    const args = sourceSchema.parse(input);
+                    const sourceId = resolveVideoAssetReference(engine, args.asset_id, args.notebook_id);
+                    checkColdOpenNotebook(engine, args.notebook_id, sourceId);
+                    return await withNotebookMutation(`cold-open-prepare:${args.book_id}:${sourceId}`, async () => {
+                        const source = await coldOpenSource(engine, sourceId);
+                        const cacheKey = coldOpenCacheKey(source);
+                        const cached = readColdOpenSuggestion(engine, cacheKey);
+                        if (cached)
+                            return json({ status: "ready", suggestion: cached });
+                        const pending = engine.jobs.queue.list({ type: "prepare_cold_open", limit: 500 })
+                            .find(job => job.payload.cacheKey === cacheKey && ["queued", "running", "completing"].includes(job.state));
+                        if (pending)
+                            return json({ status: "queued", job_id: pending.id });
+                        if (!getApiKey("OPENAI_API_KEY"))
+                            throw new Error("Set OPENAI_API_KEY in provider settings to select a cold-open highlight.");
+                        const job = await queue.enqueue(`cold-open-prepare-${cacheKey}-${randomUUID()}`, {
+                            type: "prepare_cold_open", bookId: args.book_id, sourceArtifactId: sourceId,
+                            sourceObjectHash: source.file.objectHash, cacheKey,
+                        });
+                        return json({ status: "queued", job_id: job.id });
+                    });
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            },
+        }, {
+            name: "edit_cold_open",
+            description: "Create the cold-open copy from a reviewed prepare_cold_open suggestion: the chosen range, a hard cut, then the full original clip. The source is kept; poll list_jobs for the new asset.",
+            annotations: { destructiveHint: false, readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+            schema: editSchema.shape,
+            handler: async (input) => {
+                try {
+                    const args = editSchema.parse(input);
+                    const sourceId = resolveVideoAssetReference(engine, args.asset_id, args.notebook_id);
+                    const start = parseVideoTimestamp(args.start_time, "start_time");
+                    const end = parseVideoTimestamp(args.end_time, "end_time");
+                    const fingerprint = createHash("sha256").update(JSON.stringify([sourceId, args.notebook_id, args.source_object_hash, start, end])).digest("hex");
+                    return await withNotebookMutation(`cold-open:${args.book_id}:${args.request_id}`, async () => {
+                        const key = `cold-open.request.${args.request_id}`;
+                        const existing = engine.settings.get(key);
+                        if (existing && existing.fingerprint !== fingerprint)
+                            throw new Error("This request ID belongs to a different edit. Start a new request.");
+                        if (existing && !engine.artifacts.get(existing.artifactId).ok)
+                            throw new Error("The cold-open copy was deleted. Start a new request.");
+                        const previous = existing?.jobId ? engine.jobs.queue.get(existing.jobId)
+                            : engine.jobs.queue.list({ type: "edit_cold_open", limit: 500 }).find(job => job.payload.requestId === args.request_id);
+                        if (previous && ["queued", "running", "completing", "done"].includes(previous.state)) {
+                            return json({ status: previous.state === "done" ? "completed" : "queued", job_id: previous.id, output_asset_id: existing?.artifactId });
+                        }
+                        const source = await coldOpenSource(engine, sourceId, args.source_object_hash);
+                        const rangeError = coldOpenRangeError(start, end, source.durationSeconds);
+                        if (rangeError)
+                            throw new Error(rangeError);
+                        checkColdOpenNotebook(engine, args.notebook_id, sourceId);
+                        let artifactId = existing?.artifactId;
+                        if (!artifactId) {
+                            const created = await engine.artifacts.create({ kind: "video", label: `${source.artifact.label ?? "Video"} — Cold open` });
+                            if (!created.ok)
+                                throw new Error(created.error.message);
+                            artifactId = created.value.artifactId;
+                            const stored = engine.settings.set(key, { fingerprint, artifactId });
+                            if (!stored.ok) {
+                                await engine.artifacts.delete(artifactId);
+                                throw new Error(stored.error.message);
+                            }
+                        }
+                        const job = await queue.enqueue(`cold-open-edit-${args.request_id}-${randomUUID()}`, {
+                            type: "edit_cold_open", bookId: args.book_id, assetId: artifactId,
+                            sourceArtifactId: sourceId, sourceObjectHash: args.source_object_hash,
+                            startSeconds: start, endSeconds: end, notebookId: args.notebook_id ?? null,
+                            requestId: args.request_id,
+                        });
+                        const stored = engine.settings.set(key, { fingerprint, artifactId, jobId: job.id });
+                        if (!stored.ok)
+                            throw new Error(stored.error.message);
+                        return json({ status: "queued", job_id: job.id, output_asset_id: artifactId });
+                    });
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            },
+        }];
+}