the-toob 1.0.0

A modern interface for automating a browser to upload videos to YouTube.

TheToob

"Hey bubba, what's on the Toob?"

TheToob is a Python package for uploading videos to YouTube using Selenium. It's a heavily modified and modernized fork of the original youtube_uploader_selenium by linouk23, refactored for robustness, maintainability, and modern features.

Like the original, this tool automates the browser to upload videos, bypassing the daily quota limits of the official YouTube Data API.

---

⭐ Key Features & Improvements

• Modern Architecture: Fully refactored into an object-oriented structure (Uploader, UploaderPage, ToobBrowser) for better readability and maintenance.
• Headless Operation: Run the uploader in the background without a visible browser window, perfect for servers and automation scripts.
• Robust Error Handling: Automatically saves a crash report with a screenshot and HTML dump if an operation fails, making debugging significantly easier.
• Enhanced Stability: Uses explicit waits and more reliable element locators to prevent common race conditions and timing errors.
• Updated YouTube Options: Supports newer metadata fields including:
  • Video visibility (Public, Private, Unlisted)
  • paid_promotion disclosures
  • altered_content disclosures for AI-generated or modified media
• Simplified Dependencies: Uses the core selenium library directly, removing the need for extra wrappers.

---

⚙️ Installation

pip3 install --upgrade the-toob

---

🚀 Usage

The package is designed to be used as a library within your Python projects.

🤓 First-Time Setup: Creating a Logged-in Profile

Due to Google's security policies, you cannot log in for the first time within the automated browser. You must first create a dedicated Firefox profile and log in manually using a normal browser window.

This is a one-time setup.

1. Open Firefox: Launch your regular Mozilla Firefox browser.

2. Go to Profiles Page: Type about:profiles into the address bar and press Enter.

3. Create a New Profile: Click the "Create a New Profile" button and follow the wizard.

4. Set the Profile Path: When prompted, click "Choose Folder...". Navigate to your project's folder and select the profiles/firefox_profile directory. This is critical for linking the profile to TheToob.

5. Launch and Log In: Find your new profile in the list and click "Launch profile in new browser". In the new Firefox window that opens, navigate to YouTube and log in to your Google account as you normally would.

6. Close the Profile: Once you are successfully logged in, you can close that Firefox window.

7. Run TheToob for the First Time: Now, run the thetoob command from your terminal. The script will open the browser you just logged into, pause with a message about saving cookies, and create the cookies.pkl file.

After this initial run, all future runs can be fully automated and headless.

Standard (Headless) Upload

Once authenticated, you can run the uploader in headless mode.

from youtube_uploader_selenium import Uploader
import logging

logging.basicConfig(level=logging.INFO)

# Define your video metadata
# This can also be loaded from a JSON file (see below)
video_metadata = {
    "title": "Mr. Game & Watch: The Secrets of Nair 1, 2, and 3",
    "description": "Sure, the fourth one pops them up, but Ftilt is cool, too...",
    "tags": ["carried"],
    "visibility": "PUBLIC",
    "paid_promotion": False,
    "altered_content": False
}

uploader = Uploader(
    video_path='path/to/your/video.mp4',
    thumbnail_path='path/to/your/thumbnail.jpg', # Optional
    metadata=video_metadata,
    profile_path='path/to/your/firefox_profile',
    headless=True # Headless is now possible
)
was_uploaded, video_id = uploader.upload()

---

📝 Metadata Guide

You can provide metadata as a dictionary (as shown above) or as a path to a JSON file.

Example metadata.json file:

video_metadata = {
    "title": "Mr. Game & Watch: The Secrets of Nair 1, 2, and 3",
    "description": "Sure, the fourth one pops them up, but Ftilt is cool, too...",
    "tags": ["carried"],
    "visibility": "PUBLIC",
    "paid_promotion": False,
    "altered_content": False
}

Metadata Fields

• title (str): The video title. If not provided, it defaults to the video's filename.
• description (str): The video description. \n characters are respected.
• tags (List[str]): A list of tags for the video.
• visibility (str): Sets the video's visibility. Must be one of PUBLIC, PRIVATE, or UNLISTED. Defaults to PRIVATE if not specified.
• paid_promotion (bool): Set to True if the video contains a paid promotion.
• altered_content (bool): Set to True if the video contains significantly altered or synthetic content that looks realistic.

---

💻 Command-Line Usage

Once installed, TheToob can be used directly from your terminal.

Basic Usage:

thetoob --video "path/to/my/video.mp4"

# Full Featured Usage:
```bash
thetoob --video "video.mp4" --meta "metadata.json" --thumbnail "thumb.jpg" --headless

Alternative Usage:

You can also run it as a Python module.

python3 -m the_toob --video "video.mp4"

Available Arguments:

--video: (Required) The path to the video file you want to upload.

--meta: (Optional) Path to a .json file containing the video's metadata.

--thumbnail: (Optional) Path to a custom thumbnail image for the video.

--profile: (Optional) The directory to use for the Firefox profile and cookies. Defaults to ./firefox_profile.

--headless: (Optional) A flag to run the browser in headless mode (no visible UI).

---

📦 Dependencies & Driver Management

• Mozilla Firefox: A modern, up-to-date version is recommended.
• selenium: The core automation library.

A Note on GeckoDriver

Modern versions of Selenium (4.6.0 and newer) include Selenium Manager, a tool that automatically downloads and manages the necessary web driver for you.

For most users, this means you do not need to manually download geckodriver. The first time you run TheToob, Selenium will download the correct driver and cache it for future use.

Manual Override: If you are behind a strict corporate firewall or run into any driver-related issues, you can still fall back to the manual method. Download the latest geckodriver from its official releases page and ensure the executable is in your system's PATH.

---

❤️ Original Project & Credit

TheToob is built upon the foundational work of linouk23. A huge thank you for creating the original tool and sharing it with the community.

• Original Author: linouk23
• Original Repository: youtube_uploader_selenium

🤝 Contributing

This project is maintained on a best-effort basis. While I may not be adding many new features myself, I welcome contributions from the community to help TheToob grow. Feel free to open a pull request!

---

📄 License

This project is licensed under the MIT License. Please see the LICENSE file for full details.