Update Bedienungsanleitung: in-place mode, Unterstrich-Schema, Disc-Validierung

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-17 23:52:17 +01:00 · 2026-02-17 23:52:17 +01:00 · 734bc80b79
commit 734bc80b79
parent 070a0573ae
1 changed files with 123 additions and 53 deletions
--- a/BEDIENUNGSANLEITUNG.md
+++ b/BEDIENUNGSANLEITUNG.md
@ -60,21 +60,23 @@ musiksammlung rip          ← CDs rippen, CDDB-Lookup, Dateien benennen
    │
    ▼
 temp/Album/CD1/
-  01_-_Titel_-_Künstler.flac
-  02_-_Titel_-_Künstler.flac
+  track01.flac
+  track02.flac
    │
    ├─ CDDB hat alles erkannt?
-    │     ja → musiksammlung apply
-    │     nein → musiksammlung scan (Coverbild → album.json)
+    │     ja  → track01.flac bereits umbenannt → musiksammlung apply
+    │     nein → musiksammlung scan (Coverbild/Text → album.json)
+    │              → album.json prüfen/korrigieren
+    │              → musiksammlung apply
    │
    ▼
-musiksammlung apply        ← Dateien in Jellyfin-Struktur, Tags, Cover, Playlist
+musiksammlung apply        ← Umbenennen, Tags, Cover, Playlist
    │
-    ▼
-~/Musik/Künstler/Album/
-  01_-_Titel.flac
-  cover.jpg
-  playlist.m3u
+    ├─ --in-place (Standard): Dateien bleiben im Quellverzeichnis
+    │     temp/Album/CD1/01_Titel.flac
+    │
+    └─ mit output_dir: Dateien in Jellyfin-Struktur verschieben
+          ~/Musik/Kuenstler/Album/CD1/01_Titel.flac
 ```

 ---
@ -87,14 +89,14 @@ musiksammlung apply        ← Dateien in Jellyfin-Struktur, Tags, Cover, Playli
 musiksammlung rip
 ```

-Das Programm fragt interaktiv nach Album-Name und CD-Nummer, startet `abcde` und benennt die Tracks automatisch.
+Das Programm fragt interaktiv nach Album-Name und CD-Nummer, startet `abcde` und benennt die Tracks automatisch (wenn CDDB Daten liefert).

 ### Wichtige Optionen

 | Option | Beschreibung | Empfehlung |
 |--------|-------------|------------|
 | `-f flac` | Audio-Format | `flac` für Archiv, `mp3` für Kompatibilität |
-| `-q high` | Qualität (low/medium/high) | `high` für Archiv |
+| `-q high` | Qualität (low/medium/high), Standard: `high` | `high` für Archiv |
 | `-j 0` | Alle CPU-Kerne für paralleles Encoding | empfohlen |
 | `-P` | Pipes-Modus (kein WAV-Zwischenspeicher) | empfohlen bei wenig Speicher |
 | `-o /pfad` | Ausgabe-Verzeichnis | Standard: `./temp` |
@ -111,19 +113,23 @@ musiksammlung rip -f flac -q high -j 0 -P -o ~/rip

 ```
 --- Album 1 ---
-Enter album name (or Enter for CDDB/default 'Album1'): Beethoven Sinfonien
+Album name (Enter = CDDB name / default 'Album1'): Beethoven Sinfonien

-  Album: Beethoven Sinfonien
+  Album:    Beethoven Sinfonien
  CD Drive: /dev/cdrom
-  CD number for this CD [1]: 1
-  Ripping CD to: Beethoven_Sinfonien/CD1
-  (Ripping in progress, please wait...)
-  ✓ CD 1 ripped successfully
-    Detected: Karajan
-    Tracks: 4
+  CD number [1]: 1
+
+  Ripping to: temp/Beethoven_Sinfonien/CD1
+  --------------------------------------------------
+  Track 1/4  Allegro con brio
+    [████████████████░░░░░░░░░░░░░░]  54.3%   18.2 MB
+  ...
+  ✓ Done — 4 tracks
+     1. Allegro con brio  [Karajan]
+     2. Andante con moto  [Karajan]

  Next CD for this album? (y/n): y
-  CD number for this CD [1]: 2
+  CD number [1]: 2
  ...

 Next album? (y/n): n
@ -131,30 +137,34 @@ Next album? (y/n): n

 ### Ergebnis-Verzeichnis

+**Wenn CDDB Daten liefert:**
 ```
 ~/rip/
  Beethoven_Sinfonien/
    CD1/
