Add BEDIENUNGSANLEITUNG.md (German user manual)
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>
This commit is contained in:
parent
5c7b6759ff
commit
1cb5a8fb8d
1 changed files with 263 additions and 0 deletions
263
BEDIENUNGSANLEITUNG.md
Normal file
263
BEDIENUNGSANLEITUNG.md
Normal file
|
|
@ -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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue