# Playlist Monitor Service

An automated playlist monitoring service for MeTube that tracks YouTube playlists, detects new videos, and automatically downloads them using MeTube as the download engine.

## Features

- **Playlist Monitoring**: Automatically monitor YouTube playlists for new videos
- **Smart Download Management**: Track download status and prevent re-downloads
- **Start Point Control**: Set starting points to skip older videos
- **File Movement Tracking**: Handle files moved by users without re-downloading
- **Periodic Checking**: Configurable check intervals for each playlist
- **MeTube Integration**: Seamless integration with MeTube via REST API and WebSocket
- **Real-time Updates**: WebSocket events for download progress and completion
- **Comprehensive API**: RESTful API for managing playlists and videos
- **Docker Support**: Easy deployment with Docker Compose

## Quick Start

### Prerequisites

- Python 3.13+
- MeTube instance running (default: http://localhost:8081)
- SQLite or PostgreSQL database

### Installation

1. **Clone and setup**:
   ```bash
   cd playlist-monitor
   cp .env.example .env
   # Edit .env with your configuration
   ```

2. **Install dependencies** (using uv recommended):
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync
   ```

3. **Run the service**:
   ```bash
   uv run python -m app.main
   ```

### Docker Deployment

```bash
docker build -t playlist-monitor .
docker run -d \
  --name playlist-monitor \
  -p 8082:8082 \
  -e METUBE_URL=http://metube:8081 \
  -v ./data:/app/data \
  -v ./logs:/app/logs \
  playlist-monitor
```

## API Documentation

Once running, visit http://localhost:8082/docs for interactive API documentation.

### Key Endpoints

- `POST /api/playlists` - Add a new playlist
- `GET /api/playlists` - List all playlists
- `GET /api/playlists/{id}` - Get playlist details
- `POST /api/playlists/{id}/check` - Manually check playlist for new videos
- `POST /api/videos/{id}/download` - Trigger download for a video
- `GET /api/status` - Get system status

## Configuration

See `.env.example` for all configuration options. Key settings:

- `METUBE_URL`: URL of your MeTube instance
- `DATABASE_URL`: Database connection string
- `DEFAULT_CHECK_INTERVAL`: Default playlist check interval (minutes)
- `MAX_CONCURRENT_DOWNLOADS`: Maximum concurrent downloads
- `LOG_LEVEL`: Logging level (DEBUG, INFO, WARNING, ERROR)

## Architecture

The service consists of:

- **FastAPI**: Modern async web framework
- **SQLAlchemy**: Database ORM with SQLite/PostgreSQL support
- **APScheduler**: Periodic task scheduling
- **yt-dlp**: YouTube playlist and video information extraction
- **MeTube Client**: HTTP/WebSocket client for MeTube integration

## Development

### Project Structure

```
playlist-monitor/
├── app/
│   ├── api/          # API endpoints
│   ├── core/         # Core functionality (config, database, scheduler)
│   ├── models/       # Database models
│   ├── services/     # Business logic services
│   └── main.py       # FastAPI application
├── data/             # Database files
├── logs/             # Log files
└── tests/            # Test files
```

### Running Tests

```bash
uv run pytest
```

### Code Quality

```bash
uv run black app/
uv run isort app/
uv run mypy app/
```

## License

MIT License - see LICENSE file for details.