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. Komplett-Pipeline
8. 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
    │
    ▼
temp/Album/
  CD1/
    track01.flac           ← kein CDDB-Treffer
    track02.flac
  album.json               ← automatisch erzeugt, wenn CDDB Daten liefert
    │
    ├─ CDDB hat alles erkannt?
    │     ja  → album.json bereits vorhanden → musiksammlung apply
    │     nein → musiksammlung scan (Coverbild/Text → album.json)
    │              → 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

  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 --vision-model qwen3-vl:latest -o album.json

Für mehrspaltige Tracklisten auf CD-Rückseiten das große Cloud-Modell nutzen:

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.

{
  "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

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. Komplett-Pipeline

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

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

---

8. Tipps und Hinweise

CDDB-Lookup schlägt fehl?

• Internetverbindung prüfen
• --no-cddb verwenden und Metadaten manuell per scan ermitteln

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

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ß