Initial commit: InkFlow — EPUB vers livre audio local (MLX/Kokoro)

README.md

@@ -0,0 +1,105 @@
+# 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).