pycaps: Python library and CLI for CSS-styled video subtitles

pycaps is an open-source Python tool that burns styled subtitles into videos. It transcribes audio with Whisper, animates captions word by word, and lets you tag phrases with regex, word lists, or AI. The rendering engine is standard CSS, so any web designer can author a template. Built for automating short-form video for TikTok, YouTube Shorts, and Instagram Reels.

Before you install anything: try tscaps

pycaps stays a Python library and CLI for developers who want to script captions into a pipeline. If that isn't you, the same author now builds tscaps, the browser-native sibling: same core idea (CSS as the subtitle rendering engine), full visual editor, no code. Most people who land here are better served by it.

What pycaps does

• Whisper-based transcription. Word-level timestamps are generated locally from OpenAI's Whisper models. You can also feed in an existing transcript (whisper_json, pycaps_json, srt, vtt) and skip the transcription step.
• CSS as the styling engine. Subtitles are rendered from real CSS. Target states like .word-being-narrated to drive per-word effects, and keep style cleanly separated from logic.
• Word tagging. Tag words or phrases with regular expressions, word lists, or an AI pass over the transcript. Tags become CSS selectors that trigger custom styles, animations, or effects.
• Animations and effects. Built-in fades, pops, slides, typewriter effects, contextual emoji insertion, and sound cues. Attach them to segments, lines, or individual words.
• Templates. Package a set of styles, animations, and configuration as a reusable template. Ship your own or start from the built-in ones (minimalist, default, and more).
• CLI and Python library. Use pycaps render for quick jobs, or wire CapsPipelineBuilder into a Python backend or batch pipeline.
• Offline-first. Transcription, styling, and rendering run entirely on your machine. Network access is only used for optional AI features that need to reason over the script.

Quick example

Render a video with a built-in template from the command line:

pycaps render --input my_video.mp4 --template minimalist

Or drive the pipeline from Python for full control:

from pycaps import *

builder = (
    TemplateLoader("default")
    .with_input_video("my_video.mp4")
    .load(False)
)

builder.add_animation(
    animation=FadeIn(),
    when=EventType.ON_NARRATION_STARTS,
    what=ElementType.SEGMENT,
)

builder.build().run()

Common questions