Vidkit

Vidkit is a small scripted video toolkit for AI assistants, automation, and command-line workflows.

It renders short videos from structured specs and helper commands, then verifies the output with ffmpeg/ffprobe. It is not an interactive editor, and it is not a general AI video generator. The useful part is repeatability: a caller can describe a video, render it, inspect the result, adjust the spec, and render again.

What It Is For

Use Vidkit when you want:

• short motion-graphics clips from JSON specs
• layered cards, captions, lower-thirds, UI mockups, fake app scenes, and simple visual systems
• deterministic sound cues and audio beds for generated clips
• practical ffmpeg edits such as trims, contact sheets, GIFs, subtitles, scaling, fades, remixes, and QA bundles
• optional Blender-backed 3D shots when a Blender binary is available
• assistant-friendly storyboard plans that expand into ordinary Vidkit specs
• reproducible render-job handoffs for another machine or agent

Do not reach for Vidkit when you need a timeline GUI, long-form editing, advanced color work, licensed media management, or high-end generative video. It is a compact scripting layer around repeatable video assembly.

Requirements

Core compose/helper workflows:

• Python 3.11+
• ffmpeg and ffprobe on PATH
• no Python package dependencies

Optional 3D rendering:

• Blender on PATH, or pass --blender /path/to/blender
• for GPU renders, use a Blender build with CUDA/OptiX support and request the device explicitly

Install

Install directly from GitHub with pipx:

pipx install git+https://github.com/compoodment/vidkit.git
vidkit --help

For local development, clone the repo and install it editable:

git clone https://github.com/compoodment/vidkit.git
cd vidkit
python3 -m pip install -e .
vidkit --help

You can also use the repo-local wrappers without installing:

export PATH="$PWD/bin:$PATH"
vidkit --help

First Render

Render a built-in template:

vidkit templates
vidkit show template:media-card
mkdir -p out
vidkit template:media-card out/media-card.mp4

Create a starter spec, edit it, validate it, and render:

mkdir -p out
vidkit init split-screen out/split-screen.json
vidkit validate out/split-screen.json
vidkit out/split-screen.json out/split-screen.mp4

Inspect an output:

vidkit qa out/split-screen.mp4 --out out/qa/split-screen

The QA bundle writes probe.json, contact.jpg, representative frame-*.jpg stills, audio-levels.txt when audio exists, and summary.json.

CLI Layout

vidkit compose <vidkit-compose args>
vidkit helper <vidkit-helper args>
vidkit verify
vidkit selftest
vidkit blender <vidkit-blender args>

Common shortcuts:

vidkit templates
vidkit template:<name> out.mp4
vidkit contact in.mp4 out.jpg
vidkit qa in.mp4 --out qa-dir

Legacy wrapper names remain available:

video-compose
video-kit
video-compose-verify
video-compose-selftest

Workflow

A normal Vidkit loop is:

1. Pick the lane: compose, helper, Blender, or render job.
2. Start from a template or small example.
3. Validate the spec before rendering.
4. Render to an output directory, not the repo root.
5. Run vidkit qa or inspect representative frames/contact sheets.
6. Iterate the spec until the video is readable and timed correctly.

For code or spec changes, run:

python3 -m compileall tools
vidkit selftest
vidkit verify

vidkit verify is broader and renders templates, so it can take longer than vidkit selftest.

Compose

Compose is the JSON-driven renderer for generated scenes, layered media, text, captions, transitions, and audio cues.

Render a spec:

vidkit examples/vidkit.motion-polish-example.json out/polish.mp4

Validate without rendering:

vidkit --validate-only examples/vidkit.motion-polish-example.json
vidkit validate template:split-screen

Built-in templates:

• lower-third
• motion-card
• glitch-card
• band-glitch
• media-card
• split-screen
• chat-window
• application-form

Scene types:

• generated visuals: card, bars, particles, wave, grid, orbits, typewriter
• media: image / media
• compositing: layered
• timing/comedy utility: beat

Layer types in a layered scene:

• media: image/video layer with source, fit, sizing, and placement
• sprite: media-layer alias for image/video elements that move through a scene
• panel: colored rectangle layer for cards, UI, and backing plates
• lower_third: readable caption/lower-third preset
• text: subtitle/label event burned through ASS subtitles
• shape: reusable primitives expanded into panel/text layers
• preset: reusable UI/dialog/stamp treatments expanded into layers

Common layer features:

• start / end timing
• static or keyframed x, y, opacity, and media/sprite scale
• animate entrance/exit presets
• sprite_animate helper presets
• rounded masks via radius
• borders via border, border_color, and border_opacity
• layered camera keyframes and optional shake

See docs/spec-guide.md for a more complete spec guide.

Helper

The helper wraps practical ffmpeg tasks:

• trim
• contact
• frame
• gif
• mux-audio
• burnsub
• crop
• scale
• rotate
• speed
• concat
• card
• caption
• fade
• slideshow
• remix
• qa

Examples:

