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

pip install mutagen musicbrainzngs Pillow requests tqdm beautifulsoup4

Für YouTube-Metadaten:

sudo apt install yt-dlp

Für LLM-Reasoning: Ollama muss laufen (http://localhost:11434), Modell qwen3:8b empfohlen:

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:

# 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

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)

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

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

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

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

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)

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

cp /tmp/mein_backup/ALBUMNAME__dateiname.flac \
   ~/nvme2n1p7_home/Musik/ALBUMNAME/dateiname.flac

---

Umgebungsvariablen

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

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