Musiksammlung/BEDIENUNGSANLEITUNG.md

Bedienungsanleitung – Musiksammlung

ACHTUNG! Das Programm ist nicht fertig!

Inhaltsverzeichnis

1. Voraussetzungen
2. Installation
3. Workflow-Überblick
4. Schritt 1: CDs rippen
5. Schritt 2: Album-Metadaten ermitteln
6. Schritt 3: Dateien organisieren und taggen
7. Tags und Cover prüfen
8. Komplett-Pipeline
9. Tipps und Hinweise

---

1. Voraussetzungen

Programm	Zweck	Pflicht
Python 3.11+	Laufzeitumgebung	ja
abcde	CD-Ripping	ja
cdparanoia	CD-Lesefehler korrigieren (von abcde genutzt)	ja
flac / lame / opusenc / ffmpeg	Encoder je nach Format	je nach Format
tesseract	OCR für Coverbilder	nein (optional)
Ollama / OpenAI-API	LLM für Tracklisten-Extraktion	nein (optional)

Installation der externen Tools (Debian/Ubuntu):

sudo apt install abcde cdparanoia flac lame opus-tools ffmpeg tesseract-ocr

---

2. Installation

git clone <repo-url>
cd Musiksammlung
pip install -e ".[dev]"

Danach steht der Befehl musiksammlung zur Verfügung:

musiksammlung --help

---

3. Workflow-Überblick

musiksammlung rip
    │
    ▼
EAN/Barcode eingeben (Enter = überspringen)
    │
    ├─ MusicBrainz-Treffer → Auto-Rip
    │     Zeige: Artist – Album (Year), N Discs, M Tracks
    │     Für jede Disc: "CD 1/3 einlegen, Enter" → Rip → Rename
    │     album.json automatisch aus MusicBrainz-Daten
    │     → direkt weiter mit musiksammlung apply
    │
    └─ Kein Treffer / EAN leer → Fallback
          Albumname eingeben → CD-Nummer → Rip → CDDB-Confirm
          album.json aus CDDB-Daten (falls bestätigt)
          │
          ├─ album.json vorhanden?
          │     ja  → direkt weiter mit musiksammlung apply
          │
          └─ nein → album.json manuell erzeugen:
                        A: musiksammlung scan --from-text trackliste.txt
                        B: musiksammlung scan back.jpg
                        C: musiksammlung scan back.jpg --vision
                        D: musiksammlung scan --barcode 0602557360561
                    → album.json prüfen/korrigieren
    │
    ▼
musiksammlung apply        ← Umbenennen, Tags, Cover, Playlist
    │
    ├─ --in-place (Standard): Dateien bleiben im Quellverzeichnis
    │     temp/Album/CD1/01_-_Titel_-_Kuenstler.flac
    │
    └─ mit output_dir: Dateien in Jellyfin-Struktur verschieben
          ~/Musik/Kuenstler/Album/CD1/01_-_Titel_-_Kuenstler.flac

---

4. Schritt 1: CDs rippen

Grundbefehl

musiksammlung rip

Das Programm fragt zuerst nach dem EAN/Barcode. Bei einem MusicBrainz-Treffer startet ein automatischer Rip-Vorgang für alle Discs des Albums. Ohne EAN oder bei Fehltreffer wird der manuelle Ablauf gestartet (Album-Name, CD-Nummer, CDDB-Bestätigung).

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), 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
-d /dev/sr0	CD-Laufwerk	falls nicht /dev/cdrom
--no-cddb	CDDB-Lookup deaktivieren	bei Offline-Betrieb

Beispiel: Schnelles FLAC-Ripping mit allen Kernen

musiksammlung rip -f flac -q high -j 0 -P -o ~/rip

Interaktiver Ablauf

Mit EAN (Auto-Rip):

--- Album 1 ---
EAN/Barcode (Enter = überspringen): 028943753227
  MusicBrainz-Suche nach Barcode 028943753227 ...
  ✓ Herbert von Karajan – Beethoven: 9 Symphonies (1963, 5 Disc(s), 50 Tracks)

  CD 1/5 einlegen und Enter drücken (9 Tracks) ...

  Ripping to: temp/Beethoven__9_Symphonies/CD1
  --------------------------------------------------
  Track 1/9  Allegro con brio
    [████████████████░░░░░░░░░░░░░░]  54.3%   18.2 MB
  ...
  Umbenennen (CDDB-Daten) ...

  CD 2/5 einlegen und Enter drücken (4 Tracks) ...
  ...

  album.json gespeichert: temp/Beethoven__9_Symphonies/album.json

