# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

HANDLER-NAME
============
media — Medienverwaltung (Filme, Serien, Musik, Podcasts, Audiobooks)

BESCHREIBUNG
============
MediaHandler verwaltet Mediensammlungen mit Unterstützung für verschiedene
Medientypen und Quellen. Nutzt SQLite-Backend (bach.db) mit Favoriten,
Blacklist, Wiedergabe-Historie und erweiterten Metadaten pro Medium.

MEDIENTYPEN
-----------
  [F] movie, [S] series, [M] music, [C] clip, [P] podcast, [A] audiobook, [D] document

QUELLEN
-------
  netflix, youtube, spotify, disney, prime, appletv, twitch, local

OPERATIONEN
===========

add
  Neues Medium hinzufügen
  Usage: bach media add "Titel" [--type TYPE] [--source SOURCE] [--url URL]
           [--artist "..."] [--album "..."] [--channel "..."] [--season N]
           [--episode N] [--rating 1-5] [--tags "tag1,tag2"] [--desc "..."]
           [--path "/pfad/zur/datei"]

list
  Medien auflisten und filtern
  Usage: bach media list [--type TYPE] [--source SOURCE] [--fav] [--limit N]
  Flags:
    --type TYPE      Nur einen Medientyp anzeigen
    --source SOURCE  Nur eine Quelle filtern
    --fav            Nur Favoriten anzeigen
    --limit N        Max. N Einträge (Default: 20)
  Output: Icon, Favorit(*), ID, Titel, Quelle, Bewertung

search
  Volltextsuche nach Titel, Künstler, Album, Channel, Tags, Beschreibung
  Usage: bach media search "Suchbegriff"
  Output: Bis zu 30 Treffer mit Icon, Favorit, ID, Titel, Quelle

show
  Detailansicht eines Mediums mit vollständigen Metadaten
  Usage: bach media show <id>
  Output: Alle Felder (Title, Typ, Quelle, Künstler, Album, Staffel/Episode,
          Rating, Tags, Beschreibung, Favorit, Blacklist-Status, Datum,
          letzte 5 Wiedergaben)

edit
  Medium bearbeiten (beliebige Felder)
  Usage: bach media edit <id> --title "Neu" [--type TYPE] [--source SOURCE]
           [--url URL] [--desc "..."] [--artist "..."] [--album "..."]
           [--channel "..."] [--season N] [--episode N] [--rating 1-5]
           [--tags "tag1,tag2"] [--notes "..."] [--path "/pfad"]

fav
  Favorit setzen/entfernen
  Usage: bach media fav <id> [--remove]
  Flag:
    --remove         Entfernt Favorit-Status

blacklist
  Medium sperren/entsperren (wird bei list/search ausgeblendet)
  Usage: bach media blacklist <id> [--remove]
  Flag:
    --remove         Sperre aufheben

open
  Medium öffnen: URL im Browser oder Datei starten. Aktualisiert Wiedergabe-
  Historie und last_opened_at Zeitstempel. Gesperrte Medien könnten nicht
  geöffnet werden.
  Usage: bach media open <id>

history
  Wiedergabe-Historie aller Medien (neueste zuerst)
  Usage: bach media history [--limit N]
  Zeigt: Timestamp, Icon, ID, Titel, Quelle, Open-Methode

stats
  Statistik-Übersicht: Gesamtanzahl, Favoriten, Gesperrte, Wiedergaben,
  Verteilung nach Typ und Quelle
  Usage: bach media stats

help
  Diese Hilfe anzeigen
  Usage: bach media help

BEISPIELE
=========

# Medium hinzufügen (Film auf Netflix)
bach media add "Inception" --type movie --source netflix --url "https://..." \
  --rating 5 --desc "Science-Fiction Meisterwerk"

# Medium hinzufügen (Musikalbum)
bach media add "Abbey Road" --type music --source spotify --artist "The Beatles" \
  --album "Abbey Road" --year 1969

# Medium hinzufügen (lokale Datei)
bach media add "Dokumentation" --type document --source local \
  --path "C:\\Videos\\doku.mp4"

# Alle Filme mit Favoriten anzeigen
bach media list --type movie --fav

# Nach Serie suchen
bach media search "Breaking Bad"

# Serie mit Staffel/Episode erfassen
bach media add "Breaking Bad S01E01" --type series --source netflix \
  --season 1 --episode 1 --rating 5

# Medium als Favorit markieren
bach media fav 42

# Favorit-Status entfernen
bach media fav 42 --remove

# Medium als Blacklist markieren
bach media blacklist 99

# Medium öffnen
bach media open 42

# Statistik anzeigen
bach media stats

DATEIEN
=======

Basis:         hub/media.py
Datenbank:     data/bach.db
Tabellen:      media_items, media_history
Config:        Keine (alles über CLI-Flags)

SIEHE AUCH
==========

  bach_api.media.*     Programmatische API
  hub/base.py          BaseHandler-Basisklasse
  docs/API.md          BACH-API Dokumentation
