vink
Turn YouTube transcripts into clean, timestamped Markdown and into complete, detailed notes instead of short summaries.
Why
Most "YouTube to notes" tools summarize. They squeeze an hour of teaching into a page and drop the examples, steps and asides that made the video useful. vink works the other way around. It extracts the full transcript YouTube already has, cleans it into readable paragraphs with timestamps, and serves it in parts so an AI client can write notes for each part without leaving anything out.
Features
- No API key. Reads the same captions YouTube's player shows in its Show transcript panel.
- Any language. Choose preferred languages in order (
en,hi). Manual captions are preferred over auto-generated ones, with YouTube translation as a fallback. Useoriginalfor the language spoken in the video. - Readable output. Merges caption fragments into paragraphs, removes
[Music]-style noise, and puts a clickable timestamp on every paragraph. - Notes-app friendly. Markdown with YAML front matter, ready for Obsidian and similar apps.
- MCP server. Lets Claude Desktop (or any MCP client) read long videos chunk by chunk and write full notes, with bundled note-style prompts.
- Local cache. Each transcript is fetched once; the list of available languages is refreshed daily.
Installation
Requires Python 3.11+.
From PyPI, as a standalone command:
uv tool install vink # or: pipx install vink
vink --version
From source (for development), with uv:
git clone https://github.com/navinbhagat322/youtube-vink.git
cd youtube-vink
uv sync
From a source checkout, prefix the commands below with uv run.
Quickstart
vink transcript https://youtu.be/aircAruvnKk
/your/current/folder/output/But what is a neural network Deep learning chapter 1.md
The file looks like this:
---
title: "But what is a neural network? | Deep learning chapter 1"
channel: "3Blue1Brown"
url: "https://www.youtube.com/watch?v=aircAruvnKk"
video_id: "aircAruvnKk"
language: "en"
captions: "manual"
duration: "18:25"
---
# But what is a neural network? | Deep learning chapter 1
**Channel:** [3Blue1Brown](https://www.youtube.com/@3blue1brown) · **Duration:** 18:25 · ...
## Transcript
**[0:04](https://youtu.be/aircAruvnKk?t=4)** This is a 3. It's sloppily written and rendered ...
Usage: CLI
vink transcript URL [--lang en,hi] [--output-dir DIR] [--stdout]
[--translate | --no-translate] [--cache | --no-cache]
vink languages URL
vink mcp
vink --version
| Command | What it does |
|---|---|
transcript |
Fetches a transcript and saves it as Markdown (or prints it with --stdout). |
languages |
Lists the caption tracks a video has. |
mcp |
Runs the MCP server over stdio. |
Examples:
# Hindi if available, otherwise English
vink transcript https://youtu.be/VIDEO_ID --lang hi,en
# The language spoken in the video, printed to the terminal
vink transcript VIDEO_ID --lang original --stdout
# See what is available first
vink languages https://youtu.be/VIDEO_ID
Add -v before the command for progress logs, e.g. vink -v transcript ....
Exit codes: 0 success, 1 the transcript could not be fetched, 2 invalid
input or options.
Usage: MCP (Claude Desktop)
Add vink to your Claude Desktop config. On macOS it is at
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"vink": {
"command": "uvx",
"args": ["vink", "mcp"],
"env": { "VINK_LANGUAGES": "en" }
}
}
}
Notes are saved to ~/Documents/vink unless you set VINK_OUTPUT_DIR in
env. If Claude Desktop cannot find uvx, use its absolute path (which uvx).
To run from a source checkout, see docs/mcp.md.
Restart Claude Desktop, then either:
- choose the make_notes prompt, enter a video URL, and optionally a style
and output language (for example
Hinglish), or - just ask: "Make detailed notes from https://youtu.be/VIDEO_ID and save them."
| Tool | Purpose |
|---|---|
list_languages |
Caption languages available for a video |
get_video_info |
Title, language, duration and number of parts |
get_chunk |
One part of the transcript as Markdown |
get_transcript |
The whole transcript (best for short videos) |
save_transcript |
Save the transcript as a Markdown file |
save_notes |
Save notes the client has written |
Bundled note styles: detailed-notes (default) and clean-transcript.
See docs/mcp.md for details.
Configuration
Every setting has a sensible default and can be set with an environment
variable or a .env file. Common ones:
| Variable | Default | Meaning |
|---|---|---|
VINK_LANGUAGES |
en |
Preferred languages, comma-separated |
VINK_OUTPUT_DIR |
output (CLI), ~/Documents/vink (MCP) |
Where files are saved |
VINK_CHUNK_SECONDS |
600 |
Length of one part for get_chunk |
The full list is in docs/configuration.md.
How it works
URL → caption track selection → fetch → clean → paragraphs → chunks → Markdown → file
vink uses a ports-and-adapters architecture. Fetching, rendering and saving each sit behind a small interface, so new output formats (PDF, DOCX) and destinations (Notion, Obsidian) can be added without touching the core. See docs/architecture.md.
Limitations
- Only videos that have captions (manual or auto-generated) are supported. Transcribing audio for videos without captions is planned.
- YouTube often blocks requests from cloud-server IP addresses. Run vink from your own machine.
- vink uses YouTube's internal caption endpoints through
youtube-transcript-api. These can change without notice. Keep dependencies up to date. - Playlists are not supported yet.
Contributing
Contributions are welcome. See CONTRIBUTING.md for setup, workflow and conventions.
License
Metadata
Release files for vink 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vink-0.1.1.tar.gz | 401.1 kB | With provenance | Details for vink-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vink-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for vink-0.1.1-py3-none-any.whl |
Total release size: 450.2 kB
Release files / vink-0.1.1.tar.gz
| Download URL | vink-0.1.1.tar.gz |
|---|---|
| Size | 401.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9073be66aeab90edd42013e896906e3babb58d80a0820c64771ea929d5bb52aa
|
|
BLAKE2b-256 checksum How to use checksums |
c0e9af58f12a5151fbf8280ec0d7a36a1864525d42ede983b69db26f02d0fb51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / vink-0.1.1-py3-none-any.whl
| Download URL | vink-0.1.1-py3-none-any.whl |
|---|---|
| Size | 49.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e981fd41be97e5b51006b1d01de15bcc91d3d333fd5abb1576d54820b1a6818f
|
|
BLAKE2b-256 checksum How to use checksums |
916191b20efd737601d18a96d619f2e0ccaa104edfb21f42d6490981db3c54f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for vink 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vink-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.