mkdir -p out out/qa
vidkit trim input.mp4 2.0 7.0 out/clip.mp4
vidkit contact input.mp4 out/contact.jpg
vidkit frame input.mp4 out/frame.jpg --time 3.2
vidkit gif input.mp4 out/clip.gif --start 0 --duration 3
vidkit fade input.mp4 out/faded.mp4 --fade-in 0.4 --fade-out 0.5
vidkit qa input.mp4 --out out/qa/input

An audio stream is not proof that audio is usable. When sound matters, inspect audio-levels.txt and summary.json from the QA bundle.

Blender Backend

The Blender backend is for real 3D shots: cameras, lights, materials, geometry, smooth temporal motion, and optional GPU rendering.

It can validate and emit scripts without Blender installed:

vidkit blender templates
vidkit blender show template:glass-orbit-cathedral
vidkit blender init glass-orbit-cathedral out/scene.json
vidkit blender validate out/scene.json
vidkit blender script out/scene.json out/scene.py

Render with Blender:

vidkit blender render out/scene.json out/scene.mp4 --blender /path/to/blender

For GPU/Cycles jobs, request the device explicitly and prefer image sequences for long renders:

vidkit blender render out/scene.json out/scene.mp4 \
  --device cuda \
  --output-mode sequence \
  --frames-dir out/frames \
  --no-cpu-fallback

A GPU-intended job should fail if the requested GPU backend is unavailable. Do not accept silent CPU fallback for long renders.

Blender spec support currently includes:

• render size, FPS, duration, engine, world color
• camera and look-at/orbit paths
• lights
• objects: cube, sphere/UV sphere, ico sphere, plane, torus, cylinder, cone, text
• materials with color, emission, roughness, and metallic values
• simple end-state animation for location, rotation, and scale

Storyboard Plans

Storyboard plans are a lightweight assistant-facing format for concept-first workflows. They expand into ordinary compose specs, so the generated output stays inspectable and editable.

vidkit storyboard examples/vidkit.storyboard-example.json out/storyboard-expanded.json
vidkit validate out/storyboard-expanded.json
vidkit storyboard examples/vidkit.storyboard-example.json out/storyboard.mp4 --render --keep-spec out/storyboard-expanded.json

See docs/storyboard.md for the plan format and supported beat kinds.

Render Jobs

render-jobs/ contains deterministic handoff packets for remote or stronger render machines. A job folder usually includes:

• a README.md with exact run instructions
• a render script or scene spec
• a run.sh wrapper
• expected output paths

Run the job from the repo root and return the MP4, ffprobe JSON, and render log. Render jobs should be benchmarked before long full renders when GPU/CPU utilization matters.

See render-jobs/README.md for the handoff loop and job-folder contract.

Examples

The examples/ directory contains portable specs that run without private local media:

mkdir -p out
vidkit examples/vidkit.example.json out/example.mp4
vidkit examples/vidkit.lower-third-example.json out/lower-third.mp4
vidkit examples/vidkit.motion-example.json out/motion.mp4
vidkit examples/vidkit.motion-polish-example.json out/polish.mp4
vidkit examples/vidkit.animation-presets-example.json out/presets.mp4
vidkit examples/vidkit.camera-sprite-example.json out/camera-sprite.mp4
vidkit examples/vidkit.sprite-path-example.json out/sprite-path.mp4
vidkit examples/vidkit.shapes-presets-example.json out/shapes-presets.mp4
vidkit examples/vidkit.sfx-example.json out/sfx.mp4
vidkit examples/vidkit.comedy-beats-example.json out/comedy-beats.mp4
vidkit storyboard examples/vidkit.storyboard-example.json out/storyboard-expanded.json

examples/assets/sample.ppm is bundled so examples and templates work without private local media.

Repository Map

• bin/: wrapper commands
• vidkit/: importable package and console entry points
• tools/: compatibility shims for legacy direct script paths
• vidkit/compose.py: JSON/spec renderer
• vidkit/helper.py: ffmpeg edit/inspection helpers
• vidkit/blender.py: optional Blender spec/script/render backend
• vidkit/selftest.py: focused behavioral selftests
• vidkit/verify.py: broader render/probe verifier
• examples/: public-safe runnable specs
• render-jobs/: deterministic remote-render handoff packets
• skill/: draft AgentSkill for local OpenClaw usage
• docs/: longer user-facing guides

Troubleshooting

If vidkit is not found, add the repo wrapper directory to PATH:

export PATH="$PWD/bin:$PATH"

If ffmpeg is missing:

ffmpeg -version
ffprobe -version

If a spec fails, validate before rendering:

vidkit validate path/to/spec.json

If an output renders but looks wrong, generate a QA bundle and inspect the contact sheet or frames:

vidkit qa output.mp4 --out out/qa/output

If a Blender GPU render is unexpectedly slow, verify the requested device, disable CPU fallback for GPU-intended jobs, and benchmark a short frame range or image-sequence run before committing to a long render.

Contributing

See CONTRIBUTING.md for contributor standards, issue quality expectations, feature design guidance, and verification rules.

Status

Vidkit is early and intentionally small. The core compose/helper tools are stable enough for scripted assistant workflows. The Blender backend and render-job workflow are experimental but usable for controlled 3D render handoffs.