xorbitlab
/
tubewatch
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
tubewatch/CLAUDE.md

6.5 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MeTube is a web-based GUI for youtube-dl/yt-dlp that allows downloading videos from YouTube and 100+ other sites. It consists of a Python backend with aiohttp and an Angular frontend, providing real-time download progress via WebSocket.

Development Commands

Frontend Development

cd ui
npm install                    # Install Angular dependencies
npm run build                  # Build production frontend
npm run start                  # Start development server
npm run lint                   # Run Angular linting
npm run test                   # Run Angular tests

Backend Development

# Install Python dependencies using uv (preferred)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync                        # Install dependencies from pyproject.toml
uv run python3 app/main.py     # Run the backend server

# Alternative using pip
pip install -r requirements.txt
python3 app/main.py

Docker Development

docker build -t metube .       # Build Docker image
docker-compose up -d           # Run with docker-compose
docker-compose up -d --build --force-recreate  # Rebuild and restart

Code Quality

# Python linting
pylint app/                    # Run pylint on Python code

# Type checking (if configured)
pyright                        # Run Python type checking

Architecture Overview

Backend Structure (app/)

  • main.py: Main aiohttp server with REST API and WebSocket support
  • ytdl.py: Download queue management, yt-dlp integration, and notifier pattern
  • dl_formats.py: Format selection logic for video/audio downloads

Frontend Structure (ui/src/app/)

  • app.component.ts/html: Main UI component with download interface
  • downloads.service.ts: HTTP client for backend API communication
  • metube-socket.ts: WebSocket client for real-time updates
  • downloads.pipe.ts: Angular pipes for formatting download info

Key Technologies

  • Backend: Python 3.13+, aiohttp, python-socketio, yt-dlp, shelve storage
  • Frontend: Angular 19+, TypeScript, Bootstrap 5, FontAwesome
  • Communication: REST API + WebSocket for real-time updates
  • Storage: Shelve-based persistent queues in STATE_DIR

Environment Configuration

Key environment variables (see README.md for complete list):

  • DOWNLOAD_DIR: Download location (default: /downloads)
  • DOWNLOAD_MODE: sequential|concurrent|limited (default: limited)
  • MAX_CONCURRENT_DOWNLOADS: For limited mode (default: 3)
  • YTDL_OPTIONS: JSON options passed to yt-dlp
  • URL_PREFIX: For reverse proxy setups
  • HOST/PORT: Server binding (default: 0.0.0.0:8081)

API Endpoints

REST API

  • POST /add: Add new download
  • POST /delete: Cancel/delete download
  • GET /history: Get download history
  • GET /info: Get server info and configuration

WebSocket Events

  • added: New download queued
  • updated: Download progress update
  • completed: Download finished
  • canceled: Download canceled
  • cleared: Download removed from history

Next Implementation: Playlist Monitor Service

The PLAYLIST_MONITOR_ARCHITECTURE.md document outlines a comprehensive plan for adding automated playlist monitoring capabilities. This should be implemented as a separate microservice.

Architecture Summary

  • Service Type: FastAPI-based microservice (Python 3.13+)
  • Database: SQLite with SQLAlchemy ORM
  • Scheduler: APScheduler for periodic tasks
  • Integration: MeTube REST API + WebSocket client
  • Deployment: Docker container alongside MeTube

Key Components

  1. Playlist Manager: Subscription management, yt-dlp integration
  2. Video Tracker: Status tracking, file movement handling
  3. Scheduler Engine: Periodic playlist checking, download triggering
  4. State Manager: SQLite persistence, data migrations
  5. MeTube Client: HTTP/WebSocket communication

Implementation Phases (6 weeks)

  • Phase 1: Core infrastructure, FastAPI setup, database models
  • Phase 2: Playlist management, yt-dlp integration, start point logic
  • Phase 3: Scheduler, periodic checks, MeTube integration
  • Phase 4: File tracking, re-downloads, error handling
  • Phase 5: UI integration (extend MeTube Angular or separate frontend)
  • Phase 6: Testing, Docker containerization, documentation

API Design

  • /api/playlists: CRUD operations for playlist subscriptions
  • /api/playlists/{id}/videos: Video status management
  • /api/videos/{id}/download: Manual download triggering
  • /api/status: System health and statistics

Database Schema

  • playlists: Subscription configuration
  • videos: Individual video tracking with status, errors, file location
  • activity_log: Audit trail for operations

Configuration

metube:
  url: http://localhost:8081
scheduler:
  default_check_interval: 60  # minutes
  max_concurrent_downloads: 3
database:
  url: sqlite:///data/playlists.db

Key Implementation Notes

  1. Download Queue Management: Uses async patterns with notifier callbacks for real-time updates
  2. Format Selection: Complex logic in dl_formats.py handles quality/format preferences
  3. Error Handling: Robust error tracking and retry mechanisms built into ytdl.py
  4. File Organization: Supports custom directories, templates, and file naming patterns
  5. WebSocket Integration: Real-time communication between backend and frontend
  6. Docker Considerations: Multi-stage builds, volume mounts for downloads, environment configuration

Common Development Tasks

Adding New Download Features

  1. Update ytdl.py for backend logic
  2. Modify app/main.py for new API endpoints
  3. Update frontend components in ui/src/app/
  4. Test with various URLs and formats

Modifying Frontend

  1. Angular components in ui/src/app/
  2. Use existing Bootstrap 5 styling
  3. Maintain WebSocket connection patterns
  4. Test build process with npm run build

Database/Storage Changes

  1. Shelve storage in STATE_DIR (default: /downloads/.metube)
  2. Persistent queue files: completed, pending, queue
  3. Cookie storage in cookies/ subdirectory

Testing Downloads

  1. Use Docker for consistent environment
  2. Test with various sites from yt-dlp supported sites
  3. Check different quality/format combinations
  4. Verify WebSocket updates in frontend