VidSnatch 🚀

The future of YouTube video downloading - Web App, CLI & MCP Server

</div>

VidSnatch is a futuristic YouTube video downloader with a sleek web interface, a full-featured CLI, and a Model Context Protocol (MCP) server for AI assistants and programmatic access. Built for the next generation with a stunning UI that appeals to Gen Z and Gen Alpha users.

Install

Recommended — pipx (installs CLI tools globally, no venv needed)

pipx install vidsnatch

Don't have pipx? Install it first:

brew install pipx   # macOS
pipx ensurepath

Alternative — pip (inside a virtual environment)

pip install vidsnatch

Upgrade

pipx upgrade vidsnatch   # if installed via pipx
pip install --upgrade vidsnatch   # if installed via pip

Global commands installed

After installation, these four commands are available anywhere in your terminal:

| Command | Description | |---|---| | vidsnatch | Main CLI — search, download, trim, list | | vidsnatch-web | Start the web UI on http://localhost:8080 | | vidsnatch-mcp | Start the MCP stdio server (for AI assistants) | | vidsnatch-mcp-http | Start the MCP HTTP server on port 8090 |

Prerequisites

Python 3.10+
ffmpeg — required for high-quality video downloads and trimming

brew install ffmpeg   # macOS

Features

🔍 YouTube Search: Search YouTube by keyword and browse results before downloading
🌟 Futuristic Web Interface: Beautiful glassmorphism UI with aurora background
📱 Mobile-First Design: Responsive design that works on all devices
🎥 High-Quality Downloads: Support for up to 4K video downloads with automatic audio merging
🎵 Audio Extraction: Download audio-only files as MP3, M4A, or WAV
📝 Transcript Download: Extract video transcripts with timestamps
✂️ Video Trimming: Download specific segments of videos with precise timestamp control
🎬 Stitch clips: Join multiple downloaded clips into a single compilation video
⚡ Real-Time Processing: Live video info fetching and download progress
💻 Full-Featured CLI: Subcommand-based CLI (vidsnatch info/download/trim/list) for automation, scripting, and LLM skill usage
🤖 MCP Server: Model Context Protocol server (stdio & HTTP) for AI assistants and programmatic access
🧠 LLM Skill Integration: Ships with a skill file for Claude Code, Cursor, and GitHub Copilot — install with vidsnatch install --skills
🚀 Modern Tech Stack: Built with UV, FastAPI, Click, and Tailwind CSS

Local Development Setup

Clone the repo and install dependencies with UV:

git clone https://github.com/sahajamit/VidSnatch.git
cd VidSnatch
curl -LsSf https://astral.sh/uv/install.sh | sh   # install UV if needed
uv sync

Releasing a New Version

Use the /release slash command inside Claude Code to bump the version, commit, tag, and push in one step (triggers the GitHub Action that publishes to PyPI):

/release          # patch bump: 0.1.3 → 0.1.4
/release minor    # minor bump: 0.1.3 → 0.2.0
/release major    # major bump: 0.1.3 → 1.0.0
/release 0.2.5    # explicit version

The command updates pyproject.toml, asks for confirmation, then runs git commit → git push origin main → git tag → git push origin <tag>.

Testing

To run the test suite:

# Run all tests
uv run python -m pytest tests/ -v

# Run specific test file
uv run python -m pytest tests/test_transcript.py -v

Usage

🐳 Running with Docker

You can run VidSnatch using the pre-built Docker image from Docker Hub.

Pull the Docker image:
```
docker pull sahajamit/vidsnatch:0.3
```

Run the Docker container:

docker run -p 8080:8080 sahajamit/vidsnatch:0.3

Open your browser: Navigate to http://localhost:8080

🌐 Web Interface (Recommended)

VidSnatch features a stunning futuristic web interface that's perfect for everyday use:

VidSnatch Web Interface

Launch the Web App

Start the server:
```
vidsnatch serve web
```
Or alternatively: uv run python web_app.py
Open your browser: Navigate to http://localhost:8080
Start downloading:
- Paste any YouTube URL into the input field and click "Snatch", or
- Toggle to "Search YouTube" to find videos by keyword, then click a result
- Select your desired video quality or transcript language
- Click "Download Video", "Download MP3", or "Download Transcript"

✂️ Video Trimming Feature

VidSnatch now supports precise video trimming to download specific segments:

