@contractspec/lib.video-gen 1.42.0

package/dist/docs/video-gen.docblock.js

@@ -0,0 +1,142 @@
+// @bun
+// src/docs/video-gen.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var videoGenDocBlocks = [
+  {
+    id: "docs.video-gen.overview",
+    title: "Video Generation Library",
+    summary: "Programmatic video generation with Remotion -- from content brief to rendered MP4 in a single pipeline.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/video-gen/overview",
+    tags: ["video", "remotion", "generation", "content-pipeline"],
+    owners: ["@contractspec/lib.video-gen"],
+    body: `# Video Generation Library
+
+\`@contractspec/lib.video-gen\` provides **programmatic video generation** using [Remotion](https://remotion.dev). It follows the same generator pattern as \`@contractspec/lib.content-gen\` and consumes provider contracts from \`@contractspec/lib.contracts-integrations/integrations/providers/video\`.
+
+## Architecture
+
+The library is organized into five layers, each buildable and testable independently:
+
+\`\`\`
+Content Brief
+    |
+    v
+Generators -----> ScenePlanner (brief -> scenes)
+    |              ScriptGenerator (brief -> narration)
+    |              VideoGenerator (orchestrator)
+    v
+Compositions ---> Primitives (AnimatedText, CodeBlock, Terminal, ...)
+    |              Full Compositions (ApiOverview, SocialClip, TerminalDemo)
+    v
+Design ---------> Tokens, Motion, Typography, Layouts
+    |
+    v
+Renderers ------> LocalRenderer (@remotion/renderer)
+                   DemoPlayer (@remotion/player, web embedding)
+\`\`\`
+
+### Layer Responsibilities
+
+| Layer | Import Path | Purpose |
+|-------|-------------|---------|
+| **Types** | \`@contractspec/lib.video-gen/types\` | VideoBrief, ScenePlan, GeneratedVideo, re-exported contract types |
+| **Design** | \`@contractspec/lib.video-gen/design\` | Video-optimized tokens, motion primitives, typography, layouts |
+| **Compositions** | \`@contractspec/lib.video-gen/compositions\` | Remotion components (primitives + full compositions) |
+| **Generators** | \`@contractspec/lib.video-gen/generators\` | VideoGenerator, ScenePlanner, ScriptGenerator |
+| **Renderers** | \`@contractspec/lib.video-gen/renderers\` | LocalRenderer, render config, quality presets |
+| **Player** | \`@contractspec/lib.video-gen/player\` | Embeddable DemoPlayer for web apps |
+| **Remotion** | \`@contractspec/lib.video-gen/remotion\` | Remotion Studio entry point (registerRoot) |
+
+## Getting Started
+
+### 1. Generate a video project from a content brief
+
+\`\`\`ts
+import { VideoGenerator } from "@contractspec/lib.video-gen/generators";
+import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/types";
+import type { VideoBrief } from "@contractspec/lib.video-gen/types";
+
+const generator = new VideoGenerator({ fps: 30 });
+
+const brief: VideoBrief = {
+  content: {
+    title: "Ship APIs 10x Faster",
+    summary: "ContractSpec generates everything from a single spec.",
+    problems: ["Manual API maintenance", "Inconsistent surfaces"],
+    solutions: ["One spec, every surface", "Safe regeneration"],
+    callToAction: "Try ContractSpec",
+  },
+  format: VIDEO_FORMATS.landscape,
+  targetDurationSeconds: 30,
+};
+
+const project = await generator.generate(brief);
+\`\`\`
+
+### 2. Render to MP4
+
+\`\`\`ts
+import { LocalRenderer } from "@contractspec/lib.video-gen/renderers/local";
+
+const renderer = new LocalRenderer({
+  entryPoint: "./src/remotion/index.ts",
+});
+
+const result = await renderer.render(project, {
+  outputPath: "out/video.mp4",
+});
+\`\`\`
+
+### 3. Embed in a web app
+
+\`\`\`tsx
+import { DemoPlayer } from "@contractspec/lib.video-gen/player";
+
+<DemoPlayer
+  compositionId="ApiOverview"
+  inputProps={{ specName: "CreateUser", specCode: "..." }}
+  controls
+  autoPlay
+  loop
+/>
+\`\`\`
+
+## Contract Bridge
+
+The library consumes provider contracts defined in \`@contractspec/lib.contracts-integrations\`:
+
+| Contract | Purpose |
+|----------|---------|
+| \`VideoProvider\` | Renderer abstraction (local, Lambda, Cloud Run) |
+| \`VideoProject\` | Scene graph with format, fps, audio tracks |
+| \`RenderConfig\` / \`RenderResult\` | Codec, quality, output path, dimensions |
+| \`CompositionRegistry\` | Metadata for registered Remotion compositions |
+| \`VideoFormat\` | Landscape / portrait / square / custom dimensions |
+
+Types are re-exported from the main entry for convenience:
+
+\`\`\`ts
+import type { VideoProject, RenderConfig } from "@contractspec/lib.video-gen";
+\`\`\`
+
+## Deterministic by Default
+
+All generators support two modes:
+
+- **Without LLM**: Fully deterministic, template-based output. Same brief always produces the same video project.
+- **With LLM**: Richer scene planning and narration scripts via an optional \`LLMProvider\`. Falls back to deterministic on any failure.
+
+This matches the content-gen pattern: \`constructor({ llm? })\` -> \`generate(brief)\`.
+
+## Guardrails
+
+- Compositions must be **deterministic**: same props = same visual output.
+- Design tokens bridge from \`@contractspec/lib.design-system\` -- do not duplicate brand values.
+- \`LocalRenderer\` requires Node.js (\`@remotion/renderer\` is not Bun-compatible).
+- The \`remotion\` entry point is a side-effect module (calls \`registerRoot\`) -- import it only from Remotion Studio or render scripts.
+`
+  }
+];
+registerDocBlocks(videoGenDocBlocks);

