ytgrid

🎥 YTGrid - Hybrid CLI + API for Scalable YT Video Automation

🚀 YTGrid is a powerful, scalable, and flexible YT automation tool that enables looped playback, remote control, and real-time tracking using a hybrid CLI + API architecture.
It integrates FastAPI for REST API control, Selenium for browser automation, and Python multiprocessing for concurrent tasks.

---

📌 Table of Contents

• ✨ Features
• 📂 Project Structure
• ⚡ Installation
• 🖥️ CLI Usage
• 🖥️ API Usage
• 🧪 Running Tests
• 🐳 Docker Deployment
• 📜 License

---

✨ Features

✅ New & Improved Features

🔹 Hybrid CLI + API – Use both a command-line interface and a FastAPI-powered REST API.
🔹 YT Automation – Automatically search, play, and loop videos using Selenium.
🔹 Session Tracking – Monitor active sessions in real time using WebSockets.
🔹 Parallel Execution – Run multiple YT automation sessions simultaneously.
🔹 Configurable Playback Speed – Adjust video playback speed dynamically.
🔹 WebSocket Real-Time Updates – Get live session updates.
🔹 Optimized Browser Management – Uses headless Chrome for better performance.
🔹 Session Persistence – Track running and completed sessions efficiently.
🔹 Comprehensive Logging – Logs all activity for debugging and monitoring.

---

📂 Project Structure

YTGrid/
 ├── ytgrid/                 → Core Python package (installable via pip)
 │   ├── cli.py              → CLI for managing sessions
 │   ├── backend/            → FastAPI API for remote control
 │   │   ├── main.py         → API entry point
 │   │   ├── routes.py       → API endpoints
 │   │   ├── task_manager.py → Manages multiprocessing tasks
 │   │   ├── session_store.py → In-memory session tracking
 │   ├── automation/         → YT playback automation
 │   │   ├── player.py       → Automates search & playback
 │   │   ├── browser.py      → Manages Selenium WebDriver
 │   ├── utils/              → Helper functions
 │   │   ├── logger.py       → Logging system
 │   │   ├── config.py       → Configuration settings
 │
 ├── examples/               → Example scripts
 │   ├── example_cli.py      → CLI example usage
 │   ├── example_api.py      → API example usage
 │
 ├── tests/                  → Unit tests
 │   ├── test_cli.py         → CLI tests
 │   ├── test_api.py         → API tests
 │   ├── test_automation.py  → Automation tests
 │
 ├── setup.py                → Python package setup script
 ├── requirements.txt        → Dependencies
 ├── README.md               → Documentation
 ├── .gitignore              → Ignore unnecessary files
 ├── docker-compose.yml      → Docker deployment
 ├── Dockerfile              → Docker build file

---

⚡ Installation

Step 1: Clone the Repository

git clone https://github.com/sandy-sp/ytgrid.git
cd ytgrid

Step 2: Create a Virtual Environment

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

Step 3: Install YTGrid Locally

pip install -e .

Step 4: Verify Installation

ytgrid --help

✅ If you see CLI options, installation was successful.

---

🖥️ CLI Usage

Start a YT Automation Session

ytgrid start --url "https://www.youtube.com/watch?v=OaOK76hiW8I" --speed 1.5 --loops 3

Check Active Sessions

ytgrid status

Stop a Session

ytgrid stop --session_id <num>

---

🖥️ API Usage

Start API Server

uvicorn ytgrid.backend.main:app --reload

Start a YT Session

curl -X POST "http://127.0.0.1:8000/sessions/start" -H "Content-Type: application/json" -d '{
  "url": "https://www.youtube.com/watch?v=OaOK76hiW8I",
  "speed": 1.5,
  "loop_count": 3
}'

Check Session Status

curl -X GET "http://127.0.0.1:8000/status"

Stop a Session

curl -X POST "http://127.0.0.1:8000/sessions/stop" -H "Content-Type: application/json" -d '{"session_id": 1}'

---

🧪 Running Tests

Run All Tests

pytest tests/

Run a Specific Test

pytest tests/test_api.py

✅ If all tests pass, YTGrid is working correctly.

---

🐳 Docker Deployment

Build and Run in Docker

docker-compose up --build

Stop Containers

docker-compose down

✅ YTGrid will now run in a containerized environment.

---

📜 License

YTGrid is released under the MIT License.

---