andrew.dunn.dev

Playbill

~3 min
videotoolingopen-source
Source

TOML-driven video program assembler. Define a program in program.toml, drop video files into input/, and Playbill renders title cards, intros, episode pass-throughs, and credits into a single concatenated video with fade-to-black transitions.

Playbill was extracted from a birthday party video project. The program assembler turned out to be a general-purpose tool for event programs, screening nights, or any sequenced video playlist that needs structure between clips.

temp filesPROGRAMprogram.tomlSOURCEvideo clipsPLAYBILLrendersix segment typesFFMPEGconcatfade to blackOUTPUTfinal videoacts optional
A TOML program and a folder of clips go in, playbill renders each segment, and ffmpeg concatenates them into one video with fades.

Segment types

SEGMENT TYPESconcatPROGRAMprogram.tomlsegment definitionsTEXT CARDtitleVIDEO + TEXTintroPASS-THROUGHepisodePASS-THROUGHscenePHOTO + TEXTquotePHOTO WALLcreditsEach rendered to temp filewith fade-to-black transitionsOUTPUTfinal videoIF ACTS DEFINEDper-act files
Six segment types render to temp files, and ffmpeg concatenates them into one video, plus a file per act when the program defines acts.

title: A text card (white on black) with configurable lines, duration, and fade timing. Optional background music. Used for act breaks, chapter headings, or opening titles.

intro: Portrait video on the left half with title, subtitle, and description text on the right. Originally designed for a three-year-old introducing his favorite TV shows.

episode and scene: Pass-through video files, scaled and padded to output resolution. Supports trimming and outro padding. HDR content is automatically tonemapped.

quote: Photo or video on the left with a name and quote text on the right. Works for testimonials, friend messages, or any face-next-to-words layout.

credits: Scrolling photo wall with video and photo quotes interspersed. Background music with automatic audio ducking when quotes play.

CLI

Playbill is designed for iterative work. The CLI supports several modes for fast feedback:

  • --preview truncates long segments to ~15 seconds for fast iteration
  • --segment N renders only one segment for focused work
  • --skip-render reuses existing temp files and only re-concatenates
  • --list previews the program structure without rendering

Status

The extraction from the birthday monolith is done and the tooling is in place. The README, Makefile, and CLI work. The code needs the same cleanup Pinboard went through for v1.0: type hints, argparse, ruff linting, stripped comments.

Dependencies

Python 3.11+, Pillow, NumPy, ffmpeg 7+. MIT licensed.