vidlib

vidlib converts a YouTube video's captions into a markdown text file. It has a browser extension, a Python command-line tool, and an HTML reader.

What it does • Two ways to use it • Browser extension • CLI & reader • Features • Channels • Troubleshooting

---

What it does

vidlib takes a YouTube video and writes its captions to a text file.

The file is markdown. It begins with YAML frontmatter — title, channel, date, url, duration, reading_time, pulled — followed by the caption text. The caption text is cleaned: repeated lines from auto-captions are removed, and the text is split into paragraphs. The file is saved as .md or .txt. The two formats hold identical content.

vidlib has three parts:

• Browser extension. It adds a panel to the YouTube watch page. You click a button and it writes the file. It does not use yt-dlp and does not run a server. You install it by loading a folder into the browser.
• Command-line tool (vidlib.py). You give it a YouTube URL. It downloads the captions with yt-dlp, writes the file to <channel>/<slug>.md, and updates index.md. index.md lists every file, grouped by channel, with each file's word count and reading time.
• Reader (reader.html). It is one HTML file. It opens in a browser and displays the files in the library.

The browser extension and the command-line tool produce the same file for the same video.

Two ways to use it

You can use either half on its own, or both together.

	Browser extension	Command-line tool
Best for	Grabbing the video you're watching right now	Building and browsing a library
Install	Load a folder into your browser (1 minute, no build)	Python 3.8+ (yt-dlp only to add videos)
Dependencies	None — no yt-dlp, no server, no permissions	yt-dlp for add; standard library to read
Output	A .md or .txt file you save where you want	<channel>/<slug>.md files + an index.md rollup
Reader	—	Single-file reader.html, search + keyboard nav

The extension and the CLI run the same cleaning pipeline, so a transcript captured in the browser is byte-for-byte what the CLI would have produced. Save an extension file into your library folder and it joins the reader like any other.

---

Browser extension

Capture the transcript of the video you're watching in one click — no install, no yt-dlp, no server, and no browser permissions. On any youtube.com/watch page a small vidlib panel appears in the bottom-right corner: pick a format, then Save (a native dialog lets you choose exactly where the file goes) or Copy.

Install it (step by step)

The extension isn't in the Chrome Web Store — you load it straight from the project's files. It takes about a minute, you only do it once, and there's no build step and no command line. Works in Chrome, Edge, Brave, and other Chromium browsers.

1. Get the files onto your computer. You need the extension folder from this project. Two ways to get it:

• Easiest (no tools): at the top of this page click the green < > Code button → Download ZIP, then find the downloaded file and unzip it (double-click on Windows or Mac). You'll get a vidlib folder with an extension folder inside. Your browser can't read a .zip directly, so don't skip the unzip.
• If you use git: git clone https://github.com/zellkernel/vidlib.git

Remember where you saved it — you'll point your browser at the extension folder in step 4.

2. Open your browser's Extensions page. Type chrome://extensions (Chrome), edge://extensions (Edge), or brave://extensions (Brave) in the address bar and press Enter. Or click the puzzle-piece icon 🧩 in the toolbar and choose Manage extensions.

(Once it's installed, this same menu is where vidlib shows up — notice it sits under "No access needed." That's the zero-permissions design: it never asks to read or change your data.)

3. Turn on Developer mode. Flip the Developer mode switch — it's in the top-right corner of the Extensions page — to on. A new row of buttons appears. You need this on to load an extension from a folder; it's safe to leave on.

4. Click "Load unpacked" and select the extension folder. Click Load unpacked (top-left — it only appears once Developer mode is on). In the folder picker, open the vidlib folder you saved, select the extension folder inside it, and confirm.

Pick the extension folder — not the whole vidlib folder. It's the one that contains manifest.json. If your browser says "Manifest file is missing or unreadable," you chose the wrong folder — go back and select extension.

A vidlib card appears on the Extensions page. That's it — it's installed. (Optional: click the puzzle-piece icon 🧩, then the pin 📌 next to vidlib, to keep it in your toolbar.)

Use it

5. Open any https://www.youtube.com/watch?v=… video. The vidlib panel appears in the bottom-right corner:

