# Speech-to-Text (STT) Setup Guide - Windows

Guide pour configurer les moteurs de reconnaissance vocale STT sur Windows.

## État Actuel

AISSIA supporte **5 moteurs STT** avec priorités automatiques :

| Moteur | Type | Status | Requis |
|--------|------|--------|--------|
| **Whisper.cpp** | Local | ✅ Configuré | Modèle téléchargé |
| **OpenAI Whisper API** | Cloud | ✅ Configuré | API key dans .env |
| **Google Speech** | Cloud | ✅ Configuré | API key dans .env |
| **Azure STT** | Cloud | ⚠️ Optionnel | API key manquante |
| **Deepgram** | Cloud | ⚠️ Optionnel | API key manquante |

**3 moteurs sont déjà fonctionnels** (Whisper.cpp, OpenAI, Google) ✅

---

## 1. Whisper.cpp (Local, Offline) ✅

### Avantages
- ✅ Complètement offline (pas d'internet requis)
- ✅ Excellente précision (qualité OpenAI Whisper)
- ✅ Gratuit, pas de limite d'utilisation
- ✅ Support multilingue (99 langues)
- ❌ Plus lent que les APIs cloud (temps réel difficile)

### Installation

**Modèle téléchargé** : `models/ggml-base.bin` (142MB)

Autres modèles disponibles :
```bash
cd models/

# Tiny (75MB) - Rapide mais moins précis
curl -L -o ggml-tiny.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin

# Small (466MB) - Bon compromis
curl -L -o ggml-small.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin

# Medium (1.5GB) - Très bonne qualité
curl -L -o ggml-medium.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin

# Large (2.9GB) - Meilleure qualité
curl -L -o ggml-large-v3.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
```

**Recommandé** : `base` ou `small` pour la plupart des usages.

---

## 2. OpenAI Whisper API ✅

### Avantages
- ✅ Très rapide (temps réel)
- ✅ Excellente précision
- ✅ Support multilingue
- ❌ Requiert internet
- ❌ Coût : $0.006/minute ($0.36/heure)

### Configuration

1. Obtenir une clé API OpenAI : https://platform.openai.com/api-keys
2. Ajouter à `.env` :
```bash
OPENAI_API_KEY=sk-proj-...
```

**Status** : ✅ Déjà configuré

---

## 3. Google Speech-to-Text ✅

### Avantages
- ✅ Très rapide
- ✅ Bonne précision
- ✅ Support multilingue (125+ langues)
- ❌ Requiert internet
- ❌ Coût : $0.006/15s ($1.44/heure)

### Configuration

1. Activer l'API : https://console.cloud.google.com/apis/library/speech.googleapis.com
2. Créer une clé API
3. Ajouter à `.env` :
```bash
GOOGLE_API_KEY=AIzaSy...
```

**Status** : ✅ Déjà configuré

---

## 4. Azure Speech-to-Text (Optionnel)

### Avantages
- ✅ Excellente précision
- ✅ Support multilingue
- ✅ Free tier : 5h/mois gratuit
- ❌ Requiert internet

### Configuration

1. Créer une ressource Azure Speech : https://portal.azure.com
2. Copier la clé et la région
3. Ajouter à `.env` :
```bash
AZURE_SPEECH_KEY=votre_cle_azure
AZURE_SPEECH_REGION=westeurope  # ou votre région
```

**Status** : ⚠️ Optionnel (non configuré)

---

## 5. Deepgram (Optionnel)

### Avantages
- ✅ Très rapide (streaming temps réel)
- ✅ Bonne précision
- ✅ Free tier : $200 crédit / 45,000 minutes
- ❌ Requiert internet

### Configuration

1. Créer un compte : https://console.deepgram.com
2. Créer une API key
3. Ajouter à `.env` :
```bash
DEEPGRAM_API_KEY=votre_cle_deepgram
```

**Status** : ⚠️ Optionnel (non configuré)

---

## Tester les Moteurs STT

### Option 1 : Test avec fichier audio

1. Générer un fichier audio de test :
```bash
python create_test_audio_simple.py
```

2. Lancer le test (quand compilé) :
```bash
./build/test_stt_live test_audio.wav
```

Ceci testera automatiquement tous les moteurs disponibles.

### Option 2 : Test depuis AISSIA

Les moteurs STT sont intégrés dans `VoiceModule` et accessibles via :
- `voice:start_listening` (pub/sub)
- `voice:stop_listening`
- `voice:transcribe` (avec fichier audio)

---

## Configuration Recommandée

Pour un usage optimal, voici l'ordre de priorité recommandé :

### Pour développement/tests locaux
1. **Whisper.cpp** (`ggml-base.bin`) - Offline, gratuit
2. **OpenAI Whisper API** - Si internet disponible
3. **Google Speech** - Fallback

### Pour production/temps réel
1. **Deepgram** - Meilleur streaming temps réel
2. **Azure STT** - Bonne qualité, free tier
3. **Whisper.cpp** (`ggml-small.bin`) - Offline fallback

---

## Fichiers de Configuration

### .env (API Keys)
```bash
# OpenAI Whisper API (✅ configuré)
OPENAI_API_KEY=sk-proj-...

# Google Speech (✅ configuré)
GOOGLE_API_KEY=AIzaSy...

# Azure STT (optionnel)
#AZURE_SPEECH_KEY=votre_cle
#AZURE_SPEECH_REGION=westeurope

# Deepgram (optionnel)
#DEEPGRAM_API_KEY=votre_cle
```

### config/voice.json
```json
{
    "stt": {
        "active_mode": {
            "enabled": true,
            "engine": "whisper_cpp",
            "model_path": "./models/ggml-base.bin",
            "language": "fr",
            "fallback_engine": "whisper_api"
        }
    }
}
```

---

## Dépendances

### Whisper.cpp
- ✅ Intégré dans le build (external/whisper.cpp)
- ✅ Lié statiquement à AissiaAudio
- ❌ Modèle requis : téléchargé dans `models/`

### APIs Cloud
- ✅ Httplib pour requêtes HTTP (déjà dans le projet)
- ✅ nlohmann/json pour sérialisation (déjà dans le projet)
- ❌ OpenSSL désactivé (HTTP-only mode OK)

---

## Troubleshooting

### "Whisper model not found"
```bash
cd models/
curl -L -o ggml-base.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin
```

### "API key not found"
Vérifier que `.env` contient les clés et est chargé :
```bash
cat .env | grep -E "OPENAI|GOOGLE|AZURE|DEEPGRAM"
```

### "Transcription failed"
1. Vérifier le format audio : 16kHz, mono, 16-bit PCM WAV
2. Générer un test : `python create_test_audio_simple.py`
3. Activer les logs : `spdlog::set_level(spdlog::level::debug)`

---

## Prochaines Étapes

1. ✅ Whisper.cpp configuré et fonctionnel
2. ✅ OpenAI + Google APIs configurées
3. ⚠️ Optionnel : Ajouter Azure ou Deepgram pour redondance
4. 🔜 Tester avec `./build/test_stt_live test_audio.wav`
5. 🔜 Intégrer dans VoiceModule via pub/sub

---

## Références

- [Whisper.cpp GitHub](https://github.com/ggerganov/whisper.cpp)
- [OpenAI Whisper API](https://platform.openai.com/docs/guides/speech-to-text)
- [Google Speech-to-Text](https://cloud.google.com/speech-to-text)
- [Azure Speech](https://azure.microsoft.com/en-us/services/cognitive-services/speech-to-text/)
- [Deepgram](https://developers.deepgram.com/)