Musiksammlung/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung – Musiksammlung

> **ACHTUNG! Das Programm ist nicht fertig!**

## Inhaltsverzeichnis

1. [Voraussetzungen](#1-voraussetzungen)
2. [Installation](#2-installation)
3. [Workflow-Überblick](#3-workflow-überblick)
4. [Schritt 1: CDs rippen](#4-schritt-1-cds-rippen)
5. [Schritt 2: Album-Metadaten ermitteln](#5-schritt-2-album-metadaten-ermitteln)
6. [Schritt 3: Dateien organisieren und taggen](#6-schritt-3-dateien-organisieren-und-taggen)
7. [Tags und Cover prüfen](#7-tags-und-cover-prüfen)
8. [Komplett-Pipeline](#8-komplett-pipeline)
9. [Tipps und Hinweise](#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):

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

---

## 2. Installation

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

Danach steht der Befehl `musiksammlung` zur Verfügung:

```bash
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

```bash
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

```bash
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)

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

### Variante B: Coverbild per OCR + LLM

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

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 -o album.json
```

Standard-Modell: `qwen3-vl:235b-cloud` (via Ollama). Anderes Modell:
```bash
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](https://musicbrainz.org)-Datenbank laden — ohne Bild, ohne OCR, ohne lokales LLM:

```bash
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.

```json
{
  "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:

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

---

## 6. Schritt 3: Dateien organisieren und taggen

### In-place (Dateien bleiben im Quellverzeichnis)

```bash
musiksammlung apply ~/rip/Beethoven_Sinfonien album.json
```

Oder explizit:
```bash
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

```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_-_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:

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

```bash
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ß |