add-subtitles

Add Subtitles to a Video

Take a video the user uploads (or a path to a local file) and produce a new video with styled, burned-in subtitles — ready for social media. Audio is transcribed automatically with Whisper, so no transcript or YouTube source is required.

This skill reuses burn_subtitles.py from the get-y2b-clips skill, but is scoped to the single task of subtitling an already-provided video file.

When to Use This Skill

Activate when the user:

• Uploads or references a local video file and asks to "add subtitles" / "add captions"
• Wants a subtitled / captioned version of an existing clip for social media
• Has a video (not a YouTube URL) and wants burned-in text

If the user provides a YouTube URL and wants clips extracted, use get-y2b-clips instead. This skill is for a video the user already has.

Dependencies Check

ALWAYS check dependencies first:

# ffmpeg is required to burn subtitles
command -v ffmpeg || echo "MISSING: ffmpeg"

# stable-ts (Whisper) is required to transcribe the audio
python3 -c "import stable_whisper" 2>/dev/null && echo "stable-ts OK" || echo "MISSING: stable-ts"

Install Missing Dependencies

ffmpeg:

# macOS
brew install ffmpeg
# Linux
sudo apt update && sudo apt install -y ffmpeg

stable-ts (Whisper):

pip3 install stable-ts

Input Requirements

• Required: Path to a local video file (e.g. ./videos/my-clip.mp4)
• Optional (ask only if relevant):
  • Font size (default: 24)
  • Whisper model size — tiny/base/small/medium/large (default: base). Suggest small or medium for higher accuracy on longer or harder audio.
  • Output path (default: same folder, <name> Subtitled.mp4)
  • Whether to keep the generated .srt file (default: no)

Locating the uploaded video

If the user uploaded a file but didn't give a path, look for it:

# Common locations for an uploaded/provided video
ls -la ./videos/ 2>/dev/null
find . -maxdepth 3 -type f \( -iname "*.mp4" -o -iname "*.mov" -o -iname "*.mkv" -o -iname "*.webm" \) -mmin -120 2>/dev/null