youtube-app/CLAUDE.md

YouTube App

Selbst-gehostete Anwendung: YouTube-Videos per Browser Extension erfassen, auf einem Server speichern und per Kotlin-App auf Android/Android TV streamen und herunterladen.

Dokumentation

• systems.md — Technologie-Stack pro Komponente
• commication.md — Kommunikationsflüsse zwischen den Systemen
• features.md — Konkrete Features und Benutzerinteraktionen
• architecture.md — Detaillierter Systemaufbau (Endpoints, Services, Models, Screens)
• szenarios.md — Benutzer-Szenarien

Architektur

Drei Komponenten:

Browser Extension (browser_extension/)

• Manifest V2, Firefox-kompatibel (browser.* API)
• content.js — extrahiert Videodaten direkt aus dem YouTube-DOM:
  • yt-lockup-view-model (Homepage, Abos, Kanalseiten)
  • ytd-video-renderer (Suchergebnisse)
  • Debounced MutationObserver (250ms) fuer dynamisch geladene Cards
  • yt-navigate-finish Event-Listener fuer SPA-Navigation
  • Deduplizierung ueber sentUrls Set
• background.js — empfaengt Nachrichten vom Content Script, sendet POST an Server
• Laden via about:debugging#/runtime/this-firefox → "Temporaeres Add-on laden" → manifest.json

Server (backend/)

• Python, FastAPI, SQLAlchemy, SQLite (videos/youtubeapp.db)
• yt-dlp + ffmpeg fuer Video-Download
• Dockerisiert: docker compose up --build -d im backend/ Verzeichnis
• Laeuft auf http://localhost:8000
• Download-Service speichert Videos unter /videos/{id}.mp4
• Beim Streamen wird automatisch heruntergeladen falls noetig

App (app/)

• Kotlin, Jetpack Compose, Android/Android TV
• Gradle-Projekt, Modul frontend
• Aktueller Stand: Skeleton (nur MainActivity mit Platzhalter-Text)
• Geplante Screens: AllVideos, Downloaded, VideoDetail, VideoPlayer
• Emulator: Android Studio → Device Manager → Pixel 6a, API 35

API Endpoints

• POST /videos — Videodaten von Extension empfangen
• GET /videos — alle Videos abrufen
• GET /videos/downloaded — heruntergeladene Videos abrufen
• POST /videos/{id}/download — Download auf Server triggern
• GET /videos/{id}/stream — Video streamen
• GET /videos/{id}/file — Video-Datei zum Download auf Client ausliefern

Projektstruktur

backend/
  main.py              — FastAPI App, CORS, Startup
  database.py          — SQLAlchemy Engine, Session, Base
  models.py            — Video Model (id, title, youtuber, thumbnail_url, youtube_url, file_path, created_at)
  schemas.py           — Pydantic Schemas (VideoCreate, VideoResponse)
  routes/videos.py     — Alle API-Routen
  services/
    video_service.py   — CRUD-Operationen
    download_service.py — yt-dlp Download-Logik
  Dockerfile           — Python 3.12 + ffmpeg
  docker-compose.yml   — Service-Definition, Port 8000, Volume /videos

browser_extension/
  manifest.json        — Manifest V2, Permissions fuer youtube.com + localhost
  content.js           — DOM-basierte Video-Extraktion + MutationObserver
  background.js        — POST an Server

app/
  frontend/src/main/java/com/youtubeapp/
    MainActivity.kt    — Einstiegspunkt (noch Skeleton)

Entscheidungen

• Kein Jellyfin — erfuellt nicht die Anforderung, Videos vor dem Download aufzulisten
• Kein PostgreSQL/MySQL — SQLite reicht fuer den Prototyp
• Keine Benutzerprofile im Prototyp
• Videos werden auf dem Server gespeichert, Client speichert nur bei explizitem Download
• DOM-Extraktion statt ytInitialData-Parsing — funktioniert auch bei SPA-Navigation und Scrollen
• Sprache der Dokumentation: Deutsch