@contractspec/lib.video-gen 1.44.0 → 1.46.0

package/dist/generators/script-generator.js

@@ -1,15 +1,526 @@
 // @bun
 var __require = import.meta.require;
 
+// src/i18n/catalogs/en.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var enMessages = defineTranslation({
+  meta: {
+    key: "video-gen.messages",
+    version: "1.0.0",
+    domain: "video-gen",
+    description: "All user-facing, LLM-facing, and developer-facing strings for the video-gen package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "en",
+  fallback: "en",
+  messages: {
+    "prompt.script.system": {
+      value: `You are a video narration script writer.
+Write a narration script for a short video (30-60 seconds).
+{styleGuide}
+
+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.`,
+      description: "Script generator LLM system prompt",
+      placeholders: [{ name: "styleGuide", type: "string" }]
+    },
+    "prompt.scenePlanner.system": {
+      value: `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 {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 {targetSeconds} seconds.
+Prioritize clarity and pacing. Each scene should communicate one idea.`,
+      description: "Scene planner LLM system prompt",
+      placeholders: [
+        { name: "fps", type: "number" },
+        { name: "targetSeconds", type: "number" }
+      ]
+    },
+    "prompt.style.professional": {
+      value: "Use a clear, authoritative, professional tone. Be concise and direct.",
+      description: "Style guide for professional narration"
+    },
+    "prompt.style.casual": {
+      value: "Use a friendly, conversational tone. Be approachable and relatable.",
+      description: "Style guide for casual narration"
+    },
+    "prompt.style.technical": {
+      value: "Use precise technical language. Be detailed and accurate.",
+      description: "Style guide for technical narration"
+    },
+    "script.segment.challenge": {
+      value: "The challenge: {content}",
+      description: "Narration segment prefix for problems",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "script.segment.solution": {
+      value: "The solution: {content}",
+      description: "Narration segment prefix for solutions",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "script.segment.results": {
+      value: "The results: {content}",
+      description: "Narration segment prefix for metrics",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.cta.default": {
+      value: "Learn more",
+      description: "Default call-to-action text for scenes"
+    },
+    "scene.hook.problem": {
+      value: "The Problem",
+      description: "Scene hook label for problem statement"
+    },
+    "scene.narration.problem": {
+      value: "The problem: {content}",
+      description: "Scene narration for problem statement",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.hook.solution": {
+      value: "The Solution",
+      description: "Scene hook label for solution"
+    },
+    "scene.narration.solution": {
+      value: "The solution: {content}",
+      description: "Scene narration for solution",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.hook.results": {
+      value: "Results",
+      description: "Scene hook label for results/metrics"
+    },
+    "composition.apiOverview.generates": {
+      value: "Generates:",
+      description: "ApiOverview heading for generated outputs"
+    },
+    "composition.apiOverview.tagline": {
+      value: "One spec. Every surface.",
+      description: "ApiOverview default tagline"
+    },
+    "composition.apiOverview.output.rest": {
+      value: "REST Endpoint",
+      description: "Generated output label: REST"
+    },
+    "composition.apiOverview.output.graphql": {
+      value: "GraphQL Mutation",
+      description: "Generated output label: GraphQL"
+    },
+    "composition.apiOverview.output.prisma": {
+      value: "Prisma Model",
+      description: "Generated output label: Prisma"
+    },
+    "composition.apiOverview.output.typescript": {
+      value: "TypeScript SDK",
+      description: "Generated output label: TypeScript SDK"
+    },
+    "composition.apiOverview.output.mcp": {
+      value: "MCP Tool",
+      description: "Generated output label: MCP Tool"
+    },
+    "composition.apiOverview.output.openapi": {
+      value: "OpenAPI Spec",
+      description: "Generated output label: OpenAPI"
+    },
+    "composition.socialClip.cta": {
+      value: "Learn more",
+      description: "SocialClip default CTA"
+    },
+    "composition.terminal.title": {
+      value: "Terminal",
+      description: "TerminalDemo default window title"
+    }
+  }
+});
+
+// src/i18n/catalogs/fr.ts
+import { defineTranslation as defineTranslation2 } from "@contractspec/lib.contracts-spec/translations";
+var frMessages = defineTranslation2({
+  meta: {
+    key: "video-gen.messages",
+    version: "1.0.0",
+    domain: "video-gen",
+    description: "French translations for the video-gen package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "fr",
+  fallback: "en",
+  messages: {
+    "prompt.script.system": {
+      value: `Vous \xEAtes un r\xE9dacteur de scripts de narration vid\xE9o.
+\xC9crivez un script de narration pour une courte vid\xE9o (30-60 secondes).
+{styleGuide}
+
+Retournez du JSON avec la forme\xA0:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Les identifiants de sc\xE8ne doivent \xEAtre\xA0: "intro", "problems", "solutions", "metrics", "cta".
+N'incluez que les segments pertinents au brief.`,
+      description: "Script generator LLM system prompt",
+      placeholders: [{ name: "styleGuide", type: "string" }]
+    },
+    "prompt.scenePlanner.system": {
+      value: `Vous \xEAtes un planificateur de sc\xE8nes vid\xE9o pour les vid\xE9os marketing/documentation de ContractSpec.
+\xC0 partir d'un brief, d\xE9composez-le en sc\xE8nes vid\xE9o.
+
+Chaque sc\xE8ne doit avoir\xA0:
+- compositionId\xA0: un parmi "ApiOverview", "SocialClip", "TerminalDemo"
+- props\xA0: les propri\xE9t\xE9s d'entr\xE9e de cette composition
+- durationInFrames\xA0: dur\xE9e \xE0 {fps}\xA0fps
+- narrationText\xA0: ce que le narrateur dit pendant cette sc\xE8ne
+
+Retournez un objet JSON avec la forme\xA0:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Gardez la dur\xE9e totale autour de {targetSeconds} secondes.
+Privil\xE9giez la clart\xE9 et le rythme. Chaque sc\xE8ne doit communiquer une id\xE9e.`,
+      description: "Scene planner LLM system prompt",
+      placeholders: [
+        { name: "fps", type: "number" },
+        { name: "targetSeconds", type: "number" }
+      ]
+    },
+    "prompt.style.professional": {
+      value: "Utilisez un ton clair, autoritaire et professionnel. Soyez concis et direct.",
+      description: "Style guide for professional narration"
+    },
+    "prompt.style.casual": {
+      value: "Utilisez un ton amical et conversationnel. Soyez accessible et proche.",
+      description: "Style guide for casual narration"
+    },
+    "prompt.style.technical": {
+      value: "Utilisez un langage technique pr\xE9cis. Soyez d\xE9taill\xE9 et exact.",
+      description: "Style guide for technical narration"
+    },
+    "script.segment.challenge": {
+      value: "Le d\xE9fi\xA0: {content}",
+      description: "Narration segment prefix for problems",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "script.segment.solution": {
+      value: "La solution\xA0: {content}",
+      description: "Narration segment prefix for solutions",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "script.segment.results": {
+      value: "Les r\xE9sultats\xA0: {content}",
+      description: "Narration segment prefix for metrics",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.cta.default": {
+      value: "En savoir plus",
+      description: "Default call-to-action text for scenes"
+    },
+    "scene.hook.problem": {
+      value: "Le probl\xE8me",
+      description: "Scene hook label for problem statement"
+    },
+    "scene.narration.problem": {
+      value: "Le probl\xE8me\xA0: {content}",
+      description: "Scene narration for problem statement",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.hook.solution": {
+      value: "La solution",
+      description: "Scene hook label for solution"
+    },
+    "scene.narration.solution": {
+      value: "La solution\xA0: {content}",
+      description: "Scene narration for solution",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.hook.results": {
+      value: "R\xE9sultats",
+      description: "Scene hook label for results/metrics"
+    },
+    "composition.apiOverview.generates": {
+      value: "G\xE9n\xE8re\xA0:",
+      description: "ApiOverview heading for generated outputs"
+    },
+    "composition.apiOverview.tagline": {
+      value: "Un spec. Toutes les surfaces.",
+      description: "ApiOverview default tagline"
+    },
+    "composition.apiOverview.output.rest": {
+      value: "Endpoint REST",
+      description: "Generated output label: REST"
+    },
+    "composition.apiOverview.output.graphql": {
+      value: "Mutation GraphQL",
+      description: "Generated output label: GraphQL"
+    },
+    "composition.apiOverview.output.prisma": {
+      value: "Mod\xE8le Prisma",
+      description: "Generated output label: Prisma"
+    },
+    "composition.apiOverview.output.typescript": {
+      value: "SDK TypeScript",
+      description: "Generated output label: TypeScript SDK"
+    },
+    "composition.apiOverview.output.mcp": {
+      value: "Outil MCP",
+      description: "Generated output label: MCP Tool"
+    },
+    "composition.apiOverview.output.openapi": {
+      value: "Spec OpenAPI",
+      description: "Generated output label: OpenAPI"
+    },
+    "composition.socialClip.cta": {
+      value: "En savoir plus",
+      description: "SocialClip default CTA"
+    },
+    "composition.terminal.title": {
+      value: "Terminal",
+      description: "TerminalDemo default window title"
+    }
+  }
+});
+
+// src/i18n/catalogs/es.ts
+import { defineTranslation as defineTranslation3 } from "@contractspec/lib.contracts-spec/translations";
+var esMessages = defineTranslation3({
+  meta: {
+    key: "video-gen.messages",
+    version: "1.0.0",
+    domain: "video-gen",
+    description: "Spanish translations for the video-gen package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "es",
+  fallback: "en",
+  messages: {
+    "prompt.script.system": {
+      value: `Eres un redactor de guiones de narraci\xF3n para v\xEDdeo.
+Escribe un gui\xF3n de narraci\xF3n para un v\xEDdeo corto (30-60 segundos).
+{styleGuide}
+
+Devuelve JSON con la forma:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Los identificadores de escena deben ser: "intro", "problems", "solutions", "metrics", "cta".
+Incluye solo los segmentos relevantes para el brief.`,
+      description: "Script generator LLM system prompt",
+      placeholders: [{ name: "styleGuide", type: "string" }]
+    },
+    "prompt.scenePlanner.system": {
+      value: `Eres un planificador de escenas de v\xEDdeo para v\xEDdeos de marketing/documentaci\xF3n de ContractSpec.
+Dado un brief de contenido, div\xEDdelo en escenas de v\xEDdeo.
+
+Cada escena debe tener:
+- compositionId: uno de "ApiOverview", "SocialClip", "TerminalDemo"
+- props: las propiedades de entrada de esa composici\xF3n
+- durationInFrames: duraci\xF3n a {fps} fps
+- narrationText: lo que dice el narrador durante esta escena
+
+Devuelve un objeto JSON con la forma:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Mant\xE9n la duraci\xF3n total alrededor de {targetSeconds} segundos.
+Prioriza la claridad y el ritmo. Cada escena debe comunicar una idea.`,
+      description: "Scene planner LLM system prompt",
+      placeholders: [
+        { name: "fps", type: "number" },
+        { name: "targetSeconds", type: "number" }
+      ]
+    },
+    "prompt.style.professional": {
+      value: "Usa un tono claro, autoritario y profesional. S\xE9 conciso y directo.",
+      description: "Style guide for professional narration"
+    },
+    "prompt.style.casual": {
+      value: "Usa un tono amigable y conversacional. S\xE9 accesible y cercano.",
+      description: "Style guide for casual narration"
+    },
+    "prompt.style.technical": {
+      value: "Usa un lenguaje t\xE9cnico preciso. S\xE9 detallado y exacto.",
+      description: "Style guide for technical narration"
+    },
+    "script.segment.challenge": {
+      value: "El desaf\xEDo: {content}",
+      description: "Narration segment prefix for problems",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "script.segment.solution": {
+      value: "La soluci\xF3n: {content}",
+      description: "Narration segment prefix for solutions",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "script.segment.results": {
+      value: "Los resultados: {content}",
+      description: "Narration segment prefix for metrics",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.cta.default": {
+      value: "M\xE1s informaci\xF3n",
+      description: "Default call-to-action text for scenes"
+    },
+    "scene.hook.problem": {
+      value: "El problema",
+      description: "Scene hook label for problem statement"
+    },
+    "scene.narration.problem": {
+      value: "El problema: {content}",
+      description: "Scene narration for problem statement",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.hook.solution": {
+      value: "La soluci\xF3n",
+      description: "Scene hook label for solution"
+    },
+    "scene.narration.solution": {
+      value: "La soluci\xF3n: {content}",
+      description: "Scene narration for solution",
+      placeholders: [{ name: "content", type: "string" }]
+    },
+    "scene.hook.results": {
+      value: "Resultados",
+      description: "Scene hook label for results/metrics"
+    },
+    "composition.apiOverview.generates": {
+      value: "Genera:",
+      description: "ApiOverview heading for generated outputs"
+    },
+    "composition.apiOverview.tagline": {
+      value: "Una spec. Todas las superficies.",
+      description: "ApiOverview default tagline"
+    },
+    "composition.apiOverview.output.rest": {
+      value: "Endpoint REST",
+      description: "Generated output label: REST"
+    },
+    "composition.apiOverview.output.graphql": {
+      value: "Mutaci\xF3n GraphQL",
+      description: "Generated output label: GraphQL"
+    },
+    "composition.apiOverview.output.prisma": {
+      value: "Modelo Prisma",
+      description: "Generated output label: Prisma"
+    },
+    "composition.apiOverview.output.typescript": {
+      value: "SDK TypeScript",
+      description: "Generated output label: TypeScript SDK"
+    },
+    "composition.apiOverview.output.mcp": {
+      value: "Herramienta MCP",
+      description: "Generated output label: MCP Tool"
+    },
+    "composition.apiOverview.output.openapi": {
+      value: "Spec OpenAPI",
+      description: "Generated output label: OpenAPI"
+    },
+    "composition.socialClip.cta": {
+      value: "M\xE1s informaci\xF3n",
+      description: "SocialClip default CTA"
+    },
+    "composition.terminal.title": {
+      value: "Terminal",
+      description: "TerminalDemo default window title"
+    }
+  }
+});
+
+// src/i18n/messages.ts
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory = createI18nFactory({
+  specKey: "video-gen.messages",
+  catalogs: [enMessages, frMessages, esMessages]
+});
+var createVideoGenI18n = factory.create;
+var getDefaultI18n = factory.getDefault;
+var resetI18nRegistry = factory.resetRegistry;
+
+// src/i18n/locale.ts
+import {
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  resolveLocale,
+  isSupportedLocale
+} from "@contractspec/lib.contracts-spec/translations";
+
+// src/i18n/keys.ts
+var PROMPT_KEYS = {
+  "prompt.script.system": "prompt.script.system",
+  "prompt.scenePlanner.system": "prompt.scenePlanner.system",
+  "prompt.style.professional": "prompt.style.professional",
+  "prompt.style.casual": "prompt.style.casual",
+  "prompt.style.technical": "prompt.style.technical"
+};
+var SCRIPT_KEYS = {
+  "script.segment.challenge": "script.segment.challenge",
+  "script.segment.solution": "script.segment.solution",
+  "script.segment.results": "script.segment.results"
+};
+var SCENE_KEYS = {
+  "scene.cta.default": "scene.cta.default",
+  "scene.hook.problem": "scene.hook.problem",
+  "scene.narration.problem": "scene.narration.problem",
+  "scene.hook.solution": "scene.hook.solution",
+  "scene.narration.solution": "scene.narration.solution",
+  "scene.hook.results": "scene.hook.results"
+};
+var COMPOSITION_KEYS = {
+  "composition.apiOverview.generates": "composition.apiOverview.generates",
+  "composition.apiOverview.tagline": "composition.apiOverview.tagline",
+  "composition.apiOverview.output.rest": "composition.apiOverview.output.rest",
+  "composition.apiOverview.output.graphql": "composition.apiOverview.output.graphql",
+  "composition.apiOverview.output.prisma": "composition.apiOverview.output.prisma",
+  "composition.apiOverview.output.typescript": "composition.apiOverview.output.typescript",
+  "composition.apiOverview.output.mcp": "composition.apiOverview.output.mcp",
+  "composition.apiOverview.output.openapi": "composition.apiOverview.output.openapi",
+  "composition.socialClip.cta": "composition.socialClip.cta",
+  "composition.terminal.title": "composition.terminal.title"
+};
+var I18N_KEYS = {
+  ...PROMPT_KEYS,
+  ...SCRIPT_KEYS,
+  ...SCENE_KEYS,
+  ...COMPOSITION_KEYS
+};
 // src/generators/script-generator.ts
 class ScriptGenerator {
   llm;
   model;
   temperature;
+  i18n;
   constructor(options) {
     this.llm = options?.llm;
     this.model = options?.model;
     this.temperature = options?.temperature ?? 0.5;
+    this.i18n = createVideoGenI18n(options?.locale);
   }
   async generate(brief, config) {
     const style = config?.style ?? "professional";
@@ -19,6 +530,7 @@ class ScriptGenerator {
     return this.generateDeterministic(brief, style);
   }
   generateDeterministic(brief, style) {
+    const { t } = this.i18n;
     const segments = [];
     const intro = this.formatForStyle(`${brief.title}. ${brief.summary}`, style);
     segments.push({
@@ -27,7 +539,9 @@ class ScriptGenerator {
       estimatedDurationSeconds: this.estimateDuration(intro)
     });
     if (brief.problems.length > 0) {
-      const problemText = this.formatForStyle(`The challenge: ${brief.problems.join(". ")}`, style);
+      const problemText = this.formatForStyle(t("script.segment.challenge", {
+        content: brief.problems.join(". ")
+      }), style);
       segments.push({
         sceneId: "problems",
         text: problemText,
@@ -35,7 +549,9 @@ class ScriptGenerator {
       });
     }
     if (brief.solutions.length > 0) {
-      const solutionText = this.formatForStyle(`The solution: ${brief.solutions.join(". ")}`, style);
+      const solutionText = this.formatForStyle(t("script.segment.solution", {
+        content: brief.solutions.join(". ")
+      }), style);
       segments.push({
         sceneId: "solutions",
         text: solutionText,
@@ -43,7 +559,9 @@ class ScriptGenerator {
       });
     }
     if (brief.metrics && brief.metrics.length > 0) {
-      const metricsText = this.formatForStyle(`The results: ${brief.metrics.join(". ")}`, style);
+      const metricsText = this.formatForStyle(t("script.segment.results", {
+        content: brief.metrics.join(". ")
+      }), style);
       segments.push({
         sceneId: "metrics",
         text: metricsText,
@@ -68,10 +586,11 @@ class ScriptGenerator {
     };
   }
   async generateWithLlm(brief, style) {
+    const { t } = this.i18n;
     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."
+      professional: t("prompt.style.professional"),
+      casual: t("prompt.style.casual"),
+      technical: t("prompt.style.technical")
     };
     const styleKey = style ?? "professional";
     const messages = [
@@ -80,18 +599,9 @@ class ScriptGenerator {
         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.`
+            text: t("prompt.script.system", {
+              styleGuide: styleGuide[styleKey]
+            })
           }
         ]
       },

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

@@ -2,9 +2,9 @@ import type { VideoProject } from '@contractspec/lib.contracts-integrations/inte
 import type { VideoBrief, VideoGeneratorOptions } from '../types';
 export declare class VideoGenerator {
     private readonly scenePlanner;
-    private readonly scriptGenerator;
     private readonly voice?;
-    private readonly defaultVoiceId?;
+    private readonly transcriber?;
+    private readonly image?;
     private readonly fps;
     constructor(options?: VideoGeneratorOptions);
     /**
@@ -12,9 +12,10 @@ export declare class VideoGenerator {
      *
      * Pipeline:
      * 1. Plan scenes from the content brief
-     * 2. Generate narration script
-     * 3. (Optional) Synthesize voice audio via VoiceProvider
-     * 4. Assemble into a VideoProject
+     * 2. (Optional) Synthesize voice with scene awareness via VoiceSynthesizer
+     * 3. (Optional) Generate subtitles via Transcriber
+     * 4. (Optional) Generate thumbnail via ImageGenerator
+     * 5. Assemble into a VideoProject
      */
     generate(brief: VideoBrief): Promise<VideoProject>;
 }