youtube-colab-proxy 2.1.0

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 feature-rich YouTube streaming proxy with a built-in web player. Watch videos, browse channels, explore playlists, and read comments — all through a clean, YouTube-inspired dark UI. Designed for Google Colab but works anywhere Python runs.

✨ Features

Video Streaming

• Proxy-based playback — streams MP4 bytes directly, no client-side extraction
• Up to 1080p support — automatically merges separate video+audio streams via ffmpeg for HD quality (works on Colab too!)
• Range requests for instant seeking and partial content delivery
• Resolution selector — choose quality or let auto-select pick the best available
• Theater & normal modes with keyboard shortcuts (Space, J/L, F)

Search & Discovery

• YouTube search with paginated results
• Channel pages — Videos tab, Playlists tab, and in-channel search
• Channel banners & avatars proxied for privacy
• Playlist viewer with numbered tracks and channel links
• Recommended videos sidebar on the watch page
• Watch history persisted in the browser

Comments

• Top-level comments with sort (Top / Newest) and adjustable limit
• Lazy-loaded replies — click to expand, no upfront cost
• Pinned & hearted badges, relative timestamps, avatars

Infrastructure

• FastAPI + Uvicorn — async, fast, production-ready
• In-memory TTL caching — streams (20 min), comments (10 min), streamlink (5 min)
• Image proxy — thumbnails and avatars routed through the server (no CORS, no tracking)
• Cookie support — file, raw string, or browser import for age-restricted / private content
• Password protection via SHA256 gate
• Google Colab integration — auto-detects Colab, generates public proxy URL

📦 Installation

From PyPI

pip install youtube-colab-proxy

From Source

git clone https://github.com/DAN3002/Youtube-Colab-Proxy.git
cd Youtube-Colab-Proxy
pip install -e .

Requirement: A JavaScript runtime (node, deno, or bun) is needed by yt-dlp for full YouTube extraction. Install one before running.

🚀 Quick Start

CLI

# Start the server
ycp --serve

# Custom host and port
ycp --serve --host 0.0.0.0 --port 8080

# With password protection
ycp --serve --password my_secret

# With cookies (age-restricted / private videos)
ycp --serve --cookies /path/to/cookies.txt
ycp --serve --cookies-str "SID=abc; HSID=xyz"
ycp --serve --cookies-from-browser chrome

Google Colab

Cell 1 — Install:

!pip install youtube-colab-proxy
!apt-get update -qq && apt-get install -y -qq nodejs

Cell 2 — Run:

import youtube_colab_proxy
url = youtube_colab_proxy.start()
# → Opens a clickable public URL in the output

With cookies:

url = youtube_colab_proxy.start(cookies_str="YOUR_COOKIE_STRING")

Note: apt-get install nodejs provides the JS runtime that yt-dlp needs. Without it, some video formats may be missing.

⚙️ Configuration

Edit youtube_colab_proxy/const.py:

PL_PAGE_SIZE = 8                    # Items per page
ADMIN_PASSWORD_SHA256 = "..."       # SHA256 hash (empty = no password)
YT_LANG = "en-US"                   # Accept-Language for yt-dlp
YT_GEO_BYPASS_COUNTRY = "US"       # Geo-bypass country code
OUTBOUND_PROXY = ""                 # Optional HTTP/SOCKS proxy

Password Protection

import youtube_colab_proxy
print(youtube_colab_proxy.hash_pass("my_password"))
# → paste the hash into const.py as ADMIN_PASSWORD_SHA256

Then start with:

ycp --serve --password my_password

🛠️ Development

# Clone & setup
git clone https://github.com/DAN3002/Youtube-Colab-Proxy.git
cd Youtube-Colab-Proxy
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Run (auto-creates venv if needed)
./run_ycp.sh

Tech Stack

Layer	Technology
Backend	FastAPI + Uvicorn
Extraction	yt-dlp + yt-dlp-ejs
Live Streams	Streamlink
Frontend	Tailwind CSS (CDN) + Vanilla JS
Templating	Jinja2
Video Playback	hls.js
Icons	Font Awesome 6

📄 License

Apache License 2.0

🤝 Contributing

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

⚠️ Disclaimer

This project is for educational and community purposes only. It is not intended to violate any company's policies or applicable laws. Users are responsible for ensuring their usage complies with YouTube's Terms of Service and local regulations.

---

Made by @DAN3002 · Powered by yt-dlp