@contractspec/lib.video-gen 1.42.0

package/dist/generators/scene-planner.js

@@ -0,0 +1,200 @@
+// @bun
+var __require = import.meta.require;
+
+// src/design/layouts.ts
+import { VIDEO_FORMATS } from "@contractspec/lib.contracts-integrations/integrations/providers/video";
+var DEFAULT_FPS = 30;
+var videoSafeZone = {
+  horizontal: 120,
+  vertical: 80,
+  contentWidth: 1680,
+  contentHeight: 920
+};
+function scaleSafeZone(format) {
+  const scaleX = format.width / 1920;
+  const scaleY = format.height / 1080;
+  return {
+    horizontal: Math.round(videoSafeZone.horizontal * scaleX),
+    vertical: Math.round(videoSafeZone.vertical * scaleY),
+    contentWidth: Math.round(videoSafeZone.contentWidth * scaleX),
+    contentHeight: Math.round(videoSafeZone.contentHeight * scaleY)
+  };
+}
+var videoPositions = {
+  center: { x: 960, y: 540 },
+  topLeft: { x: 120, y: 80 },
+  topRight: { x: 1800, y: 80 },
+  bottomLeft: { x: 120, y: 1000 },
+  bottomRight: { x: 1800, y: 1000 },
+  bottomCenter: { x: 960, y: 960 }
+};
+function getAllFormatVariants() {
+  return [
+    VIDEO_FORMATS.landscape,
+    VIDEO_FORMATS.square,
+    VIDEO_FORMATS.portrait
+  ];
+}
+
+// src/generators/scene-planner.ts
+class ScenePlanner {
+  llm;
+  model;
+  temperature;
+  fps;
+  constructor(options) {
+    this.llm = options?.llm;
+    this.model = options?.model;
+    this.temperature = options?.temperature ?? 0.3;
+    this.fps = options?.fps ?? DEFAULT_FPS;
+  }
+  async plan(brief) {
+    if (this.llm) {
+      return this.planWithLlm(brief);
+    }
+    return this.planDeterministic(brief);
+  }
+  planDeterministic(brief) {
+    const { content } = brief;
+    const scenes = [];
+    const fps = this.fps;
+    scenes.push({
+      compositionId: "SocialClip",
+      props: {
+        hook: content.title,
+        message: content.summary,
+        points: content.solutions.slice(0, 3),
+        cta: content.callToAction ?? "Learn more"
+      },
+      durationInFrames: 3 * fps,
+      narrationText: `${content.title}. ${content.summary}`
+    });
+    if (content.problems.length > 0) {
+      scenes.push({
+        compositionId: "SocialClip",
+        props: {
+          hook: "The Problem",
+          message: content.problems[0] ?? "",
+          points: content.problems.slice(1, 4)
+        },
+        durationInFrames: 4 * fps,
+        narrationText: `The problem: ${content.problems.join(". ")}`
+      });
+    }
+    if (content.solutions.length > 0) {
+      scenes.push({
+        compositionId: "SocialClip",
+        props: {
+          hook: "The Solution",
+          message: content.solutions[0] ?? "",
+          points: content.solutions.slice(1, 4)
+        },
+        durationInFrames: 5 * fps,
+        narrationText: `The solution: ${content.solutions.join(". ")}`
+      });
+    }
+    if (content.metrics && content.metrics.length > 0) {
+      scenes.push({
+        compositionId: "SocialClip",
+        props: {
+          hook: "Results",
+          message: content.metrics[0] ?? "",
+          points: content.metrics.slice(1, 3)
+        },
+        durationInFrames: 3 * fps,
+        narrationText: content.metrics.join(". ")
+      });
+    }
+    if (content.callToAction) {
+      scenes.push({
+        compositionId: "SocialClip",
+        props: {
+          hook: content.callToAction,
+          message: "",
+          cta: content.callToAction
+        },
+        durationInFrames: 2 * fps,
+        narrationText: content.callToAction
+      });
+    }
+    if (brief.targetDurationSeconds) {
+      const targetFrames = brief.targetDurationSeconds * fps;
+      const currentFrames = scenes.reduce((sum, s) => sum + s.durationInFrames, 0);
+      const ratio = targetFrames / currentFrames;
+      for (const scene of scenes) {
+        scene.durationInFrames = Math.round(scene.durationInFrames * ratio);
+      }
+    }
+    const totalDuration = scenes.reduce((sum, s) => sum + s.durationInFrames, 0);
+    const narrationScript = scenes.filter((s) => s.narrationText).map((s) => s.narrationText).join(" ");
+    return {
+      scenes,
+      estimatedDurationSeconds: totalDuration / fps,
+      narrationScript
+    };
+  }
+  async planWithLlm(brief) {
+    const messages = [
+      {
+        role: "system",
+        content: [
+          {
+            type: "text",
+            text: `You are a video scene planner for ContractSpec marketing/documentation videos.
+Given a content brief, break it into video scenes.
+
+Each scene must have:
+- compositionId: one of "ApiOverview", "SocialClip", "TerminalDemo"
+- props: the input props for that composition (see type definitions)
+- durationInFrames: duration at ${this.fps}fps
+- narrationText: what the narrator says during this scene
+
+Return a JSON object with shape:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Keep the total duration around ${brief.targetDurationSeconds ?? 30} seconds.
+Prioritize clarity and pacing. Each scene should communicate one idea.`
+          }
+        ]
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(brief.content)
+          }
+        ]
+      }
+    ];
+    if (!this.llm) {
+      return this.planDeterministic(brief);
+    }
+    try {
+      const response = await this.llm.chat(messages, {
+        model: this.model,
+        temperature: this.temperature,
+        responseFormat: "json"
+      });
+      const text = response.message.content.find((p) => p.type === "text");
+      if (!text || text.type !== "text") {
+        return this.planDeterministic(brief);
+      }
+      const parsed = JSON.parse(text.text);
+      const totalDuration = parsed.scenes.reduce((sum, s) => sum + s.durationInFrames, 0);
+      return {
+        scenes: parsed.scenes,
+        estimatedDurationSeconds: totalDuration / this.fps,
+        narrationScript: parsed.narrationScript
+      };
+    } catch {
+      return this.planDeterministic(brief);
+    }
+  }
+}
+export {
+  ScenePlanner
+};

