Skip to content
Back to search

subtle

SkillWorks with Claude CodeGitHub

Transcribe and render animated captions or export SRT locally from video or audio. Use for word-by-word subtitles, highlighted keywords or prices, Hinglish captions, text behind a speaker, or beat-synced lyric videos. Includes 39 styles, editable word timings, and visual checks for the finished render.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xpratzyy--subtle/badge.svg)](/listings/0xpratzyy--subtle)

HTML

<a href="/listings/0xpratzyy--subtle"><img src="/api/listings/0xpratzyy--subtle/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Codex**:

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

**Claude Code**:

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

Then ask your agent to *"add captions to ~/Movies/talk.mp4"* or *"put a giant keyword behind me"*. For the standalone CLI, clone the repo anywhere and run the commands below from that directory.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 149 lines
  1. ---
  2. name: subtle
  3. description: Transcribe and render animated captions or export SRT locally from video or audio. Use for word-by-word subtitles, highlighted keywords or prices, Hinglish captions, text behind a speaker, or beat-synced lyric videos. Includes 39 styles, editable word timings, and visual checks for the finished render.
  4. ---
  5. # Subtle: beautiful captions for any video
  6. You add animated captions to a video with the tools in this folder. Everything runs on the user's machine. Nothing is
  7. uploaded and no key is needed. Run commands from this skill's folder (the folder holding this file).
  8. ## Inputs
  9. | Input | Default | Notes |
  10. |---|---|---|
  11. | video path | required | any file ffmpeg reads |
  12. | style | `glide` | any name from the Styles tables below, `name:variant` for a colourway (`ticket:yellow`, `singalong:lit`, `chalkline:marker`), or a path to your own style JSON |
  13. | lyrics | none | music styles: a text file with the right words, one lyric line per line. Its words replace the transcript's, on the sung timings |
  14. | canvas | `9:16` | for an input with no picture (a song): the frame to draw on: `9:16`, `16:9`, `1:1` or `4:5` |
  15. | emphasis | `auto` | `auto`: highlight numbers, prices, names and contrast words. `numbers`: numbers only. `off`: no highlights |
  16. | emphasis-words | none | words to highlight for sure: `--emphasis-words 'gold, $5,000'` |
  17. | numbers | `auto` | spoken numbers become one token (`$5,000`, `40%`, `₹5 lakh`). `western`, `indian` or `european` (`5.000`, `3,5`) sets the digit grouping; `off` keeps the transcript as heard |
  18. | behind | `auto` | `auto`: with `--style keyword`, put the giant word behind the speaker if the subject check passes. `on`: force it. `off`: draw it in front |
  19. | placement | `auto` | `auto`: each page moves off the face and the hands (macOS, Apple Vision), inside the style's `position.flex` range, and only when it has to. `off`: every page keeps the style's `y` |
  20. | cuts | `auto` | `auto`: find hard cuts with ffmpeg; no page straddles one. `off`: ignore cuts |
  21. | language | detect | `--lang en`, `--lang hi`, `--lang es`; `--hinglish` writes Hindi in Latin letters. Spanish has its own number and highlight rules |
  22. | vocab | none | names and brand words Whisper should spell right: `--vocab "Refs, Claude"` |
  23. | legibility | `auto` | `auto`: measure what is behind every page and add a soft halo, scrim or outline where the type would not read; clean dark footage is left untouched. `off`: draw the preset as it is |
  24. | palette | `auto` | `auto`: styles with an accent colour (`glide`, `keyword`, `shine`, `accent`, `hype`, `highlighter`, `haiku`, `karaoke`) take it from the footage: a colour that suits the scene and reads on it. `off`: the preset's colours |
  25. | aspect | `source` | `9:16`, `1:1`, `4:5`, `16:9` centre-crop the video first |
  26. If the user did not name a style, use `glide` and say which other styles exist. Ask nothing else up front.
  27. ## Steps
  28. 1. **Check dependencies.** Run `bash scripts/doctor.sh`, adding `--from-timings` when using `--words` or `--captions`.
  29. Resolve any dependencies required for the requested workflow before rendering.
  30. 2. **Transcribe.** `python3 scripts/subtle.py "<video>" --stop-after transcribe [--lang ..] [--vocab ".."] [--hinglish]`
  31. It prints the transcript. Read it.
  32. - Fix wrong names with `--replace heard=Shown` (repeatable) or better `--vocab`.
  33. - For Hindi or Hinglish, check names and transliteration against the audio. Flag uncertain words.
  34. 3. **Group.** `python3 scripts/subtle.py "<video>" --style <style> --stop-after group`.
  35. Keep the transcription flags from step 2. For a song, pass the chosen music style and any supplied
  36. `--lyrics <file>` and `--canvas <ratio>`. For video, add the requested `--aspect` if needed.
  37. This writes `<name>.captions.json` and prints the words the rules highlighted. Spoken numbers are already single
  38. tokens here: "five thousand dollars" is `$5,000`, "forty percent" is `40%`, "one lakh rupees" is `₹1 lakh`.
  39. 4. **Pick the highlights. This is your job, and it is what makes the captions good.**
  40. `python3 scripts/emphasis.py "<name>.captions.json" --style <style> --show` prints every page with the highlighted
  41. words in [brackets] and the reason for each. The rules find numbers and names; they cannot tell what matters.
  42. Read the pages and decide, in this order of priority:
  43. 1. numbers, prices, percentages, dates and counts (`$5,000`, `3x`, `1991`, `40%`);
  44. 2. names, brands and places;
  45. 3. the punchline or contrast word (`never`, `free`, `broke`);
  46. 4. the topic noun, the first time it appears.
  47. At most 1 highlight per page, 2 on pages of 5 words or more. Never filler words (`the`, `really`, `that's`).
  48. Remove the rule guesses that are not the point of their line. Then save your picks, each with a one-line reason:
  49. ```
  50. python3 scripts/emphasis.py "<name>.captions.json" --style <style> \
  51. --pick '21:25,000=the size of the hoard' --pick '38:broke=the turn of the story' --drop '34:smuggling'
  52. ```
  53. `PAGE:WORD` uses the page number and the word as `--show` prints them. Use single quotes, or the shell eats `$5`.
  54. `--clear` removes every highlight first if you would rather start from nothing.
  55. 5. **Render.** `python3 scripts/subtle.py "<video>" --style <style> --captions "<name>.captions.json"`
  56. Keep the same `--canvas` or `--aspect` as in step 3.
  57. The transcript is cached, so this does not transcribe again. The first render installs the renderer (about a minute).
  58. In a hurry, or running with no one to pick: skip steps 3 and 4 and render directly with
  59. `python3 scripts/subtle.py "<video>" --style <style>`; the rules pick the highlights (`--emphasis auto`).
  60. 6. **Verify.** The command prints JSON with `ok`, `warnings` and `preview` (a contact sheet). **Open the preview image
  61. and look at it** before you say anything. Check: text readable, inside the cyan safe-area box, not over the face,
  62. and the highlighted words are the ones that matter. Placement moves captions off the face and hands on its own; `notes` says
  63. how many pages moved and how many cuts it found. A caption still on the face: lower `position.flex` in the style or pass `--placement off`.
  64. - Warning about the safe area or an overflowing line: lower `--max-words`, or use a style with smaller type.
  65. - Warning about low contrast: switch to a style with a container: `glass`, `chip` or `block`. The grouping `notes` say how many pages
  66. needed help and the weakest contrast; `<name>.captions.json` has one `legibility` line per page.
  67. - `keyword`: numbers are drawn large in front of the speaker, never behind (hidden digits would change them). `numeral` is the exception: it is built for numerals behind the speaker.
  68. - Behind styles (`keyword`, `cover`, `outline`, `poster`, `rise`, `numeral`) decide **per shot**: `notes` says how many shots leave room. In a close-up the giant word is drawn in front or skipped (the words stay in the small line); in a wide shot it goes behind the head.
  69. - `keyword`, a big word mostly hidden: it is dropped automatically (see `notes`). To change which words go big,
  70. edit `big` in `<name>.captions.json`, then re-render with `--captions <name>.captions.json`.
  71. - Behind effect skipped (see `notes`): tell the user why; the big words were drawn in front of the speaker instead.
  72. - A music style: read the grouping `notes` for the beat grid ("120 BPM, 129 beats"). "no steady beat found" means the pages
  73. follow the words; say so. With `--lyrics`, `notes` says how many lyric words were found in the audio: under about
  74. 60% usually means the wrong lyrics file or a transcript in the wrong language.
  75. 7. **Hand over.** Give the paths: `<name>.captioned.mp4`, `<name>.srt`, `<name>.captions.json`, `<name>.preview.jpg`,
  76. and the one-line command to try another style.
  77. ## Styles
  78. Caption styles:
  79. | Style | Looks like | Best for |
  80. |---|---|---|
  81. | `glide` | Key words in a large calligraphic script, the small words in bold white sans, on one baseline. | default; editorial talking heads |
  82. | `glass` | One frosted-glass pill per page in soft lowercase; upcoming words are dim and brighten as they are spoken. | calm, premium, any footage |
  83. | `whisper` | Lowercase warm-yellow text; each word is revealed by a soft left-to-right wipe and the page dissolves with a blur. | soft, intimate delivery |
  84. | `terminal` | Green monospace typed character by character with a blinking block cursor. | tech, code, developer content |
  85. | `keyword` | One giant pale-lime keyword behind the speaker, the other words small and stacked beside it. | one person, steady camera, macOS (uses the person matte) |
  86. | `cover` | One giant serif italic word behind the head like a magazine masthead; the rest small and tracked in front. | one person, a wide shot with some headroom (macOS) |
  87. | `outline` | A giant hollow word behind the speaker that draws on, then fills as it is spoken. | one person, a wide shot (macOS) |
  88. | `poster` | Two or three words stacked behind the speaker, each line its own face fitted to the same width (needs headroom: weak on tight shots). | wide shots with plenty of headroom (macOS) |
  89. | `rise` | The giant word climbs out from behind the speaker's shoulders letter by letter. | one person, a wide shot (macOS) |
  90. | `numeral` | Numbers, years and names go giant behind the speaker, digits rolling like an odometer. | talks full of numbers, dates and names (macOS) |
  91. | `magazine` | A tight justified block: big serif-italic keywords, small grotesk capitals for the glue words. | ad supers, launch films, any footage |
  92. | `flip` | Every letter flips in like a split-flap tile, with a motion trail. | hooks, playful edits |
  93. | `cinema` | Tiny wide-tracked serif capitals, slow blur fades, arthouse-trailer subtitles. | trailers, quiet interviews |
  94. | `split` | Words alternate to the two sides of the speaker and step down around the head, never over the face. | one person in a wide shot (macOS) |
  95. | `accent` | Pale-lime sans in very short pages, with the key word in a light serif italic; soft fade with a small drift. | launch films, quiet editorial |
  96. | `chip` | A light rounded chip that hugs the page; words turn from grey to black as they are spoken. | explainers; readable on any footage |
  97. | `title` | A typed title whose letter spacing collapses as the letters arrive, with a small handwritten note under it. | section headers and lists |
  98. | `hype` | A calm medium-weight line in soft white with a gentle shadow; the key word turns warm yellow. Hard cut in, no outline. | authority, education |
  99. | `block` | Every line in its own warm coloured block with depth; lines rise in with motion blur and pile up as a stack. | bold brand colour, promos |
  100. | `impact` | Heavy round caps; every letter bounces in along an arc with overshoot and a little tilt, on a hard offset shadow. | hooks, high energy |
  101. | `bottom` | Big bold caps low in the frame that build word by word with no animation; the key word is yellow. | fast speech, zero delay |
  102. | `stack` | A tilted, overlapping pile of words, each at its own size and angle, key words in yellow; the tilt mirrors on alternate pages. | social cuts, poster feel |
  103. | `serif` | Display serif italic filled with a top-lit silver gradient; quiet and luxurious. | luxury, titles |
  104. | `shine` | Serif italic in one accent colour; a diagonal band of light sweeps across each word, then a soft glow fades. | one accent colour, premium titles |
  105. | `karaoke` | The whole line shows dim; each word turns solid as it is spoken. One weight, no motion. | long lines, product videos |
  106. | `sticker` | Rounded pink bubbles, one per line, each new line offset to the right of the last and stacked like typed messages; the stack tilts a little more on every page. Words are dark until spoken, then white. | chatty, casual, story time |
  107. | `ticket` | A hard-edged label tight around the text, tilted a different angle on every page. The hot word sits alone on a big label, filler phrases on a small one. Hard cuts. Colourway: yellow. Also: `ticket:yellow`. | edits with rhythm: the key word alone and big |
  108. | `highlighter` | Bold caps with one flat box behind the word being spoken, hopping from word to word. A finished word turns lime; the hot word comes alone, large. | follow-the-speech captions, podcasts |
  109. | `haiku` | One small condensed serif word at a time in acid yellow. Hard cuts, no box. A hot word turns italic and a lighter yellow. | cinematic talking heads, slow delivery |
  110. | `duo` | A big condensed caps headline word with a tiny spaced-out lead-in above and a bold italic tail below. The lead-in fades in, the headline cuts in, the tail fades in. | Hinglish and any line with the key word in the middle |
  111. | `editorial` | A bold sans lowercase line with the keyword set about three times larger in a high-contrast italic serif in cinema red, overlapping the sans. Lower-left third. | magazine feel, fashion, opinion |
  112. | `newsroom` | Bold yellow sans, every word on screen at once, the spoken word turns white; soft black outline, lower third. | news explainers, any footage |
  113. | `cards` | White serif on a dark rounded card, the phrase appears at once, key words in red italic. | essays, interviews, serif-card look |
  114. | `punch` | Heavy upper-case sans popping in word by word with overshoot; the spoken word swells and turns lime, thick outline. | short-form creator edits |
  115. | `quiet` | Lowercase medium sans, each line rises gently into place; no box, refined shadow. | premium brand films |
  116. Music / lyric styles (pages start on the beat; use them for songs and for speech set to music):
  117. | Style | Looks like | Best for |
  118. |---|---|---|
  119. | `downbeat` | Bold caps on flat colour fields, one to four words a page. Lines spin or slide in with overshoot on the beat; the field flips colour every few bars. | kinetic lyric videos, hooks set to music |
  120. | `billboard` | A fat lowercase serif, one or two words so big they bleed off the frame. Three flat tones swap between text and background; the pair changes every two beats. | pop songs, poster-style lyric videos |
  121. | `chalkline` | Hand-written lines that write on, left to right, over a dark chalkboard. Lines pile up down the page and indent in steps, then the page clears. The key word is bigger and gets a hand-drawn underline. Variant marker: coloured marker on paper. Also: `chalkline:marker`. | quiet, human songs; acoustic |
  122. | `singalong` | A block of up to four lyric lines; the sung part of each line fills with a soft colour, letter by letter, as it is sung. Variant lit: no fill, words light up over the picture. Also: `singalong:lit`. | karaoke and sing-along videos; `singalong:lit` over footage |
  123. ## Editing by hand
  124. `<name>.captions.json` holds every page, word, line break, highlight (`emphasis`) and its `reason` (format:
  125. `docs/ARCHITECTURE.md`). Edit it, run `python3 scripts/emphasis.py <file> --style <style>` once so page holds and giant
  126. words follow your edit, and re-render with `--captions <file>`. A style is one JSON file in `styles/`; copy one, change fonts, colours, size or
  127. timing, and pass its path to `--style`.
  128. ## Rules
  129. - Never upload the video or its audio anywhere. Do not call paid caption APIs.
  130. - Do not force the behind effect on fast pans, sports, or a subject that fills the frame: the matte lags and the text
  131. glitches. Trust the subject check.
  132. - Keep the user's words. Fix spelling; never rewrite what was said.
