programmatic_video_generation v1.0.0

name: programmatic_video_generation description: "Generate video from code and templates in a framework-neutral way: pick a seekable renderer, design scene templates with a data schema, render data-driven variants in a resumable batch, choose local or remote rendering, and QA every output before it ships. Use when asked to generate video programmatically, build a video template, batch-render personalized or data-driven videos, automate explainer or stat-card video, or set up a render pipeline."

Programmatic Video Generation

Purpose

Turn a repeatable video format into a system: one template, a data file, and a batch of finished videos that all pass the same checks. This skill is framework-neutral on purpose. It covers how to pick a renderer, how to design the template so variants cannot break it, how to run the batch, and how to verify the output. For generative AI video from prompts, use an AI video skill instead. For hand editing real footage, use an editing skill.

Workflow

1. Decide whether code is the right tool. Programmatic video pays off when the same format repeats: data reports, personalized variants, stat cards, audiograms, explainers with drawn scenes, catalog or recap videos. For a single one-off video with unique art direction, the setup cost is real and a normal editor is faster. Say so when that is the case.
2. Pick a renderer by render model first. Require a seekable renderer for anything templated or batched: each frame is a pure function of time and data, so renders are reproducible, a single frame can be re-rendered alone, and scenes can render in parallel. Families, with tradeoffs in references/frameworks.md: HTML and React compositions (Remotion, Revideo, HyperFrames, or a plain page with a seek function), TypeScript vector animation (Motion Canvas), Python (Manim for math and diagrams, MoviePy for compositing real clips, Pillow frames for simple high-volume cards), FFmpeg filtergraphs alone for title cards and audiograms, and 3D or creative-coding tools as scene generators feeding the main pipeline.
3. Check the license before committing. Licenses differ across these tools and some charge teams for commercial use. Read the current license page for the chosen tool with the team's actual size and use in mind. Never quote a price or a free-use claim from memory.
4. Design the template as a contract. Separate data schema, layout, timing, theme, and assets, per references/template-design.md. Every text slot gets a max length, an overflow behavior, and a minimum font size. Timing comes from content length or voiceover length, never from one hard-coded duration per variant. Validate the design against the longest value, the largest number, and a missing optional field before rendering anything real.
5. Validate all data before rendering. Check every row against the schema in one pass and report every bad row with its id and field. A batch that renders halfway and then dies on a bad row has wasted the expensive half.
6. Pilot one row. Render a single representative row end to end, run QA (step 8), and look at it. Fix template problems at pilot cost. Only then start the batch.
7. Run the batch with scripts/batch_render.py. Feed it a JSON or CSV manifest (see assets/sample-manifest.json) and a render command template. Props reach the renderer through a per-job props file, which is the safe route for text with spaces or punctuation. The script renders with set concurrency, retries failures, writes a state file, and skips finished jobs on resume, so a crashed batch picks up where it stopped.
8. QA every output with scripts/qa_video.py, then look. The script probes each file for duration, resolution, frame rate, codec, and audio presence, flags long black segments, reports silent stretches, and writes a contact sheet. Then follow references/qa-checklist.md: read the contact sheet, check full-size stills on text-heavy scenes, and watch one whole file per template version with sound on. Loudness gets checked against the destination target stated in the job.
9. Record the job. Keep template version, renderer and FFmpeg versions, fonts, data file, and QA results together for each batch. When a bad file surfaces later, that record is how you find every other file the same version produced.

Output Contract

• One finished video per manifest row, at the format the template promises: stated resolution, frame rate, codec, and duration within one frame plus the stated tolerance.
• A batch report listing each job id as done or failed, with the failure stage for failed jobs (validation, asset fetch, render, encode, QA).
• A QA report per file from scripts/qa_video.py (JSON), plus a contact sheet for visual review.
• The template version and environment record for the batch.

Operating Rules

• Seekable or it does not ship as a pipeline. No wall-clock time, no unseeded randomness, and no timer-based animation inside a rendered scene. If the same frame can render two different ways, that is a bug in the template.
• Never interpolate free text into a shell command string. Pass data through the props file or a text file the renderer reads. A shell-quoted value nested inside another quoted argument breaks, and titles with spaces are exactly the data that breaks it. This failure was reproduced while testing this skill's batch script.
• Fix the template or the data, then re-render. Never patch a finished video by hand. The next batch would bring the defect back.
• Two files failing the same QA check means the template is broken. Stop the batch, fix, re-pilot, then resume from the state file.
• Local versus remote is a workload call, not a preference. Local for small batches, frequent iteration, long renders, and data that stays on one machine. Remote, behind a queue with explicit job states, for large batches and on-demand app rendering. Details in references/frameworks.md.
• Pin the environment. Renderer, browser, font, and FFmpeg versions are part of the output contract because a different font on the render box moves text.
• Cache by template version plus props hash. Identical inputs never render twice.
• Bulky material lives in references/: frameworks.md (renderer families and the local versus remote call), template-design.md (schema, text, motion, and versioning rules), qa-checklist.md (the three QA layers and failure handling).