yt-chapters

Generate accurate YouTube chapters from the final edited video at $ARGUMENTS. ## Workflow Context **Final step of the weekly content pipeline** — runs post-edit when the editor delivers the final `.mp4`. Do NOT run this before filming or editing. After this, the description is ready to copy-paste into YouTube. ## Flow ### Step 1: Parse Input From $ARGUMENTS, extract: - **Video path**: The local `.mp4` file (required) - **Slug** (optional): `--slug <video-slug>` to identify the video package at `~/content/youtube/<slug>/` If no slug is provided: - Check if the video filename or parent folder matches an existing `~/content/youtube/<slug>/` package - If not, ask the user: **"Which video package does this belong to?"** and list existing packages from `~/content/youtube/` If the video path doesn't exist, ask the user for the correct path. ### Step 2: Extract Audio Extract the audio track from the video using ffmpeg: ``` ffmpeg -i "<video_path>" -vn -acodec libmp3lame -q:a 2 ~/content/transcripts/chapters_audio_<slug>.mp3 -y ``` This is faster and smaller than processing the full video file. ### Step 3: Transcribe Transcribe the extracted audio using the transcribe skill's script: ``` python3 ~/.claude/skills/transcribe/transcribe_video.py ~/content/transcripts/chapters_audio_<slug>.mp3 ``` Read the resulting transcript file. It should contain timestamped segments. ### Step 4: Identify Chapters Analyze the transcript to identify natural chapter breaks. Look for: - **Topic transitions** — When the speaker shifts to a new subject - **Section markers** — Phrases like "next", "now let's", "moving on", "the first thing", "step one" - **Demo transitions** — Shifts between talking and showing something - **Energy shifts** — New introductions of concepts after a conclusion of the previous one Generate **5-15 chapters** depending on video length: - Videos under 5 min: 3-5 chapters - Videos 5-15 min: 5-10 chapters - Videos 15+ min: 8-15 chapters For each chapter: - **Timestamp** in `MM:SS` format (or `H:MM:SS` for videos over 1 hour) - **Title** — Short, descriptive, 2-6 words The first chapter MUST be `0:00 - Introduction` (or a more specific hook title). ### Step 5: Read Existing Description Read `~/content/youtube/<slug>/description.md` if it exists. Identify: - Is there an existing chapters section with `[UPDATE]` placeholders? - What's the overall structure of the description? ### Step 6: Present Chapters to User Show the user the generated chapters: ``` 0:00 - Introduction 0:45 - Setting Up the Project 2:12 - First Demo ... ``` Ask: **"Do these chapters look right? Want to adjust any timestamps or titles?"** ### Step 7: Update Description After the user approves (or after revisions): **If `description.md` exists with placeholder chapters:** - Replace the entire chapters section (the `[UPDATE]` placeholders) with the real timestamps **If `description.md` exists without a chapters section:** - Add a chapters section in the appropriate location (after the main body, before the CTA/links). Do not add a tags or hashtag line to the description — tags belong in `tags.txt` (YouTube tags field) only. **If no `description.md` exists:** - Create `~/content/youtube/<slug>/description.md` with just the chapters section and a note to fill in the rest Show the user the updated description and confirm the file was saved. ### Step 8: Cleanup Delete the temporary audio file: ``` rm ~/content/transcripts/chapters_audio_<slug>.mp3 ``` Report what was done: - Transcript location - Updated description path - Number of chapters generated ## Rules - Always extract audio first — don't try to transcribe the full video file directly (it's slower and larger) - Chapters must start at `0:00` — YouTube requires this - Chapter titles should be concise (2-6 words) — they appear in the progress bar - Minimum 3 chapters for YouTube to recognize them as chapters - Timestamps must be accurate to within ~5 seconds — round to clean numbers when the transition isn't instant - Don't create chapters shorter than 10 seconds — YouTube may not display them - When updating `description.md`, preserve all existing content outside the chapters section - Clean up the temporary mp3 after transcription - If the transcription doesn't have clear timestamps, estimate based on word count (~150 words per minute of speech)