tubewatch/playlist-monitor/QUICK_START_GUIDE.md

Playlist Monitor Service - Quick Start Guide

🚀 Quick Start (5 minutes)

Prerequisites

• Python 3.13+ installed
• MeTube running (or available to start)
• Basic command line knowledge

Option 1: Docker (Recommended)

# From the main tubewatch directory
cd /root/workspace/tubewatch

# Start both MeTube and Playlist Monitor
docker-compose -f docker-compose-with-monitor.yml up -d

# Check if services are running
docker-compose -f docker-compose-with-monitor.yml ps

# View logs
docker-compose -f docker-compose-with-monitor.yml logs -f playlist-monitor

Option 2: Manual Installation

# Navigate to playlist monitor directory
cd /root/workspace/tubewatch/playlist-monitor

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.cargo/env

# Install dependencies
uv sync

# Copy environment file
cp .env.example .env

# Start the service
uv run python -m app.main

Access the Services

• Playlist Monitor API: http://localhost:8082/docs
• MeTube: http://localhost:8081
• API Documentation: http://localhost:8082/docs

🎯 Your First Playlist

Using the API (Interactive)

1. Open http://localhost:8082/docs
2. Click on POST /api/playlists
3. Click "Try it out"
4. Enter this data:

{
  "url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf",
  "check_interval": 60,
  "quality": "best",
  "format": "mp4",
  "folder": "kurzgesagt",
  "enabled": true
}

5. Click "Execute"

Using curl

# Add a playlist
curl -X POST http://localhost:8082/api/playlists \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf",
    "check_interval": 60,
    "quality": "best",
    "format": "mp4",
    "folder": "kurzgesagt"
  }'

# List playlists
curl http://localhost:8082/api/playlists

# Check system status
curl http://localhost:8082/api/status

📊 Monitor Your Downloads

Check Status

# System status
curl http://localhost:8082/api/status

# List playlists with stats
curl http://localhost:8082/api/playlists

# Get specific playlist details
curl http://localhost:8082/api/playlists/{playlist_id}

View Videos

# List videos for a playlist
curl http://localhost:8082/api/playlists/{playlist_id}/videos

# Get specific video details
curl http://localhost:8082/api/videos/{video_id}

🛠️ Troubleshooting

Service Won't Start

# Check if port 8082 is available
netstat -tulpn | grep 8082

# Check logs
tail -f logs/playlist-monitor.log

# Test configuration
uv run python -c "from app.core.config import settings; print(settings.METUBE_URL)"

MeTube Connection Issues

# Test MeTube connectivity
curl http://localhost:8081/info

# Check MeTube logs
docker logs metube

# Verify MeTube URL in .env file
grep METUBE_URL .env

Database Issues

# Check database file
ls -la data/playlists.db

# Reset database (WARNING: deletes all data)
rm data/playlists.db
# Then restart the service

🎮 Common Operations

Add Multiple Playlists

# YouTube channel uploads playlist
curl -X POST http://localhost:8082/api/playlists \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/playlist?list=UUX6OQ3DkcsbYNE6H8uQQuVA",
    "check_interval": 30,
    "folder": "tech-channels"
  }'

# Specific playlist
curl -X POST http://localhost:8082/api/playlists \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/playlist?list=PLQVvvaa0QuDfpEcGUM6ogsbrlWtqpS5-1",
    "check_interval": 120,
    "folder": "python-tutorials"
  }'

Manual Playlist Check

# Force check a playlist
curl -X POST http://localhost:8082/api/playlists/{playlist_id}/check?force=true

Manage Videos

# Mark video as moved
curl -X POST http://localhost:8082/api/videos/{video_id}/file-moved \
  -H "Content-Type: application/json" \
  -d '{"location_note": "Moved to /mnt/nas/videos/"}'

# Reset failed video
curl -X POST http://localhost:8082/api/videos/{video_id}/reset

📈 Next Steps

1. Set up a web UI (see BUILD_GUIDE.md for UI options)
2. Configure automatic startup with systemd or Docker
3. Set up monitoring with health checks
4. Customize settings for your needs
5. Add authentication if needed (see ADVANCED_CONFIG.md)

🆘 Need Help?

• Check the full documentation: README.md
• View API docs: http://localhost:8082/docs
• Check logs: tail -f logs/playlist-monitor.log
• Run health check: curl http://localhost:8082/health

🚀 Going Further

See these guides for advanced usage:

• BUILD_GUIDE.md - Detailed build instructions
• TESTING_GUIDE.md - Comprehensive testing
• UI_INTEGRATION.md - UI implementation options
• ADVANCED_CONFIG.md - Advanced configuration