Music_Metadata_Enricher/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung — Music Metadata Enricher

## Überblick

Das Programm liest ein Album-Verzeichnis ein, analysiert alle verfügbaren Quellen
(Dateinamen, Tags, Tracklisten, Bilder, YouTube-Metadaten) und schreibt saubere
Metadaten-Tags in die Audiodateien. Optional benennt es die Dateien nach einem
einheitlichen Schema um und bettet Cover-Art ein.

---

## Voraussetzungen

```bash
pip install mutagen musicbrainzngs Pillow requests tqdm beautifulsoup4
```

Für YouTube-Metadaten:
```bash
sudo apt install yt-dlp
```

Für LLM-Reasoning: **Ollama** muss laufen (`http://localhost:11434`),
Modell `qwen3:8b` empfohlen:
```bash
ollama pull qwen3:8b
ollama pull qwen3-vl:latest   # für OCR (optional)
```

---

## Album-Verzeichnis — Was wird erkannt?

Das Programm versteht eine Vielzahl von Verzeichnis-Layouts:

| Datei / Muster | Wird genutzt für |
|----------------|-----------------|
| Verzeichnisname `Artist_-_Album` | Künstler, Albumtitel |
| Dateiname `01_-_Artist_-_Titel.flac` | Tracknummer, Artist, Titel |
| Dateiname mit YouTube-ID am Ende | Metadaten via yt-dlp |
| `tracklist.txt` / `tracklist.htm` | Vollständige Trackliste |
| `back.jpg` / `booklet.jpg` | OCR-Trackliste via Ollama Vision |
| `Front.jpg` / `folder.jpg` / `Front.webp` | Cover-Art |
| `*.m3u` / `*.m3u8` | Wiedergabereihenfolge |
| ID3/FLAC/M4A-Tags | Bestehende Metadaten |

### YouTube-IDs im Dateinamen

Dateien, die mit `yt-dlp` oder `musikvideo2audio` heruntergeladen wurden,
enthalten oft eine 11-stellige YouTube-ID am Ende des Dateinamens:

```
Hohe_Tannen_BxmOrMN-Kss.flac     → ID: BxmOrMN-Kss
Ade_zur_guten_Nacht_SOx8dgI2gGU.flac  → ID: SOx8dgI2gGU
```

Das Programm entfernt die ID aus dem Titel und holt automatisch Titel,
Uploader und Kapitel (= Trackliste) via `yt-dlp`.

---

## Grundprinzip: erst Dry-Run, dann scharf

**Immer zuerst mit `--dry-run` testen**, bevor Dateien verändert werden:

```bash
# Schritt 1: Vorschau
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --dry-run --no-fingerprint \
    --album ~/nvme2n1p7_home/Musik/MEIN_ALBUM

# Schritt 2: Scharf (wenn Vorschau OK)
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --auto --confidence 0.1 --rename --embed-cover --no-fingerprint \
    --backup /tmp/mein_backup \
    --album ~/nvme2n1p7_home/Musik/MEIN_ALBUM
```

> **Tipp:** Der `--backup`-Ordner enthält Kopien aller Originaldateien vor der
> Änderung. Bei Problemen können Dateien von dort wiederhergestellt werden.

---

## Alle Optionen

| Option | Beschreibung |
|--------|-------------|
| `--album PFAD` | Einzelnes Album-Verzeichnis verarbeiten |
| `PFAD [PFAD ...]` | Mehrere Root-Verzeichnisse (Unterordner = Alben) |
| `--dry-run` | Nur anzeigen, nichts schreiben |
| `--auto` | Ohne interaktive Rückfrage ausführen |
| `--confidence 0.X` | Minimale Konfidenz für `--auto` (default: 0.85) |
| `--rename` | Dateien nach Namens-Schema umbenennen |
| `--embed-cover` | Cover-Art in Audiodatei einbetten |
| `--backup PFAD` | Backup-Verzeichnis vor Änderungen |
| `--report PFAD` | CSV-Protokoll aller Änderungen |
| `--no-fingerprint` | AcoustID-Fingerprinting überspringen (schneller) |
| `--no-api` | Keine externen Zugriffe (MusicBrainz, OCR, YouTube) |
| `--no-cover` | Kein Cover-Art-Download |
| `--no-tqdm` | Fortschrittsbalken deaktivieren |
| `--status` | Bibliotheksstatus anzeigen (fehlende Cover, schlechte Tags) — nichts schreiben |
| `--skip-complete` | Alben überspringen, die bereits Cover + gute Tags haben |
| `--except PATTERN` | Album ausschließen, dessen Verzeichnisname das Muster enthält (Glob oder Substring, mehrfach verwendbar) |

---

## Typische Anwendungsfälle

### A) Album mit YouTube-IDs in Dateinamen

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --auto --confidence 0.1 --rename --embed-cover --no-fingerprint \
    --backup /tmp/backup \
    --album ~/nvme2n1p7_home/Musik/Die_Bergvagabunden_Am_Lagefeuer.audio
```

Das Programm erkennt die YouTube-IDs, lädt Titel und Künstler, entfernt die
IDs aus den Dateinamen und benennt die Dateien sauber um.

### B) Klassik-Album (Komponist ≠ Performer)

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --auto --confidence 0.5 --rename --embed-cover \
    --backup /tmp/backup \
    --album ~/nvme2n1p7_home/Musik/Bach_Organ_-_Peter_Hurford
```

Bei Klassik-Alben (Performer ≠ Komponist) wird automatisch das Klassik-Schema
verwendet:
```
01_-_Peter_Hurford_-_Johann_Sebastian_Bach_-_Toccata_And_Fugue_In_D_Minor_BWV_565.mp3
```

### C) Album ohne Cover — Cover nachträglich hinzufügen