package/dist/generators/script-generator.d.ts

@@ -0,0 +1,49 @@
+import type { LLMProvider } from '@contractspec/lib.contracts-integrations/integrations/providers/llm';
+import type { ContentBrief } from '@contractspec/lib.content-gen/types';
+import type { NarrationConfig } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+export interface NarrationScript {
+    /** Full narration text */
+    fullText: string;
+    /** Per-scene narration segments */
+    segments: NarrationSegment[];
+    /** Estimated speaking duration in seconds (at ~150 words/min) */
+    estimatedDurationSeconds: number;
+    /** Style used */
+    style: NarrationConfig['style'];
+}
+export interface NarrationSegment {
+    /** Scene identifier this segment maps to */
+    sceneId: string;
+    /** Narration text for this segment */
+    text: string;
+    /** Estimated duration in seconds */
+    estimatedDurationSeconds: number;
+}
+export interface ScriptGeneratorOptions {
+    llm?: LLMProvider;
+    model?: string;
+    temperature?: number;
+}
+export declare class ScriptGenerator {
+    private readonly llm?;
+    private readonly model?;
+    private readonly temperature;
+    constructor(options?: ScriptGeneratorOptions);
+    /**
+     * Generate a narration script from a content brief.
+     */
+    generate(brief: ContentBrief, config?: NarrationConfig): Promise<NarrationScript>;
+    private generateDeterministic;
+    private generateWithLlm;
+    /**
+     * Adjust text tone based on style.
+     * In the deterministic path, this is a simple pass-through.
+     * The LLM path handles style natively.
+     */
+    private formatForStyle;
+    /**
+     * Estimate speaking duration based on word count.
+     * Average speaking rate: ~150 words per minute.
+     */
+    private estimateDuration;
+}

package/dist/generators/script-generator.js

