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

CD einlegen
    │
    ▼
musiksammlung rip          ← CDs rippen, CDDB-Lookup, Dateien benennen
    │                         (optional: EAN-Abfrage → MusicBrainz)
    ▼
temp/Album/
  CD1/
    track01.flac           ← kein CDDB-Treffer
    track02.flac
  album.json               ← automatisch erzeugt (CDDB oder MusicBrainz)
    │
    ├─ album.json bereits vorhanden (CDDB/MusicBrainz)?
    │     ja  → direkt weiter mit musiksammlung apply
    │
    └─ nein → album.json manuell erzeugen (eine Variante wählen):
                  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
    │
    ▼
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 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), 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

--- Album 1 ---
Album name (Enter = CDDB name / default 'Album1'): Beethoven Sinfonien
EAN/Barcode für MusicBrainz (Enter = überspringen): 028943753227
  MusicBrainz-Suche nach Barcode 028943753227 ...
  ✓ Herbert von Karajan – Beethoven: 9 Symphonies (1963, 50 Tracks)

  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
  ...
  ✓ Done — 4 tracks
     1. Allegro con brio  [Karajan]
     2. Andante con moto  [Karajan]

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

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.

Alternativ kann die EAN auch während des interaktiven Rippens eingegeben werden (Abfrage „EAN/Barcode für MusicBrainz"). Das Ergebnis wird dann direkt als album.json 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,
  "discs": [
    {
      "disc_number": 1,
      "tracks": [
        {"track_number": 1, "title": "Allegro con brio"},
        {"track_number": 2, "title": "Andante con moto"}
      ]
    }
  ]
}

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

Ergebnis:

~/rip/Beethoven_Sinfonien/
  CD1/
    01_-_Allegro_con_brio_-_Karajan.flac
    02_-_Andante_con_moto_-_Karajan.flac
    ...
  CD2/
    ...
  back.jpg
  Beethoven_Sinfonien.m3u

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)
• musiksammlung scan --barcode 0602557360561 -o album.json
• Oder beim rip-Befehl die EAN-Abfrage verwenden — dann wird album.json direkt gespeichert
• 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 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ß