youtube-colab-proxy 0.5.2

A Python web application that provides a YouTube video streaming proxy with a built-in web player. Designed to work seamlessly in Google Colab environments while also supporting local development and deployment.

YouTube Colab Proxy

A Python web application that provides a YouTube video streaming proxy with a built-in web player. Designed to work seamlessly in Google Colab environments while also supporting local development and deployment.

Features

🎥 Video Streaming

• Direct YouTube video streaming through a proxy server
• Progressive MP4 format support (≤720p) with both audio and video
• Range request support for video seeking and partial content delivery
• Automatic format selection using yt-dlp for optimal compatibility

🔍 Search & Discovery

• YouTube search functionality with keyword-based video discovery
• Playlist support for YouTube playlists and channel videos
• Paginated results for efficient browsing

🛡️ Security & Configuration

• Optional password protection using SHA256 hashing
• Cookie support for accessing age-restricted or private content
• Configurable geo-bypass and language settings
• Outbound proxy support for network routing

Installation

From Source

# Clone the repository
git clone https://github.com/DAN3002/Youtube-Colab-Proxy.git
cd Youtube-Colab-Proxy

# Install in development mode
pip install -e .

Using pip (when published)

pip install youtube-colab-proxy

Quick Start

Command Line Interface

# Start the web server
ycp --serve

# Specify custom host and port
ycp --serve --host 127.0.0.1 --port 8080

# Start with password protection
ycp --serve --password your_password

# Use YouTube cookies for private/age-restricted content
ycp --serve --cookies /path/to/cookies.txt

# Use raw cookie string
ycp --serve --cookies-str "session_token=abc123; other_cookie=xyz"

Google Colab Usage

# Install in Colab
!pip install youtube-colab-proxy

# Start the proxy server
import youtube_colab_proxy
url = youtube_colab_proxy.start()

# The app will automatically:
# 1. Start a Flask server
# 2. Create a public Colab proxy URL
# 3. Display a clickable link in the output

Configuration

Environment Variables

The application can be configured through constants in src/youtube_colab_proxy/const.py:

# Pagination settings
PL_PAGE_SIZE = 8  # Number of items per page

# Security (set to enable password protection)
ADMIN_PASSWORD_SHA256 = "your_sha256_hash_here"

# Localization
YT_LANG = "en-US"  # Language preference
YT_GEO_BYPASS_COUNTRY = "US"  # Country for geo-bypass

# Network settings
OUTBOUND_PROXY = ""  # Optional proxy for outbound requests

Password Protection

To enable password protection:

1. Generate a SHA256 hash of your password:

import youtube_colab_proxy
hash_value = youtube_colab_proxy.hash_pass("your_password")
print(hash_value)

2. Set the hash in const.py:

ADMIN_PASSWORD_SHA256 = "your_generated_hash"

3. Start the server with the password:

ycp --serve --password your_password

API Endpoints

Web Interface

• GET / - Main web application interface

Video Operations

• GET /stream?id={video_id} - Stream YouTube video by ID
• GET /stream?url={youtube_url} - Stream YouTube video by URL

Search & Discovery

• GET /api/search?q={query}&page={page} - Search YouTube videos
• GET /api/playlist?url={playlist_url}&page={page} - Get playlist/channel videos
• GET /api/thumb/{video_id}?q={quality} - Get video thumbnail

Dependencies

• yt-dlp - YouTube video extraction and metadata
• Flask - Web application framework
• youtube-search-python - YouTube search functionality
• portpicker - Automatic port selection
• requests - HTTP client for proxy streaming

Development

Setup Development Environment

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

# Install development dependencies
pip install -U pip setuptools wheel build pytest
pip install -e .

Author

• @DAN3002

License

Apache License 2.0 - see LICENSE file for details.

Contributing

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

Disclaimer

This tool is for educational and legitimate use cases only. Please respect YouTube's Terms of Service and copyright laws. Users are responsible for ensuring their usage complies with applicable laws and regulations.