youtube-cli/web/README.md

# 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**:
```bash
cd web
pip install -r requirements-web.txt
```

2. **Install Node.js dependencies**:
```bash
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:
```json
{
  "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:

```bash
# 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

```bash
# 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