Build a searchable markdown library from YouTube videos

Builds a personal library of YouTube talks for deep study. 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 lives as files on disk, fully owned by the user. The markdown library is the single source of truth: the browser artifact is a thin HTML shell that fetches from the server and writes notes back, and video data is never hardcoded into the HTML. Sourced from dair-ai/dair-academy-plugins (MIT licensed).

Use it to build a searchable, portable archive of talks worth re-watching in depth - conference talks, lectures, technical presentations - where slide-level notes tied to transcript timestamps matter more than a quick summary. It requires yt-dlp and ffmpeg on PATH plus Python 3 with Pillow and PyYAML:

pip install yt-dlp pillow pyyaml      # ffmpeg via your package manager

It also includes an explicit human-judgment curation step (picking real content slides out of a scene-detected contact sheet) that keeps it from being a fully automated pipeline - it is not meant for hands-off bulk processing of many videos.

Given a YouTube URL or id, the pipeline runs through named helper scripts in scripts/: setup.sh resolves the id, creates a scratch directory, and checks whether YouTube embedding is allowed (oembed 200) or blocked (oembed 401, as with some university talks - the artifact then degrades gracefully to an "open on YouTube" link); download.sh pulls the video (720p or lower) and the best available subtitles via yt-dlp; detect_slides.sh runs ffmpeg scene detection (select='gt(scene,0.3)', adjustable 0.2-0.4) to propose slide timestamps; contact_sheet.py builds a labeled contact sheet for the human to curate down to the real content slides (a typical talk yields 15-25); extract_slides.py pulls the kept frames at 1280px JPEG into _media/ as <YTID>-slide-NN.jpg; vtt_to_transcript.py collapses YouTube's duplicated auto-caption text into clean [HH:MM:SS] lines; and write_library_item.py assembles the final <YTID>.md file with frontmatter (title, speaker, tags, a slides array) and the transcript body. serve.py --dir <library> --port 8000 then serves the library, and verify.sh <YTID> curls the collection list, the item, the first slide image, and the artifact to confirm everything renders correctly.

Storage is a single environment variable (VIDEO_LIBRARY_DIR, default ~/video-deepdives/) pointing at a plain folder of standard-YAML markdown files, portable enough to open directly in Obsidian or any other editor; the whole serving layer is one stdlib-plus-PyYAML file (serve.py) with no orchestrator or database involved.

People who watch technical talks to actually study them - engineers, researchers, students - who want slide-referenced, transcript-grounded notes they fully own as plain files, rather than a cloud note-taking service.