TubeZ

A powerful, self-hosted web dashboard to search, play, and download video or audio from hundreds of sites using yt-dlp.

Table of Contents

• ✨ Features in Depth
• 🛠️ Technology Stack
• 🚀 Installation
• ▶️ How to Run
• 🐳 Docker Deployment (Advanced)
• 🔧 Configuration
• 🤝 Contributing
• 📄 License

✨ Features in Depth

• Modern & Responsive UI: Clean, beautiful, and mobile-friendly interface built with Bootstrap. It includes a dark mode theme and a fully responsive layout that works on any device.

• Universal Support:

  • YouTube Search: Find any video on YouTube directly from the app.
  • Direct URL Support: Paste a video, playlist, or channel URL from hundreds of websites supported by yt-dlp.

• Direct Streaming: Why wait? Play videos and audio directly in your browser with a multi-stage loading animation that provides clear feedback. It intelligently handles sites that don't support direct streaming.

• Advanced Downloads:

  • Format Selection: Choose the exact video quality, audio quality, or file format you need.
  • Playlist & Channel Downloading: Paste a playlist or channel URL, select the videos you want, and download them all in one go.
  • One-Click Audio: A dedicated "Get Audio" button streamlines downloading music and podcasts.
  • Subtitle Support: Automatically fetches available subtitle languages and allows you to embed them directly into your downloaded video file.

• Robust Download Management:

  • Background Queue: Add multiple items to a download queue that processes sequentially in the background, so you can keep browsing.
  • Live Progress: The UI dynamically updates to show real-time download progress, speed, and ETA without needing a page refresh.
  • File Management: View, download, and delete your completed files directly from the web interface.

• Secure & Maintainable:

  • Self-Hosted: You control your data. Run it on your own machine, home server, or in the cloud.
  • Password Protection: An optional password can be set to protect access to the dashboard.
  • Auto-Update Notifications: The app automatically checks for new versions on PyPI and will prompt for an update, ensuring you're always on the latest stable release.

🛠️ Technology Stack

• Backend: Python with Flask
• Core Engine: yt-dlp for all media downloading and metadata extraction.
• Frontend: Bootstrap 5, HTML5, CSS3, and modern JavaScript (no framework).
• WSGI Server: Waitress for a lightweight production-ready server.
• Packaging: PyPI for distribution and GitHub Actions for automated publishing.

🚀 Installation

Make sure you have Python 3.8+ and ffmpeg installed on your system.

On Linux (Debian/Ubuntu)

sudo apt update && sudo apt install python3 python3-pip ffmpeg -y

On Termux (Android)

pkg update && pkg install python ffmpeg -y

Install with pip (Recommended)

(Note: You may need to use pip3 instead of pip on some systems).

▶️ How to Run

After a successful installation, you can start the web server from anywhere in your terminal.

1. Install using pip:

   pip install TubeZ
   

2. Start the Server:

   tubez
   

3. Open the Web Dashboard: Open your web browser and go to: http://127.0.0.1:8089

4. Find Your Files: Your downloaded videos and audio will be saved in a folder named TubeZ inside your main Downloads directory. This can be changed in the Settings page.