Build a searchable markdown library from YouTube videos

Builds a personal library of YouTube talks for study, where each video becomes one plain markdown file holding slide snapshots at their timestamps, a full timestamped transcript, and editable notes. A small bundled server renders the library as an interactive deep-dive in the browser. There is no database and no cloud service - everything is files on disk, fully owned by the user.

The markdown library is the single source of truth; the HTML artifact is a thin shell that fetches from the server and writes notes back, never hardcoding video data. The library lives in a plain folder set by VIDEO_LIBRARY_DIR (default ~/video-deepdives/), with one markdown file per video named by its YouTube id, frontmatter holding video metadata plus a slides array, a body holding the full transcript as [HH:MM:SS] text lines, and a _media/ folder holding slide images namespaced per video as <youtube_id>-slide-NN.jpg to avoid collisions. The server, scripts/serve.py, is a single stdlib-plus-PyYAML file started with python3 scripts/serve.py --dir ~/video-deepdives --port 8000; it serves the artifact plus an API (list videos, fetch one video's meta/body, serve a slide image, and PATCH a video's slides array to write notes back) and picks up new videos automatically the moment a markdown file exists.

Adding a video follows an eight-step pipeline, all via scripts in scripts/: (1) setup.sh resolves the YouTube id, creates a private scratch directory, and checks whether embedding is allowed via oembed - if blocked, the artifact degrades to an "open on YouTube" link rather than failing; (2) download.sh uses yt-dlp to grab the video (720p is plenty) and the best available subtitles (manual if present, else auto-captions) as .vtt, plus title/uploader; (3) detect_slides.sh runs ffmpeg scene detection (select='gt(scene,0.3)', tunable 0.2-0.4) to write candidate slide timestamps; (4) contact_sheet.py builds a labeled contact sheet for a human-judgment curation step - keeping real content slides and dropping talking-head shots, transitions, duplicates, and blurry frames, typically yielding 15-25 slides; (5) extract_slides.py extracts the curated timestamps at 1280px JPEG into _media/, printing a slides.json scaffold to stdout; (6) vtt_to_transcript.py parses the VTT into clean, de-duplicated timestamped lines, collapsing YouTube's rolling auto-caption repetition; (7) notes are written per slide (1-3 sentences grounded in the transcript, never invented) and write_library_item.py assembles the final markdown file with frontmatter and body; (8) serve.py plus verify.sh confirm the collection list, item, slide image, and artifact all return HTTP 200 and the new id appears in the index.

Use it to build a personal, ownable study library from YouTube talks - slides, transcript, and notes together in one place.

Do NOT hardcode video data into the HTML artifact - it fetches from the server. Do NOT touch existing videos' files when adding a new one; each video is an independent file. Do NOT reuse bare slide-NN.jpg filenames across videos - always namespace by YouTube id to avoid image collisions. Do NOT dump raw VTT captions into the markdown body - use the provided parser, since raw auto-captions duplicate rolling text.

Requires yt-dlp and ffmpeg on PATH, plus Python 3 with Pillow and PyYAML (pip install yt-dlp pillow pyyaml). Input is a YouTube URL or id; output is one markdown file per video (frontmatter with metadata and a slides array, body with the full timestamped transcript) plus numbered slide JPEGs in _media/, served locally with no external hosting. Do not use em dashes or arrows in notes or titles.

The server exposes a small local API namespace (/api/video-deepdives and related routes) that only the bundled artifact talks to. The markdown files themselves are portable and readable in Obsidian or any editor, since the frontmatter is standard YAML - there is no orchestrator, no database, and no cloud dependency beyond the one-time YouTube download.

Anyone building a personal, searchable study library from YouTube talks - conference videos, lectures, product walkthroughs - who wants timestamped slides and transcript notes stored as plain, portable files instead of in a cloud note-taking service.