Metadata-Version: 2.4
Name: converso-ytdl
Version: 1.0.19b0
Summary: Professional-grade YouTube & media downloader from Converso Empire - Enterprise-ready Python library for downloading videos, audio, and playlists with advanced features
Project-URL: Homepage, https://github.com/converso-empire/converso-ytdl
Project-URL: Documentation, https://github.com/converso-empire/converso-ytdl/blob/main/README.md
Project-URL: Repository, https://github.com/converso-empire/converso-ytdl.git
Project-URL: Bug Tracker, https://github.com/converso-empire/converso-ytdl/issues
Project-URL: Source Code, https://github.com/converso-empire/converso-ytdl
Project-URL: Contributing, https://github.com/converso-empire/converso-ytdl/blob/main/CONTRIBUTING.md
Project-URL: Security, https://github.com/converso-empire/converso-ytdl/blob/main/SECURITY.md
Project-URL: Changelog, https://github.com/converso-empire/converso-ytdl/blob/main/CHANGELOG.md
Author-email: Converso Empire <info@conversoempire.com>
Maintainer-email: Converso Engineering Team <engineering@conversoempire.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: audio,batch-download,conversion,downloader,enterprise,ffmpeg,media,multimedia,playlist,streaming,video,youtube,yt-dlp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: rich>=13.0.0
Requires-Dist: yt-dlp>=2024.1.1
Provides-Extra: all
Requires-Dist: bandit>=1.7; extra == 'all'
Requires-Dist: black>=23.0; extra == 'all'
Requires-Dist: fastapi>=0.110.0; extra == 'all'
Requires-Dist: flake8-docstrings>=1.7; extra == 'all'
Requires-Dist: flake8>=6.0; extra == 'all'
Requires-Dist: isort>=5.0; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: pydantic>=2.0.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: requests>=2.31.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.110.0; extra == 'api'
Requires-Dist: pydantic>=2.0.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: flake8-docstrings>=1.7; extra == 'dev'
Requires-Dist: flake8>=6.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: webhooks
Requires-Dist: requests>=2.31.0; extra == 'webhooks'
Description-Content-Type: text/markdown

# Converso Media Downloader

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/converso-ytdl.svg)](https://pypi.org/project/converso-ytdl/)
[![Python versions](https://img.shields.io/pypi/pyversions/converso-ytdl.svg)](https://pypi.org/project/converso-ytdl/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/converso-empire/converso-ytdl/tests.yml?branch=main)](https://github.com/converso-empire/converso-ytdl/actions)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![Security: bandit](https://img.shields.io/badge/security-bandit-green.svg)](https://github.com/PyCQA/bandit)

**Professional-grade Python library for downloading YouTube videos, playlists, and audio with enterprise-level features.**

Built and maintained by **[Converso Empire](https://converso.io/)** | [Documentation](#documentation) | [Quick Start](#installation) | [API Reference](API_REFERENCE.md)

</div>

---

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Configuration](#configuration)
- [Advanced Features](#advanced-features)
- [REST API](#rest-api)
- [Docker](#docker)
- [Troubleshooting](#troubleshooting)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#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)

```bash
# 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](https://ffmpeg.org/download.html) 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)

```bash
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)

```bash
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)

```bash
# 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)

```python
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)

```bash
# Start server
converso-ytdl-api --host 0.0.0.0 --port 8000

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

```bash
# 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`:

```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:

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

### Audio Formats

| Format | Quality | Usecase | Command |
|--------|---------|---------|---------|
| **FLAC** | Lossless, 16/24/32-bit | Archival, professional | `--codec flac --sample-rate 96000 --bit-depth 24` |
| **WAV** | Lossless, uncompressed | Editing, mixing | `--codec wav --sample-rate 48000` |
| **MP3** | Lossy, broad compatibility | Portable devices | `--codec mp3` |
| **AAC** | Lossy, 320 kbps | iTunes, Apple devices | `--codec aac` |
| **Opus** | Modern lossy, best compression | Streaming | `--codec opus` |
| **OGG** | Open source, Vorbis | Web, Linux | `--codec ogg` |

---

## Advanced Features

### Batch Download with Progress

```bash
# 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

```bash
# 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

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

### Detailed Logging

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

# View logs
tail -f download.log
```

### Rate Limiting & Proxies

```bash
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](API_REFERENCE.md)

### Key Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/health` | Server health & statistics |
| GET | `/api/v1/info?url=...` | Video metadata |
| GET | `/api/v1/formats?url=...` | Available formats |
| **POST** | `/api/v1/jobs/video` | **Start video download** |
| **POST** | `/api/v1/jobs/audio` | **Start audio download** |
| **POST** | `/api/v1/jobs/batch` | **Batch download** |
| **POST** | `/api/v1/jobs/playlist` | **Playlist download** |
| GET | `/api/v1/jobs` | List all jobs |
| GET | `/api/v1/jobs/{id}` | Job status |
| GET | `/api/v1/jobs/{id}/download` | Download completed file |
| DELETE | `/api/v1/jobs/{id}` | Delete job record |

### Example: Python Client

```python
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

```bash
# 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 0.0.0.0
```

### Docker Compose

```yaml
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 0.0.0.0 --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](README.md)
- 🏗️ See [Architecture](ARCHITECTURE.md)
- 🔗 View [API Reference](API_REFERENCE.md)
- 🤝 See [Contributing Guide](CONTRIBUTING.md)
- 🐛 Report [Issues](https://github.com/converso-empire/converso-ytdl/issues)
- 🔐 Report [Security Issues](SECURITY.md)

---

## Documentation

Comprehensive guides available:

- 📄 **[Quick Start Guide](GETTING_STARTED.md)** - 5-minute setup guide
- 🏗️ **[Architecture](ARCHITECTURE.md)** - System design and internals
- 🔌 **[API Reference](API_REFERENCE.md)** - Complete API documentation
- 📦 **[Deployment Guide](DEPLOYMENT.md)** - Publishing to PyPI
- 🤝 **[Contributing](CONTRIBUTING.md)** - Development guidelines
- 🔐 **[Security Policy](SECURITY.md)** - Vulnerability reporting
- 📋 **[Changelog](CHANGELOG.md)** - Version history

---

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:

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

### Quick Links

- **Report Issues**: [GitHub Issues](https://github.com/converso-empire/converso-ytdl/issues)
- **Discussions**: [GitHub Discussions](https://github.com/converso-empire/converso-ytdl/discussions)
- **Security**: [SECURITY.md](SECURITY.md)
- **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

---

## License

Licensed under the **Apache License 2.0**. See [LICENSE](LICENSE) for details.

© 2025 **Converso Empire** – Professional Media Tools

---

## Acknowledgments

Built with:
- 🎬 [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Media downloading engine
- ⚡ [FastAPI](https://fastapi.tiangolo.com/) - Web framework
- 🎨 [Rich](https://rich.readthedocs.io/) - Terminal formatting
- 🎛️ [FFmpeg](https://ffmpeg.org/) - Media processing

---

**Made with ❤️ by Converso Empire**

[⬆ Back to Top](#converso-media-downloader)