Next album? (y/n): n

Ohne EAN (Fallback):

--- Album 1 ---
EAN/Barcode (Enter = überspringen):
Album name (Enter = CDDB name / default 'Album1'): Beethoven Sinfonien

  Album:    Beethoven Sinfonien
  CD Drive: /dev/cdrom
  CD number [1]: 1

  Ripping to: temp/Beethoven_Sinfonien/CD1
  --------------------------------------------------
  Track 1/4  Allegro con brio
    [████████████████░░░░░░░░░░░░░░]  54.3%   18.2 MB
  ...
  CDDB-Treffer: 'Karajan / Beethoven Sinfonien' — 4 Tracks:
     1. Allegro con brio  [Karajan]
     2. Andante con moto  [Karajan]

  Treffer korrekt? (j/n) [j]: j
  Umbenennen ...

  Next CD for this album? (y/n): n

Next album? (y/n): n

Ergebnis-Verzeichnis

Wenn CDDB Daten liefert:

~/rip/
  Beethoven_Sinfonien/
    CD1/
      01_-_Allegro_con_brio_-_Karajan.flac
      02_-_Andante_con_moto_-_Karajan.flac
      ...
    album.json               ← automatisch gespeichert

→ Direkt weiter mit musiksammlung apply ~/rip/Beethoven_Sinfonien album.json

Wenn kein CDDB-Treffer:

~/rip/
  Beethoven_Sinfonien/
    CD1/
      track01.flac
      track02.flac
      ...

→ 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 (Dateien heißen noch track01.flac etc.).

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

musiksammlung scan --from-text trackliste.txt -o album.json

Variante B: Coverbild per OCR + LLM

musiksammlung scan back.jpg -o album.json --lang deu+eng

Standard-Modell: gemma3:12b (via Ollama). Anderes Modell:

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):

musiksammlung scan back.jpg --vision -o album.json

Standard-Modell: qwen3-vl:235b-cloud (via Ollama). Anderes Modell:

musiksammlung scan back.jpg --vision --vision-model qwen3-vl:7b -o album.json

Variante D: EAN/Barcode → MusicBrainz (schnellste Methode)

Wenn die EAN-13- oder UPC-12-Nummer der CD bekannt ist (aufgedruckt auf der Hülle), kann das Programm die Metadaten direkt aus der MusicBrainz-Datenbank laden — ohne Bild, ohne OCR, ohne lokales LLM:

musiksammlung scan --barcode 0602557360561 -o album.json

Die EAN lässt sich auch mit einem Barcode-Scanner oder einer Smartphone-App ablesen.

MusicBrainz liefert bei einem Treffer: Interpret, Albumtitel, Erscheinungsjahr und vollständige Trackliste. Kein API-Schlüssel erforderlich.

Beim interaktiven Rip-Befehl (musiksammlung rip) wird die EAN als erstes abgefragt. Bei einem MusicBrainz-Treffer startet automatisch der Rip-Vorgang für alle Discs — kein Albumname, keine CDDB-Bestätigung nötig. Das album.json wird direkt aus den MusicBrainz-Daten gespeichert.

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.

{
  "artist": "Karajan",
  "album": "Beethoven Sinfonien",
  "year": 1963,
  "genre": "Classical",
  "discs": [
    {
      "disc_number": 1,
      "tracks": [
        {"track_number": 1, "title": "Allegro con brio"},
        {"track_number": 2, "title": "Andante con moto"}
      ]
    }
  ]
}

Das Feld "genre" ist optional und wird automatisch befüllt, wenn GnuDB ein DGENRE liefert.

Das Feld "artist" auf Track-Ebene ist optional. Wird es gesetzt, überschreibt es den Album-Künstler für diesen Track — sinnvoll bei Samplern oder Klassik mit verschiedenen Solisten:

