venice-video-harness 2.4.0

package/dist/storyboard/assembler.js

@@ -0,0 +1,319 @@
+// ---------------------------------------------------------------------------
+// Storyboard Assembler -- orchestrates image generation for each shot and
+// compiles the results into a structured Storyboard object.
+//
+// Handles Venice API calls, image persistence, and final JSON export.
+// ---------------------------------------------------------------------------
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeImageProvenance } from "../venice/provenance.js";
+// ---- Constants ------------------------------------------------------------
+/** Default image resolution and aspect ratio for Venice API. */
+const DEFAULT_RESOLUTION = "1K";
+const DEFAULT_ASPECT_RATIO = "16:9";
+/**
+ * Image-generation model for panels.
+ *
+ * Seedance 2.0 used to reject face-bearing images from non-seedream families,
+ * so face-bearing panels were forced onto seedream-v5-lite. Venice removed that
+ * restriction (2026-07), so all panels — character and faceless alike — use a
+ * single high-quality default (`nano-banana-2`). FACE_MODEL / NO_FACE_MODEL are
+ * kept as aliases so the per-shot selection call sites don't need to change.
+ */
+const FACE_MODEL = "nano-banana-2";
+const NO_FACE_MODEL = "nano-banana-2";
+/** Diffusion steps -- higher = better quality, slower. */
+const DEFAULT_STEPS = 30;
+/** Classifier-free guidance scale. */
+const DEFAULT_CFG_SCALE = 7.5;
+// ---- Assembler class ------------------------------------------------------
+export class StoryboardAssembler {
+    outputDir;
+    constructor(outputDir) {
+        this.outputDir = outputDir;
+    }
+    // ---- Scene generation ---------------------------------------------------
+    /**
+     * Generate images for every shot in a scene and return an array of
+     * StoryboardPanel objects.
+     *
+     * For each shot the method:
+     * 1. Calls the Venice API (with reference images when available).
+     * 2. Saves the generated image to disk.
+     * 3. Saves a video prompt JSON file alongside the image.
+     * 4. Records metadata in a StoryboardPanel.
+     *
+     * @param sceneNumber      - 1-based scene index.
+     * @param scene            - The parent Scene data.
+     * @param shots            - Ordered array of shots planned for this scene.
+     * @param promptResults    - Parallel array of PromptResult objects (one per shot).
+     * @param client           - An authenticated VeniceClient instance.
+     * @param videoPrompts     - Parallel array of VideoPromptResult objects (one per shot).
+     * @returns Array of StoryboardPanel objects in shot order.
+     */
+    async generateScene(sceneNumber, scene, shots, promptResults, client, videoPrompts) {
+        // Ensure the scene output directory exists.
+        const sceneDir = join(this.outputDir, `scene-${String(sceneNumber).padStart(3, "0")}`);
+        await mkdir(sceneDir, { recursive: true });
+        const panels = [];
+        for (let i = 0; i < shots.length; i++) {
+            const shot = shots[i];
+            const pr = promptResults[i];
+            let imageBase64;
+            let usedSeed;
+            // Choose the generation model based on face presence. Face-bearing
+            // panels need seedream-v5-lite so they can be passed to Seedance
+            // video; faceless panels use the higher-quality no-face model.
+            const hasFace = (shot.characters?.length ?? 0) > 0;
+            const imageModel = hasFace ? FACE_MODEL : NO_FACE_MODEL;
+            if (pr.referenceImages.length > 0) {
+                // Use reference-augmented generation
+                const result = await this.generateWithReferences(client, pr, imageModel);
+                imageBase64 = result.base64;
+                usedSeed = result.seed ?? 0;
+            }
+            else {
+                // Standard generation (no character references)
+                const result = await this.generateStandard(client, pr, imageModel);
+                imageBase64 = result.base64;
+                usedSeed = result.seed ?? 0;
+            }
+            // Save image to disk
+            const shotId = String(shot.shotNumber).padStart(3, "0");
+            const fileName = `shot-${shotId}.png`;
+            const imagePath = join(sceneDir, fileName);
+            const imageBuffer = Buffer.from(imageBase64, "base64");
+            await writeFile(imagePath, imageBuffer);
+            // Track which image model produced this panel so the Seedance
+            // pre-flight gate can validate it later.
+            await writeImageProvenance(imagePath, imageModel, [], { hasFace });
+            // Save video prompt JSON alongside the image
+            const vp = videoPrompts?.[i];
+            if (vp) {
+                const panelId = `S${sceneNumber}-P${shot.shotNumber}`;
+                // Use new `video` block; fall back to legacy `veo` for old data
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const videoBlock = (vp.video ?? vp.veo);
+                const videoJson = {
+                    panelId,
+                    sceneNumber,
+                    shotNumber: shot.shotNumber,
+                    video: {
+                        model: videoBlock.model,
+                        prompt: videoBlock.prompt,
+                        duration: videoBlock.duration ?? `${videoBlock.durationSeconds ?? "8"}s`,
+                        audio: videoBlock.audio ?? videoBlock.generateAudio ?? true,
+                    },
+                    metadata: {
+                        imagePrompt: pr.prompt,
+                        characters: shot.characters,
+                        dialogue: shot.dialogue
+                            ? { character: shot.focusCharacter || shot.characters[0] || "UNKNOWN", line: shot.dialogue }
+                            : undefined,
+                        sfx: vp.audioNotes.sfx || undefined,
+                        ambient: vp.audioNotes.ambient || undefined,
+                        transition: vp.transition,
+                        cameraMovement: vp.cameraMovement,
+                        aesthetic: `${pr.prompt.match(/\[AESTHETIC\] (.+)/)?.[1] || ""}`.trim() || undefined,
+                    },
+                };
+                const videoJsonPath = join(sceneDir, `shot-${shotId}.video.json`);
+                await writeFile(videoJsonPath, JSON.stringify(videoJson, null, 2), "utf-8");
+            }
+            // Determine transition (if not last shot in scene)
+            const transition = i < shots.length - 1 ? (shot.transitionOut || "CUT") : undefined;
+            panels.push({
+                id: `S${sceneNumber}-P${shot.shotNumber}`,
+                sceneNumber,
+                panelNumber: shot.shotNumber,
+                totalPanelsInScene: shots.length,
+                prompt: pr.prompt,
+                imageBase64,
+                imageMimeType: "image/png",
+                shotType: shot.type,
+                cameraAngle: shot.angle,
+                cameraMovement: shot.movement,
+                transition,
+                characters: shot.characters,
+                dialogue: shot.dialogue ? {
+                    character: shot.focusCharacter || shot.characters[0] || "UNKNOWN",
+                    line: shot.dialogue,
+                } : undefined,
+                notes: shot.notes,
+                seed: usedSeed,
+                imagePath,
+                shot,
+                scene,
+                videoPrompt: vp?.videoPrompt,
+                videoDuration: vp?.duration,
+                videoCameraMovement: vp?.cameraMovement,
+                videoAudioNotes: vp?.audioNotes,
+                videoTransition: vp?.transition,
+                videoStartFrame: vp?.startFrame,
+                veoConfig: vp?.video ?? vp?.veo,
+            });
+        }
+        return panels;
+    }
+    // ---- Storyboard compilation ---------------------------------------------
+    /**
+     * Assemble all generated panels into a final Storyboard structure.
+     *
+     * @param title       - Screenplay title.
+     * @param scenePanels - Map of scene number to its generated panels.
+     * @param scenes      - All Scene objects in order.
+     * @param characters  - All locked character references.
+     * @param aesthetic   - The aesthetic profile used for generation.
+     * @returns A complete Storyboard object.
+     */
+    async compileStoryboard(title, scenePanels, scenes, characters, aesthetic) {
+        const storyboardScenes = [];
+        for (const scene of scenes) {
+            const panels = scenePanels.get(scene.number) ?? [];
+            storyboardScenes.push({ scene, panels });
+        }
+        return {
+            title,
+            scenes: storyboardScenes,
+            characters,
+            aesthetic,
+            generatedAt: new Date().toISOString(),
+        };
+    }
+    // ---- Persistence --------------------------------------------------------
+    /**
+     * Save the complete storyboard as a JSON file and ensure all images are
+     * written to the output directory.
+     *
+     * The JSON manifest omits the raw base64 image data from panels to keep
+     * the file manageable. Full base64 data is available on the in-memory
+     * Storyboard object for downstream consumers that need it.
+     *
+     * @param storyboard - The complete Storyboard to persist.
+     * @returns The absolute path to the saved JSON file.
+     */
+    async saveStoryboard(storyboard) {
+        await mkdir(this.outputDir, { recursive: true });
+        // Build a JSON-safe manifest that strips large base64 blobs.
+        const manifest = {
+            title: storyboard.title,
+            generatedAt: storyboard.generatedAt,
+            aesthetic: storyboard.aesthetic,
+            characters: storyboard.characters.map((c) => ({
+                name: c.name,
+                locked: c.locked,
+                seed: c.seed,
+                shortDescription: c.description.shortDescription,
+            })),
+            scenes: storyboard.scenes.map((s) => ({
+                scene: {
+                    number: s.scene.number,
+                    heading: s.scene.heading,
+                    location: s.scene.location,
+                    timeOfDay: s.scene.timeOfDay,
+                    characters: s.scene.characters,
+                    mood: s.scene.mood,
+                },
+                panels: s.panels.map((p) => ({
+                    id: p.id,
+                    sceneNumber: p.sceneNumber,
+                    panelNumber: p.panelNumber,
+                    totalPanelsInScene: p.totalPanelsInScene,
+                    imagePath: p.imagePath,
+                    prompt: p.prompt,
+                    seed: p.seed,
+                    shotType: p.shotType,
+                    cameraAngle: p.cameraAngle,
+                    cameraMovement: p.cameraMovement,
+                    characters: p.characters,
+                    dialogue: p.dialogue,
+                    notes: p.notes,
+                    transition: p.transition,
+                    videoPrompt: p.videoPrompt,
+                    videoDuration: p.videoDuration,
+                    videoCameraMovement: p.videoCameraMovement,
+                    videoAudioNotes: p.videoAudioNotes,
+                    videoTransition: p.videoTransition,
+                    shot: p.shot ? {
+                        shotNumber: p.shot.shotNumber,
+                        type: p.shot.type,
+                        angle: p.shot.angle,
+                        movement: p.shot.movement,
+                        lens: p.shot.lens,
+                        characters: p.shot.characters,
+                        focusCharacter: p.shot.focusCharacter,
+                        action: p.shot.action,
+                        dialogue: p.shot.dialogue,
+                        transitionIn: p.shot.transitionIn,
+                        transitionOut: p.shot.transitionOut,
+                        notes: p.shot.notes,
+                    } : undefined,
+                })),
+            })),
+        };
+        const jsonPath = join(this.outputDir, "storyboard.json");
+        await writeFile(jsonPath, JSON.stringify(manifest, null, 2), "utf-8");
+        return jsonPath;
+    }
+    // ---- Private: Venice API wrappers ---------------------------------------
+    /**
+     * Generate an image using the standard (no-reference) endpoint.
+     */
+    async generateStandard(client, pr, model = NO_FACE_MODEL) {
+        const raw = await client.post("/api/v1/image/generate", {
+            model,
+            prompt: pr.prompt,
+            negative_prompt: pr.negativePrompt,
+            resolution: DEFAULT_RESOLUTION,
+            aspect_ratio: DEFAULT_ASPECT_RATIO,
+            steps: DEFAULT_STEPS,
+            cfg_scale: DEFAULT_CFG_SCALE,
+            seed: pr.seed,
+            hide_watermark: true,
+            safe_mode: false,
+        });
+        // Venice returns { images: ["base64string"] } or { images: [{ b64_json }] }.
+        const rawImages = raw.images ?? [];
+        if (rawImages.length === 0) {
+            throw new Error("Venice API returned no images.");
+        }
+        const first = rawImages[0];
+        const b64 = typeof first === "string" ? first : first.b64_json;
+        return { base64: b64, seed: undefined };
+    }
+    /**
+     * Generate an image using the reference-augmented endpoint.
+     *
+     * Constructs a multi-reference prompt following the Venice protocol:
+     * the main prompt text is augmented with `Image N:` annotations, and
+     * reference images are sent as separate base64 payloads keyed by slot.
+     */
+    async generateWithReferences(client, pr, model = FACE_MODEL) {
+        // nano-banana-pro does not accept reference image payloads (image_1, image_2, etc.).
+        // Character consistency relies on exhaustive text descriptions + seed anchoring.
+        const raw = await client.post("/api/v1/image/generate", {
+            model,
+            prompt: pr.prompt,
+            negative_prompt: pr.negativePrompt,
+            resolution: DEFAULT_RESOLUTION,
+            aspect_ratio: DEFAULT_ASPECT_RATIO,
+            steps: DEFAULT_STEPS,
+            cfg_scale: DEFAULT_CFG_SCALE,
+            seed: pr.seed,
+            hide_watermark: true,
+            safe_mode: false,
+        });
+        // Venice returns { images: ["base64string"] } or { images: [{ b64_json }] }.
+        const rawImages = raw.images ?? [];
+        if (rawImages.length === 0) {
+            throw new Error("Venice API returned no images for reference-augmented generation.");
+        }
+        const first = rawImages[0];
+        const b64 = typeof first === "string" ? first : first.b64_json;
+        return {
+            base64: b64,
+            seed: undefined,
+        };
+    }
+}
+//# sourceMappingURL=assembler.js.map