Wenn kein Cover gefunden wurde:
1. Cover-Bild in das Album-Verzeichnis kopieren (Name: `Front.jpg` oder `Front.webp`)
2. Programm erneut laufen lassen — es erkennt das neue Bild und bettet es ein

```bash
cp /pfad/zum/cover.jpg ~/nvme2n1p7_home/Musik/MEIN_ALBUM/Front.jpg
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --auto --confidence 0.1 --embed-cover --no-fingerprint \
    --album ~/nvme2n1p7_home/Musik/MEIN_ALBUM
```

### D) Ganze Bibliothek verarbeiten

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --auto --confidence 0.85 --embed-cover --no-fingerprint \
    --backup /tmp/bibliothek_backup \
    --report /tmp/report.csv \
    ~/nvme2n1p7_home/Musik
```

Alben mit Konfidenz unter 0.85 werden übersprungen und müssen manuell
mit `--album` und niedrigerem `--confidence`-Wert bearbeitet werden.

### E) Batch-Lauf mit Ausschlüssen und Überspringen bereits fertiger Alben

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --auto --confidence 0.5 --rename --embed-cover --no-fingerprint \
    --skip-complete \
    --except 'Eigene_Aufnahmen*' \
    --except Hoerbuch \
    --backup /tmp/backup \
    ~/nvme2n1p7_home/Musik
```

- `--skip-complete` überspringt Alben, die bereits Cover und gute Tags haben.
- `--except` schließt Alben anhand des Verzeichnisnamens aus.  
  Glob-Muster (`*`, `?`) und einfache Substrings werden beide unterstützt.  
  Die Option kann mehrfach angegeben werden.

### F) Bibliotheksstatus anzeigen

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --status ~/nvme2n1p7_home/Musik
```

Zeigt alle Alben mit fehlenden Covern oder schlechten Tags — ohne etwas zu schreiben.

### G) Interaktiver Modus (ohne --auto)

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/music_enricher.py \
    --rename --embed-cover --no-fingerprint \
    --album ~/nvme2n1p7_home/Musik/MEIN_ALBUM
```

Das Programm zeigt den Vorschlag und fragt:
```
[Enter] Akzeptieren  [s] Überspringen  [q] Abbrechen:
```

---

## Dateinamen-Schema (mit `--rename`)

### Pop / Volkslieder / Standard
```
TT_-_Künstler_-_Titel.ext
01_-_ABBA_-_Dancing_Queen.mp3
14_-_Die_Bergvagabunden_-_Wir_sind_durch_Deutschland_gefahren.flac
```

### Klassik (Performer ≠ Komponist)
```
TT_-_Performer_-_Komponist_-_Werk.ext
01_-_Peter_Hurford_-_Johann_Sebastian_Bach_-_Toccata_And_Fugue_In_D_Minor_BWV_565.mp3
```

### Multi-CD
```
D-TT_-_Künstler_-_Titel.ext
1-01_-_..._-_....mp3    ← CD 1, Track 1
2-01_-_..._-_....mp3    ← CD 2, Track 1
```

Regeln:
- Leerzeichen → Unterstriche
- Teile durch `_-_` getrennt
- Sonderzeichen (`/ : " * ? < >`) → Unterstriche
- Nachbereinigung durch `NameToUnix` (falls installiert)

---

## Konfidenz-Anzeige verstehen

```
Konfidenz:   [████░░░░░░] 40%  Quellen: local-hints, musicbrainz-text, llm-resolve
```

| Konfidenz | Bedeutung |
|-----------|-----------|
| < 20% | Nur Dateiname/Ordnername bekannt, LLM hat geraten |
| 20–50% | MusicBrainz-Treffer mit mittlerem Score |
| 50–75% | Guter MusicBrainz-Treffer oder AcoustID-Match |
| > 75% | AcoustID-Fingerprint + MusicBrainz bestätigt |

Für Albums die nicht in MusicBrainz sind (Eigenaufnahmen, YouTube-Downloads):
`--confidence 0.1` verwenden.

---

## Fehlerbehandlung

### "Cover nicht gefunden"
→ `Front.jpg` oder `Front.webp` manuell ins Album-Verzeichnis legen,
dann erneut mit `--embed-cover` laufen lassen.

### "Artist: F.R. David" (falscher Künstler)
→ Das LLM hat falsch geraten. Im Interaktiv-Modus mit `s` überspringen
oder Tags nachträglich mit einem Tag-Editor (z.B. Kid3, MusicBrainz Picard)
korrigieren.

### Programm läuft, aber nichts passiert
→ Prüfen ob Ollama läuft: `ollama list`
→ `--no-api` verwenden wenn kein Netzwerk / kein Ollama verfügbar

### Backup wiederherstellen
```bash
cp /tmp/mein_backup/ALBUMNAME__dateiname.flac \
   ~/nvme2n1p7_home/Musik/ALBUMNAME/dateiname.flac
```

---

## Umgebungsvariablen

```bash
export OLLAMA_HOST=http://localhost:11434      # Ollama-Server
export OLLAMA_RESOLVE_MODEL=qwen3:8b           # LLM für Metadaten
export OLLAMA_OCR_MODEL=qwen3-vl:latest        # Vision-Modell für OCR
export OPENROUTER_API_KEY=sk-or-...            # OpenRouter-Fallback (optional)
export ACOUSTID_API_KEY=...                    # AcoustID-Fingerprinting (optional)
export DISCOGS_TOKEN=...                       # Discogs-API (optional)
export LASTFM_API_KEY=...                      # Last.fm Cover + Tracklist (optional)
```

Kostenloser Last.fm API-Key: https://www.last.fm/api/account/create

---

## Tests ausführen

```bash
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/test_suite_enricher.py
# 📊 33/33 Tests erfolgreich
```