Converso Media Downloader

Table of Contents

• Features
• Installation
• Quick Start
• Usage
• Configuration
• Advanced Features
• REST API
• Docker
• Troubleshooting
• Documentation
• Contributing
• License

Features

🎬 Download Capabilities

✅ Video Downloads

• Best-quality video in MKV/MP4/WebM containers
• 4K/8K support with adaptive bitrate selection
• Automatic subtitle embedding (20+ languages)
• Thumbnail and metadata embedding
• Format fallback if preferred quality unavailable

✅ Audio Extraction

• Professional audio codecs: WAV, FLAC, MP3, AAC, Opus, OGG
• Lossless FLAC at up to 192kHz/24-bit
• Batch conversion with parallel processing
• Metadata tagging (ID3v2, Vorbis comments)

✅ Playlist & Batch

• Full playlist downloading with archive progress tracking
• Parallel batch processing (2-8 concurrent workers)
• Error recovery with configurable retry logic
• Resume support for interrupted downloads

✅ Advanced Processing

• FFmpeg-based upscaling to 4K/8K (Lanczos or bilinear filtering)
• Local file analysis with ffprobe (codec, bitrate, resolution)
• Format inspection without downloading

🔧 Developer Features

✅ Integration Options

• Clean Python API for programmatic use
• FastAPI REST server with async job management
• CLI with interactive menu and argument modes
• Webhook support for job completion notifications

✅ Production-Ready

• Thread-safe design for concurrent downloads
• Comprehensive error handling and logging
• Type hints throughout (Python 3.8+)
• Exhaustive documentation with examples

✅ Enterprise Features

• Configurable retry logic with exponential backoff
• Job history and status tracking
• Cookie/proxy/authentication support
• Rate limiting and socket timeouts
• Extensive logging (file + console)

Installation

From PyPI (Recommended)

# Basic installation (CLI and Python API)
pip install converso-ytdl

# With REST API server support
pip install converso-ytdl[api]

# With webhook notifications
pip install converso-ytdl[webhooks]

# Complete installation (everything)
pip install converso-ytdl[all]

System Requirements

FFmpeg must be installed:

• Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
• macOS: brew install ffmpeg
• Windows: Download here or choco install ffmpeg
• Docker: Use official ffmpeg image

Python: 3.8 or 3.9 or 3.10 or 3.11 or 3.12

From Source (Development)

git clone https://github.com/converso-empire/converso-ytdl.git
cd converso-ytdl

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -e ".[all]"

Quick Start

1️⃣ Interactive Mode (Easiest)

converso-ytdl

Follow the on-screen menu:

1. Download video - Select quality and container
2. Download audio - Choose codec and sample rate
3. Batch download - Upload file with URLs
4. Playlist download - Paste playlist URL
5. Get info - View video metadata
6. List formats - See all available qualities
7. Upscale video - Enhance resolution
8. Analyze file - Inspect local media

2️⃣ Command Line (Flexible)

# Download best-quality video
converso-ytdl video "https://youtu.be/dQw4w9WgXcQ"

# Download audio as FLAC (192kHz 24-bit)
converso-ytdl audio "https://youtu.be/..." \
  --codec flac --sample-rate 192000 --bit-depth 24

# Batch download with 4 parallel workers
converso-ytdl batch -f urls.txt --workers 4

# Download playlist (with progress tracking)
converso-ytdl playlist "https://www.youtube.com/playlist?list=..." \
  --mode audio --archive done.txt

3️⃣ Python API (Programmatic)

from converso_ytdl import MediaDownloader, DownloadConfig

# Configuration
config = DownloadConfig(
    output_dir="downloads",
    video_container="mkv",
    verbose=True
)

# Create downloader
downloader = MediaDownloader(config)

# Download video
result = downloader.download_video("https://youtu.be/...")

if result.status == "success":
    print(f"✓ Downloaded: {result.output_file}")
    print(f"  Resolution: {result.resolution}")
    print(f"  Size: {result.file_size / 1024 / 1024:.1f} MB")
else:
    print(f"✗ Error: {result.error}")

4️⃣ REST API Server (Remote Access)

# Start server
converso-ytdl-api --host localhost --port 8000

# Interactive API docs: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc

# Get video info
curl "http://localhost:8000/api/v1/info?url=https://youtu.be/..."

# Start async download
curl -X POST http://localhost:8000/api/v1/jobs/video \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/...", "container": "mkv"}'

Usage

Configuration Files

Create config.json:

{
  "output_dir": "downloads",
  "video_container": "mkv",
  "embed_thumbnail": true,
  "embed_metadata": true,
  "audio_codec": "flac",
  "audio_sample_rate": 96000,
  "audio_bit_depth": 24,
  "workers": 2,
  "retries": 5,
  "verbose": false
}

Use it:

converso-ytdl --config config.json video "https://youtu.be/..."

Audio Formats

Advanced Features

Batch Download with Progress

# urls.txt (one URL per line)
https://youtu.be/aaa
https://youtu.be/bbb
# https://youtu.be/ccc  [commented] 
https://youtu.be/ddd

converso-ytdl batch -f urls.txt --workers 2 --delay 1

Playlist with Archive Tracking

# Download new videos only (tracks what's downloaded)
converso-ytdl playlist "https://www.youtube.com/playlist?list=..." \
  --archive playlist_archive.txt \
  --mode audio

Upscaling Videos

# Upscale 1080p video to 4K using Lanczos filtering
converso-ytdl upscale video.mkv --target 4k --method lanczos

Detailed Logging

converso-ytdl \
  --verbose \
  --log-file download.log \
  video "https://youtu.be/..."

# View logs
tail -f download.log

Rate Limiting & Proxies

converso-ytdl video "https://youtu.be/..." \
  --rate-limit 5M \
  --proxy "http://user:pass@proxy.example.com:8080"

REST API

Full API documentation at API_REFERENCE.md

Key Endpoints

Example: Python Client

import requests
import time

BASE_URL = "http://localhost:8000/api/v1"

# Start download
response = requests.post(
    f"{BASE_URL}/jobs/video",
    json={"url": "https://youtu.be/...", "container": "mkv"}
)
job_id = response.json()["job_id"]

# Poll status
while True:
    status = requests.get(f"{BASE_URL}/jobs/{job_id}").json()
    print(f"Status: {status['status']}")
    
    if status['status'] == "completed":
        print(f"Downloaded: {status['output_file']}")
        break
    elif status['status'] == "failed":
        print(f"Error: {status['error']}")
        break
    
    time.sleep(2)

Docker

Using Docker

# Build image
docker build -t converso-ytdl .

# Run downloader
docker run -v $(pwd)/downloads:/app/downloads converso-ytdl:latest \
  video "https://youtu.be/..."

# Run API server
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/downloads:/app/downloads \
  converso-ytdl:latest \
  converso-ytdl-api --host localhost

Docker Compose

version: '3.8'

services:
  converso-api:
    image: converso-ytdl:latest
    container_name: converso-media-downloader
    ports:
      - "8000:8000"
    volumes:
      - ./downloads:/app/downloads
      - ./logs:/app/logs
    environment:
      - LOG_LEVEL=INFO
    command: converso-ytdl-api --host localhost --port 8000
    restart: unless-stopped

Troubleshooting

Common Issues

Q: "Video not available in your country"
A: Use --proxy flag or change your network location.

Q: "Permission denied" on output file
A: Ensure write permissions: chmod 755 downloads/

Q: "FFmpeg not found"
A: Install FFmpeg using your package manager.

Q: API server won't start
A: Ensure port 8000 is free: lsof -i :8000

Q: Memory usage very high
A: Reduce --workers (default 2) or memory-intensive operations.

Getting Help

• 📖 Check Documentation
• 🏗️ See Architecture
• 🔗 View API Reference
• 🤝 See Contributing Guide
• 🐛 Report Issues
• 🔐 Report Security Issues

Documentation

Comprehensive guides available:

• 📄 Quick Start Guide - 5-minute setup guide
• 🏗️ Architecture - System design and internals
• 🔌 API Reference - Complete API documentation
• 📦 Deployment Guide - Publishing to PyPI
• 🤝 Contributing - Development guidelines
• 🔐 Security Policy - Vulnerability reporting
• 📋 Changelog - Version history

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• How to report bugs
• How to suggest features
• Development setup
• Pull request process
• Code standards

Quick Links

• Report Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: SECURITY.md
• Code of Conduct: CODE_OF_CONDUCT.md

License

Licensed under the Apache License 2.0. See LICENSE for details.

© 2025 Converso Empire – Professional Media Tools

Acknowledgments

Built with:

• 🎬 yt-dlp - Media downloading engine
• ⚡ FastAPI - Web framework
• 🎨 Rich - Terminal formatting
• 🎛️ FFmpeg - Media processing

Made with ❤️ by Converso Empire

⬆ Back to Top