tubegrab 0.1.0

A simple library for extracting YouTube content using yt-dlp

🎥🎵 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
• 📦 Installation
• 🚀 Quick Start
• 🗂 JSON Serialization
• ⚙️ Django REST Framework Integration
• 🛠 Development
• 🤝 Contributing
• 📦 Build & Publish
• 🔐 Versioning
• 📝 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

pip install tubegrab

Requires Python 3.8+

---

🚀 Quick Start

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:

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

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

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

Create virtual environment

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

Install in editable mode

pip install -e .

---

🤝 Contributing

Contributions are welcome!

How to Contribute

1. Fork the repository

2. Create a new branch

   git checkout -b feature/my-feature
   

3. Make your changes

4. Add tests (if applicable)

5. Commit your changes

   git commit -m "Add: my new feature"
   

6. Push to your fork

   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

pip install build twine

2️⃣ Build the package

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)

twine upload --repository testpypi dist/*

Test installation:

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

---

4️⃣ Publish to PyPI

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