# Service ASR Skull Pi

Service de reconnaissance vocale automatique (ASR) en français utilisant Vosk pour le projet Skull Pi.

## Vue d'ensemble

Le service ASR écoute les événements VAD (Voice Activity Detection) via MQTT, capture l'audio du microphone, effectue la reconnaissance vocale en français avec Vosk, et publie le texte transcrit.

### Fonctionnalités

- ✅ Reconnaissance vocale française avec Vosk
- ✅ Déclenchement par VAD (Voice Activity Detection)
- ✅ Configuration dynamique via MQTT
- ✅ Publication des résultats en temps réel
- ✅ Gestion robuste des erreurs
- ✅ Optimisé pour Raspberry Pi Zero 2 W

## Architecture

```
[Microphone] → [AudioCapture] → [VoskEngine] → [MQTT Publisher]
     ↑              ↑              ↑              ↑
[VAD Events] ← [MQTT Subscriber] ← [ASRService] ← [Config]
```

## Installation

### 1. Prérequis système

```bash
# Dépendances audio pour Raspberry Pi
sudo apt-get update
sudo apt-get install -y \
    portaudio19-dev \
    python3-pyaudio \
    alsa-utils \
    pulseaudio

# Test du micro
arecord -l
```

### 2. Modèle Vosk français

Télécharger le modèle compact français :

```bash
# Créer le dossier des modèles
sudo mkdir -p /opt/Skull/models
cd /opt/Skull/models

# Télécharger le modèle (≈70MB)
sudo wget https://alphacephei.com/vosk/models/vosk-model-fr-0.22-lgraph.zip
sudo unzip vosk-model-fr-0.22-lgraph.zip
sudo rm vosk-model-fr-0.22-lgraph.zip

# Vérifier
ls -la vosk-model-fr-0.22-lgraph/
```

### 3. Installation Python

```bash
cd /opt/Skull/apps/asr
pip install -r requirements.txt
```

### 4. Service systemd

```bash
# Copier les fichiers
sudo cp systemd/skull-asr.service /etc/systemd/system/
sudo cp bin/skull-asr.sh /opt/Skull/bin/
sudo chmod +x /opt/Skull/bin/skull-asr.sh

# Activer le service
sudo systemctl daemon-reload
sudo systemctl enable skull-asr
sudo systemctl start skull-asr
```

## Configuration

### Topics MQTT

#### Entrées (souscription)

- `audio/vad` : Événements VAD

  ```json
  {
    "active": true,
    "end_of_speech": false,
    "confidence": 0.85
  }
  ```

- `asr/config` : Configuration dynamique
  ```json
  {
    "lang": "fr",
    "eos_ms": 800,
    "vad": {
      "threshold": 0.5
    }
  }
  ```

#### Sorties (publication)

- `asr/text` : Texte transcrit

  ```json
  {
    "ts_ms": 1699123456789,
    "text": "bonjour skull"
  }
  ```

- `asr/capabilities` : Capacités (retained)
  ```json
  {
    "engine": "vosk",
    "lang": "fr",
    "sample_rate": 16000
  }
  ```

## Utilisation

### Démarrage manuel

```bash
# Mode développement
cd /opt/Skull/apps
python -m asr.main

# Avec le wrapper
/opt/Skull/bin/skull-asr.sh
```

### Test rapide

Terminal 1 - Écouter les messages :

```bash
mosquitto_sub -t 'asr/#' -v
```

Terminal 2 - Simuler VAD et parole :

```bash
# Activer VAD
mosquitto_pub -t audio/vad -m '{"active": true}'

# (Parler dans le micro : "Bonjour Skull")

# Déclencher fin de phrase
mosquitto_pub -t audio/vad -m '{"end_of_speech": true}'
```

Résultat attendu :

```
asr/capabilities {"engine":"vosk","lang":"fr","sample_rate":16000}
asr/text {"ts_ms":1699123456789,"text":"bonjour skull"}
```

