Caption YouTube Clips

Download YouTube video clips with timestamps, transcribe with Deepgram, and burn styled captions.

Prerequisites

• yt-dlp installed
• ffmpeg installed
• DEEPGRAM_API_KEY in .env file (or environment variable)
• Avenir Next font (falls back to Arial if unavailable)

Workflow

Step 1: Download Clip

Download a specific section of a YouTube video using yt-dlp:

yt-dlp --download-sections "*START-END" -o "clip_name.%(ext)s" "YOUTUBE_URL"

Example with timestamps 02:53-04:15:

yt-dlp --download-sections "*02:53-04:15" -o "clip_intro.%(ext)s" "https://www.youtube.com/watch?v=VIDEO_ID"

Step 2: Convert to MP4

Ensure consistent encoding with ffmpeg defaults:

ffmpeg -i clip_name.webm -y clip_name.mp4

Step 3: Transcribe with Deepgram

Load API key from .env and call Deepgram API:

DEEPGRAM_API_KEY=$(grep '^DEEPGRAM_API_KEY=' .env | cut -d'=' -f2 | tr -d '"' | tr -d "'")

curl -s --request POST \
  --url 'https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&punctuate=true&utterances=true' \
  --header "Authorization: Token $DEEPGRAM_API_KEY" \
  --header 'Content-Type: audio/mp4' \
  --data-binary @clip_name.mp4 > clip_transcript.json

Step 4: Generate SRT

Convert Deepgram JSON to SRT format using bundled script:

python3 ~/.claude/skills/caption-clip/scripts/json-to-srt.py clip_transcript.json clip.srt

Step 5: Clean Up Transcription

Read the generated SRT file and create a cleaned version (clip_clean.srt):

1. Fix transcription errors - Correct misheard words
2. Remove filler words - Delete: "like", "you know", "I'd say", "yeah", "um", "uh", "sort of", "kind of"
3. Consolidate fragments - Merge short utterances into complete sentences
4. Improve readability - Adjust phrasing to flow better when read vs. heard
5. Fix timestamps - Ensure no invalid times (e.g., 00:00:60 should be 00:01:00)

Write the cleaned content to clip_clean.srt.

Step 6: Burn Captions

Apply styled subtitles with semi-transparent background:

ffmpeg -i clip_name.mp4 \
  -vf "subtitles=clip_clean.srt:force_style='FontSize=24,FontName=Avenir Next Medium,PrimaryColour=&H00FFFFFF,BackColour=&H80000000,BorderStyle=4,Outline=0,Shadow=0,MarginV=30,MarginL=40,MarginR=40'" \
  -c:a copy -y clip_captioned.mp4

Caption Styling Reference

| Parameter | Value | Description | |-----------|-------|-------------| | FontSize | 24 | Point size | | FontName | Avenir Next Medium | Clean sans-serif (use Arial as fallback) | | PrimaryColour | &H00FFFFFF | White text (AABBGGRR format) | | BackColour | &H80000000 | 50% transparent black background | | BorderStyle | 4 | Opaque box using BackColour | | MarginV | 30 | Vertical margin from bottom | | MarginL/R | 40 | Horizontal margins |

Alternative Fonts

If Avenir Next is unavailable, these work well for captions:

• SF Pro Display
• Helvetica Neue
• Futura
• Arial (universal fallback)

Check available fonts:

fc-list : family | sort -u | grep -iE '(avenir|sf pro|helvetica|futura)'

Output Files

After completing the workflow:

| File | Description | |------|-------------| | clip_name.mp4 | Original downloaded clip | | clip_transcript.json | Raw Deepgram transcription (preserved for re-runs) | | clip.srt | Auto-generated subtitles | | clip_clean.srt | Cleaned/edited subtitles | | clip_captioned.mp4 | Final video with burned-in captions |