Load a video: Paste a YouTube URL and click "Snatch Video Info"
Navigate to Trim Video section: Scroll down to the "✂️ Trim Video" panel
Select time range using sliders:
- Start Time Slider: Drag to set the beginning of your segment
- End Time Slider: Drag to set the end of your segment
- Visual Timeline: See your selection highlighted on the progress bar
- Time Display: View exact start/end times and segment duration
Choose quality: Select video quality for the trimmed segment
Download: Click "Download Trimmed Video" to get your custom segment

Features:

Precise Control: Frame-accurate trimming with visual feedback
Real-time Preview: See exact timestamps and duration as you adjust
Quality Selection: Choose from available video qualities
Smart Validation: Prevents invalid time ranges automatically

The web interface features:

Real-time video info fetching
Quality selection with visual feedback
Video trimming with interactive sliders
Transcript download with timestamps
Fancy loading animations
Automatic file downloads
Mobile-responsive design

💻 As a Python module

from youtube_downloader import YouTubeDownloader

# Create downloader instance
downloader = YouTubeDownloader()

# Download video
downloader.download_video("https://www.youtube.com/watch?v=VIDEO_ID", output_path="./downloads")

# Download audio only
downloader.download_audio("https://www.youtube.com/watch?v=VIDEO_ID", output_path="./downloads")

# Download transcript with timestamps
downloader.download_transcript("https://www.youtube.com/watch?v=VIDEO_ID", output_path="./downloads")

# Download a trimmed video segment (start_time and end_time in seconds)
downloader.download_video_segment("https://www.youtube.com/watch?v=VIDEO_ID", 
                                 start_time=30, end_time=120, 
                                 output_path="./downloads", quality="720p")

⚡ Command Line Interface

VidSnatch provides a full-featured CLI covering all download operations. Install with pip install vidsnatch (or uv sync for local development), then use the vidsnatch command directly.

Command Overview

vidsnatch search "query" [--sort relevance|date|views]     # search YouTube videos
vidsnatch info <url>                                      # video metadata, formats, duration
vidsnatch download video <url> [--quality LEVEL]          # download video file
vidsnatch download audio <url> [--format mp3|m4a|wav]     # extract audio
vidsnatch download transcript <url> [--language LANG]     # get timestamped transcript
vidsnatch trim <url> --start HH:MM:SS --end HH:MM:SS      # download a clip
vidsnatch stitch <file1> <file2> [<file3>...]             # join clips into one video
vidsnatch list [--output DIR]                             # list downloaded files
vidsnatch serve web [--port PORT]                         # start the web app
vidsnatch serve mcp                                       # start MCP stdio server
vidsnatch serve mcp-http [--port PORT]                    # start MCP HTTP server
vidsnatch install --skills                                # install LLM skill files
vidsnatch uninstall --skills                              # remove LLM skill files

Global options available on all commands:

--output DIR — save to a specific directory (overrides config default)
--json — output structured JSON instead of human-readable text
--help — show command help

Examples

Search YouTube:

vidsnatch search "python tutorial"
vidsnatch search "lo-fi music" --sort views
vidsnatch search "react hooks" --sort date --json

Search then download:

# Step 1: search for videos
vidsnatch search "python tutorial" --sort views

# Step 2: pick a result URL and download
vidsnatch download video "https://youtube.com/watch?v=RESULT_ID" --quality high

Inspect a video before downloading:

vidsnatch info "https://www.youtube.com/watch?v=VIDEO_ID"

Download video:

# Highest quality (default)
vidsnatch download video "https://www.youtube.com/watch?v=VIDEO_ID"

# Specific quality level, custom output directory
vidsnatch download video "https://www.youtube.com/watch?v=VIDEO_ID" --quality high --output ./my_videos

Download audio only:

# MP3 (default format)
vidsnatch download audio "https://www.youtube.com/watch?v=VIDEO_ID"

# Specific format
vidsnatch download audio "https://www.youtube.com/watch?v=VIDEO_ID" --format m4a

Download transcript:

vidsnatch download transcript "https://www.youtube.com/watch?v=VIDEO_ID"

# Different language
vidsnatch download transcript "https://www.youtube.com/watch?v=VIDEO_ID" --language es

Trim a specific segment:

vidsnatch trim "https://www.youtube.com/watch?v=VIDEO_ID" --start 00:01:30 --end 00:03:00

Stitch clips together:

# Join two trimmed clips into one video
vidsnatch stitch ./downloads/clip1.mp4 ./downloads/clip2.mp4

# Stitch three clips with a custom output filename
vidsnatch stitch clip1.mp4 clip2.mp4 clip3.mp4 --fi

VidSnatch

Install / Use

README