• Pick a format — .md (default) or .txt. Same clean markdown either way; .txt just avoids the hidden-.md-extension problem on Windows.
• Click Save — a dialog lets you choose the folder and filename. The file is named after the video's title.
• Or click Copy to put the transcript on your clipboard.

If the panel doesn't appear on a video you already had open, refresh that tab once after installing.

What you get — a clean transcript file, exactly like the CLI produces. Here two videos have been saved, one as .txt and one as .md:

Open one and it's YAML frontmatter followed by readable, paragraphed prose — greppable, quotable, and ready to read anywhere:

Notes and limits

• Zero permissions. The extension's manifest.json requests nothing. Captions are fetched same-origin from the YouTube page you're already on; Save uses the browser's built-in File System Access API (or a plain download as a fallback); Copy runs on your click. No background page, no network calls off youtube.com, no telemetry.
• Save location: on Chromium browsers Save opens a native dialog so you choose exactly where the file lands. On Firefox/Safari (no File System Access API) it falls back to a normal download into your Downloads folder.
• English captions only, matching the CLI. A video with no English caption track reports "no English captions on this video."
• Capture only. To browse a whole library, use the reader below. To file an extension-saved transcript into the reader, drop it under its channel directory as <channel>/<slug>.md and run python3 vidlib.py index.

For how the extension works internally — a MAIN-world bridge that reads the player state plus an isolated content script that runs the cleaning pipeline, and why it uses YouTube's ANDROID_VR client — see extension/README.md.

---

Command-line tool and reader

The CLI builds a library on disk and the reader browses it. This repo ships with a sample library so you can see the reader immediately.

Quickstart

git clone https://github.com/zellkernel/vidlib.git
cd vidlib

# 1. Read the library that ships with the repo (no install, no dependencies):
python3 vidlib.py serve                # serves the folder, opens reader.html in your browser

# 2. Add your own videos (this step needs yt-dlp):
pip install -r requirements.txt
python3 vidlib.py add "https://youtu.be/tIeHLnjs5U8"   # any YouTube URL (keep the quotes)

serve prints http://localhost:8000/reader.html and opens it in your browser; press Ctrl-C to stop. That is the whole tool: serve to read, add to grow the library.

Windows: type python (or py) wherever this README says python3.

Requirements: Python 3.8+ reads a library with the standard library alone (nothing to install). Adding videos also needs yt-dlp; pip install -r requirements.txt installs it.

Adding videos

vidlib.py is the CLI. It uses yt-dlp to pull the transcript and metadata, so install that once:

pip install -r requirements.txt         # installs yt-dlp

python3 vidlib.py add "<youtube-url>"   # fetch transcript + metadata, clean, file under channel, reindex
python3 vidlib.py add "<url>" --raw     # same, but skip paragraphing (write one unbroken block)
python3 vidlib.py index                 # rebuild index.md from the transcript files on disk

On success, add prints the file it wrote and the reading time:

added: 3blue1brown/backpropagation-calculus-deep-learning-chapter-4.md  (7 min read, manual subtitles)

add cleans the transcript into markdown prose, writes it to <channel>/<slug>.md, and regenerates index.md. Pass --raw to skip the paragraph-splitting pass. Quote the URL so the shell does not treat ? and & as special characters. index rebuilds the rollup on its own, in case files were added or edited by hand. The transcript files are the source of truth; index.md is derived, never hand-edited.

Caption quality. vidlib prefers a video's human-written subtitles, which come out clean and punctuated. When only auto-generated captions exist, it does a best-effort pass: it strips the rolling-overlap repetition and splits the text into paragraphs, but auto-captions have no punctuation and can drop a word at a seam. The added: line (and the panel's status in the extension) tells you which you got (manual subtitles or auto-captions). Either way the file is faithful and greppable; polish an auto-caption transcript afterward if you want publication-clean prose.

Reading

One command serves the library and opens the reader:

python3 vidlib.py serve                # opens http://localhost:8000/reader.html
# --port N to change the port, --no-open to skip launching a browser
# press Ctrl-C to stop the server

Or serve it yourself and open the URL by hand:

python3 -m http.server 8000
# then visit http://localhost:8000/reader.html