{"track_number": 3, "title": "Klavierkonzert Nr. 5", "artist": "Brendel"}`

---

6. Schritt 3: Dateien organisieren und taggen

In-place (Dateien bleiben im Quellverzeichnis)

musiksammlung apply ~/rip/Beethoven_Sinfonien album.json

Oder explizit:

musiksammlung apply ~/rip/Beethoven_Sinfonien album.json --in-place

Das Programm:

• Benennt Audiodateien um (track01.flac → 01_-_Allegro_con_brio_-_Karajan.flac)
• Setzt ID3/FLAC-Tags (Titel, Künstler, Album, Jahr, Track-Nummer, Disc-Nummer)
• Kopiert Cover-Bilder (back.jpg)
• Erzeugt eine M3U-Playlist
• Benennt das Album-Verzeichnis automatisch um (wenn input_dir ein CD-Unterverzeichnis ist, z.B. CD1)

Ergebnis:

~/rip/Beethoven_Sinfonien (2024)/      ← automatisch umbenannt
  CD1/
    01_-_Allegro_con_brio_-_Karajan.flac
    02_-_Andante_con_moto_-_Karajan.flac
    ...
  CD2/
    ...
  back.jpg
  Beethoven_Sinfonien.m3u

Hinweis zur Auto-Umbenennung: Das Album-Verzeichnis wird automatisch umbenannt, wenn input_dir ein CD-Unterverzeichnis (CD1, CD2 ...) ist. Wird stattdessen das Album-Wurzelverzeichnis übergeben, gibt das Programm einen mv-Hinweis aus, aber benennt nicht selbst um.

In Jellyfin-Verzeichnis verschieben

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_-_Karajan.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

Cover-Konvention

Im Album-Verzeichnis werden folgende Dateinamen erwartet:

Datei	Zweck
frontcover.jpg oder frontcover.png	Front-Cover
backcover.jpg oder backcover.png	Rückseiten-Cover

Symbolische Links auf diese Namen sind erlaubt. apply kopiert die mit --front/--back angegebenen Bilder automatisch als frontcover.jpg bzw. backcover.jpg ins Album-Verzeichnis und bettet das Frontcover anschließend in alle Audio-Dateien ein (skaliert auf max. 500 px).

Ist bereits ein frontcover.* vorhanden (z.B. bei erneutem apply), wird es ohne --front-Option verwendet.

Dateinamen-Schema

<Track-Nr>_-_<Titel>_-_<Künstler>.<Endung>

Beispiel: 01_-_Allegro_con_brio_-_Karajan.flac

• Leerzeichen und Satzzeichen → _
• Mehrere _ hintereinander → ein _
• Umlaute (ä, ö, ü, ß) bleiben erhalten
• Künstler pro Track: falls im album.json ein Track-artist gesetzt ist, wird dieser verwendet; sonst der Album-Künstler

---

7. Tags und Cover prüfen

Nach apply lässt sich der Zustand aller Dateien mit einem Befehl prüfen:

musiksammlung check ~/rip/Beethoven_Sinfonien

Ausgabe:

Verzeichnis: ~/rip/Beethoven_Sinfonien
  frontcover: frontcover.jpg
  backcover:  backcover.jpg

  CD1/
    [♪] 01_-_Allegro_con_brio_-_Karajan.flac
         Titel:    Allegro con brio
         Künstler: Karajan  |  AlbumArtist: Karajan
         Album:    Beethoven Sinfonien  |  Jahr: 1963
         Track:    1/4  |  Disc: 1
    ...

[♪] zeigt an, dass ein Cover eingebettet ist. [ ] bedeutet kein eingebettetes Cover.

---

8. Komplett-Pipeline

Für einfache Fälle (alles in einem Schritt):

musiksammlung process temp/Album/CD1 ~/Musik --back back.jpg

---

9. Tipps und Hinweise

EAN/Barcode verfügbar? → Schnellster Weg

• EAN-13 oder UPC-12 von der CD-Hülle ablesen (ggf. Barcode-Scanner-App nutzen)
• Beim rip-Befehl wird die EAN als erstes abgefragt — bei MusicBrainz-Treffer startet der Auto-Rip sofort (keine weiteren Fragen)
• Alternativ: musiksammlung scan --barcode 0602557360561 -o album.json
• Kein Bild, kein OCR, kein lokales LLM notwendig

CDDB-Lookup schlägt fehl?

• Internetverbindung prüfen
• --no-cddb verwenden und Metadaten per scan --barcode oder scan (Bild) ermitteln

Falsches oder kein CDDB-Ergebnis?

• Tracks sind trotzdem korrekt gerippt (als track01.flac etc.)
• musiksammlung scan --barcode EAN verwenden (wenn EAN bekannt)
• Oder musiksammlung scan mit Coverbild oder Textdatei aufrufen
• album.json manuell korrigieren, dann musiksammlung apply ausführen

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 EAN-Treffer: MusicBrainz kennt die Disc-Anzahl, der Auto-Rip fordert automatisch jede CD an
• Ohne EAN: 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:

Format	Qualität high	Verwendung
flac	Verlustfrei	Archiv
mp3	VBR -V0	maximale Kompatibilität
opus	192 kbit/s	modern, effizient
aac	Qualität 4	Apple-Geräte
wav	Verlustfrei	maximale Kompatibilität, groß