tubewatch/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

MeTube is a web-based GUI for youtube-dl/yt-dlp that allows downloading videos from YouTube and 100+ other sites. It consists of a Python backend with aiohttp and an Angular frontend, providing real-time download progress via WebSocket.

## Development Commands

### Frontend Development
```bash
cd ui
npm install                    # Install Angular dependencies
npm run build                  # Build production frontend
npm run start                  # Start development server
npm run lint                   # Run Angular linting
npm run test                   # Run Angular tests
```

### Backend Development
```bash
# Install Python dependencies using uv (preferred)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync                        # Install dependencies from pyproject.toml
uv run python3 app/main.py     # Run the backend server

# Alternative using pip
pip install -r requirements.txt
python3 app/main.py
```

### Docker Development
```bash
docker build -t metube .       # Build Docker image
docker-compose up -d           # Run with docker-compose
docker-compose up -d --build --force-recreate  # Rebuild and restart
```

### Code Quality
```bash
# Python linting
pylint app/                    # Run pylint on Python code

# Type checking (if configured)
pyright                        # Run Python type checking
```

## Architecture Overview

### Backend Structure (`app/`)
- `main.py`: Main aiohttp server with REST API and WebSocket support
- `ytdl.py`: Download queue management, yt-dlp integration, and notifier pattern
- `dl_formats.py`: Format selection logic for video/audio downloads

### Frontend Structure (`ui/src/app/`)
- `app.component.ts/html`: Main UI component with download interface
- `downloads.service.ts`: HTTP client for backend API communication
- `metube-socket.ts`: WebSocket client for real-time updates
- `downloads.pipe.ts`: Angular pipes for formatting download info

### Key Technologies
- **Backend**: Python 3.13+, aiohttp, python-socketio, yt-dlp, shelve storage
- **Frontend**: Angular 19+, TypeScript, Bootstrap 5, FontAwesome
- **Communication**: REST API + WebSocket for real-time updates
- **Storage**: Shelve-based persistent queues in STATE_DIR

## Environment Configuration

Key environment variables (see README.md for complete list):
- `DOWNLOAD_DIR`: Download location (default: `/downloads`)
- `DOWNLOAD_MODE`: `sequential`|`concurrent`|`limited` (default: `limited`)
- `MAX_CONCURRENT_DOWNLOADS`: For limited mode (default: 3)
- `YTDL_OPTIONS`: JSON options passed to yt-dlp
- `URL_PREFIX`: For reverse proxy setups
- `HOST`/`PORT`: Server binding (default: 0.0.0.0:8081)

## API Endpoints

### REST API
- `POST /add`: Add new download
- `POST /delete`: Cancel/delete download
- `GET /history`: Get download history
- `GET /info`: Get server info and configuration

### WebSocket Events
- `added`: New download queued
- `updated`: Download progress update
- `completed`: Download finished
- `canceled`: Download canceled
- `cleared`: Download removed from history

## Next Implementation: Playlist Monitor Service

The PLAYLIST_MONITOR_ARCHITECTURE.md document outlines a comprehensive plan for adding automated playlist monitoring capabilities. This should be implemented as a separate microservice.

### Architecture Summary
- **Service Type**: FastAPI-based microservice (Python 3.13+)
- **Database**: SQLite with SQLAlchemy ORM
- **Scheduler**: APScheduler for periodic tasks
- **Integration**: MeTube REST API + WebSocket client
- **Deployment**: Docker container alongside MeTube

### Key Components
1. **Playlist Manager**: Subscription management, yt-dlp integration
2. **Video Tracker**: Status tracking, file movement handling
3. **Scheduler Engine**: Periodic playlist checking, download triggering
4. **State Manager**: SQLite persistence, data migrations
5. **MeTube Client**: HTTP/WebSocket communication

### Implementation Phases (6 weeks)
- **Phase 1**: Core infrastructure, FastAPI setup, database models
- **Phase 2**: Playlist management, yt-dlp integration, start point logic
- **Phase 3**: Scheduler, periodic checks, MeTube integration
- **Phase 4**: File tracking, re-downloads, error handling
- **Phase 5**: UI integration (extend MeTube Angular or separate frontend)
- **Phase 6**: Testing, Docker containerization, documentation

### API Design
- `/api/playlists`: CRUD operations for playlist subscriptions
- `/api/playlists/{id}/videos`: Video status management
- `/api/videos/{id}/download`: Manual download triggering
- `/api/status`: System health and statistics

### Database Schema
- `playlists`: Subscription configuration
- `videos`: Individual video tracking with status, errors, file location
- `activity_log`: Audit trail for operations

### Configuration
```yaml
metube:
  url: http://localhost:8081
scheduler:
  default_check_interval: 60  # minutes
  max_concurrent_downloads: 3
database:
  url: sqlite:///data/playlists.db
```

## Key Implementation Notes

1. **Download Queue Management**: Uses async patterns with notifier callbacks for real-time updates
2. **Format Selection**: Complex logic in `dl_formats.py` handles quality/format preferences
3. **Error Handling**: Robust error tracking and retry mechanisms built into ytdl.py
4. **File Organization**: Supports custom directories, templates, and file naming patterns
5. **WebSocket Integration**: Real-time communication between backend and frontend
6. **Docker Considerations**: Multi-stage builds, volume mounts for downloads, environment configuration

## Common Development Tasks

### Adding New Download Features
1. Update `ytdl.py` for backend logic
2. Modify `app/main.py` for new API endpoints
3. Update frontend components in `ui/src/app/`
4. Test with various URLs and formats

### Modifying Frontend
1. Angular components in `ui/src/app/`
2. Use existing Bootstrap 5 styling
3. Maintain WebSocket connection patterns
4. Test build process with `npm run build`

### Database/Storage Changes
1. Shelve storage in STATE_DIR (default: `/downloads/.metube`)
2. Persistent queue files: `completed`, `pending`, `queue`
3. Cookie storage in `cookies/` subdirectory

### Testing Downloads
1. Use Docker for consistent environment
2. Test with various sites from yt-dlp supported sites
3. Check different quality/format combinations
4. Verify WebSocket updates in frontend