### Configuration à chaud

```bash
# Changer le timeout EOS
mosquitto_pub -t asr/config -m '{"eos_ms": 1500}'

# Changer la langue (redémarre le moteur)
mosquitto_pub -t asr/config -m '{"lang": "en"}'
```

## Tests

### Tests unitaires

```bash
# Tous les tests
pytest

# Tests spécifiques
pytest tests/test_asr_service.py -v
pytest tests/test_vosk_engine.py -v

# Avec couverture
pytest --cov=asr --cov-report=html
```

### Tests d'intégration

```bash
# Test complet avec mocks
pytest tests/test_integration.py -v

# Test avec vrai modèle Vosk (si disponible)
VOSK_TEST_REAL=1 pytest tests/test_integration.py::test_real_vosk -v
```

### Validation du code

```bash
# Linting
ruff check asr/
ruff check tests/

# Type checking
mypy asr/

# Formatage
black asr/ tests/
```

## Dépannage

### Problèmes courants

**Module vosk introuvable :**

```bash
pip install vosk==0.3.45
```

**PyAudio ne fonctionne pas :**

```bash
sudo apt-get install portaudio19-dev
pip install --upgrade pyaudio
```

**Aucun périphérique audio :**

```bash
# Lister les périphériques
arecord -l
cat /proc/asound/cards

# Test d'enregistrement
arecord -D plughw:0 -f S16_LE -r 16000 test.wav
```

**Service ne démarre pas :**

```bash
# Vérifier les logs
journalctl -u skull-asr -f

# Test manuel
/opt/Skull/bin/skull-asr.sh test
```

### Logs

```bash
# Logs du service
tail -f /opt/Skull/logs/asr.log

# Logs systemd
journalctl -u skull-asr -f

# Debug complet
SKULL_LOG_LEVEL=DEBUG systemctl restart skull-asr
```

## Performance

### Métriques typiques (Pi Zero 2 W)

- **Latence transcription** : 500-800ms après EOS
- **Charge CPU** : 15-25% en écoute, 40-60% en transcription
- **Mémoire** : ~150MB (modèle + processus)
- **Précision** : ~90% phrases simples français

### Optimisations

```python
# Configuration optimisée Pi Zero
{
  "eos_ms": 600,        # Plus réactif
  "vad": {
    "threshold": 0.6    # Moins sensible au bruit
  }
}
```

## Architecture des fichiers

```
asr/
├── __init__.py           # Module principal
├── main.py              # Point d'entrée
├── service.py           # Service principal ASR
├── vosk_engine.py       # Moteur Vosk
├── audio_capture.py     # Capture audio
└── config.py            # Configuration

tests/
├── conftest.py          # Configuration pytest
├── test_asr_service.py  # Tests service
├── test_vosk_engine.py  # Tests Vosk
├── test_audio_capture.py # Tests audio
└── test_integration.py  # Tests d'intégration

systemd/
└── skull-asr.service    # Service systemd

bin/
└── skull-asr.sh         # Wrapper de démarrage
```

## Développement

### Environnement de dev

```bash
# Installer les dépendances de dev
pip install -e .[dev]

# Pre-commit hooks
pre-commit install

# Tests en continu
pytest-watch
```

### Ajout de langues

1. Télécharger le modèle Vosk pour la langue
2. Mettre à jour `MODEL_MAPPING` dans `vosk_engine.py`
3. Ajouter les tests correspondants

### Debugging

```bash
# Mode debug avec breakpoints
PYTHONBREAKPOINT=pdb.set_trace python -m asr.main

# Profiling performance
python -m cProfile -o profile.out -m asr.main
```

## Contributions

1. Fork le projet
2. Créer une branche feature
3. Tests et validation : `ruff check && mypy && pytest`
4. Commit avec message conventionnel
5. Pull Request

## Licence

Projet Skull Pi - Usage interne