From 1cb5a8fb8d644c9ba934ef42304c82099dc93345 Mon Sep 17 00:00:00 2001 From: dschlueter Date: Wed, 29 Apr 2026 06:52:44 +0200 Subject: [PATCH] Add BEDIENUNGSANLEITUNG.md (German user manual) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- BEDIENUNGSANLEITUNG.md | 263 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 BEDIENUNGSANLEITUNG.md diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md new file mode 100644 index 0000000..7f57d8a --- /dev/null +++ b/BEDIENUNGSANLEITUNG.md @@ -0,0 +1,263 @@ +# 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 +```