tubewatch/playlist-monitor

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:

   cd playlist-monitor
   cp .env.example .env
   # Edit .env with your configuration
   

2. Install dependencies (using uv recommended):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync
   

3. Run the service:

   uv run python -m app.main
   

Docker Deployment

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

uv run pytest

Code Quality

uv run black app/
uv run isort app/
uv run mypy app/

License

MIT License - see LICENSE file for details.