youtube-chapter-clipper（YouTube 章节剪辑器）

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.py for 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-dlp and ffmpeg. 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>.mp4 using 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