dschlueter
1cb5a8fb8d
Covers: album directory structure, YouTube ID handling, typical workflows (dry-run → live), all CLI options, filename schemas, confidence levels, error handling, backup/restore, and environment variables. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
263 lines
7.9 KiB
Markdown
263 lines
7.9 KiB
Markdown
# 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 |
|
||
|
||
---
|
||
|
||
## 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) 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)
|
||
```
|
||
|
||
---
|
||
|
||
## Tests ausführen
|
||
|
||
```bash
|
||
python3 ~/nvme2n1p7_home/Musik/Music_Metadata_Enricher/test_suite_enricher.py
|
||
# 📊 17/17 Tests erfolgreich
|
||
```
|