authoring-video-templates

Authoring Video Templates

Overview

A template is a JSON descriptor that the engine compiles into a video. It has two top-level keys: global (project-wide defaults) and sections (the ordered list of clips). The descriptor is the LLM-clear authoring standard — validate against the schema, don't guess fields.

Sources of truth (in order of authority):

• Machine-readable JSON Schema: docs/template-descriptor.schema.json — generated from the zod source; feed it to an editor/agent for autocompletion + validation. Regenerate with pnpm --filter ffmpeg-video-composer generate:schema.
• Full field reference + examples: docs/template-configuration.md.
• zod source (every field has .describe()): packages/ffmpeg-video-composer/src/schemas/ (template.schemas.ts re-exports effects/global/filter/section).
• Validator: packages/ffmpeg-video-composer/src/services/TemplateValidator.ts (+ templateValidationRules.ts).
• Built-in examples: packages/leclap-creative-kit/src/templates/*.json.

Two layers: structured sugar vs. raw filters

• Structured sugar (prefer this): transition, look, grade, motion, audio, layers, animation inputs, and text sugar (caption, titleCard, lowerThird, reveal, global.overlays/look/grade). Editor-friendly camelCase intents that compile to ordinary, on-device-safe FFmpeg filters.
• Raw filters (escape hatch): filters[], inputs[].filters, maps[] — passed to FFmpeg verbatim. Their values keys stay FFmpeg-native (x/y/w/h/c/t/fontcolor/fontsize/fontfile/alpha/d/st/color/box/boxcolor/boxborderw), not camelCase, by design.

Structure

{
  "global": {
    "variables": { "video": "https://…/earth.mp4" },
    "orientation": "landscape", // "landscape" (1280x720) | "portrait" (720x1280) | "square" (1080x1080)
    "musicEnabled": true,
    "music": { "name": "track.mp3" },
    "transition": { "type": "fade", "duration": 0.4 }, // xfade name | "cut"; duration in SECONDS
    "audio": { "sourceVolume": 1, "musicVolume": 0.5 },
  },
  "sections": [
    {
      "name": "intro",
      "type": "video", // see Section types
      "options": { "videoUrl": "{{ video }}", "duration": 4, "musicVolume": 1 }, // SECONDS
      "transition": { "type": "wipeleft", "duration": 0.4 }, // boundary AFTER this section
      "look": "cinematic",
      "filters": [{ "type": "fadein", "values": { "color": "#000000" } }],
    },
  ],
}