m4b-tool/README.md

# to-m4b

Kleines Bash‑Skript, das Hörbuch‑Ordner unter `src/` erkennt und mit
[m4b-tool](https://github.com/sandreas/m4b-tool) zu einzelnen `.m4b`‑Dateien
zusammenführt. Metadaten (Autor, Serie, Titel, Jahr, Sprecher:in) werden aus
der Ordnerstruktur extrahiert und als Tags gesetzt. Die Ergebnisse werden unter
`out/` abgelegt.

> Das Skript startet `m4b-tool` über docker (`docker run -it --rm -u $(id -u):$(id -g) -v "$(pwd)":/mnt sandreas/m4b-tool:latest`) oder  
> Nix (`nix run github:sandreas/m4b-tool#m4b-tool-libfdk`).

## Inhaltsverzeichnis

- [to-m4b](#to-m4b)
  - [Inhaltsverzeichnis](#inhaltsverzeichnis)
  - [Voraussetzungen](#voraussetzungen)
  - [Quickstart](#quickstart)
  - [Verzeichnisstruktur](#verzeichnisstruktur)
  - [Ausgabepfade](#ausgabepfade)
  - [Verwendete Tags](#verwendete-tags)
  - [Nutzung](#nutzung)
  - [Konfiguration](#konfiguration)
  - [Beispiele](#beispiele)
    - [Quelle (src):](#quelle-src)
    - [Ergebnis (out):](#ergebnis-out)
  - [Fehlersuche](#fehlersuche)
  - [Hinweise](#hinweise)


## Voraussetzungen

- Nix oder docker installiert (für den Aufruf von `m4b-tool` via `docker run` oder `nix run`)
- Audio‑Quellen in unterstützten Formaten: `mp3`, `m4a`, `m4b`, `aac`, `flac`, `wav`, `ogg`
- Bash (unter macOS/Linux vorhanden)

## Quickstart

1) Quellen in die passende Ordnerstruktur unter `src/` legen (siehe Beispiele unten).
2) Script ausführbar machen: `chmod +x to-m4b.sh`
3) Konvertierung starten: `./to-m4b.sh`
4) Ergebnis unter `out/` prüfen.

## Verzeichnisstruktur

Das Skript erwartet unter `src/` je Hörbuch einen Ordner in einer der beiden Formen:

1) Serie (mit Folgennummer)

```
src/<Autor>/<Serie>/Book <Folge> - <YYYY> - <Titel> {<Sprecher>}/
```

Beispiel:

```
src/WinterZeit Verlag/Das Schwarze Auge/Book 15 - 2022 - Auf Schusters Rappen/
  249_Das schwarze Auge_Teil 1 - Folge 15_ Auf Schusters Rappen.ogg
  ...
```

2) Einzelband (ohne Serie)

```
src/<Autor>/<YYYY> - <Titel> {<Sprecher>}/
```

Die Angabe `{<Sprecher>}` ist optional; Leerzeichen dürfen enthalten sein.

## Ausgabepfade

Für jede erkannte Quelle wird genau eine `.m4b` erzeugt und unter `out/` abgelegt.

- Serie:
  - Ordner: `out/<Autor>/<Serie>/Book <NN> - <YYYY> - <Titel>/`
  - Datei:  `<YYYY> - <Titel> {<Sprecher>}.m4b`
- Einzelband:
  - Ordner: `out/<Autor>/<YYYY> - <Titel> {<Sprecher>}/`
  - Datei:  `<YYYY> - <Titel> {<Sprecher>}.m4b`

Hinweis: `<NN>` ist die null‑aufgefüllte Folgennummer (Standard: 2 Stellen, z. B. `01`).

## Verwendete Tags

- Autor → `writer`
- Sprecher:in → `artist`
- Titel → `album`
- Jahr → `year`
- Serie → `series`, Folgennummer → `series-part`

## Nutzung

1) Quellen in die passende Ordnerstruktur unter `src/` legen (siehe oben).
2) Skript ausführbar machen (einmalig):

```
chmod +x to-m4b.sh
```

3) Konvertierung starten:

```
./to-m4b.sh
```

Das Skript durchsucht `src/` rekursiv auf den erwarteten Ebenen, erzeugt pro
gefundenem Hörbuch eine `.m4b` und schreibt Ausgaben nach `out/`.

## Konfiguration

Die wichtigsten Einstellungen stehen am Anfang von `to-m4b.sh` und können bei Bedarf angepasst werden:

```bash
# to-m4b.sh (Auszug)
LEADING_ZEROES=2   # Stellen für Serienfolgen (z. B. 01, 02, ...)
SRC="${script_dir}/src"  # Quellverzeichnis
OUT="${script_dir}/out"  # Zielverzeichnis
```

Weitere relevante `m4b-tool`‑Parameter (im Skript `m4b-merge()`):

- `--jobs=6` (Parallelität)
- `--audio-samplerate=44100`
- `--audio-quality=100`
- Ausführung über `m4b-tool-libfdk` (AAC‑Encoder libfdk_aac)

Wenn du `m4b-tool` lokal ohne Nix verwenden willst, kannst du den Aufruf in
`m4b-merge()` entsprechend auf ein lokales `m4b-tool` ändern.

## Beispiele

### Quelle (src):

```
󰣞 src/                                                                                (Source Directory, für Hör-bücher/-spiele)
├──  'Corvus Corax'/                                                                 (Author)
│   └──  '2017 - Der Fluch des Drachen'/                                             (Jahr - Titel)
│       ├──  '101 - Einführung.flac'                                                 (Audiodateien)
│       ├──  '102 - Nimmer mehr (Die Ballade von Adamas) (Hörbuch Edit).flac'
│       ├──  '...'
│       ├──  '...'
│       ├──  '224 - Wer hat euch vom Schmied erzählt.flac'
│       └──  cover.jpg                                                               (Cover-Bild für das m4b Hörbuch)
└──  'WinterZeit Verlag'/                                                            (Author)
    └──  'Das Schwarze Auge'/                                                        (Serien Titel)
        ├──  'Book 1 - 2017 - Im Kerker von Gareth'/                                 (Book <Serien index> - Jahr - Title)
        │   ├──  '001_Das schwarze Auge_Teil 1 - Folge 1_ Im Kerker von Gareth.ogg'  (Audiodateien)
        │   ├──  '002_Das schwarze Auge_Teil 2 - Folge 1_ Im Kerker von Gareth.ogg'
        │   ├──  '...'
        │   ├──  '...'
        │   ├──  '017_Das schwarze Auge_Teil 17 - Folge 1_ Im Kerker von Gareth.ogg'
        │   ├──  cover.jpg                                                           (Cover-Bild für das m4b Hörbuch)
        │   └──  description.txt                                                     (Beschreibung für das m4b Hörbuch)
        └──  'Book 2 - 2017 - Freund oder Feind'/
            ├──  '018_Das schwarze Auge_Teil 1 - Folge 2_ Freund oder Feind.ogg'
            ├──  '019_Das schwarze Auge_Teil 2 - Folge 2_ Freund oder Feind.ogg'
            ├──  '...'
            ├──  '...'
            ├──  '035_Das schwarze Auge_Teil 18 - Folge 2_ Freund oder Feind.ogg'
            ├──  cover.jpg
            └──  description.txt
```

### Ergebnis (out):

```
 out/                                                                                (Output Directory, für die m4b Hör-bücher/-spiele)
├──  'Corvus Corax'/                                                                 (Author)
│   └──  '2017 - Der Fluch des Drachen'/                                             (Jahr - Titel)
│       └──  '2017 - Der Fluch des Drachen.m4b'                                      (Fertiges m4b Hörbuch)
└──  'WinterZeit Verlag'/                                                            (Author)
    └──  'Das Schwarze Auge'/                                                        (Serien Titel)
        ├──  'Book 01 - 2017 - Im Kerker von Gareth'/                                (Book <Serien index> - Jahr - Title)
        │   └──  '2017 - Im Kerker von Gareth.m4b'                                   (Fertiges m4b Hörbuch -- Jahr - Titel.m4b)
        └──  'Book 02 - 2017 - Freund oder Feind'/                                   (Book <Serien index> - Jahr - Title)
            └──  '2017 - Freund oder Feind.m4b'                                      (Fertiges m4b Hörbuch -- Jahr - Titel.m4b)
```

## Fehlersuche

- „No book directories found …“: Struktur unter `src/` prüfen; siehe Abschnitt „Verzeichnisstruktur“.
- „Skipping '…': could not parse …“: Ordnername an die erwartten Muster anpassen.
- „nix: command not found“: Nix installieren oder den `m4b-tool`‑Aufruf auf ein lokales Binary umstellen.
- „permission denied“ beim Start: `chmod +x to-m4b.sh` ausführen.

## Hinweise

- Cover/weitere Dateien im Quellordner werden nicht explizit an `m4b-tool` übergeben; das Tagging beruht vollständig auf der Ordnerbenennung.
- Unterstützte Audioformate werden automatisch erkannt; die Reihenfolge bestimmt `m4b-tool` anhand von Track‑Infos/Dateinamen.