youtube-cli/web

YouTube Web Interface

A modern React-based web interface for the YouTube CLI application. Provides a browser-based UI for searching, downloading, and managing YouTube videos with the same functionality as the TUI, but accessible from any device on your network.

Features

• Search YouTube - Search for videos with autocomplete and history
• Browse Results - View search results with thumbnails, duration, and view counts
• Download Videos - Download videos with category selection
• Download Playlists - Download entire playlists
• Queue Management - Manage download queue with progress tracking
• Download Archive - View and manage downloaded videos
• Real-time Updates - Polling-based progress updates
• Responsive Design - Works on desktop and mobile

Architecture

youtube-cli/
├── youtube_cli/           # Core CLI application (existing)
├── youtube_tui/           # Textual TUI (existing)
├── web/                   # React web interface
│   ├── server/            # Flask API server
│   │   ├── app.py         # Main Flask application
│   │   └── requirements-web.txt
│   └── web-app/           # React frontend
│       ├── src/
│       │   ├── api/       # API client functions
│       │   ├── pages/     # Page components
│       │   └── components/# UI components
│       └── package.json

Setup

Prerequisites

• Python 3.8+ with pip
• yt-dlp installed: pip install yt-dlp
• Node.js 18+ with npm

Installation

1. Install Python dependencies:

cd web
pip install -r requirements-web.txt

2. Install Node.js dependencies:

cd web-app
npm install

Configuration

The application uses the same configuration as the CLI/TUI:

• Config location: ~/.config/youtube_cli/config.json
• Archive location: ~/.config/youtube_cli/downloaded_videos.json

Make sure your config has the necessary settings:

{
  "download_dir": "/path/to/downloads",
  "default_locations": ["/path/to/downloads/Music", "/path/to/downloads/Videos"],
  "max_videos_per_page": 15,
  "yt_dlp_args": {
    "format": "bestvideo[height<=1080]+bestaudio/best"
  }
}

Usage

Development Mode

Run both backend and frontend:

# Terminal 1: Start Flask backend
cd web/server
python app.py

# Terminal 2: Start React frontend
cd web/web-app
npm run dev

The frontend will be available at http://localhost:3000 and will proxy API requests to the Flask backend on port 4096.

Production Mode

# Build the React app
cd web/web-app
npm run build

# Serve static files with Flask
cd web/server
python app.py

The frontend will be served from the dist/ folder at http://localhost:4096.

API Endpoints

Health & Configuration

• GET /api/health - Health check
• GET /api/config - Get configuration
• GET /api/categories - Get available download categories

Search

• GET /api/search?q=query&page=1 - Search for videos

Download

• POST /api/download - Download a video
• POST /api/download/playlist - Download a playlist

Queue

• GET /api/queue - Get all queue items
• DELETE /api/queue/:id - Remove item from queue
• POST /api/queue/:id/retry - Retry a failed download
• POST /api/queue/:id/cancel - Cancel a download
• GET /api/queue/:id/status - Get download progress
• POST /api/queue/clear/completed - Clear completed items
• POST /api/queue/clear/failed - Clear failed items

Archive

• GET /api/archive - Get download archive
• DELETE /api/archive/:videoId - Remove from archive

Project Structure

Backend (web/server/)

• app.py - Flask application with all API endpoints
• requirements-web.txt - Python dependencies

Frontend (web/web-app/)

• src/api/ - API client functions
  • client.ts - Axios instance with interceptors
  • search.ts - Search API calls
  • download.ts - Download API calls
  • queue.ts - Queue management API calls
  • archive.ts - Archive API calls
• src/pages/ - Page components
  • SearchPage.tsx - Search interface
  • SearchResults.tsx - Search results grid
  • Queue.tsx - Download queue management
  • Archive.tsx - Download history
• src/components/ - UI components
  • Navbar.tsx - Navigation bar
• tailwind.config.js - Tailwind CSS configuration

Design Decisions

1. Flask Backend: Used Flask for simplicity and integration with existing YouTubeCLI
2. Polling for Updates: Implemented polling instead of WebSockets for simpler deployment
3. In-memory Queue: Queue stored in memory (can be extended to persist to file)
4. CORS Enabled: For development; should be restricted in production
5. API Proxy: Vite configured to proxy /api requests to Flask backend

Future Enhancements

• Persist queue to file
• WebSocket support for real-time updates
• Authentication system
• Settings page for configuration
• Download history with filtering
• Batch download functionality
• Email notifications for downloads
• Scheduled downloads

Troubleshooting

Backend won't start

• Ensure yt-dlp is installed: yt-dlp --version
• Check Python dependencies: pip install -r requirements-web.txt

Frontend won't compile

• Clear node_modules: rm -rf node_modules && npm install
• Check Node version: node --version (should be 18+)

API requests fail

• Ensure backend is running on port 4096
• Check CORS settings in app.py
• Verify API base URL in src/api/client.ts

License

MIT License - same as the main YouTube CLI project