Video Downloader

A modern, feature-rich video downloading tool with multi-threading support, built with inspiration from the double-mouse-downloader project.

Features

• 🚀 Multi-threaded Downloads: Fast downloading with configurable thread count
• 🎬 Multiple Platform Support: Bilibili (with plans for more platforms)
• 📊 Rich CLI Interface: Beautiful terminal UI with progress bars
• ⚙️ Flexible Configuration: Customizable download settings
• 🔍 Video Information: Detailed video metadata and format information
• 🛡️ Error Handling: Robust error handling with retry logic
• 📝 Logging: Comprehensive logging system
• 🎯 Smart File Naming: Automatic safe filename generation

Installation

From Source

git clone https://github.com/tekintian/video-downloader.git
cd video-downloader
pip install -r requirements.txt
pip install -e .

Using pip (when published)

pip install video-downloader

Quick Start

Basic Usage

# Download a video
python main.py download "https://www.bilibili.com/video/BV1xx411c7mD"

# Download with custom output path
python main.py download "https://www.bilibili.com/video/BV1xx411c7mD" -o "/path/to/output.mp4"

# Download with specific quality and threads
python main.py download "https://www.bilibili.com/video/BV1xx411c7mD" -q "best" -t 8

Get Video Information

# Show video details
python main.py info "https://www.bilibili.com/video/BV1xx411c7mD"

Configuration

# Show current configuration
python main.py config

# Set configuration values
python main.py set-config max_threads 8
python main.py set-config download_dir "/path/to/downloads"

CLI Commands

download

Download video from URL

python main.py download [OPTIONS] URL

Options:
  -o, --output PATH     Output file path
  -q, --quality TEXT    Video quality (best/worst/specific format) [default: best]
  -t, --threads INTEGER Number of download threads [default: 4]
  --info-only          Show video info only, no download
  -v, --verbose        Enable verbose logging

info

Show video information without downloading

python main.py info URL

config

Show current configuration

python main.py config

set-config

Set configuration value

python main.py set-config KEY VALUE

Configuration

The application supports both environment variables and configuration files:

Environment Variables

Prefix with VIDEO_DOWNLOADER_:

• VIDEO_DOWNLOADER_MAX_THREADS=4
• VIDEO_DOWNLOADER_DOWNLOAD_DIR=./downloads
• VIDEO_DOWNLOADER_TIMEOUT=30
• VIDEO_DOWNLOADER_RETRY_TIMES=3

Configuration File

Configuration is stored in ~/.video_downloader/config.json:

{
  "download_dir": "./downloads",
  "max_threads": 4,
  "video_quality": "best",
  "subtitle": true,
  "theme": "dark"
}

Architecture

The project follows a modular architecture inspired by double-mouse-downloader:

video_down/
├── src/
│   ├── core/                 # Core functionality
│   │   ├── config.py        # Configuration management
│   │   ├── exceptions.py    # Custom exceptions
│   │   └── logger.py        # Logging setup
│   ├── services/             # Business logic
│   │   ├── bilibili.py      # Bilibili service
│   │   └── downloader.py    # Download engine
│   ├── utils/                # Utility functions
│   │   ├── file_utils.py    # File operations
│   │   └── url_utils.py     # URL handling
│   └── cli/                  # Command line interface
│       └── main.py          # CLI implementation
├── main.py                   # Entry point
├── requirements.txt          # Dependencies
├── setup.py                 # Package setup
└── README.md                # Documentation

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/tekintian/video-downloader.git
cd video-downloader

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements.txt
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/test_bilibili.py

Code Formatting

# Format code
black src/ tests/
isort src/ tests/

# Lint code
flake8 src/ tests/
mypy src/

Requirements

• Python 3.8+
• See requirements.txt for detailed dependencies

Main Dependencies

• yt-dlp: Video extraction and download
• aiohttp: Async HTTP client
• aiofiles: Async file operations
• click: CLI framework
• rich: Rich terminal output
• pydantic: Data validation
• loguru: Logging
• tenacity: Retry logic
• pathvalidate: Safe filename handling

CI / Cross-platform builds ✅

This repository includes a GitHub Actions workflow that automatically builds both Python packages and desktop executables for multiple platforms (Windows, macOS, Linux) on pushes to main and when tags v* are pushed.

• What it builds:

  • Python sdist and wheel (dist/*.tar.gz, dist/*.whl)
  • Desktop standalone executables created with PyInstaller for Windows / macOS / Linux (zipped artifacts uploaded to Actions artifacts)
  • When you push a tag like v1.2.3, the workflow will also create a GitHub Release and attach the build artifacts.

• Where to find artifacts:

  • Open the Actions tab and select the workflow run for the commit/tag. Download artifacts from the run artifacts list.
  • For tagged releases (v*), check the Releases page for attached assets.

• How to trigger manually:

  • Use the Actions → workflow_dispatch button, or push a tag (git tag vX.Y.Z && git push origin vX.Y.Z).

• Notes & extension points:

  • The current workflow uses pyinstaller to produce desktop binaries. If you prefer flet-pack or buildozer for mobile builds (Android/iOS), the workflow can be extended to add those jobs.
  • Signing macOS .app or Windows installers requires additional secrets / signing keys and is not automated by default.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the double-mouse-downloader project
• Built with modern Python async patterns
• UI powered by the excellent Rich library

Roadmap

• Support for YouTube
• Support for more platforms (TikTok, Instagram, etc.)
• GUI interface (Electron/React)
• Playlist/Batch downloads
• Auto subtitle download
• Video conversion capabilities
• Download scheduling
• Browser extension

Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Join our Discussions for general questions

---

Happy Downloading! 🚀