Skip to content

README.md

Latest commit

 

History

History
366 lines (267 loc) · 10.7 KB

README.md

File metadata and controls

366 lines (267 loc) · 10.7 KB

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.