-      01_-_Sinfonie_Nr.5_c-Moll_op.67_Allegro_con_brio_-_Karajan.flac
-      02_-_Andante_con_moto_-_Karajan.flac
-      ...
-    CD2/
+      01_Allegro_con_brio_Karajan.flac
+      02_Andante_con_moto_Karajan.flac
      ...
 ```

-**Dateinamen-Schema:**
+**Wenn kein CDDB-Treffer:**
 ```
-<Track-Nr>_-_<Titel>_-_<Künstler>.<Endung>
+~/rip/
+  Beethoven_Sinfonien/
+    CD1/
+      track01.flac
+      track02.flac
+      ...
 ```
-Leerzeichen werden durch Unterstriche ersetzt.
+→ In diesem Fall weiter mit Schritt 2 (Metadaten ermitteln).

 ---

 ## 5. Schritt 2: Album-Metadaten ermitteln

-Dieser Schritt ist nur nötig, wenn CDDB keine vollständigen Daten geliefert hat.
+Dieser Schritt ist nur nötig, wenn CDDB keine vollständigen Daten geliefert hat (Dateien heißen noch `track01.flac` etc.).

-### Variante A: Textdatei (z.B. von Perplexity/Wikipedia kopiert)
+### Variante A: Textdatei (z.B. von Wikipedia/Perplexity kopiert)

 ```bash
 musiksammlung scan --from-text trackliste.txt -o album.json
@ -166,14 +176,40 @@ musiksammlung scan --from-text trackliste.txt -o album.json
 musiksammlung scan back.jpg -o album.json --lang deu+eng
 ```

-### Variante C: Vision-LLM (Bild direkt an LLM)
+Standard-Modell: `gemma3:12b` (via Ollama). Anderes Modell:
+```bash
+musiksammlung scan back.jpg -o album.json --model llama3.3:latest
+```
+
+### Variante C: Vision-LLM (Bild direkt an LLM, empfohlen)
+
+Besser als OCR bei komplexen Layouts (mehrere Spalten, schwierige Schriften):

 ```bash
 musiksammlung scan back.jpg --vision --vision-model qwen3-vl:latest -o album.json
 ```

+Für mehrspaltige Tracklisten auf CD-Rückseiten das große Cloud-Modell nutzen:
+```bash
+musiksammlung scan back.jpg --vision --vision-model qwen3-vl:235b-cloud -o album.json
+```
+
 ### album.json prüfen und bearbeiten

+Das Programm prüft automatisch, ob die Anzahl der erkannten Tracks mit den gerippten Dateien übereinstimmt. Bei Abweichungen erscheint eine Fehlermeldung:
+
+```
+FEHLER: Track-Diskrepanz zwischen gerippten Dateien und album.json:
+
+  [OK] Disc 1: 25 Datei(en), 25 JSON-Track(s)
+  [!!] Disc 2: 23 Datei(en), 20 JSON-Track(s)
+       → 3 Track(s) fehlen im JSON (Tracks 21–23 eintragen)
+
+Bitte album.json korrigieren und erneut aufrufen.
+```
+
+In diesem Fall `album.json` manuell ergänzen, dann `apply` erneut aufrufen.
+
 ```json
 {
  "artist": "Karajan",
@ -190,44 +226,78 @@ musiksammlung scan back.jpg --vision --vision-model qwen3-vl:latest -o album.jso
 }
 ```

-Die JSON-Datei kann vor dem nächsten Schritt manuell korrigiert werden.
-
 ---

 ## 6. Schritt 3: Dateien organisieren und taggen

+### In-place (Dateien bleiben im Quellverzeichnis)
+
 ```bash
