🎬 Snatchr: Lightning-Fast Video Downloader! ⚡

A blazing-fast HTTP API for downloading videos from YouTube with automatic cleanup, file serving, and a modern web interface!

---

🌟 Welcome to Snatchr, the Ultimate Video Download API!

This project provides a robust HTTP API for downloading videos from YouTube using yt-dlp, built with Rust and Axum for maximum performance and reliability.

🎮 Features That Power Your Downloads

🚀 Lightning-Fast Downloads Powered by yt-dlp with concurrent downloads and optimized performance settings.	📁 Automatic File Serving Direct HTTP access to downloaded files with secure path validation and streaming support.
🌐 Modern Web Interface Beautiful, responsive web UI with video preview, download history, and drag-and-drop support.	🔧 Configurable Quality Choose video/audio quality, codecs, and format preferences through environment configuration.
🧹 Smart Cleanup System Automated cleanup of old downloads with configurable retention periods and scheduling.	⚡ Intelligent Caching Smart video caching by YouTube ID - never download the same video twice! Instant returns for cached content.
📊 Comprehensive Logging Detailed request tracking, error handling, and performance monitoring with structured logging.	🎯 Request Tracking Unique job IDs for each request with full traceability from HTTP handler to download completion.

🚀 Requirements

• Rust (1.70 or later)

🛠️ Setup Guide

🌐 Web Interface

Snatchr includes a beautiful, modern web interface for easy video downloading!

Snatchr_WebUI.mp4

✨ Features

• 🎬 Instant Video Preview - Watch downloaded videos directly in the browser with our sleek video player
• 📋 Smart Download History - Keep track of all your previous downloads with timestamps and file info
• 🎨 Modern & Responsive - Beautiful design that works perfectly on desktop, tablet, and mobile
• ⚡ Lightning-Fast - Just paste a YouTube URL and watch your video download in seconds
• 🎯 One-Click Downloads - No complex settings, just pure simplicity and speed

🚀 How to Use

1. Start your Snatchr server
2. Open your browser and navigate to http://localhost:3000
3. Paste any YouTube URL in the elegant input field
4. Click "Download Video" and watch the magic happen!

🎯 Pro Tips

• 📋 Clipboard Integration - Use the "Paste" button for instant URL pasting from your clipboard
• 🎬 Instant Preview - Downloaded videos appear immediately in the video player for instant gratification
• 📱 Mobile-First - The interface is optimized for mobile devices with touch-friendly controls
• 🔄 Auto-Refresh - The interface automatically updates to show your latest downloads

⚠️ Important Note

If you're running locally and your server is bound to 0.0.0.0, some browsers and extensions may block video playback. Use localhost in your browser URL instead of 0.0.0.0 for the best experience.

🔧 Configuration

You can disable the web interface by setting the environment variable:

ENABLE_WEB_UI=false

When disabled, only the API endpoints will be available.

📱 iOS Shortcut (Beta)

Download videos directly from your Apple device with our iOS Shortcut integration!

🔗 Download: Snatchr iOS Shortcut

⚙️ Setup Instructions

1. Configure Server URL: After downloading, open the shortcut and update the EXTERNAL_URL in the dictionary at the top

   • Include the /download endpoint (e.g., https://your-server.com/download)

2. Codec Compatibility: For automatic saving to your photo gallery, ensure your Snatchr instance uses compatible codecs:

   • Video: AVC1 (recommended)
   • Audio: AAC (recommended)

3. Alternative Save Method: If you experience issues with gallery saving, edit the shortcut and change Save URL to Recents to Save File instead

Note: This shortcut is currently in beta. Please report any issues on our GitHub Issues page.

🐳 Deploy with Docker

1. Download the docker-compose.yml file or clone the repository:

git clone https://github.com/Valhalla-Development/Snatchr.git
cd Snatchr

2. Review and modify the environment variables in docker-compose.yml if needed (PORT, DOWNLOAD_DIR, etc.)

3. Run with Docker Compose:

   docker-compose up -d

4. The server will be available at http://localhost:3000

🚀 Build Locally (Rust)

1. Download the latest release or clone the repository:

git clone https://github.com/Valhalla-Development/Snatchr.git

2. Navigate to the project directory:

   cd Snatchr

3. Install Rust (if not already installed):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

4. Rename or copy the .env.example > .env and fill in the required variables.

5. Build the project:

   cargo build --release

6. Run the server:

   cargo run --release

📡 API Usage

Download a Video

curl -X POST "http://localhost:3000/download" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Response:

{
  "success": true,
  "file_url": "http://localhost:3000/files/dQw4w9WgXcQ/file_name.mp4"
}

🧹 Automatic Cleanup

The server automatically cleans up old downloads based on your CLEANUP_AFTER_MINUTES setting. Cleanup runs periodically in the background and logs all operations.

⚡ Smart Caching System

Snatchr features intelligent video caching that dramatically improves performance:

🎯 How It Works

• Video ID Caching: Videos are stored using their YouTube video ID (e.g., dQw4w9WgXcQ)
• Instant Returns: If a video is already cached, it's returned immediately without re-downloading
• Bandwidth Savings: Never download the same video twice
• Automatic Validation: Cached files are verified to ensure they're not corrupted

📁 Cache Structure

downloads/
├── dQw4w9WgXcQ/          # Video ID directory
│   └── video_title.mp4   # Cached video file
├── zwMEhBq4kYM/          # Another video ID
│   └── another_video.mp4
└── cache/                # System cache (preserved)

🚀 Performance Benefits

• First Download: Normal speed (downloads and caches)
• Subsequent Downloads: Instant! (returns cached file)
• Multiple Users: Share cached content across all users
• Server Efficiency: Reduced bandwidth and processing load

🤝 Contributing

We welcome contributions to improve Snatchr! If you'd like to contribute:

1. Fork the repository
2. Create a new branch for your feature or bug fix:

   git checkout -b feature/your-feature-name

3. Make your changes and commit them with a clear, descriptive message:

   git commit -m 'Add feature: brief description of your changes'

4. Push your changes to your fork:

   git push origin feature/your-feature-name

5. Open a Pull Request against the main repository's main branch

Please ensure your code adheres to the project's coding standards and include tests for new features or bug fixes where applicable. We appreciate detailed descriptions in your Pull Request to help with the review process.

📜 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details. (It's mostly "Share the love, and keep it open!")

🙏 Acknowledgements

• yt-dlp for the powerful video download engine
• Axum for the high-performance web framework
• Tokio for the async runtime
• Rust for the blazing-fast and memory-safe foundation
• All contributors who help improve this project

🚀 What's Next?

We're constantly working to make Snatchr even better! Here's what we're cooking up:

🎯 Upcoming Features

• 🌐 Multi-Platform Support - Support for more video platforms beyond YouTube

🤝 Community Ideas

Have a feature request or idea? We'd love to hear it! Open an issue or join our Discord to discuss.

---

📬 Support & Community

Got questions or need help? Join our Discord server for support and to connect with other bot developers!

---

💻 Crafted with ❤️ by Valhalla-Development

🐛 Spotted an issue? | 💡 Got an idea? | 🤔 Need help?

🔝 Back to Top