124 lines
3.5 KiB
Markdown
124 lines
3.5 KiB
Markdown
# 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. |