@contractspec/lib.video-gen 1.44.0 → 1.46.0

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

@@ -5,12 +5,14 @@ export interface ScenePlannerOptions {
     model?: string;
     temperature?: number;
     fps?: number;
+    locale?: string;
 }
 export declare class ScenePlanner {
     private readonly llm?;
     private readonly model?;
     private readonly temperature;
     private readonly fps;
+    private readonly i18n;
     constructor(options?: ScenePlannerOptions);
     /**
      * Plan scenes for a video brief.

package/dist/generators/scene-planner.js

@@ -36,17 +36,528 @@ function getAllFormatVariants() {
   ];
 }
 
+// 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/scene-planner.ts
 class ScenePlanner {
   llm;
   model;
   temperature;
   fps;
+  i18n;
   constructor(options) {
     this.llm = options?.llm;
     this.model = options?.model;
     this.temperature = options?.temperature ?? 0.3;
     this.fps = options?.fps ?? DEFAULT_FPS;
+    this.i18n = createVideoGenI18n(options?.locale);
   }
   async plan(brief) {
     if (this.llm) {
@@ -56,6 +567,7 @@ class ScenePlanner {
   }
   planDeterministic(brief) {
     const { content } = brief;
+    const { t } = this.i18n;
     const scenes = [];
     const fps = this.fps;
     scenes.push({
@@ -64,7 +576,7 @@ class ScenePlanner {
         hook: content.title,
         message: content.summary,
         points: content.solutions.slice(0, 3),
-        cta: content.callToAction ?? "Learn more"
+        cta: content.callToAction ?? t("scene.cta.default")
       },
       durationInFrames: 3 * fps,
       narrationText: `${content.title}. ${content.summary}`
@@ -73,31 +585,35 @@ class ScenePlanner {
       scenes.push({
         compositionId: "SocialClip",
         props: {
-          hook: "The Problem",
+          hook: t("scene.hook.problem"),
           message: content.problems[0] ?? "",
           points: content.problems.slice(1, 4)
         },
         durationInFrames: 4 * fps,
-        narrationText: `The problem: ${content.problems.join(". ")}`
+        narrationText: t("scene.narration.problem", {
+          content: content.problems.join(". ")
+        })
       });
     }
     if (content.solutions.length > 0) {
       scenes.push({
         compositionId: "SocialClip",
         props: {
-          hook: "The Solution",
+          hook: t("scene.hook.solution"),
           message: content.solutions[0] ?? "",
           points: content.solutions.slice(1, 4)
         },
         durationInFrames: 5 * fps,
-        narrationText: `The solution: ${content.solutions.join(". ")}`
+        narrationText: t("scene.narration.solution", {
+          content: content.solutions.join(". ")
+        })
       });
     }
     if (content.metrics && content.metrics.length > 0) {
       scenes.push({
         compositionId: "SocialClip",
         props: {
-          hook: "Results",
+          hook: t("scene.hook.results"),
           message: content.metrics[0] ?? "",
           points: content.metrics.slice(1, 3)
         },
@@ -134,29 +650,17 @@ class ScenePlanner {
     };
   }
   async planWithLlm(brief) {
+    const { t } = this.i18n;
     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.`
+            text: t("prompt.scenePlanner.system", {
+              fps: this.fps,
+              targetSeconds: brief.targetDurationSeconds ?? 30
+            })
           }
         ]
       },

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

@@ -23,11 +23,13 @@ export interface ScriptGeneratorOptions {
     llm?: LLMProvider;
     model?: string;
     temperature?: number;
+    locale?: string;
 }
 export declare class ScriptGenerator {
     private readonly llm?;
     private readonly model?;
     private readonly temperature;
+    private readonly i18n;
     constructor(options?: ScriptGeneratorOptions);
     /**
      * Generate a narration script from a content brief.