Musiksammlung/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung – Musiksammlung

## 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. [Komplett-Pipeline](#7-komplett-pipeline)
8. [Tipps und Hinweise](#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):

```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
    │
    ▼
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

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

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

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

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

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

### album.json prüfen und bearbeiten

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

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

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