package/dist/storyboard/assembler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembler.js","sourceRoot":"","sources":["../../src/storyboard/assembler.ts"],"names":[],"mappings":"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"}

package/dist/storyboard/prompt-builder.d.ts

@@ -0,0 +1,113 @@
+import type { Shot } from "./shot-planner.js";
+import type { Scene } from "../parsers/scene-extractor.js";
+import type { CharacterDescription } from "../characters/describer.js";
+import type { CharacterLock } from "../characters/reference-manager.js";
+export interface AestheticProfile {
+    /** Overall visual style, e.g. "Cinematic photography". */
+    style: string;
+    /** Color palette, e.g. "warm amber palette". */
+    palette: string;
+    /** Lighting approach, e.g. "natural lighting with film grain". */
+    lighting: string;
+    /** Lens rendering traits, e.g. "anamorphic lens characteristics". */
+    lensCharacteristics: string;
+    /** Emulated film stock, e.g. "35mm Kodak Vision3 500T". */
+    filmStock: string;
+}
+export interface PromptResult {
+    /** The assembled text prompt ready for the generation API. */
+    prompt: string;
+    /** Reference images to attach to the generation request. */
+    referenceImages: {
+        base64: string;
+        role: string;
+    }[];
+    /** Negative prompt describing what to exclude. */
+    negativePrompt: string;
+    /** Reproducibility seed (from the first character lock that has one). */
+    seed?: number;
+    /** Paired video generation prompt (populated by buildVideoPrompt). */
+    videoPrompt?: VideoPromptResult;
+}
+/** Audio cue metadata for a video clip. */
+export interface AudioNotes {
+    dialogue?: string;
+    sfx?: string;
+    ambient?: string;
+}
+/** Video API-ready configuration block. */
+export interface VideoConfig {
+    model: string;
+    prompt: string;
+    duration: string;
+    audio: boolean;
+}
+/** @deprecated Use VideoConfig instead. Kept for backward compatibility. */
+export type VeoConfig = VideoConfig & {
+    negativePrompt?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    durationSeconds?: string;
+    generateAudio?: boolean;
+    seed?: number;
+};
+/** Result of buildVideoPrompt() -- describes motion over time for a shot. */
+export interface VideoPromptResult {
+    /** The text prompt for a video generation model. */
+    videoPrompt: string;
+    /** Suggested clip duration in seconds. */
+    duration: number;
+    /** Specific camera motion instruction (e.g. "dolly-in, slow"). */
+    cameraMovement: string;
+    /** Description tying this clip to the image panel (first-frame reference). */
+    startFrame: string;
+    /** Audio cue metadata. */
+    audioNotes: AudioNotes;
+    /** Transition to the next clip. */
+    transition: string;
+    /** Video API-ready configuration block. */
+    video: VideoConfig;
+    /** @deprecated Use `video` instead. */
+    veo?: VeoConfig;
+}
+/**
+ * Build a structured image-generation prompt from a shot, its parent scene,
+ * an aesthetic profile, and character data.
+ *
+ * The prompt follows a structured template with tagged sections so the
+ * image model can attend to each aspect independently:
+ *
+ * ```
+ * [AESTHETIC] ...
+ * [SHOT] ...
+ * [SETTING] ...
+ * [CHARACTERS] ...
+ * [ACTION] ...
+ * [MOOD] ...
+ * [LIGHTING] ...
+ * ```
+ *
+ * Reference images are collected from character locks (front-facing angles)
+ * and returned alongside the prompt for multi-reference generation.
+ */
+export declare function buildPrompt(shot: Shot, scene: Scene, aesthetic: AestheticProfile, characterDescriptions: Map<string, CharacterDescription>, characterLocks: Map<string, CharacterLock>): PromptResult;
+/**
+ * Build a video-generation prompt from a shot, its parent scene, and
+ * aesthetic data.
+ *
+ * The prompt is plain descriptive prose kept under ~150 words: camera
+ * movement, subject + action, setting, style, and audio cues. Only the
+ * aesthetic register relevant to the current scene is included.
+ *
+ * Directing principle (see .claude/agents/prompt-engineer.md and the README
+ * "Directing layer"): the prose should DIRECT the shot -- one intention
+ * expressed through camera/light/blocking/performance/sound -- rather than
+ * stack "cinematic" adjectives. Camera, angle, and movement come from the
+ * shot's authored intention, not from a generic "make it cinematic" default.
+ *
+ * The returned `video` block is API-ready for any supported video model.
+ * The model field is a default -- the generation script chooses the actual
+ * model at runtime.
+ */
+export declare function buildVideoPrompt(shot: Shot, scene: Scene, aesthetic: AestheticProfile): VideoPromptResult;
+//# sourceMappingURL=prompt-builder.d.ts.map

package/dist/storyboard/prompt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../../src/storyboard/prompt-builder.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAIxE,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IAEd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAEhB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IAEjB,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,CAAC;IAE5B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,eAAe,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAEpD,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IAEvB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;IAEvB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IAEnB,0BAA0B;IAC1B,UAAU,EAAE,UAAU,CAAC;IAEvB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,KAAK,EAAE,WAAW,CAAC;IAEnB,uCAAuC;IACvC,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AA8MD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,gBAAgB,EAC3B,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,EACxD,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACzC,YAAY,CAmGd;AAwOD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,gBAAgB,GAC1B,iBAAiB,CAqFnB"}