# InkFlow

Transforme un **EPUB** en **livre audio**, 100 % en local sur Mac (Apple Silicon / MLX),
avec des modèles open-source. Sortie : **1 dossier par livre, 1 MP3 par chapitre**
(tags ID3 + cover), au format calqué sur un audiobook classique.

- **Analyse de texte** : Gemma via `mlx-lm` (segmentation narration/dialogue,
  attribution des locuteurs, extraction du casting, prononciations).
- **Synthèse vocale** : backend pluggable —
  - **Kokoro** : rapide, voix préréglées → previews / mono-narrateur.
  - **Qwen3-TTS** : qualité + clonage par audio de référence → rendu final, casting par personnage.
- **Langue** : optimisé français (puis multilingue).

## Pré-requis

- macOS Apple Silicon (arm64), Python ≥ 3.11
- `ffmpeg` et `espeak-ng` :
  ```bash
  brew install ffmpeg espeak-ng
  ```

## Installation

```bash
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e backend            # installe inkflow + dépendances
python backend/scripts/setup_models.py   # vérifie l'env + télécharge les modèles MLX
```

> Kokoro en français nécessite `espeak-ng` ; InkFlow localise automatiquement
> `libespeak-ng.dylib` (sinon, exporter `PHONEMIZER_ESPEAK_LIBRARY`).

## Utilisation (CLI)

```bash
# 1. Parser l'EPUB -> data/<slug>/book.json + chapters/chNN.json
inkflow parse "samples/Colère de Tiamat, La - James S.A. Corey.epub"

# 2. Analyser (Gemma) -> analysis/chNN.json + cast.json
inkflow analyze la-colere-de-tiamat --chapter 5      # un chapitre
inkflow analyze la-colere-de-tiamat                  # tous les chapitres

# 3. Synthétiser un chapitre -> output/<livre>/NN-....mp3
inkflow render la-colere-de-tiamat 5 --backend kokoro          # rapide
inkflow render la-colere-de-tiamat 5 --backend qwen3 --no-mono # qualité + multi-voix (M3)

# Infos
inkflow info la-colere-de-tiamat
```

(Sans installation `-e`, lancer depuis `backend/` via `python -m inkflow.cli …`.)

## Interface web

```bash
# 1. Build du frontend (une fois)
cd frontend && npm install && npm run build && cd ..

# 2. Lancer l'app (API + UI servie sur le même port)
inkflow serve            # http://127.0.0.1:8000
```

L'UI permet : import EPUB par glisser-déposer, suivi temps réel des étapes
(WebSocket), édition du casting (personnage → voix, avec preview), édition du
dictionnaire de prononciation, choix du moteur (Kokoro/Qwen3) et rendu des
chapitres avec lecteur audio + téléchargement.

Pour le développement frontend avec rechargement à chaud :
```bash
inkflow serve            # backend sur :8000
cd frontend && npm run dev   # UI sur :5173 (proxy API/WS vers :8000)
```

## Architecture

```
backend/inkflow/
  epub/parser.py        EPUB -> book.json + texte par chapitre
  analysis/gemma.py     wrapper mlx-lm (Gemma)
  analysis/segmenter.py narration/dialogue + locuteurs + casting
  analysis/pronunciation.py
  tts/base.py           interface TTSBackend + VoiceSpec
  tts/kokoro.py tts/qwen3.py tts/factory.py
  audio/postprocess.py  concat + normalisation + MP3 (ffmpeg) + cover
  pipeline/render.py     (segments + voix) -> MP3
  store/artifacts.py    persistance JSON (reprenable)
data/<slug>/            artefacts intermédiaires (json, wav, cover)
output/<livre>/         MP3 finaux (1 par chapitre)
voicebank/              clips de référence pour le clonage (M3)
```

## État d'avancement

- [x] **M1** — Parsing EPUB, analyse Gemma (segments + casting), CLI.
- [x] **M2** — TTS bout-en-bout (Kokoro/Qwen3), mono-narrateur → MP3 taggé + cover.
- [x] **M3** — Multi-voix : voice bank + auto-casting personnage → voix (clonage Qwen3).
- [x] **M4** — Interface web (FastAPI + WebSocket + React) : suivi, éditeurs casting/prononciation, previews.
- [x] **M5** — État reprenable (réconciliation avec les artefacts), run par lots via UI/CLI.

### Note sur les moteurs
- **Kokoro** : ~30 s/chapitre, voix distinctes par timbre (rendu rapide, brouillons).
- **Qwen3-TTS** : clonage des voix de la banque par personnage, qualité supérieure,
  nettement plus lent — réservé au rendu final. Tout rendu est **repris** chapitre
  par chapitre (relancer ne refait pas les MP3 déjà produits).