README.md · README · 164 lines
  1. # Subtle
  2. Animated captions for talking-head video, rendered locally.
  3. Subtle is a skill for Codex and Claude Code, with a standalone CLI. Give it a video to transcribe and animate
  4. captions in one of 35 styles. It runs on your machine without uploading the footage or asking for an API key.
  5. **See every style on a real clip: https://subtle.refs.video** (the showcase site runs the same caption engine in the
  6. browser; its source is in `site/`).
  7. ![All 35 styles on one frame](docs/stills/styles.jpg)
  8. All 35 styles on the same frame. Every one runs live at https://subtle.refs.video.
  9. Demo frames: Sam Altman on David Senra's podcast (https://www.youtube.com/watch?v=kG8AoExkX40), used only to show captions; not affiliated with or endorsed by Sam Altman, OpenAI or the show.
  10. ## Smart highlights
  11. Say "the gold price is five thousand dollars" and the caption shows **$5,000**, highlighted, in one piece.
  12. ![Highlighted numbers in four styles](docs/stills/highlights.jpg)
  13. - **The words that matter get the highlight.** Numbers, prices, percentages and dates first, then names and places, then
  14. the punchline word, then the topic the first time it comes up. Claude reads your captions and picks them, with a
  15. one-line reason for each that you can read and change. One highlight per page, two on long pages, never filler words.
  16. - **Numbers are written the way you would write them.** "five thousand dollars" and "$5000" become `$5,000`; "forty
  17. percent" becomes `40%`; "one lakh rupees" becomes `₹1 lakh`; years stay `1991`. An amount is one token: it is never
  18. split across two lines or two pages. Indian digit grouping (`₹15,00,000`) is used for rupee amounts and Hindi speech.
  19. - **Spanish works the same way.** "cinco mil dólares" becomes `$5,000`, "cuarenta por ciento" becomes `40%`, "dos mil
  20. veinticuatro" becomes `2024`, and the highlight rules use Spanish word lists. A transcript that already writes `5.000`
  21. and `3,5` keeps that convention; `--numbers european` or `--numbers western` forces one.
  22. - **Every style has its own highlight**: a serif italic, a colour, an inverted chip, a second block colour, the giant
  23. word behind the speaker. A highlighted page also stays on screen a beat longer when there is room.
  24. - **It works with no one picking, too.** Rules find the numbers, names and contrast words (`--emphasis auto`, the
  25. default). `--emphasis numbers` keeps only numbers, `--emphasis off` turns highlights off, and
  26. `--emphasis-words 'gold, $5,000'` forces words.
  27. ## Newer in v2
  28. - **Text behind the speaker, per shot.** Six styles (`keyword`, `cover`, `outline`, `poster`, `rise`, `numeral`) put the
  29. giant word behind the person. Subtle checks every shot on its own: in a wide shot the word goes behind the head, in a
  30. close-up (where it would be hidden) it is drawn in front or skipped. Needs macOS (Apple Vision cut-out).
  31. - **Smart placement.** Each page moves off the face and the hands, inside the style's allowed range, and only when it has
  32. to (`--placement auto`, the default; `off` keeps the style's own position).
  33. - **Cut-aware pages.** Hard cuts are found with ffmpeg and no page straddles one (`--cuts auto`; `off` ignores cuts).
  34. - **Automatic legibility.** Subtle measures what is behind every page and adds a soft halo, scrim or outline only where
  35. the type would not read. Clean dark footage is left untouched (`--legibility auto`; `off` draws the preset as it is).
  36. - **Palette from the footage.** Styles with an accent colour take one that suits the scene and reads on it
  37. (`--palette auto`; `off` uses the preset's colours).
  38. - **Recipe styles.** One generic style driven by a `recipe` block in the style JSON, so a new caption treatment needs
  39. no new TSX (see `docs/ARCHITECTURE.md`).
  40. ## What it does
  41. 1. Transcribes the speech with word-level timing (Whisper large-v3-turbo through `mlx-whisper`).
  42. 2. Writes spoken numbers as single tokens (`$5,000`, `40%`, `₹1 lakh`), groups the words into short, readable pages
  43. and highlights the words that matter.
  44. 3. Renders the captions in the style you pick, at the video's own size and frame rate.
  45. 4. With a behind-the-speaker style (`keyword`, `cover`, `outline`, `poster`, `rise`, `numeral`), cuts the speaker out with Apple Vision and puts the giant word behind them, shot by shot.
  46. 5. Moves pages off faces and hands, keeps them clear of cuts, and adds a halo or scrim where the footage would hide the type.
  47. 6. Checks the result (safe area, contrast, how much of each big word is visible) and makes a contact sheet.
  48. You get `<name>.captioned.mp4`, `<name>.srt`, `<name>.captions.json` (editable) and `<name>.preview.jpg`.
  49. ## Install
  50. **Codex**:
  51. ```bash
  52. git clone https://github.com/0xpratzyy/subtle ~/.agents/skills/subtle
  53. ```
  54. **Claude Code**:
  55. ```bash
  56. git clone https://github.com/0xpratzyy/subtle ~/.claude/skills/subtle
  57. ```
  58. Then ask your agent to *"add captions to ~/Movies/talk.mp4"* or *"put a giant keyword behind me"*.
  59. For the standalone CLI, clone the repo anywhere and run the commands below from that directory.
  60. ## Requirements
  61. | Need | For | Install |
  62. |---|---|---|
  63. | macOS on Apple Silicon | transcription (`mlx-whisper`) and the behind-the-speaker effect (Apple Vision) | |
  64. | ffmpeg | reading and writing video | `brew install ffmpeg` |
  65. | Node 18 or newer | the caption renderer | `brew install node` |
  66. | Python 3.9 or newer and `uv` | transcription and visual checks | `brew install uv` |
  67. | Swift (Xcode command line tools) | the behind-the-speaker styles and smart placement | `xcode-select --install` |
  68. `bash scripts/doctor.sh` checks all of this and prints what is missing. The first run downloads the speech model (about
  69. 1.6 GB) and installs the renderer's packages (about a minute). On Linux or Intel Macs you can still render captions
  70. from your own word timings (`--words`). Run `bash scripts/doctor.sh --from-timings` for this workflow.
  71. Without `uv`, install `mlx-whisper` for transcription and `numpy` and `pillow` for visual checks
  72. in the Python environment that runs Subtle.
  73. ## Styles
  74. 35 caption styles. Six of them (*behind you*) put the giant word behind the speaker, decided per shot (macOS for the person cut-out).
  75. | | | | |
  76. |---|---|---|---|
  77. | ![accent](docs/stills/accent.jpg)<br>**accent**<br>Pale-lime sans in very short pages, with the key word in a light serif italic; soft fade with a small drift. | ![block](docs/stills/block.jpg)<br>**block**<br>Every line in its own warm coloured block with depth; lines rise in with motion blur and pile up as a stack. | ![bottom](docs/stills/bottom.jpg)<br>**bottom**<br>Big bold caps low in the frame that build word by word with no animation; the key word is yellow. | ![cards](docs/stills/cards.jpg)<br>**cards**<br>White serif on a dark rounded card; the phrase appears at once, key words in red. The essay and serif-card look. |
  78. | ![chip](docs/stills/chip.jpg)<br>**chip**<br>A light rounded chip that hugs the page; words turn from grey to black as they are spoken. | ![cinema](docs/stills/cinema.jpg)<br>**cinema**<br>Tiny, wide-tracked serif capitals low in the frame that fade in and out slowly, like the subtitles of an arthouse trailer. | ![cover](docs/stills/cover.jpg)<br>**cover** *(behind you)*<br>One huge serif italic word behind the speaker's head, like a magazine masthead; the rest of the line small and tracked in front. | ![duo](docs/stills/duo.jpg)<br>**duo**<br>A big condensed caps headline word with a tiny spaced-out lead-in above and a bold italic tail below. The lead-in fades in, the headline cuts in, the tail fades in. |
  79. | ![editorial](docs/stills/editorial.jpg)<br>**editorial**<br>A bold sans lowercase line with the keyword set about three times larger in a high-contrast italic serif in cinema red, overlapping the sans. Lower-left third. | ![flip](docs/stills/flip.jpg)<br>**flip**<br>Every letter flips in like a split-flap tile, turning edge-on and settling upright with a motion-blur trail. | ![glass](docs/stills/glass.jpg)<br>**glass**<br>One frosted-glass pill per page in soft lowercase; upcoming words are dim and brighten as they are spoken. | ![glide](docs/stills/glide.jpg)<br>**glide** (default)<br>Key words in a large calligraphic script, the small words in bold white sans, on one baseline. |
  80. | ![haiku](docs/stills/haiku.jpg)<br>**haiku**<br>One small condensed serif word at a time in acid yellow. Hard cuts, no box. A hot word turns italic and a lighter yellow. | ![highlighter](docs/stills/highlighter.jpg)<br>**highlighter**<br>Bold caps with one flat box behind the word being spoken, hopping from word to word. A finished word turns lime; the hot word comes alone, large. | ![hype](docs/stills/hype.jpg)<br>**hype**<br>A calm medium-weight line in soft white with a gentle shadow; the key word turns warm yellow. Hard cut in, no outline. | ![impact](docs/stills/impact.jpg)<br>**impact**<br>Heavy round caps; every letter bounces in along an arc with overshoot and a little tilt, on a hard offset shadow. |
  81. | ![karaoke](docs/stills/karaoke.jpg)<br>**karaoke**<br>The whole line shows dim; each word turns solid as it is spoken. One weight, no motion. | ![keyword](docs/stills/keyword.jpg)<br>**keyword** *(behind you)*<br>One giant pale-lime keyword behind the speaker, the other words small and stacked beside it. | ![magazine](docs/stills/magazine.jpg)<br>**magazine**<br>A tight justified block like an ad super: keywords in big serif italic, glue words in small grotesk capitals, every line the same width. | ![newsroom](docs/stills/newsroom.jpg)<br>**newsroom**<br>Bold yellow sans, every word on screen at once, the word being spoken turns white; soft black outline, lower third. The news-explainer look. |
  82. | ![numeral](docs/stills/numeral.jpg)<br>**numeral** *(behind you)*<br>Numbers, years and names go giant behind the speaker, digits rolling into place like an odometer; everything else stays small in front. | ![outline](docs/stills/outline.jpg)<br>**outline** *(behind you)*<br>A giant hollow word behind the speaker that draws on, then fills with colour as it is spoken; a small bold line in front. | ![poster](docs/stills/poster.jpg)<br>**poster** *(behind you)*<br>Two or three words stacked behind the speaker, each line a different face fitted to the same width, like a film poster's title block. | ![punch](docs/stills/punch.jpg)<br>**punch**<br>Heavy upper-case sans that pops in word by word with overshoot; the spoken word swells and turns lime, thick black outline. The short-form creator look. |
  83. | ![quiet](docs/stills/quiet.jpg)<br>**quiet**<br>Lowercase medium sans, each line rises gently into place; no box, a refined soft shadow. The premium brand-film look. | ![rise](docs/stills/rise.jpg)<br>**rise** *(behind you)*<br>The giant word climbs out from behind the speaker's shoulders letter by letter, and sinks back when the word is done. | ![serif](docs/stills/serif.jpg)<br>**serif**<br>Display serif italic filled with a top-lit silver gradient; quiet and luxurious. | ![shine](docs/stills/shine.jpg)<br>**shine**<br>Serif italic in one accent colour; a diagonal band of light sweeps across each word, then a soft glow fades. |
  84. | ![split](docs/stills/split.jpg)<br>**split**<br>Words alternate to the two sides of the speaker and step down around the head like a staircase, never over the face. | ![stack](docs/stills/stack.jpg)<br>**stack**<br>A tilted, overlapping pile of words, each at its own size and angle, key words in yellow; the tilt mirrors on alternate pages. | ![sticker](docs/stills/sticker.jpg)<br>**sticker**<br>Rounded pink bubbles, one per line, each new line offset to the right of the last and stacked like typed messages; the stack tilts a little more on every page. Words are dark until spoken, then white. | ![terminal](docs/stills/terminal.jpg)<br>**terminal**<br>Green monospace typed character by character with a blinking block cursor. |
  85. | ![ticket](docs/stills/ticket.jpg)<br>**ticket**<br>A hard-edged label tight around the text, tilted a different angle on every page. The hot word sits alone on a big label, filler phrases on a small one. Hard cuts. Colourway: yellow. | ![title](docs/stills/title.jpg)<br>**title**<br>A typed title whose letter spacing collapses as the letters arrive, with a small handwritten note under it. | ![whisper](docs/stills/whisper.jpg)<br>**whisper**<br>Lowercase warm-yellow text; each word is revealed by a soft left-to-right wipe and the page dissolves with a blur. | |
  86. A style is one JSON file in `styles/` plus one small component in `template/src/styles/`. Copy a preset, change the
  87. font, colours, size or timing, and pass its path to `--style`. Some styles have colourways: `--style ticket:yellow`.
  88. `python3 scripts/subtle.py --list-styles` prints them all.
  89. ## Use it from the command line
  90. ```bash
  91. python3 scripts/subtle.py talk.mp4 # glide
  92. python3 scripts/subtle.py talk.mp4 --style glass # frosted-glass pill
  93. python3 scripts/subtle.py talk.mp4 --style keyword # a giant keyword behind the speaker
  94. python3 scripts/subtle.py talk.mp4 --style cover --legibility off --palette off # behind a headline, preset colours
  95. python3 scripts/subtle.py talk.mp4 --style ticket:yellow # a colourway of a style
  96. python3 scripts/subtle.py talk.mp4 --style accent --emphasis-words 'gold, $5,000' --vocab "Meera, RBI"
  97. python3 scripts/subtle.py talk.mp4 --emphasis numbers # highlight only numbers, prices, percentages and years
  98. python3 scripts/subtle.py talk.mp4 --hinglish # Hindi written in Latin letters
  99. python3 scripts/subtle.py talk.mp4 --lang es # Spanish (detected by itself when --lang is left out)
  100. python3 scripts/subtle.py talk.mp4 --aspect 9:16 # centre-crop first
  101. python3 scripts/subtle.py talk.mp4 --placement off --cuts off # keep the style's own position, ignore cuts
  102. python3 scripts/subtle.py talk.mp4 --behind off # draw giant words in front, never behind
  103. python3 scripts/subtle.py talk.mp4 --captions talk.captions.json # re-render after editing the captions
  104. ```
  105. The transcript is cached by the file's hash, so trying another style does not transcribe again.
  106. ## Limits
  107. - The behind-the-speaker effect (`keyword`, `cover`, `outline`, `poster`, `rise`, `numeral`) works best with one person and a steady camera. Fine hair, fast hand
  108. movement and fast pans show at the matte edge. Subtle checks the subject first and draws the words in front when it
  109. would look bad.
  110. - Styles without a container (soft-shadow text) can be hard to read on bright or busy footage; the check warns about
  111. low contrast and suggests `glass`, `chip` or `block`.
  112. - Whisper spells Hindi words in Latin letters unevenly. Read the transcript before rendering and fix words with
  113. `--replace heard=Shown`.
  114. - A giant number is never put behind the speaker in `keyword` (hidden digits would change it): it is drawn in front. `numeral` is built for numerals behind the speaker.
  115. - Word timings come from Whisper's attention, not forced alignment. They are usually within a frame or two; very fast
  116. speech can drift.
  117. ## Licences
  118. Subtle's code is MIT. The bundled fonts are under the SIL Open Font License. The default renderer uses
  119. [Remotion](https://www.remotion.dev), which is free for individuals and companies of up to 3 people; larger companies
  120. need a Remotion company licence. Details for every dependency are in [THIRD_PARTY.md](THIRD_PARTY.md).
  121. The showcase site (`site/`) uses a third-party clip for demo only. That media is not in this repo; see
  122. [site/README.md](site/README.md) for how to make your own.
  123. How the pieces fit together: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  124. ---
  125. Made by [Refs](https://refs.video).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.