YouTube Chapter Clipper

Overview

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