tubegrab 0.1.1
A simple library for extracting YouTube content using yt-dlp
Requires Python: >=3.11
Keywords: youtube, extract, yt-dlp

# 🎥🎵 Tubegrab

[![PyPI version](https://img.shields.io/pypi/v/tubegrab.svg)](https://pypi.org/project/tubegrab/)
[![Python versions](https://img.shields.io/pypi/pyversions/tubegrab.svg)](https://pypi.org/project/tubegrab/)
[![License](https://img.shields.io/pypi/l/tubegrab.svg)](https://pypi.org/project/tubegrab/)
[![Downloads](https://static.pepy.tech/badge/tubegrab)](https://pepy.tech/project/tubegrab)

A Python library for extracting **video, audio, and metadata** from YouTube.

It provides a clean **dataclass-based API** with built-in JSON serialization (`to_json` / `from_json`) and integrates well with frameworks like **Django REST Framework**.

Built on top of yt-dlp for reliable and fast YouTube extraction.

---

# 📚 Table of Contents

* [✨ Features](#-features)
* [📦 Installation](#-installation)
* [🚀 Quick Start](#-quick-start)
* [🗂 JSON Serialization](#-json-serialization)
* [⚙️ Django REST Framework Integration](#-django-rest-framework-integration)
* [🛠 Development](#-development)
* [🤝 Contributing](#-contributing)
* [📦 Build & Publish](#-build--publish)
* [🔐 Versioning](#-versioning)
* [📝 License](#-license)

---

## ✨ Features

* 📥 Extract video metadata – title, id, duration, uploader, thumbnails, and more
* 🎶 List all available audio formats – codecs, bitrates, container, size, and direct download URL
* 🎬 List all available video formats – resolution, fps, codecs, container, and direct download URL
* 🌍 Subtitle extraction – download subtitles in multiple languages
* 💾 Built-in serialization (`to_json` / `from_json`)
* 🛠 Django REST Framework friendly
* ⚡ Powered by `yt-dlp`

---

## 📦 Installation

```bash
pip install tubegrab
```

> Requires **Python 3.8+**

---

## 🚀 Quick Start

```python
from tubegrab import YouTube

video_url = "https://www.youtube.com/watch?v=Wpi1_RsRaAU"

youtube = YouTube(video_url)
youtube.extract_info(download=True)

# Metadata
data = youtube.video_data()
print("Title:", data.title)
print("Duration:", data.duration)
print("Uploader:", data.uploader)

# Audio formats
audio = youtube.audio_formats()
print(audio.to_json())

# Video formats
videos = youtube.video_formats()
print(videos.to_json())

# Subtitles (if available)
if data.subtitles:
    for lang, subs in data.subtitles.items():
        print(f"Language: {lang}, Available formats: {[s.ext for s in subs]}")
```

---

## 🗂 JSON Serialization

All returned objects support:

* `to_json(to_dict=True)` → convert to serializable dictionary
* `from_json(data)` → restore object from dictionary

Example:

```python
import json
from tubegrab import YouTube

youtube = YouTube("https://www.youtube.com/watch?v=Wpi1_RsRaAU")
youtube.extract_info(download=True)

data = youtube.video_data()

# Save
with open("video.json", "w") as f:
    json.dump(data.to_json(to_dict=True), f, indent=4)

# Restore
with open("video.json", "r") as f:
    restored = YouTube.VideoData.from_json(json.load(f))
    print(restored.title)
```

---

## ⚙️ Django REST Framework Integration

```python
from rest_framework import serializers
from tubegrab import YouTube


class VideoDataSerializer(serializers.Serializer):
    id = serializers.CharField()
    title = serializers.CharField()
    duration = serializers.IntegerField()
    uploader = serializers.CharField()
    thumbnails = serializers.ListField()


youtube = YouTube("https://www.youtube.com/watch?v=Wpi1_RsRaAU")
youtube.extract_info()

serializer = VideoDataSerializer(
    youtube.video_data().to_json(to_dict=True)
)

print(serializer.data)
```

---

# 🛠 Development

### Clone the repository

```bash
git clone https://github.com/yourusername/tubegrab.git
cd tubegrab
```

### Create virtual environment

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

### Install in editable mode

```bash
pip install -e .
```

---

# 🤝 Contributing

Contributions are welcome!

## How to Contribute

1. Fork the repository

2. Create a new branch

   ```bash
   git checkout -b feature/my-feature
   ```

3. Make your changes

4. Add tests (if applicable)

5. Commit your changes

   ```bash
   git commit -m "Add: my new feature"
   ```

6. Push to your fork

   ```bash
   git push origin feature/my-feature
   ```

7. Open a Pull Request

---

## Code Style

* Follow **PEP 8**
* Use type hints
* Keep API clean and minimal
* Ensure serialization (`to_json` / `from_json`) remains stable

---

# 📦 Build & Publish

This project uses a modern `pyproject.toml` build system.

## 1️⃣ Install build tools

```bash
pip install build twine
```

## 2️⃣ Build the package

```bash
python -m build
```

This generates:

```
dist/
 ├── tubegrab-x.x.x.tar.gz
 └── tubegrab-x.x.x-py3-none-any.whl
```

---

## 3️⃣ Upload to TestPyPI (Recommended)

```bash
twine upload --repository testpypi dist/*
```

Test installation:

```bash
pip install --index-url https://test.pypi.org/simple/ tubegrab
```

---

## 4️⃣ Publish to PyPI

```bash
twine upload dist/*
```

---

# 🔐 Versioning

Use **Semantic Versioning**:

```
MAJOR.MINOR.PATCH
```

Examples:

* `1.0.0` – First stable release
* `1.1.0` – New features
* `1.1.1` – Bug fixes

---

# 📝 License

MIT License © 2026