YouTube Chapter Clipper
Overview
Generate chapter clips from a YouTube video by downloading MP4 + English subtitles, segmenting content, cutting clips, and producing per-chapter English SRTs. Chapter length is user-selectable (1-2, 2-3, or 3-4 minutes).
Workflow
1) Use the automation script to reduce tokens
- Prefer
scripts/smart_edit.pyfor end-to-end runs (download, chaptering, clip cut, subtitle slicing). - The script uses heuristic chaptering to avoid AI token usage.
- Create and use a local venv (no external packages required):
- python3 -m venv.venv - source.venv/bin/activate - python scripts/smart_edit.py --help - Speed-focused default: --mode fast (approximate cuts, faster encode, optional downscale). - Use --mode accurate when you need precise boundaries.
2) Confirm inputs and environment
- Ask for the YouTube URL and whether English subtitles are available (manual preferred; auto as fallback).
- Check tools:
yt-dlpandffmpeg. If missing, install before proceeding. - Use command templates in
references/commands.md.
3) Download source video and subtitles
- Check current directory for existing source files before downloading:
- If <id>.mp4 and <id>.en.vtt already exist, skip yt-dlp download.
- Download highest 1080p MP4 and English VTT. Save in current directory with ID-based names:
- <id>.mp4 - <id>.en.vtt (or <id>.en.auto.vtt if manual subs absent)
- Also capture video metadata (id, title, duration, uploader) for reporting.
- The script handles this when --url is provided.
4) Prepare output directory
- Create output directory using the original video title:
- Replace spaces with underscores. - Remove/replace filesystem-unsafe characters.
- Place all chapter clips and subtitle files into this directory.
5) Generate fine-grained chapters (user-selected length)
- Ask the user to choose a chapter length preset: 1-2, 2-3, or 3-4 minutes.
- Perform AI analysis (critical step):
- Read the full subtitle content. - Understand the semantic flow and topic transitions. - Identify natural topic switch points.
- Draft chapter boundaries based on semantic topic changes and sentence boundaries.
- Target the selected range; avoid cutting mid-sentence.
- Prefer semantic breaks (new concept, example, recap) over strict timing.
- Produce a chapter list with:
- title, start, end, reason - The script uses --chapter-preset (or --min-seconds/--target-seconds/--max-seconds for custom).
6) Cut precise clips (speed vs accuracy)
- Use ffmpeg with accurate trimming and stable outputs. Always re-encode:
- Place -ss after -i for accurate seeking. - Use libx264 + aac, -movflags +faststart, and -pix_fmt yuv420p to maximize player compatibility. - Use a fast preset (e.g., -preset veryfast) to avoid long encodes and timeouts.
- Run clips serially and avoid external timeouts that kill ffmpeg mid-write.
- After each clip, validate with
ffprobe; retry once if validation fails. - If speed is the priority (listening practice), prefer approximate cuts:
- Put -ss before -i to avoid decoding from the start every time. - Use -preset ultrafast and a higher CRF (e.g., 28). - Optionally downscale (e.g., width 1280) to reduce encode time.
- Name each clip with an ordered prefix:
<nn>_<chapter_title>.mp4using safe filenames:
- Use a 2-digit index starting at 01. - Replace spaces with underscores. - Remove filesystem-unsafe characters.
7) Extract and convert subtitles per chapter
- Extract VTT segment for each chapter by time range.
- Convert each segment to SRT:
- <nn>_<chapter_title>.en.srt - The script deletes per-chapter VTT unless --keep-vtt is set.
8) Report outputs
- Print output directory path, chapter list, and generated files.
Output Rules
- Source files stay in current directory (
<id>.mp4,<id>.en.vtt). - All chapter clips and subtitle files are placed in the per-video directory named after the sanitized title.
- Use consistent time formats (
HH:MM:SS.mmm).
References
- Command templates and copy/paste examples:
references/commands.md - Automation:
scripts/smart_edit.py