-musiksammlung apply temp/Beethoven_Sinfonien/CD1 album.json ~/Musik
+musiksammlung apply ~/rip/Beethoven_Sinfonien album.json
+```
+
+Oder explizit:
+```bash
+musiksammlung apply ~/rip/Beethoven_Sinfonien album.json --in-place
 ```

 Das Programm:
- Kopiert Audiodateien in die Jellyfin-Struktur
- Setzt ID3/FLAC-Tags (Titel, Künstler, Album, Jahr, Track-Nummer)
- Kopiert Cover-Bilder (`cover.jpg`, `back.jpg`)
+- Benennt Audiodateien um (`track01.flac` → `01_Allegro_con_brio.flac`)
+- Setzt ID3/FLAC-Tags (Titel, Künstler, Album, Jahr, Track-Nummer, Disc-Nummer)
+- Kopiert Cover-Bilder (`back.jpg`)
 - Erzeugt eine M3U-Playlist

+Ergebnis:
+```
+~/rip/Beethoven_Sinfonien/
+  CD1/
+    01_Allegro_con_brio.flac
+    02_Andante_con_moto.flac
+    ...
+  CD2/
+    ...
+  back.jpg
+  Beethoven_Sinfonien.m3u
+```
+
+### In Jellyfin-Verzeichnis verschieben
+
+```bash
+musiksammlung apply ~/rip/Beethoven_Sinfonien album.json ~/Musik \
+  --front front.jpg --back back.jpg
+```
+
+Ergebnis:
+```
+~/Musik/
+  Karajan/
+    Beethoven_Sinfonien_1963/
+      CD1/
+        01_Allegro_con_brio.flac
+        ...
+      back.jpg
+      Beethoven_Sinfonien.m3u
+```
+
 ### Optionen

 | Option | Beschreibung |
 |--------|-------------|
+| `--in-place` | Dateien im Quellverzeichnis umbenennen (kein output_dir nötig) |
 | `--front cover.jpg` | Front-Cover-Bild |
 | `--back back.jpg` | Rückseiten-Bild |
 | `--dry-run` | Nur anzeigen, nichts ändern |

-### Ergebnis
+### Dateinamen-Schema

 ```
-~/Musik/
-  Karajan/
-    Beethoven_Sinfonien/
-      CD1/
-        01_-_Allegro_con_brio.flac
-        ...
-      cover.jpg
-      back.jpg
-      Beethoven_Sinfonien.m3u
+<Track-Nr>_<Titel>.<Endung>
 ```

+- Leerzeichen und Satzzeichen → `_`
+- Mehrere `_` hintereinander → ein `_`
+- Umlaute (ä, ö, ü, ß) bleiben erhalten
+
 ---

 ## 7. Komplett-Pipeline
@ -246,20 +316,20 @@ musiksammlung process temp/Album/CD1 ~/Musik --back back.jpg
 - Internetverbindung prüfen
 - `--no-cddb` verwenden und Metadaten manuell per `scan` ermitteln

-**Falsches CDDB-Ergebnis?**
- Tracks sind trotzdem korrekt gerippt
+**Falsches oder kein CDDB-Ergebnis?**
+- Tracks sind trotzdem korrekt gerippt (als `track01.flac` etc.)
 - `musiksammlung scan` mit Coverbild oder Textdatei aufrufen
 - `album.json` manuell korrigieren
 - `musiksammlung apply` ausführen

-**Sonderzeichen in Dateinamen?**
- Umlaute (ä, ö, ü) bleiben erhalten
- Problematische Zeichen (`/ : * ? " < > |`) werden entfernt
- Leerzeichen werden durch `_` ersetzt
+**Mehrspaltige Trackliste auf dem Backcover?**
+- OCR erkennt mehrspaltige Layouts oft unvollständig
+- Vision-LLM verwenden: `--vision --vision-model qwen3-vl:235b-cloud`

 **Mehrere CDs eines Albums (Multi-Disc)?**
 - Bei der Abfrage "Next CD for this album?" mit `y` antworten
 - Jede CD erhält ein eigenes Unterverzeichnis `CD1`, `CD2`, ...
+- `apply` einmal mit dem Album-Verzeichnis aufrufen (nicht pro CD)

 **Unterstützte Audio-Formate:**