aissia/docs/STT_CONFIGURATION.md

Configuration STT - Speech-to-Text

AISSIA supporte 4 engines STT différents, configurables via config/voice.json.

Engines Disponibles

1. PocketSphinx - Keyword Spotting Léger

• Usage : Détection de mots-clés (mode passif)
• Taille : ~10 MB
• Performance : Très économe (CPU/RAM)
• Précision : Moyenne (bon pour wake words)
• Installation : sudo apt install pocketsphinx libpocketsphinx-dev
• Modèle : /usr/share/pocketsphinx/model/en-us

Config :

{
    "stt": {
        "passive_mode": {
            "enabled": true,
            "engine": "pocketsphinx",
            "keywords": ["celuna", "hey celuna", "ok celuna"],
            "threshold": 0.8,
            "model_path": "/usr/share/pocketsphinx/model/en-us"
        }
    }
}

2. Vosk - STT Local Équilibré

• Usage : Transcription complète locale
• Taille : 50 MB (small), 1.8 GB (large)
• Performance : Rapide, usage modéré
• Précision : Bonne
• Installation : Télécharger modèle depuis alphacephei.com/vosk/models
• Modèle : ./models/vosk-model-small-fr-0.22

Config :

{
    "stt": {
        "active_mode": {
            "enabled": true,
            "engine": "vosk",
            "model_path": "./models/vosk-model-small-fr-0.22",
            "language": "fr"
        }
    }
}

3. Whisper.cpp - STT Local Haute Qualité

• Usage : Transcription de haute qualité offline
• Taille : 75 MB (tiny) à 2.9 GB (large)
• Performance : Plus lourd, très précis
• Précision : Excellente
• Installation : Compiler whisper.cpp et télécharger modèles GGML
• Modèle : ./models/ggml-base.bin

Config :

{
    "stt": {
        "active_mode": {
            "enabled": true,
            "engine": "whisper-cpp",
            "model_path": "./models/ggml-base.bin",
            "language": "fr"
        }
    }
}

4. Whisper API - STT Cloud OpenAI

• Usage : Transcription via API OpenAI
• Taille : N/A (cloud)
• Performance : Dépend de latence réseau
• Précision : Excellente
• Installation : Aucune (API key requise)
• Coût : $0.006 / minute

Config :

{
    "stt": {
        "active_mode": {
            "enabled": true,
            "engine": "whisper-api",
            "fallback_engine": "whisper-api"
        },
        "whisper_api": {
            "api_key_env": "OPENAI_API_KEY",
            "model": "whisper-1"
        }
    }
}

Configuration Complète

Dual Mode (Passive + Active)

{
    "tts": {
        "enabled": true,
        "engine": "auto",
        "rate": 0,
        "volume": 80,
        "voice": "fr-fr"
    },
    "stt": {
        "passive_mode": {
            "enabled": true,
            "engine": "pocketsphinx",
            "keywords": ["celuna", "hey celuna", "ok celuna"],
            "threshold": 0.8,
            "model_path": "/usr/share/pocketsphinx/model/en-us"
        },
        "active_mode": {
            "enabled": true,
            "engine": "vosk",
            "model_path": "./models/vosk-model-small-fr-0.22",
            "language": "fr",
            "timeout_seconds": 30,
            "fallback_engine": "whisper-api"
        },
        "whisper_api": {
            "api_key_env": "OPENAI_API_KEY",
            "model": "whisper-1"
        },
        "microphone": {
            "device_id": -1,
            "sample_rate": 16000,
            "channels": 1,
            "buffer_size": 1024
        }
    }
}

Mode Auto

Utilise "engine": "auto" pour sélection automatique :

1. Essaie Vosk si modèle disponible
2. Essaie Whisper.cpp si modèle disponible
3. Fallback sur Whisper API si clé API présente
4. Sinon utilise Stub (mode désactivé)

{
    "stt": {
        "active_mode": {
            "engine": "auto",
            "model_path": "./models/vosk-model-small-fr-0.22",
            "language": "fr"
        }
    }
}

Comparaison des Engines

Engine	Taille	CPU	RAM	Latence	Précision	Usage Recommandé
PocketSphinx	10 MB	Faible	Faible	Très rapide	Moyenne	Wake words, keywords
Vosk	50 MB+	Moyen	Moyen	Rapide	Bonne	Transcription générale
Whisper.cpp	75 MB+	Élevé	Élevé	Moyen	Excellente	Haute qualité offline
Whisper API	0 MB	Nul	Nul	Variable	Excellente	Simplicité, cloud

Workflow Recommandé

Scénario 1 : Assistant Vocal Local

Mode Passif (PocketSphinx) → Détecte "hey celuna"
    ↓
Mode Actif (Vosk) → Transcrit la commande
    ↓
Traite la commande

Scénario 2 : Haute Qualité avec Fallback

Essaie Vosk (local, rapide)
    ↓ (si échec)
Essaie Whisper.cpp (local, précis)
    ↓ (si échec)
Fallback Whisper API (cloud)

Scénario 3 : Cloud-First

Whisper API directement (simplicité, pas de setup local)

Installation des Dépendances

Ubuntu/Debian

# PocketSphinx
sudo apt install pocketsphinx libpocketsphinx-dev

# Vosk
# Télécharger depuis https://alphacephei.com/vosk/models
mkdir -p models
cd models
wget https://alphacephei.com/vosk/models/vosk-model-small-fr-0.22.zip
unzip vosk-model-small-fr-0.22.zip

# Whisper.cpp
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp
make
# Télécharger modèles GGML
bash ./models/download-ggml-model.sh base

Variables d'Environnement

Configurez dans .env :

# Whisper API (OpenAI)
OPENAI_API_KEY=sk-...

# Optionnel : Chemins personnalisés
STT_MODEL_PATH=/path/to/models

Troubleshooting

PocketSphinx ne fonctionne pas

# Vérifier installation
dpkg -l | grep pocketsphinx

# Vérifier modèle
ls /usr/share/pocketsphinx/model/en-us

Vosk ne détecte rien

# Vérifier que libvosk.so est installée
ldconfig -p | grep vosk

# Télécharger le bon modèle pour votre langue

Whisper.cpp erreur

# Recompiler avec support GGML
cd whisper.cpp && make clean && make

# Vérifier format du modèle (doit être .bin)
file models/ggml-base.bin

Whisper API timeout

# Vérifier clé API
echo $OPENAI_API_KEY

# Tester l'API manuellement
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"