Over http the reader auto-loads the whole library, fetching index.md and every transcript, with no manual file loading. It remembers your last-open transcript and scroll position, and every transcript has a shareable #channel/slug URL. Opening reader.html straight from file:// can't fetch, so it falls back to drag-drop: drop .md files onto the window to read them.

Or read any transcript directly on GitHub — the files are plain markdown. index.md is the table of contents: it groups transcripts by channel and lists reading time and word count.

How it works

YouTube URL
    │  yt-dlp pulls video metadata + the best English captions
    ▼
clean                  dedup the rolling auto-caption overlap, split into paragraphs
    │
    ▼
<channel>/<slug>.md    one markdown file per video (YAML frontmatter + clean prose)
    │
    ▼
index.md               rollup grouped by channel, with word count + reading time
    │
    ▼
reader.html            dark-mode reader; over http it auto-loads the whole library

add runs this whole chain for one URL. index rebuilds index.md from the files already on disk. serve starts a local http server and opens reader.html so the reader can fetch the library. The browser extension runs the same clean → paragraph steps in the page, without yt-dlp.

Layout

vidlib/
  index.md                       # rollup of all transcripts with word counts
  reader.html                    # single-file dark-mode reader
  vidlib.py                      # the CLI
  extension/                     # the browser extension (load unpacked)
  3blue1brown/                   # one directory per channel
    backpropagation-calculus-deep-learning-chapter-4.md
    ...
  artem-kirsanov/
  freecodecamp-talks/
  oxfordunion/
  scienceclic-english/
  the-tim-dillon-show/
  ...

Each transcript is YAML frontmatter followed by clean prose. See CLAUDE.md for the exact file format: the slug rules, the frontmatter fields, and the index.md shape.

Features

• Zero-install browser extension: capture the video you're watching straight to .md or .txt, choosing where to save — no yt-dlp, no server, no permissions
• One-command CLI: add a YouTube URL, index the library, serve the reader
• Per-channel directories with one markdown file per video
• index.md rollup with word counts and reading-time estimates for every transcript
• Single-file HTML reader, no build step, opens in any browser, auto-loads the whole library over http
• Remembers your last-open transcript and scroll position; shareable #channel/slug links; search, keyboard nav, mobile
• Plain markdown on disk. Grep, quote, archive, ingest into anything that reads files

Channels

A sampling of what is in the library:

• 3Blue1Brown. Deep learning chapters: neural networks, gradient descent, backpropagation
• Artem Kirsanov. Neuroscience and machine learning intersection
• freeCodeCamp Talks. Conference talks (e.g., physical pen testing tactics)
• Oxford Union. Long-form debates
• ScienceClic English. Physics and geometry
• Tim Dillon Show. Long-form interviews
• Thorin's Side, dustmane, charls-carroll(-clips). Philosophy and culture
• WKUK. Sketches

Total library state is at the top of index.md.

Troubleshooting

Extension

• No panel on the video. Refresh the tab once after installing. The panel only appears on youtube.com/watch?v=… pages (not the homepage or search).
• "Manifest file is missing or unreadable" when loading. You selected the wrong folder — choose the extension folder (the one containing manifest.json), not the whole vidlib folder.
• Save drops the file into Downloads without asking where. Your browser doesn't support the File System Access API (Firefox/Safari) — the file still saves correctly, just to your default Downloads folder.
• "no English captions on this video." That video has no English caption track. The extension (like the CLI) handles English captions only.

CLI and reader

• python3: command not found. On Windows, use python or py. Otherwise install Python 3.8+ from python.org.
• add reports yt-dlp is not installed. Run pip install -r requirements.txt. Only add needs yt-dlp; serve and index do not.
• add reports no English subtitles or auto-captions available. That video has no captions to pull. Try another one.
• serve reports cannot bind ... address already in use. Another program holds the port. Pick a new one: python3 vidlib.py serve --port 8001.
• The reader is blank after you opened reader.html from file://. Browsers block file:// pages from loading the library. Run python3 vidlib.py serve and use the http://localhost URL it prints, or drag .md files onto the page.

Our other projects

• zellkernel, AI/ML infrastructure security research
• aimap, AI/ML infrastructure fingerprint scanner
• colophon, O'Reilly book chapters to clean markdown via the content API

License

MIT. Transcripts are derivative of their source videos and remain the property of their respective channels. Contact: zellkernel.com