/sub-packages/yt-tools/CLAUDE.md

CLAUDE.md at /sub-packages/yt-tools/CLAUDE.md

Path: sub-packages/yt-tools/CLAUDE.md

yt-tools

YouTube video processing tools for guide article creation. Downloads videos, extracts frames, and fetches transcripts.

Prerequisites

Install via Homebrew:

brew install yt-dlp ffmpeg

Then set up the Python venv:

pnpm setup

This creates .venv/ with youtube-transcript-api installed.

Commands

All commands run from sub-packages/yt-tools/.

Command	Description
`pnpm download <youtube-url>`	Download video, metadata, and transcript
`pnpm capture <video-id-or-dir> <timestamps...>`	Capture frames at specific timestamps
`pnpm capture:auto <video-id-or-dir> [--interval=N]`	Auto-extract frames every N seconds (default: 2)
`pnpm list`	List all downloaded videos
`pnpm info <video-id-or-dir>`	Show detailed info about a downloaded video
`pnpm setup`	Set up Python virtual environment

Storage Location

All downloads go to ~/youtube-dl/ (not in the repo). Video files are large and centrally managed.

Directory Structure

Each downloaded video creates:

~/youtube-dl/{YYYYMMDD}-{videoId}-{slug}/
├── transcript/
│   ├── transcript.json     # Full transcript with timestamps
│   └── transcript.txt      # Plain text version
├── movies/
│   └── video.mp4           # Downloaded video
└── captures/
    ├── capture-00-00-00.jpg
    ├── capture-00-00-02.jpg
    └── ...                 # Frames at captured timestamps

Naming Convention

{YYYYMMDD} — date of download
{videoId} — 11-character YouTube video ID
{slug} — kebab-cased video title, truncated to 50 chars

Example: 20260326-2E0bAefWr4g-how-to-use-a-modular-synth

Video Lookup

Commands accept either:

A YouTube video ID (e.g., 2E0bAefWr4g) — scans ~/youtube-dl/ for matching directories
A full directory name (e.g., 20260326-2E0bAefWr4g-how-to-use-a-modular-synth)

Capture Timestamps

Timestamps for manual capture can be in these formats:

SS (e.g., 30)
MM:SS (e.g., 1:30)
HH:MM:SS (e.g., 1:02:30)

Auto-capture uses ffmpeg’s fps filter to extract frames at regular intervals.