@@ -0,0 +1,142 @@
+// @bun
+var __require = import.meta.require;
+
+// src/generators/script-generator.ts
+class ScriptGenerator {
+  llm;
+  model;
+  temperature;
+  constructor(options) {
+    this.llm = options?.llm;
+    this.model = options?.model;
+    this.temperature = options?.temperature ?? 0.5;
+  }
+  async generate(brief, config) {
+    const style = config?.style ?? "professional";
+    if (this.llm) {
+      return this.generateWithLlm(brief, style);
+    }
+    return this.generateDeterministic(brief, style);
+  }
+  generateDeterministic(brief, style) {
+    const segments = [];
+    const intro = this.formatForStyle(`${brief.title}. ${brief.summary}`, style);
+    segments.push({
+      sceneId: "intro",
+      text: intro,
+      estimatedDurationSeconds: this.estimateDuration(intro)
+    });
+    if (brief.problems.length > 0) {
+      const problemText = this.formatForStyle(`The challenge: ${brief.problems.join(". ")}`, style);
+      segments.push({
+        sceneId: "problems",
+        text: problemText,
+        estimatedDurationSeconds: this.estimateDuration(problemText)
+      });
+    }
+    if (brief.solutions.length > 0) {
+      const solutionText = this.formatForStyle(`The solution: ${brief.solutions.join(". ")}`, style);
+      segments.push({
+        sceneId: "solutions",
+        text: solutionText,
+        estimatedDurationSeconds: this.estimateDuration(solutionText)
+      });
+    }
+    if (brief.metrics && brief.metrics.length > 0) {
+      const metricsText = this.formatForStyle(`The results: ${brief.metrics.join(". ")}`, style);
+      segments.push({
+        sceneId: "metrics",
+        text: metricsText,
+        estimatedDurationSeconds: this.estimateDuration(metricsText)
+      });
+    }
+    if (brief.callToAction) {
+      const ctaText = this.formatForStyle(brief.callToAction, style);
+      segments.push({
+        sceneId: "cta",
+        text: ctaText,
+        estimatedDurationSeconds: this.estimateDuration(ctaText)
+      });
+    }
+    const fullText = segments.map((s) => s.text).join(" ");
+    const totalDuration = segments.reduce((sum, s) => sum + s.estimatedDurationSeconds, 0);
+    return {
+      fullText,
+      segments,
+      estimatedDurationSeconds: totalDuration,
+      style
+    };
+  }
+  async generateWithLlm(brief, style) {
+    const styleGuide = {
+      professional: "Use a clear, authoritative, professional tone. Be concise and direct.",
+      casual: "Use a friendly, conversational tone. Be approachable and relatable.",
+      technical: "Use precise technical language. Be detailed and accurate."
+    };
+    const styleKey = style ?? "professional";
+    const messages = [
+      {
+        role: "system",
+        content: [
+          {
+            type: "text",
+            text: `You are a video narration script writer.
+Write a narration script for a short video (30-60 seconds).
+${styleGuide[styleKey]}
+
+Return JSON with shape:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Scene IDs should be: "intro", "problems", "solutions", "metrics", "cta".
+Only include segments that are relevant to the brief content.`
+          }
+        ]
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: JSON.stringify(brief) }]
+      }
+    ];
+    if (!this.llm) {
+      return this.generateDeterministic(brief, style);
+    }
+    try {
+      const response = await this.llm.chat(messages, {
+        model: this.model,
+        temperature: this.temperature,
+        responseFormat: "json"
+      });
+      const text = response.message.content.find((p) => p.type === "text");
+      if (!text || text.type !== "text") {
+        return this.generateDeterministic(brief, style);
+      }
+      const parsed = JSON.parse(text.text);
+      const segments = parsed.segments.map((s) => ({
+        sceneId: s.sceneId,
+        text: s.text,
+        estimatedDurationSeconds: this.estimateDuration(s.text)
+      }));
+      return {
+        fullText: parsed.fullText,
+        segments,
+        estimatedDurationSeconds: segments.reduce((sum, s) => sum + s.estimatedDurationSeconds, 0),
+        style
+      };
+    } catch {
+      return this.generateDeterministic(brief, style);
+    }
+  }
+  formatForStyle(text, _style) {
+    return text;
+  }
+  estimateDuration(text) {
+    const wordCount = text.split(/\s+/).length;
+    return Math.ceil(wordCount / 150 * 60);
+  }
+}
+export {
+  ScriptGenerator
+};

package/dist/generators/video-generator.d.ts

@@ -0,0 +1,20 @@
+import type { VideoProject } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import type { VideoBrief, VideoGeneratorOptions } from '../types';
+export declare class VideoGenerator {
+    private readonly scenePlanner;
+    private readonly scriptGenerator;
+    private readonly voice?;
+    private readonly defaultVoiceId?;
+    private readonly fps;
+    constructor(options?: VideoGeneratorOptions);
+    /**
+     * Generate a complete video project from a brief.
+     *
+     * Pipeline:
+     * 1. Plan scenes from the content brief
+     * 2. Generate narration script
+     * 3. (Optional) Synthesize voice audio via VoiceProvider
+     * 4. Assemble into a VideoProject
+     */
+    generate(brief: VideoBrief): Promise<VideoProject>;
+}