Clip Hand Skill

IMPORTANT: ffmpeg filter paths (-vf "subtitles=...") always need forward slashes. On Windows with absolute paths, escape the colon: subtitles=C\\:/Users/me/clip.srt

Prefer using file_write tool for creating SRT/text files instead of shell echo/heredoc.

yt-dlp Reference

Download with Format Selection

# Best video up to 1080p + best audio, merged
yt-dlp -f "bv[height<=1080]+ba/b[height<=1080]" --restrict-filenames -o "source.%(ext)s" "URL"

# 720p max (smaller, faster)
yt-dlp -f "bv[height<=720]+ba/b[height<=720]" --restrict-filenames -o "source.%(ext)s" "URL"

# Audio only (for transcription-only workflows)
yt-dlp -x --audio-format wav --restrict-filenames -o "audio.%(ext)s" "URL"

Metadata Inspection

# Get full metadata as JSON (duration, title, chapters, available subs)
yt-dlp --dump-json "URL"

# Key fields: duration, title, description, chapters, subtitles, automatic_captions

YouTube Auto-Subtitles

# Download auto-generated subtitles in json3 format (word-level timing)
yt-dlp --write-auto-subs --sub-lang en --sub-format json3 --skip-download --restrict-filenames -o "source" "URL"

# Download manual subtitles if available
yt-dlp --write-subs --sub-lang en --sub-format srt --skip-download --restrict-filenames -o "source" "URL"

# List available subtitle languages
yt-dlp --list-subs "URL"

Useful Flags

• --restrict-filenames — safe ASCII filenames (no spaces/special chars) — important on all platforms
• --no-playlist — download single video even if URL is in a playlist
• -o "template.%(ext)s" — output template (%(ext)s auto-detects format)
• --cookies-from-browser chrome — use browser cookies for age-restricted content
• --extract-audio / -x — extract audio only
• --audio-format wav — convert audio to wav (for whisper)

Whisper Transcription Reference

Audio Extraction for Whisper

# Extract mono 16kHz WAV (whisper's preferred input format)
ffmpeg -i source.mp4 -vn -ar 16000 -ac 1 -y audio.wav

Basic Transcription

# Standard transcription with word-level timestamps
whisper audio.wav --model small --output_format json --word_timestamps true --language en

# Faster alternative (same flags, 4x speed)
whisper-ctranslate2 audio.wav --model small --output_format json --word_timestamps true --language en

Model Sizes

Note: On macOS Apple Silicon, consider mlx-whisper as a faster native alternative.

JSON Output Structure

{
  "text": "full transcript text...",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 4.52,
      "text": " Hello everyone, welcome back.",
      "words": [
        {"word": " Hello", "start": 0.0, "end": 0.32, "probability": 0.95},
        {"word": " everyone,", "start": 0.32, "end": 0.78, "probability": 0.91},
        {"word": " welcome", "start": 0.78, "end": 1.14, "probability": 0.98},
        {"word": " back.", "start": 1.14, "end": 1.52, "probability": 0.97}
      ]
    }
  ]
}

• segments[].words[] gives word-level timing when --word_timestamps true
• probability indicates confidence (< 0.5 = likely wrong)

YouTube json3 Subtitle Parsing

Format Structure

{
  "events": [
    {
      "tStartMs": 1230,
      "dDurationMs": 5000,
      "segs": [
        {"utf8": "hello ", "tOffsetMs": 0},
        {"utf8": "world ", "tOffsetMs": 200},
        {"utf8": "how ", "tOffsetMs": 450},
        {"utf8": "are you", "tOffsetMs": 700}
      ]
    }
  ]
}

Extracting Word Timing

For each event and each segment within it:

• word_start_ms = event.tStartMs + seg.tOffsetMs
• word_start_secs = word_start_ms / 1000.0
• word_text = seg.utf8.trim()

Events without segs are line breaks or formatting — skip them. Events with segs containing only "\n" are newlines — skip them.

SRT Generation from Transcript

SRT Format

1