package/dist/generators/index.d.ts

@@ -0,0 +1,5 @@
+export { VideoGenerator } from './video-generator';
+export { ScenePlanner } from './scene-planner';
+export type { ScenePlannerOptions } from './scene-planner';
+export { ScriptGenerator } from './script-generator';
+export type { ScriptGeneratorOptions, NarrationScript, NarrationSegment, } from './script-generator';

package/dist/generators/index.js

@@ -0,0 +1,411 @@
+// @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);
+    }
+  }
+}
+
+// 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);
+  }
+}
+
+// src/generators/video-generator.ts
+import { VIDEO_FORMATS as VIDEO_FORMATS2 } from "@contractspec/lib.contracts-integrations/integrations/providers/video";
+class VideoGenerator {
+  scenePlanner;
+  scriptGenerator;
+  voice;
+  defaultVoiceId;
+  fps;
+  constructor(options) {
+    this.fps = options?.fps ?? DEFAULT_FPS;
+    this.voice = options?.voice;
+    this.defaultVoiceId = options?.defaultVoiceId;
+    this.scenePlanner = new ScenePlanner({
+      llm: options?.llm,
+      model: options?.model,
+      temperature: options?.temperature,
+      fps: this.fps
+    });
+    this.scriptGenerator = new ScriptGenerator({
+      llm: options?.llm,
+      model: options?.model,
+      temperature: options?.temperature
+    });
+  }
+  async generate(brief) {
+    const scenePlan = await this.scenePlanner.plan(brief);
+    let narrationAudio;
+    if (brief.narration?.enabled && this.voice) {
+      const script = await this.scriptGenerator.generate(brief.content, brief.narration);
+      const voiceId = brief.narration.voiceId ?? this.defaultVoiceId;
+      if (voiceId && script.fullText) {
+        try {
+          const result = await this.voice.synthesize({
+            text: script.fullText,
+            voiceId,
+            format: "mp3"
+          });
+          narrationAudio = {
+            data: result.audio,
+            format: "mp3",
+            durationSeconds: result.durationSeconds ?? script.estimatedDurationSeconds,
+            volume: 1
+          };
+        } catch {}
+      }
+    }
+    const format = brief.format ?? VIDEO_FORMATS2.landscape;
+    const scenes = scenePlan.scenes.map((planned, i) => ({
+      id: `scene-${i}`,
+      compositionId: planned.compositionId,
+      props: planned.props,
+      durationInFrames: planned.durationInFrames,
+      narrationText: planned.narrationText
+    }));
+    const totalDurationInFrames = scenes.reduce((sum, s) => sum + s.durationInFrames, 0);
+    const project = {
+      id: generateProjectId(),
+      scenes,
+      totalDurationInFrames,
+      fps: this.fps,
+      format,
+      audio: narrationAudio ? { narration: narrationAudio } : undefined
+    };
+    return project;
+  }
+}
+function generateProjectId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `vp_${timestamp}_${random}`;
+}
+export {
+  VideoGenerator,
+  ScriptGenerator,
+  ScenePlanner
+};

package/dist/generators/scene-planner.d.ts

@@ -0,0 +1,23 @@
+import type { LLMProvider } from '@contractspec/lib.contracts-integrations/integrations/providers/llm';
+import type { ScenePlan, VideoBrief } from '../types';
+export interface ScenePlannerOptions {
+    llm?: LLMProvider;
+    model?: string;
+    temperature?: number;
+    fps?: number;
+}
+export declare class ScenePlanner {
+    private readonly llm?;
+    private readonly model?;
+    private readonly temperature;
+    private readonly fps;
+    constructor(options?: ScenePlannerOptions);
+    /**
+     * Plan scenes for a video brief.
+     * With LLM: produces richer, context-aware scene breakdowns.
+     * Without LLM: deterministic template-based planning.
+     */
+    plan(brief: VideoBrief): Promise<ScenePlan>;
+    private planDeterministic;
+    private planWithLlm;
+}