youtube-clipper

name	youtube-clipper
description	YouTube video smart clipping tool. Downloads video and subtitles, uses AI to analyze and generate fine-grained chapters (2-5 minute segments), lets user select clips, then auto-clips, translates subtitles to bilingual format, burns subtitles, and generates summary copy. Use when: clipping YouTube videos, generating short clips, making bilingual subtitle versions, creating Shorts/Reels/TikTok from long-form video. Keywords: video clip, YouTube, subtitle translation, bilingual subtitles, video download, shorts, reels, tiktok, yt-dlp, ffmpeg, clip video
allowed-tools	["Read","Write","Bash","Glob","AskUserQuestion"]

YouTube Video Smart Clipper

Workflow — 6 Phases

Phase 1: Environment Check

Verify required tools are installed:

yt-dlp --version
ffmpeg -version
ffmpeg -filters 2>&1 | grep subtitles   # verify libass for subtitle burn
python3 -c "import pysrt; print('ok')"

If missing:

• yt-dlp: brew install yt-dlp or pip install yt-dlp
• FFmpeg without libass (macOS): brew install ffmpeg-full
• Python deps: pip install pysrt

Note: Standard Homebrew FFmpeg lacks libass. On macOS install ffmpeg-full. On Windows, gyan.dev FFmpeg builds include libass.

---

Phase 2: Download Video

Ask user for YouTube URL, then download video + English subtitles:

yt-dlp -f "bestvideo[height<=1080][ext=mp4]+bestaudio/best" \
  --write-auto-sub --sub-lang en --convert-subs srt \
  -o "%(id)s.%(ext)s" <youtube_url>

Show user: title, duration, file size, download path.

Output: <id>.mp4 + <id>.en.srt

If 429 rate limit on subtitles: download video first (--no-write-subs), then retry subtitle download separately after a delay.

---

Phase 3: AI Chapter Analysis

Parse the subtitle file and analyze content semantically:

1. Read full subtitle text with timestamps
2. Identify natural topic transitions
3. Generate chapters at 2-5 minute granularity (not coarse 30-minute cuts)

For each chapter provide:

• Title: concise topic summary (10-20 words)
• Time range: start → end (MM:SS or HH:MM:SS)
• Summary: 1-2 sentences on what this segment covers
• Keywords: 3-5 key concepts

Show numbered chapter list with all segments covered, no gaps.

---

Phase 4: User Selection

Ask user which chapters to clip (multi-select by number).

Also ask:

• Generate bilingual subtitles? (original + translated)
• Burn subtitles into video? (hardcoded)
• Generate summary copy for social media?

---

Phase 5: Process Selected Clips

For each selected chapter:

5.1 — Cut clip

ffmpeg -i input.mp4 -ss <start> -to <end> -c copy clip.mp4

5.2 — Extract subtitle segment

Filter subtitle entries within the time range, reset timestamps to start from 00:00:00.

5.3 — Translate subtitles (if requested)

Batch translate in groups of 20 entries to minimize API calls. Target language: user's preferred language. Keep technical terms accurate; use natural spoken language suitable for short video.

5.4 — Generate bilingual SRT (if requested)

Merge original + translated lines into dual-language SRT (original on top, translation below).

5.5 — Burn subtitles (if requested)

ffmpeg -i clip.mp4 -vf "subtitles=subs.srt:force_style='FontSize=24,MarginV=30,Bold=1'" \
  -c:v libx264 -crf 18 -c:a copy output_with_subs.mp4

Windows path fix: copy files to tempfile.mkdtemp() before running FFmpeg to avoid subtitle filter failures on paths with spaces.

5.6 — Generate summary copy (if requested)

Based on chapter title, summary, and keywords — generate social media copy (title, key points, platform-appropriate format).

---

Phase 6: Output Results

Organize output under ./youtube-clips/<datetime>/:

<chapter-title>/
├── clip.mp4                  # raw cut
├── clip_with_subtitles.mp4   # burned subtitle version
├── bilingual.srt             # bilingual subtitle file
└── summary.md                # social media copy

Show file list with sizes and quick-open commands. Ask if user wants to clip more chapters.

---

9:16 Vertical (Shorts / Reels / TikTok)

When user requests vertical format — use blurred background fill, never crop:

[0:v]split[bg][fg];
[bg]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,gblur=sigma=40[blurred];
[fg]scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black@0[front];
[blurred][front]overlay=0:0,subtitles=subs.srt:force_style='FontSize=28,MarginV=120,Bold=1'

Rules:

• Never crop original content — presenter/slides must be fully visible
• Place subtitles in the lower blurred area (MarginV=120)
• Black letterbox padding is not acceptable — blurred background only

---

RTL Subtitles (Hebrew / Arabic)

Basic burn with SRT works for simple subtitles. For per-word karaoke highlight with RTL:

• Each word needs its own ASS Dialogue line with \pos(x,y) — no inline tags within a text run
• Use PIL to measure word widths with ~0.74 scale factor (PIL→libass calibration)
• Use Alignment=7 and Encoding=177 (Hebrew) in ASS style
• Render punctuation as separate positioned elements to the left of the last word
• Use two named ASS styles (e.g., White + Yellow) instead of inline \c color tags

Critical: Inline ASS tags (\c, \K, etc.) between RTL words break Unicode bidi in libass — causing words to render left-to-right. Always use separate Dialogue lines per word.

---

Shorts Mode (~40s clips)

When user wants highlights rather than full chapters, identify:

1. Strong hook — opening line that grabs attention immediately
2. Pain point — relatable problem statement
3. WOW moment — impressive demo or revelation
4. Core value prop — clear, concise statement of the main idea
5. Counter-intuitive insight — breaks common assumptions

For each candidate clip provide: timestamps, content summary, why it works as a short, suggested title.

---

Key Technical Notes

• Batch translation (20 entries/call) saves ~95% API calls vs per-entry
• Chapter granularity: semantic topic transitions, not mechanical time splits
• File naming: strip special chars (/ \ : * ? " < > |), replace spaces with _, max 100 chars
• Windows encoding: set PYTHONIOENCODING=utf-8 when running Python scripts that print Unicode