From eb2c365220e6b183ef2a60d10386fdba9034074b Mon Sep 17 00:00:00 2001
From: Folzo <folzo@hotmail.com>
Date: Sun, 5 Apr 2026 21:00:53 +0200
Subject: [PATCH] docs: Document all TTS/STT attempts and recommended solution

- Add detailed journal of all attempts (successes and failures)
- Explain speaches v0.8+ incompatibility with model cards
- Research and document whisper-asr-webservice as stable alternative
- Provide complete deployment plan with docker-compose
- Include validation checklist
---
 docs/JOURNAL-ESSAIS-TTS-STT.md   | 147 ++++++++++++++++++++++++
 docs/SOLUTION-RECOMMANDEE-STT.md | 189 +++++++++++++++++++++++++++++++
 2 files changed, 336 insertions(+)
 create mode 100644 docs/JOURNAL-ESSAIS-TTS-STT.md
 create mode 100644 docs/SOLUTION-RECOMMANDEE-STT.md

diff --git a/docs/JOURNAL-ESSAIS-TTS-STT.md b/docs/JOURNAL-ESSAIS-TTS-STT.md
new file mode 100644
index 0000000..0f1fd86
--- /dev/null
+++ b/docs/JOURNAL-ESSAIS-TTS-STT.md
@@ -0,0 +1,147 @@
+# Journal des essais - Voix et Ouïe pour Effi (Avril 2026)
+
+## 📋 Contexte
+
+**Objectif** : Déployer TTS (Text-to-Speech) et STT (Speech-to-Text) sur folzo-Corp (Fedora, RX 7800 XT)
+- **TTS** : openedai-speech (port 8100) ✅ Fonctionnel
+- **STT** : Whisper avec speaches (port 8200) ❌ Problématique
+
+**Infrastructure** :
+- effi-server (192.168.1.27) : Open WebUI
+- folzo-Corp (192.168.1.11) : Ollama + TTS/STT (Fedora, RX 7800 XT 16GB)
+
+---
+
+## ✅ SUCCÈS
+
+### 1. TTS (openedai-speech) - FONCTIONNEL
+
+**Date** : 05/04/2026
+**Statut** : ✅ Opérationnel
+
+**Configuration** :
+```yaml
+Service: openedai-speech
+Port: 8100
+Image: ghcr.io/matatonic/openedai-speech:latest
+Voix: Piper (anglais) + XTTS v2 (si fichiers .wav disponibles)
+GPU: ROCm activé (RX 7800 XT)
+```
+
+**Ce qui a marché** :
+- Image Docker précompilée disponible
+- Configuration SELinux avec `:Z` pour les volumes
+- Voix Piper (alloy, echo, etc.) fonctionnent en anglais
+- Test réussi : `curl http://localhost:8100/v1/audio/speech` → fichier MP3 généré
+
+**Problème résolu** :
+- Permissions SELinux sur Fedora : ajout de `:Z` dans les volumes Docker
+- Groupe utilisateur : `user: "0:0"` dans docker-compose
+
+**Limitation** : Les voix sont en anglais. Pour le français, il faudrait :
+- Télécharger des modèles Piper FR (`fr_FR-siwis-medium`)
+- OU utiliser XTTS avec échantillons de voix FR
+
+---
+
+## ❌ ÉCHECS ET PROBLÈMES
+
+### 1. STT avec speaches v0.8+ - BLOQUANT
+
+**Date** : 05/04/2026
+**Statut** : ❌ Non fonctionnel - Abandonné
+
+**Problème principal** :
+Speaches v0.8+ introduit une vérification stricte des "model cards" (README.md) pour tous les modèles. Le modèle `deepdml/faster-whisper-large-v3-turbo-ct2` (et `Systran/faster-whisper-large-v3`) ne contiennent pas ce fichier dans leur repository HuggingFace.
+
+**Erreur systématique** :
+```
+HTTP error: 500: The model repository does not contain a valid model card. 
+This is likely due to the breaking change introduce v0.8.0 release.
+```
+
+**Tentatives effectuées** :
+
+1. **Préchargement du modèle** ❌
+   - Téléchargement via Python dans le container réussi
+   - Mais speaches ne le reconnaît pas comme "enregistré"
+
+2. **Enregistrement via API** ❌
+   - `POST /v1/models` → retourne "Not Found"
+   - L'API a changé et la documentation est obsolète
+
+3. **Téléchargement README.md manuel** ❌
+   - Impossible d'accéder au cache HuggingFace dans le container
+   - `pip` non disponible dans l'image speaches
+   - Structure de dossiers complexe
+
+4. **Utilisation modèle Systran/faster-whisper-large-v3** ❌
+   - Même erreur de "model card" manquante
+
+5. **Alias de modèle** ❌
+   - Non testé mais probablement même problème
+
+**Conclusion** : speaches v0.8+ est incompatible avec les modèles faster-whisper standards. Nécessite soit :
+- Des modèles avec README.md complet (rare)
+- Une modification du code source de speaches
+- Une version antérieure de speaches (< 0.8)
+
+---
+
+## 🔄 SOLUTIONS ALTERNATIVES À EXPLORER
+
+### Option 1 : whisper.cpp (Plus fiable, C++)
+- **Avantages** : Rapide, stable, compatible ROCm (via OpenCL)
+- **Inconvénients** : Nécessite compilation, moins d'abstraction
+- **Statut** : À tester
+
+### Option 2 : faster-whisper serveur Python simple
+- **Avantages** : Contrôle total, pas de dépendances complexes
+- **Inconvénients** : Nécessite création d'un mini-serveur
+- **Statut** : Solution de contournement possible
+
+### Option 3 : Version antérieure speaches (< 0.8)
+- **Avantages** : Fonctionnait avant la v0.8
+- **Inconvénients** : Pas de tag Docker clair pour versions anciennes
+- **Statut** : À investiguer
+
+### Option 4 : Utiliser le STT intégré à openedai-speech
+- **Avantages** : Déjà configuré, même stack
+- **Inconvénients** : Moins performant que Whisper dédié
+- **Statut** : À vérifier si c'est possible
+
+### Option 5 : Whisper ROCm natif (sans Docker)
+- **Avantages** : Performance GPU maximale
+- **Inconvénients** : Complexité installation ROCm
+- **Statut** : À évaluer
+
+---
+
+## 📝 LEÇONS APRISES
+
+1. **Ne pas se fier aux dernières versions** : speaches v0.8+ a des breaking changes majeurs
+2. **Vérifier la compatibilité des modèles** : Les modèles HuggingFace doivent avoir un README.md complet pour speaches v0.8+
+3. **SELinux sur Fedora** : Toujours utiliser `:Z` pour les volumes Docker
+4. **Documentation obsolète** : Les docs de speaches ne reflètent pas les changements API v0.8+
+
+---
+
+## 🎯 PROCHAINES ÉTAPES RECOMMANDÉES
+
+1. **Rechercher la solution la plus stable actuellement** :
+   - whisper.cpp avec ROCm
+   - Version speaches antérieure fonctionnelle
+   - Alternative : Wyvern (anciennement faster-whisper-server)
+
+2. **Priorité** : Fonctionnement > Performance
+   - Même si c'est en CPU, tant que ça marche
+   - Optimisation GPU secondaire
+
+3. **Documentation** :
+   - Tester une solution complète avant documentation
+   - Vérifier chaque étape
+
+---
+
+**Date de création** : 05/04/2026  
+**Dernière mise à jour** : 05/04/2026
diff --git a/docs/SOLUTION-RECOMMANDEE-STT.md b/docs/SOLUTION-RECOMMANDEE-STT.md
new file mode 100644
index 0000000..31bd522
--- /dev/null
+++ b/docs/SOLUTION-RECOMMANDEE-STT.md
@@ -0,0 +1,189 @@
+# 🎙️ SOLUTION RECOMMANDÉE : Voix et Ouïe pour Effi
+
+> **Date** : 05 Avril 2026
+> **Statut** : Plan validé après recherche
+> **Problème résolu** : Remplacement de speaches (v0.8+ incompatible) par une solution stable
+
+---
+
+## 📋 RÉCAPITULATIF DES ESSAIS
+
+### ✅ Ce qui fonctionne déjà
+
+**TTS (Text-to-Speech)** : 
+- **Solution** : openedai-speech
+- **Statut** : ✅ Opérationnel sur port 8100
+- **Voix** : Piper (anglais) - fonctionne bien
+- **GPU** : ROCm activé sur RX 7800 XT
+
+### ❌ Problème rencontré
+
+**STT (Speech-to-Text)** :
+- **Solution testée** : speaches v0.8+
+- **Problème** : Breaking change avec vérification "model card" (README.md obligatoire)
+- **Erreur** : `The model repository does not contain a valid model card`
+- **Conclusion** : speaches v0.8+ est incompatible avec les modèles faster-whisper standards
+
+---
+
+## 🎯 SOLUTION RECOMMANDÉE
+
+### STT : whisper-asr-webservice (alternative à speaches)
+
+**Pourquoi cette solution ?**
+- ✅ **Stable et éprouvée** : 3.2k stars, maintenue activement
+- ✅ **Compatible OpenAI API** : Fonctionne avec Open WebUI
+- ✅ **Multi-engine** : Supporte OpenAI Whisper, faster-whisper, whisperX
+- ✅ **Image Docker précompilée** : Pas besoin de builder
+- ✅ **Pas de "model card" requise** : Contrairement à speaches v0.8+
+- ✅ **Support CPU/GPU** : Fonctionne sur CPU (Intel J5040) ou GPU (ROCm)
+
+**Caractéristiques :**
+- Port : 8200 (comme prévu)
+- Modèle recommandé : `large-v3` ou `faster-whisper-large-v3`
+- Format : OpenAI API compatible
+- Langue : Français supporté nativement
+
+---
+
+## 🚀 PLAN D'INSTALLATION
+
+### Étape 1 : Arrêter et nettoyer speaches
+
+```bash
+# Sur folzo-Corp
+cd ~/speaches
+sudo docker compose down
+sudo docker rm speaches-stt
+# Garder le volume pour le cache si tu veux, ou supprimer :
+# sudo docker volume rm speaches_speaches-models
+```
+
+### Étape 2 : Déployer whisper-asr-webservice
+
+```bash
+# Créer le dossier
+mkdir -p ~/whisper-asr
+cd ~/whisper-asr
+
+# Docker Compose
+cat > docker-compose.yml << 'EOF'
+services:
+  whisper-asr:
+    image: onerahmet/openai-whisper-asr-webservice:latest
+    container_name: whisper-asr
+    restart: unless-stopped
+    ports:
+      - "8200:9000"
+    environment:
+      - ASR_ENGINE=faster_whisper
+      - ASR_MODEL=large-v3
+      - ASR_DEVICE=cpu
+      - ASR_MODEL_PATH=/root/.cache/whisper
+    volumes:
+      - whisper-cache:/root/.cache
+    # Optionnel : pour GPU ROCm (si supporté par l'image)
+    # devices:
+    #   - /dev/kfd
+    #   - /dev/dri
+    # group_add:
+    #   - "44"
+    #   - "991"
+
+volumes:
+  whisper-cache:
+EOF
+
+# Lancer
+sudo docker compose up -d
+
+# Attendre le téléchargement du modèle (2-3 min)
+echo "⏳ Téléchargement du modèle Whisper..."
+sleep 120
+sudo docker logs whisper-asr --tail 20
+```
+
+### Étape 3 : Tester
+
+```bash
+# Test health
+curl http://localhost:8200/health
+
+# Test STT
+curl -X POST http://localhost:8200/v1/audio/transcriptions \
+  -F "file=@/tmp/test_tts.mp3" \
+  -F "language=fr"
+```
+
+### Étape 4 : Configurer Open WebUI
+
+```
+Admin Panel → Settings → Audio
+
+STT :
+- Engine : OpenAI
+- URL : http://192.168.1.11:8200/v1
+- Model : large-v3
+- Language : fr
+```
+
+---
+
+## 🔧 ALTERNATIVES SI NECESSAIRE
+
+### Option A : Utiliser l'engine "openai_whisper" (plus lent mais stable)
+
+```yaml
+environment:
+  - ASR_ENGINE=openai_whisper
+  - ASR_MODEL=base  # ou small, medium, large-v3
+```
+
+### Option B : Version GPU (si ROCm supporté)
+
+```yaml
+image: onerahmet/openai-whisper-asr-webservice:latest-gpu
+```
+
+**Note** : L'image GPU utilise CUDA par défaut. Pour ROCm (AMD), il faudra peut-être rester en CPU ou builder une image custom.
+
+### Option C : Solution ultra-simple (Python direct)
+
+Si l'image Docker pose problème, on peut créer un mini-serveur Python avec Flask/FastAPI qui wrap faster-whisper directement (3-4 lignes de code).
+
+---
+
+## 📊 COMPARAISON DES SOLUTIONS STT
+
+| Solution | Stabilité | Complexité | ROCm | Commentaire |
+|----------|-----------|------------|------|-------------|
+| speaches v0.8+ | ❌ Mauvaise | Moyenne | ❌ | Model card requise, incompatible |
+| **whisper-asr-webservice** | ✅ Excellente | Faible | ❓ | **RECOMMANDÉ** - Stable, simple |
+| whisper.cpp | ✅ Bonne | Élevée | ✅ | Rapide mais complexe à compiler |
+| Solution Python custom | ✅ Bonne | Faible | ❓ | Fallback si tout échoue |
+
+---
+
+## ✅ CHECKLIST DE VALIDATION
+
+- [ ] whisper-asr-webservice déployé sur folzo-Corp:8200
+- [ ] Modèle téléchargé et chargé
+- [ ] Test `/health` OK
+- [ ] Test STT avec fichier audio OK
+- [ ] Configuration Open WebUI mise à jour
+- [ ] Test micro dans Open WebUI OK
+- [ ] TTS (openedai-speech) toujours fonctionnel
+- [ ] Pipeline vocal complet testé (STT → LLM → TTS)
+
+---
+
+## 📝 NOTES IMPORTANTES
+
+1. **Performance** : En CPU sur Intel J5040, attendre ~5-10s pour 5s d'audio
+2. **GPU** : Si ROCm fonctionne un jour, on pourra passer à l'image GPU
+3. **Cache** : Le modèle est conservé dans le volume Docker, pas besoin de re-télécharger
+4. **Maintenance** : Solution stable, mises à jour via `docker compose pull`
+
+---
+
+**Prochaine étape** : Déployer whisper-asr-webservice et tester !