dschlueter 92af4eeb9c Add BEDIENUNGSANLEITUNG.md and update README.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-17 17:39:24 +01:00

6.2 KiB

Raw Blame History

Bedienungsanleitung – Musiksammlung

Inhaltsverzeichnis

Voraussetzungen
Installation
Workflow-Überblick
Schritt 1: CDs rippen
Schritt 2: Album-Metadaten ermitteln
Schritt 3: Dateien organisieren und taggen
Komplett-Pipeline
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/
  01_-_Titel_-_Künstler.flac
  02_-_Titel_-_Künstler.flac
    │
    ├─ CDDB hat alles erkannt?
    │     ja → musiksammlung apply
    │     nein → musiksammlung scan (Coverbild → album.json)
    │
    ▼
musiksammlung apply        ← Dateien in Jellyfin-Struktur, Tags, Cover, Playlist
    │
    ▼
~/Musik/Künstler/Album/
  01_-_Titel.flac
  cover.jpg
  playlist.m3u

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.

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
`-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 ---
Enter album name (or Enter for CDDB/default 'Album1'): 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

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

Next album? (y/n): n

Ergebnis-Verzeichnis

~/rip/
  Beethoven_Sinfonien/
    CD1/
      01_-_Sinfonie_Nr.5_c-Moll_op.67_Allegro_con_brio_-_Karajan.flac
      02_-_Andante_con_moto_-_Karajan.flac
      ...
    CD2/
      ...

Dateinamen-Schema:

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

Leerzeichen werden durch Unterstriche ersetzt.

5. Schritt 2: Album-Metadaten ermitteln

Dieser Schritt ist nur nötig, wenn CDDB keine vollständigen Daten geliefert hat.

Variante A: Textdatei (z.B. von Perplexity/Wikipedia 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

Variante C: Vision-LLM (Bild direkt an LLM)

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

album.json prüfen und bearbeiten

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

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

6. Schritt 3: Dateien organisieren und taggen

musiksammlung apply temp/Beethoven_Sinfonien/CD1 album.json ~/Musik

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)
Erzeugt eine M3U-Playlist

Optionen

Option	Beschreibung
`--front cover.jpg`	Front-Cover-Bild
`--back back.jpg`	Rückseiten-Bild
`--dry-run`	Nur anzeigen, nichts ändern

Ergebnis

~/Musik/
  Karajan/
    Beethoven_Sinfonien/
      CD1/
        01_-_Allegro_con_brio.flac
        ...
      cover.jpg
      back.jpg
      Beethoven_Sinfonien.m3u

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 CDDB-Ergebnis?

Tracks sind trotzdem korrekt gerippt
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

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, ...

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ß

6.2 KiB Raw Blame History Unescape Escape