# Karaoke Captions

Generate TikTok/Shorts-style karaoke captions using MLX Whisper, ASS subtitles, and...

- Repository: https://github.com/AI-Builder-Club/skills (1308 stars)
- Category: Media
- License: see repository
- Last updated: 2026-09-15
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add AI-Builder-Club/skills --skill karaoke-captions -g -a claude-code -y`
Codex: `npx skills add AI-Builder-Club/skills --skill karaoke-captions -g -a codex -y`
Cursor: `npx skills add AI-Builder-Club/skills --skill karaoke-captions -g -a cursor -y`
Gemini CLI: `npx skills add AI-Builder-Club/skills --skill karaoke-captions -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add AI-Builder-Club/skills`

## Description

Generate TikTok/Shorts-style karaoke captions using MLX Whisper, ASS subtitles, and FFmpeg libass. Use when burning word-level highlight captions into a video, matching caption style from a screenshot, rendering ASS karaoke subtitles, or when the user runs /karaoke-captions.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Karaoke Captions Skill

Generate dynamic, TikTok/Shorts-style karaoke captions with word-level highlight sweeps using ASS subtitles and FFmpeg `libass`. Supports style matching from a reference screenshot.

Scripts, presets, and references live next to this skill. Run the commands from the skill directory (or pass absolute paths).

## Requirements

- macOS with Apple Silicon (MLX Whisper)
- Python 3.10+
- [FFmpeg](https://ffmpeg.org/) with `libass` (`brew install ffmpeg`)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

```text
reference.png --------(match_style_from_image.py)--------> style.json --+
                                                                   +--(gen_ass.py)--> captions.ass --(render.sh)--> output.mp4
input.mp4 ---------------------------------->(extract_words.py)--> words.json --+
```

---

## File Architecture

| File | Purpose | Role |
|---|---|---|
| `input.mp4` | Source video | Input |
| `reference.png` | Style reference image (optional) | Visual Prompt |
| `words.json` | Word-level timestamps `[{"word": ..., "start": ..., "end": ...}]` | Persistent Raw Data |
| `style.json` | Font, size, highlight color, outline, soft shadow, margin, words per line | Style Config |
| `captions.ass` | ASS subtitle script with two-layer blurred drop shadow and inline color overrides | Generated Intermediate |
| `output.mp4` | Final video with burned-in subtitles | Output Deliverable |

---

## Standard Workflow

### Step 1. Extract Word Timestamps

```bash
python scripts/extract_words.py \
  input.mp4 words.json \
  --model mlx-community/whisper-large-v3-turbo
```

*(For Chinese videos, add `--language zh`)*.

### Step 2. Select Style or Auto-match from Reference Image

The rest: https://github.com/AI-Builder-Club/skills/blob/HEAD/skills/karaoke-captions/SKILL.md