🎵 Doradura

High-performance Telegram bot for downloading music and videos

Download audio & video from YouTube and SoundCloud with ease

---

✨ Features

• 🎵 Audio Downloads - High-quality MP3 downloads (320kbps) with embedded metadata and thumbnails
• 🎥 Video Downloads - Get videos in the best available quality
• ⚡ Fast & Efficient - Built with Rust for maximum performance
• 🔄 Retry Logic - Automatic retries for reliable file delivery
• 🛡️ Rate Limiting - Prevent abuse with intelligent rate limiting (30s cooldown per user)
• 📊 Queue System - Handle multiple downloads seamlessly
• 🗄️ Database Logging - Track all user requests and history
• 🔧 Multi-Platform - Support for both youtube-dl and yt-dlp
• 💾 Auto-Cleanup - Temporary files are automatically removed after sending

🚀 Quick Start

Prerequisites

Install the required system tools:

# Install FFmpeg (audio/video processing)
brew install ffmpeg  # macOS
# or
sudo apt install ffmpeg  # Ubuntu/Debian

# Install youtube-dl or yt-dlp
brew install yt-dlp  # macOS (recommended)
# or
pip install yt-dlp  # Python alternative

Installation

1. Clone the repository:

git clone https://github.com/yourusername/doradura.git
cd doradura

2. Create a .env file:

cp .env.example .env
# Edit .env and add your Telegram bot token

3. Build and run:

cargo build --release

# Run the bot (default mode)
./target/release/doradura run

# Or use cargo
cargo run -- run

💡 Note: The bot now supports CLI commands. See CLI_USAGE.md for all available commands including run-staging, run-with-cookies, and refresh-metadata.

Environment Variables

Create a .env file in the project root:

TELOXIDE_TOKEN=your_telegram_bot_token_here
ADMIN_USERNAME=your_telegram_username  # Admin user (without @) for /admin, /users, /setplan commands
YTDL_BIN=yt-dlp  # Optional: override default youtube-dl
BOT_API_URL=http://localhost:8081  # Optional: use local Bot API server (allows files up to 2GB)
DOWNSUB_GRPC_ENDPOINT=http://localhost:50051  # Optional: gRPC endpoint for Downsub summarization/subtitles

# YouTube Cookies (required for YouTube downloads)
# Option 1: Automatic extraction from browser (Linux/Windows recommended)
YTDL_COOKIES_BROWSER=chrome  # chrome, firefox, safari, brave, chromium, edge, opera, vivaldi

# Option 2: Export cookies to file (macOS recommended)
YTDL_COOKIES_FILE=youtube_cookies.txt

📋 Quick Setup for Cookies:

Linux/Windows (Automatic):

# 1. Install dependencies
pip3 install keyring pycryptodomex

# 2. Login to YouTube in your browser
# 3. Set environment variable
export YTDL_COOKIES_BROWSER=chrome

# 4. Restart bot

macOS (File-based, recommended):

# 1. Export cookies using browser extension (see MACOS_COOKIES_FIX.md)
# 2. Set environment variable
export YTDL_COOKIES_FILE=youtube_cookies.txt

# 3. Restart bot

See docs/YOUTUBE_COOKIES.md for detailed instructions.

🚀 Local Bot API Server (Optional)

For sending files larger than 50 MB (up to 2 GB), you can use a local Bot API server:

1. Quick start with Docker:

   ./scripts/start_local_bot_api.sh

   See LOCAL_BOT_API_SETUP.md for detailed instructions.

2. Benefits:

   • Upload files up to 2 GB (instead of 50 MB)
   • Lower latency
   • More flexibility with webhooks

📖 Usage

Once running, interact with the bot on Telegram:

• Send a YouTube/SoundCloud link - Downloads audio by default
• Send "video" + link - Downloads video instead
• /start - Shows welcome message
• /help - Display bot commands
• /settings - View your settings
• /tasks - Check active downloads
• /downsub summary <URL> [lang=<code>] - Ask your Downsub service for a summary/highlights for a link
• /downsub subtitles <URL> [format=<srt|vtt>] [lang=<code>] - Fetch subtitles via Downsub and receive them as a document

The /downsub commands only work if you set DOWNSUB_GRPC_ENDPOINT to a running Downsub gRPC server (local calls only).

Examples

https://youtube.com/watch?v=...
https://soundcloud.com/...
video https://youtube.com/watch?v=...

🏗️ Architecture

Core Components

• src/main.rs - Bot initialization, dispatcher setup, queue processing
• src/downloader.rs - Audio/video download logic with retry mechanisms
• src/queue.rs - Thread-safe download queue system
• src/rate_limiter.rs - Per-user rate limiting
• src/commands.rs - Message and URL parsing handlers
• src/db.rs - SQLite database for logging
• src/fetch.rs - Metadata fetching from URLs

🧪 Testing

# Run all tests
cargo test

# Run tests including integration tests
cargo test -- --ignored

# Test specific module
cargo test --test download_video

🛠️ Development

Build

# Development build
cargo build

# Release build (optimized)
cargo build --release

Run

# Run with default settings
cargo run

# Run with custom logger
RUST_LOG=info cargo run

📦 Dependencies

Key technologies used:

• teloxide - Modern Telegram bot framework
• tokio - Async runtime
• rusqlite - Database integration
• reqwest - HTTP client
• anyhow - Error handling
• chrono - Date and time handling

🔧 Configuration

Rate Limiting

Default rate limit: 30 seconds between downloads per user

To modify, edit src/main.rs:

let rate_limiter = Arc::new(RateLimiter::new(Duration::from_secs(30)));

Download Location

Files are downloaded to a configurable folder with platform-specific defaults:

• macOS: ~/downloads/dora-files/
• Other platforms: ~/downloads/

To customize the download folder, set the DOWNLOAD_FOLDER environment variable in your .env file:

DOWNLOAD_FOLDER=~/downloads/my-custom-folder

The path supports tilde (~) expansion for the home directory.

Retry Logic

Default: 3 attempts with 10 second delays

Configure in src/downloader.rs:

let max_attempts = 3;
// ...
tokio::time::sleep(tokio::time::Duration::from_secs(10)).await;

📚 Documentation

• AGENTS.md
• BOT_FLOWS.md
• CACHE_ISSUE.md
• CLAUDE.md
• CODE_QUALITY_ANALYSIS.md
• COOKIE_FIX_SUMMARY.md
• FILENAME_FIX.md
• FIX_UNKNOWN_TRACK.md
• FIX_YOUTUBE_ERRORS.md
• IDEAS.md
• IMPROVEMENTS.md
• LOCAL_BOT_API_SETUP.md
• MACOS_COOKIES_FIX.md
• TELEGRAM_FILE_DOWNLOAD.md - Admin feature for downloading files from Telegram
• OPTIMIZATION_OPPORTUNITIES.md
• OPTIMIZATION_REALISTIC_ANALYSIS.md
• PROGRESS_BAR_FIX.md
• QUICKSTART.md
• QUICK_FIX.md
• REMAINING_TASKS.md
• RUN_TESTS.md
• SESSION_SUMMARY.md
• SUBSCRIPTIONS.md
• TESTING.md
• TEST_SUMMARY.md
• VIDEO_BLACK_SCREEN_FIX.md
• VIDEO_BLACK_SCREEN_FIX_V2.md
• YOUTUBE_COOKIES.md
• YOUTUBE_PO_TOKEN_FIX.md

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⚠️ Disclaimer

This bot is for personal use only. Please respect copyright laws and terms of service of the platforms you download from.

💡 Credits

Built with ❤️ using Rust and the amazing teloxide library.

---

Made with 🔥 by Dora