Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

0xpratzyy/subtle

Media & Design

Locally renders animated talking-head captions and lyric videos in 35 styles, as a Codex/Claude Code skill or standalone CLI.

This project ships 1 agent skillsSkill list and install →
109
27
TypeScript
NOASSERTION
3 days old

What it does

Subtle turns a talking-head video into a captioned video rendered on your own machine. It transcribes speech with word-level timing via mlx-whisper, normalizes spoken numbers into single tokens ($5,000, 40%, ₹1 lakh), groups words into short caption pages, and highlights emphasized words. It then renders one of 35 caption styles at the source video's size and frame rate and runs checks on safe area, contrast and big-word visibility, producing a contact sheet. The output includes <name>.captioned.mp4, <name>.srt, editable <name>.captions.json, and <name>.preview.jpg.

It ships as both a Codex / Claude Code skill and a standalone Python CLI. Six styles (keyword, cover, outline, poster, rise, numeral) place a giant word behind the speaker, using Apple Vision for the cut-out on macOS.

Quick start

Requirements: macOS on Apple Silicon for transcription and the behind-the-speaker effect, plus ffmpeg, Node 18+, Python 3.9+ with uv, and Xcode command line tools for the Swift components. Run bash scripts/doctor.sh to confirm the environment.

Install as an agent skill by cloning into the skills directory:

git clone https://github.com/0xpratzyy/subtle ~/.claude/skills/subtle

For Codex, clone to ~/.agents/skills/subtle instead. Then ask the agent to add captions to a video. For the standalone CLI, clone anywhere and run from that directory:

python3 scripts/subtle.py talk.mp4 --style glass

The first run downloads the speech model (about 1.6 GB) and installs renderer packages (about a minute). Transcripts are cached by file hash, so switching styles does not re-transcribe.

Using the CLI

Without a style argument, the default glide style is used. Examples from the README:

python3 scripts/subtle.py talk.mp4 --style keyword
python3 scripts/subtle.py talk.mp4 --style ticket:yellow
python3 scripts/subtle.py talk.mp4 --emphasis numbers
python3 scripts/subtle.py talk.mp4 --lang es --aspect 9:16
python3 scripts/subtle.py talk.mp4 --captions talk.captions.json

--captions re-renders after editing the caption JSON. --placement off and --cuts off keep the style's own position and ignore hard cuts; --behind off draws giant words in front. python3 scripts/subtle.py --list-styles lists styles and colourways. You can preview every style on the showcase site, which runs the same engine in a browser; its source is in site/.

Constraints

  • Full transcription and behind-the-speaker styles require macOS on Apple Silicon. On Linux or Intel Macs you can still render from your own word timings with --words; bash scripts/doctor.sh --from-timings checks that workflow.
  • The behind-the-speaker effect works best with one person and a steady camera; fine hair, fast hands and fast pans can show at the matte edge, and the tool falls back to drawing words in front when needed.
  • Styles without a container can be hard to read on bright or busy footage; the contrast check suggests container styles.
  • Whisper word timings come from attention rather than forced alignment and can drift on very fast speech. Hindi words in Latin script are spelled inconsistently; review the transcript and use --replace heard=Shown.
  • Code is MIT, bundled fonts are under the SIL OFL, and the default renderer uses Remotion, which is free for individuals and companies up to 3 people; larger companies need a Remotion licence. Dependency details are in THIRD_PARTY.md.

HotRepo's take

The project appeared on the HotRepo new-project list for TypeScript on 2026-11-21, gaining 9 stars in a window of roughly four hours while collecting 27 forks. That combination suggests an early, design-heavy project whose output is visual rather than a library, and the README backs that up with a full style gallery and a browser showcase. It has no daily all-language rank record. The most practical signal is the platform split: the macOS Apple Silicon requirement shapes who can use transcription and the behind-the-speaker styles, so the Linux/Intel fallback matters as much as the style count.

Written by AI from the project's public information and HotRepo's records, updated . The project's own docs are the source of truth.

You might also like

  1. owlinthebarnai/video-studio-kitLocal web studio that turns a prompt into a short animated video using your own Claude Code subscription.JavaScript106
  2. andyhuo520/digital-human-kouboTurns one photo and a script into a packaged talking-head video, driven by an AI agent instead of manual editing.TypeScript357
  3. Moessif/code-video-showcaseA recipe for producing 30–90s beat-synced showcase videos with code-drawn frames and synthesized audio, aimed at coding agents.JavaScript128
  4. mromidev/claude-animated-shortsClaude skill for rendering 55–70 second vertical animated story shorts with three.js and Remotion on your own machine.TypeScript108
  5. StewdioAI/blank-pageA Claude Code and Codex skill that expands a one-line motion brief into a reference-backed prompt with look, beats and assets.Python108