tubewatch/playlist-monitor/GETTING_STARTED.md

Playlist Monitor Service - Complete Getting Started Guide

🎯 What You Have Now

✅ Fully Implemented Backend

• Complete REST API with 20+ endpoints
• Database models with SQLite/PostgreSQL support
• MeTube integration via HTTP API + WebSocket
• Automated playlist monitoring with configurable intervals
• Video tracking with status management
• Docker support with multi-stage builds
• Comprehensive testing with pytest

❌ Missing: User Interface

The service currently only provides a REST API with Swagger documentation at http://localhost:8082/docs. There is no web UI for visual management.

🚀 Quick Start (Choose Your Path)

Path 1: API-Only (Immediate Use)

# Start the service
cd /root/workspace/tubewatch/playlist-monitor
uv run python -m app.main

# Access API documentation
open http://localhost:8082/docs

# Test with curl
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"
  }'

Path 2: Add Simple UI (30 minutes)

# Create basic HTML dashboard
cd /root/workspace/tubewatch/playlist-monitor
mkdir ui
cp templates/simple-dashboard.html ui/index.html

# Modify backend to serve UI
echo "app.mount('/ui', StaticFiles(directory='ui', html=True), name='ui')" >> app/main.py

# Restart and access UI
uv run python -m app.main
open http://localhost:8082/ui

Path 3: Full React App (2-4 hours)

# Create React application
cd /root/workspace/tubewatch
npx create-react-app playlist-monitor-ui --template typescript
cd playlist-monitor-ui

# Install UI libraries
npm install @mui/material @emotion/react @emotion/styled axios react-query

# Follow UI_INTEGRATION.md for complete setup

📚 Documentation You Have

Essential Guides

• QUICK_START_GUIDE.md - Get started in 5 minutes
• BUILD_GUIDE.md - Comprehensive build instructions
• TESTING_GUIDE.md - Complete testing procedures
• UI_INTEGRATION.md - UI implementation options

Reference Documents

• IMPLEMENTATION_STATUS.md - What was built
• PLAYLIST_MONITOR_ARCHITECTURE.md - Original architecture

🎯 What You Can Do Right Now

1. Start Using the API (No UI Needed)

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

# Add a playlist
curl -X POST http://localhost:8082/api/playlists \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/playlist?list=TEST123"}'

# Monitor downloads
curl http://localhost:8082/api/playlists/{id}/videos

2. Test the Service

# Run all tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/unit/test_models.py -v

# Check coverage
uv run pytest --cov=app --cov-report=html

3. Deploy with Docker

# From main tubewatch directory
docker-compose -f docker-compose-with-monitor.yml up -d

# Check status
docker-compose -f docker-compose-with-monitor.yml ps

🎨 UI Implementation Priority

Since you mentioned the UI is missing, here are your options ranked by effort:

🟢 15 Minutes: Basic HTML Dashboard

• Simple Bootstrap-based interface
• List playlists, show status
• Add/delete operations
• Good for: Quick setup, basic needs

🟡 2-4 Hours: React App

• Modern Material-UI interface
• Real-time updates, charts
• Full CRUD operations
• Good for: Production use, modern UX

🔴 8+ Hours: Extend MeTube Angular

• Integrate with existing MeTube UI
• Consistent styling and navigation
• Most complex but seamless
• Good for: Existing MeTube deployments

🚀 Recommended Next Steps

Immediate (Next 30 minutes)

1. Start the service: uv run python -m app.main
2. Test the API: Visit http://localhost:8082/docs
3. Add a playlist: Use the interactive API docs
4. Monitor progress: Check logs and status endpoints

Short Term (Next few hours)

1. Choose UI option based on your needs
2. Implement basic interface following UI_INTEGRATION.md
3. Test end-to-end workflow with real playlists
4. Set up monitoring and health checks

Long Term (Next few days)

1. Deploy to production with Docker
2. Set up automated monitoring and alerts
3. Add authentication if needed
4. Optimize performance based on usage

🔧 Common First-Time Setup Issues

"MeTube connection failed"

• Ensure MeTube is running on port 8081
• Check MeTube logs: docker logs metube
• Verify network connectivity

"Port 8082 already in use"

• Find process: lsof -i :8082
• Kill process or change port in .env

"Database locked"

• Remove lock file: rm data/*.db-journal
• Check for zombie processes

"Python version too old"

• Install Python 3.13+ or use Docker
• Use pyenv for version management

📞 Getting Help

Documentation

• API Reference: http://localhost:8082/docs (when running)
• Architecture: See PLAYLIST_MONITOR_ARCHITECTURE.md
• Build Issues: See BUILD_GUIDE.md troubleshooting section

Debugging

• Check logs: tail -f logs/playlist-monitor.log
• Health check: curl http://localhost:8082/health
• System status: curl http://localhost:8082/api/status

Community

• Check existing issues in the repository
• Create detailed bug reports with logs
• Include system information and reproduction steps

🎉 Success Metrics

You'll know everything is working when you can:

1. ✅ Start the service without errors
2. ✅ Access API docs at http://localhost:8082/docs
3. ✅ Add a playlist via API or UI
4. ✅ See videos detected from the playlist
5. ✅ Monitor download progress in real-time
6. ✅ Manage video status (skip, reset, etc.)

🎯 Final Recommendation

Start with the API-only approach to verify everything works, then add a UI based on your comfort level:

• API-only: Great for automation, scripts, or integration with other tools
• Simple HTML: Perfect for personal use or quick setup
• React App: Best for production deployments and user-friendly experience

The backend is production-ready and thoroughly tested. Focus your effort on the UI implementation based on your specific needs! 🚀

---

Next Step: Choose your UI path and follow the relevant guide in UI_INTEGRATION.md!