Skip to main content

vink

CI Python License: MIT PyPI

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. Use original for 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.

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

The examples below use uv run vink from a source checkout. With the PyPI install, run vink directly.

Quickstart

uv run vink transcript https://youtu.be/aircAruvnKk
/path/to/vink/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
uv run vink transcript https://youtu.be/VIDEO_ID --lang hi,en

# The language spoken in the video, printed to the terminal
uv run vink transcript VIDEO_ID --lang original --stdout

# See what is available first
uv run vink languages https://youtu.be/VIDEO_ID

Add -v before the command for progress logs, e.g. uv run 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_OUTPUT_DIR": "/absolute/path/to/your/notes" }
    }
  }
}

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 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

MIT

Metadata

Release files for vink 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vink 0.1.0
File Size Uploaded Provenance Actions
vink-0.1.0.tar.gz 169.6 kB With provenance Details for vink-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vink 0.1.0
File Interpreter ABI Platform Actions
vink-0.1.0-py3-none-any.whl Python 3 none any Details for vink-0.1.0-py3-none-any.whl

Total release size: 216.2 kB

Release files / vink-0.1.0.tar.gz

Download URL vink-0.1.0.tar.gz
Size 169.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ba01ad254d4c4e086bbfaceca29bbc4e4caf5655b97a1654950e3a866bd872f1
BLAKE2b-256 checksum
How to use checksums
a1ddfc9552700f941a4d78cd536f7158e951a2090535499164df388c3970177a
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 log

Release files / vink-0.1.0-py3-none-any.whl

Download URL vink-0.1.0-py3-none-any.whl
Size 46.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
997057d3cff5a54e903737e9dfdb4001dafe6688cc844548c638b0a26a53b388
BLAKE2b-256 checksum
How to use checksums
c4f0c891a3d83473e9569e54162f565abc3ed6824fbd30c46b73376eb8bf1f31
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 log

Security for vink 0.1.0

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.

Select from 2 files

Attestation for vink-0.1.0.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page