yoink-yt 0.1.0

Yoink videos off YouTube. Fast TUI + MCP server.

yoink

grab videos, fast
_{A no-nonsense YouTube downloader with a slick terminal UI and an MCP server so your AI assistant can yoink videos too.}

pip install yoink-yt  ·  uv run yoink  ·  MCP Server  ·  Docs

---

Three ways to yoink   TUI — Beautiful interactive terminal app. Paste a URL, pick a quality, hit download. Progress bars, speed stats, the works.   MCP — Expose download tools to AI assistants like Claude. Let your AI yoink videos for you.   CLI — Just a script. python download.py <url> and done. All three share the same core engine powered by yt-dlp.

Highlights  Concurrent downloads (up to 10)  Playlist support with search/filter  Quality selector — 1080p to audio-only  Audio-only & MP3 conversion  Subtitle downloads  Speed limiting  Retry failed downloads  Open folder on complete  Friendly error messages  Keyboard shortcuts

⚡ Quick Start

# Install from PyPI
pip install yoink-yt

# Launch
yoink

Or install from source:

git clone https://github.com/JayshKhan/yoink.git
cd yoink && uv sync
uv run yoink

That's it. Paste a YouTube URL, pick your quality, download.

[!TIP] Install ffmpeg for best results — it's needed to merge separate video+audio streams into a single file.

brew install ffmpeg          # macOS
sudo apt install ffmpeg      # Ubuntu/Debian

🎬 TUI Mode

uv run yoink              # default: 3 concurrent downloads
uv run yoink -j 5         # or up to 10

Keyboard shortcuts Key Action / Focus URL input d Start download r Retry last failed a Select all (playlist) n Select none (playlist) q Quit

Download features Feature Details Output dir Editable path below URL bar Speed limit Set in queue header (e.g. 5M) Subtitles Checkbox — auto + manual subs MP3 convert Checkbox — uses ffmpeg Filename template Customizable in Advanced Settings Retry One click on failed downloads Open folder One click on finished downloads

🤖 MCP Server

uv run yoink-mcp

Exposes 7 tools over STDIO for AI assistants:

Tool	What it does
get_video_info	Fetch title, duration, formats
get_playlist_info	List all videos in a playlist
get_formats	Available qualities for a URL
start_download	Start downloading, get a tracking ID
list_downloads	See all downloads + progress
get_download_progress	Check on a specific download
cancel_download	Stop a download

Claude Desktop configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "yoink": {
      "command": "uv",
      "args": ["--directory", "/path/to/yoink", "run", "yoink-mcp"]
    }
  }
}

Then just ask Claude: "Download this video in 720p: https://youtube.com/watch?v=..."

🛠 Architecture

src/yoink/
├── core/              # The engine room
│   ├── models.py      # Pydantic models shared everywhere
│   ├── errors.py      # Friendly error translation
│   ├── extractor.py   # yt-dlp metadata extraction
│   ├── engine.py      # Single download with progress hooks
│   └── manager.py     # Concurrent download orchestration
├── mcp_server/        # AI-friendly tools
│   └── server.py      # FastMCP with 7 tools
└── tui/               # The pretty terminal UI
    ├── app.py         # Main Textual app
    ├── screens/       # Main screen, format picker modal
    ├── widgets/       # URL bar, video panel, playlist, queue
    └── styles/        # Textual CSS

Key design decisions

• yt-dlp is synchronous → each download runs in its own thread via ThreadPoolExecutor
• FIFO dispatcher thread ensures downloads start in submission order
• Progress hooks are rate-limited to 100ms to keep the UI smooth
• Playlists use extract_flat for speed — no fetching full metadata for 500 videos upfront
• Pydantic models everywhere = clean contracts between core / TUI / MCP
• Duplicate URL detection prevents double-downloading the same video
• Cancellation via threading.Event checked in progress hooks

📦 Dependencies

Package	Why
yt-dlp	The extraction & download engine
Textual	Terminal UI framework
Pydantic	Data models & validation
MCP SDK	AI tool server protocol

Dev dependencies: pytest — install with uv sync --extra dev

🔧 Development

uv sync --extra dev       # install with test deps
uv run pytest tests/ -v   # run the test suite
uv run yoink              # test the TUI
uv run yoink-mcp          # test the MCP server

📄 License

MIT — do whatever you want with it. Yoink responsibly.

_{Built with Textual and yt-dlp}