DOCS/voice-latency-plan.md

Assistant vocal — latence, accusés de réception et langues

Créé le 2026-08-13. Point d'entrée unique pour le finetuning de l'expérience vocale (mymuseum-visitapp, mode lunettes et mode téléphone). Découpé en trois horizons : ce qui se fait maintenant, ce qui se décide après les tests de terrain, et ce qui est V2.

⚠️ Ce document ne remet pas en cause la priorité du plan V1. Tout ce qui est ici est du finetuning : le flux vocal complet doit d'abord être testé et validé de bout en bout. Le bloc « maintenant » est inclus parce qu'il rend les tests eux-mêmes plus honnêtes — pas parce qu'il est urgent.

---

0. L'idée de départ, et pourquoi elle est repoussée

Remplacer le bip de détection du wake word (assets/sounds/wake_detected.mp3) par une phrase parlée dans la langue et la voix du visiteur — « Oui, je vous écoute » — avec 2 ou 3 variantes pour éviter la répétition mécanique sur une visite entière.

L'idée est bonne et elle est retenue — mais pas maintenant, et la raison est chiffrable : elle demande de générer, écouter et valider à la main de l'ordre de 40 fichiers audio (2 voix × 4 langues × 5 phrases). Produire ce lot avant d'avoir vécu le flux réel avec Viva et Marco, c'est décider à l'aveugle. Et surtout : une partie du problème que l'ack parlé compense — l'attente — se règle en amont, par la latence. Si le §1 fait son travail, l'ack parlé redevient un raffinement plutôt qu'un pansement.

---

1. Maintenant — avant les tests, sans produire un seul fichier audio

Six chantiers, tous contenus dans mymuseum-visitapp, aucun nouvel asset.

✅ Livré le 2026-08-13 : 1.1, 1.2, 1.4, 1.5, 1.6. flutter analyze lib/Services/Glasses/ → 0 erreur (5 issues restantes, toutes préexistantes et hors de ces changements). Le matching des commandes est couvert par 16 cas de test joués en vrai (dart run), 16/16. ⏸️ 1.3 (découpage du TTS par phrase) volontairement non fait — c'est le seul chantier structurant du lot, il mérite un feu vert séparé.

1.1 Le son « done » bloque la réponse

voice_orchestrator.dart:212 fait await _playDoneSound() juste avant ttsEngine.speak(). Or _playSound attend _soundPlayer.play(), dont le future ne se résout qu'à la fin de la lecture. Ce son retarde donc la réponse de toute sa durée, et fait doublon avec la voix qui démarre immédiatement après : la parole est le signal de fin.

✅ Fait. L'appel est retiré. _playDoneSound, la constante _doneSound et l'asset ne sont plus référencés nulle part : le helper et la constante sont supprimés plutôt que conservés « au cas où », il n'existe aujourd'hui aucun chemin de réponse sans TTS. assets/sounds/done.mp3 reste sur disque, à supprimer si rien ne le reprend.

1.2 Les assets se décodent à chaud

_playSound appelle setAsset à chaque déclenchement — décodage à chaque wake word, sur le chemin le plus sensible à la latence qui soit.

✅ Fait. _preloadSounds() appelé une fois depuis start(), les deux players restent chargés et _playWakeSound se contente d'un seek(0) + play(). Un drapeau _soundsReady rend le pipeline silencieux — et non plantant — si les assets manquent.

⚠️ play() n'est jamais awaité sur ces sons, et c'est délibéré : dans just_audio, le future de play() ne se résout qu'à la fin de la lecture. C'est exactement le piège du §1.1.

1.3 Découpage du TTS par phrase — le vrai gain

C'est le chantier structurant, et le seul qui change l'ordre de grandeur.

Aujourd'hui la chaîne est bloquante de bout en bout :

• LlmClient.chat() retourne un Future<({String reply, bool expectsReply})> — réponse complète, pas de flux. Avec les tool calls (GetSectionDetail, RAG), c'est plusieurs secondes.
• GeminiTtsEngine._synthesize() fait un generateContent unaire, récupère tout le PCM base64, écrit un WAV sur disque, puis lit.

Donc time-to-first-audio = LLM complet + TTS complet. C'est ce trou que le son de réflexion bouche aujourd'hui.

À faire : découper result.reply en phrases, synthétiser la première, la jouer, et synthétiser les suivantes en tâche de fond pendant la lecture. Le time-to-first-audio tombe à LLM + TTS(1 phrase). Contenu dans GeminiTtsEngine, ne touche ni l'orchestrateur ni le backend.

⚠️ Non vérifié : :streamGenerateContent émet-il des chunks audio progressifs sur gemini-2.5-flash-preview-tts ? Si oui, ce chantier devient encore meilleur. C'est un test curl de 20 minutes — à faire, pas à supposer.

1.4 Les commandes ne sont reconnues qu'en français

_isStopCommand, _isRepeatCommand, _isQrScanCommand, _isPhotoCommand (voice_orchestrator.dart:375-397) cherchent des mots français en dur : « répète », « arrête », « prends », « regarde ».

Ce n'est pas un manque de langues, c'est un manque dans les langues déjà annoncées. Un visiteur néerlandophone qui dit « herhaal » n'est pas compris. Tester un flux multilingue avec ces listes, c'est tester autre chose que ce qu'on croit.

⛔ Et un faux positif franc : _isQrScanCommand matche sur code. Un anglophone qui demande « what's the code of this painting » déclenche un scan QR au lieu d'une réponse.

✅ Fait. Quatre listes static const couvrant FR/NL/EN/DE, et surtout un changement de méthode de matching : _matchesAny compare sur mot entier ((^|\W)phrase($|\W)) au lieu de contains.

Ce changement de méthode a révélé deux faux positifs qui vivaient déjà là :

• ⛔ contains('prends') reconnaissait « je ne comprends pas » comme une demande de photo ;
• ⛔ contains('encore') reconnaissait « raconte encore une histoire » comme « répète », ce qui rejouait la réponse précédente au lieu d'en produire une nouvelle. encore nu est retiré au profit d'encore une fois. Arbitrage assumé : « encore ? » tout court ne déclenche plus de replay et part au LLM, qui s'en sort. À rouvrir si les tests montrent que le mot seul est fréquent.

Et le match nu sur code est supprimé — « what's the code of this painting » ne déclenche plus de scan QR.

Vérifié, pas supposé : 16 cas joués via dart run (11 doivent matcher dans les 4 langues, 5 ne doivent pas). 16/16.

1.5 Escalade du son de réflexion

Le drone continu (thinking.mp3 en LoopMode.one) joue même quand la réponse arrive vite — il devient alors du bruit pur.

À faire, sans nouvel asset, uniquement du timing sur le fichier existant :

Délai	Comportement
0 → 700 ms	silence — le visiteur vient de parler, il n'attend pas encore
700 ms → 3,5 s	nappe en fade-in, plus discrète qu'aujourd'hui
> 3,5 s	(après les tests) filler parlé, cf. §2

✅ Fait pour les deux premiers paliers. _thinkingDelay = 700ms, fondu d'entrée en 6 pas de 100 ms jusqu'à _thinkingVolume = 0.45 (soit ~7 dB sous le niveau précédent). Un drapeau _thinkingWanted interrompt le fondu si la réponse arrive pendant la montée.

⚠️ Corrigé au passage : stop() n'appelait pas _stopThinkingLoop(). Le timer de 700 ms pouvait donc se déclencher après l'arrêt de l'orchestrateur et jouer une nappe alors que plus rien n'était en cours.

1.6 Acter la limite à 4 langues

_toLangCode (voice_orchestrator.dart:399-407) ne mappe que FR/NL/EN/DE et renvoie fr-FR par défaut, alors que constants.dart:59-70 déclare 10 langues. Un visiteur en IT ou ES se fait déjà répondre en français aujourd'hui, silencieusement.

Décidé le 2026-08-13 : l'assistant vocal est officiellement à 4 langues — FR, NL, EN, DE. À refléter dans le CMS et la doc commerciale. Le reste de l'app garde ses 10 langues, seul le canal vocal est restreint.

Le coût d'en ajouter une plus tard est faible, et c'est vérifié :

• les traductions voice.* existent déjà pour les 10 langues dans translations.dart ;
• Whisper prend le code générique (fr-FR → fr) et est multilingue ;
• Gemini TTS couvre largement IT/ES/PL ;
• le wake word est phonétique, indépendant de la langue parlée ensuite.

Reste donc, par langue ajoutée : une entrée dans _toLangCode, les listes de mots-clés du §1.4, et une vérification du prompt côté backend. Pas de chantier caché.

✅ Fait côté code : _toLangCode porte désormais le commentaire qui dit la limite et ce qu'ajouter une langue implique — les deux endroits, pas seulement le mapping. La décision est répercutée dans v1-plan.md §5 et STATUS.md §5bis. Reste à faire hors code : la refléter dans le CMS et la doc commerciale.

---

2. Après les tests — décisions qui demandent d'avoir entendu le flux

Rien ici ne se tranche sur intuition. Toutes ces décisions supposent d'avoir vécu une visite complète avec Viva et avec Marco, sur lunettes et sur téléphone.

a. Ack parlé ou earcon ? Et si parlé, combien de variantes. Le point de comparaison n'existe qu'après avoir mesuré la latence post-§1.3.

b. Génération du lot audio — uniquement si (a) est positif. Arborescence : assets/sounds/ack/{viva|marco}/{fr,nl,en,de}/ack_{1..3}.mp3, plus filler_{1,2}. ~40 fichiers, ~1,5 Mo.

Deux pièges à ne pas redécouvrir :

• ⚠️ pubspec.yaml:133 déclare assets/sounds/ — les déclarations de dossier ne sont pas récursives en Flutter. Chaque sous-dossier devra être listé.
• ⚠️ Générer avec exactement le même voicePrompt que le runtime (kGeminiTtsPrompt), sinon le timbre et la prosodie décrochent entre l'ack et la réponse. Gemini TTS n'est pas déterministe : prévoir plusieurs prises et un choix à l'oreille. Via un script tool/generate_voice_assets.dart, joué une fois, résultat commité.

c. Ordonnancement ack → écoute. Aujourd'hui : bip non awaité + Future.delayed(200ms). Avec un ack parlé d'environ 800 ms, ouvrir le micro pendant la lecture ferait transcrire la voix de l'assistant par Whisper — sur Ray-Ban, micro et haut-parleur partagent la monture, le couplage est fort. Plutôt que de faire de l'AEC : démarrer le STT à player.duration - 150ms, calibré à l'oreille sur le terrain. Budget avant écoute : ~400 ms → ~700 ms, acceptable parce que pendant ces 700 ms le visiteur sait qu'il a été entendu.

d. Filler parlé au-delà de 3,5 s. Probablement inutile si §1.3 fait son travail — à décider sur mesure.

e. Règle de cohérence, non négociable. Si GEMINI_API_KEY est absente, le moteur retombe sur FlutterTtsEngine (voix système). Des acks pré-générés en Sulafat suivis d'une réponse en voix Android seraient pires que le bip. Les acks vocaux ne s'activent que si le moteur runtime est Gemini et que la voix de l'asset correspond à guideVoiceId. Sinon, earcon.

---

3. V2

3.1 Streaming LLM

C'est là qu'est le gros de la latence restante, une fois §1.3 livré. Implique du SSE côté manager-service et un changement de signature de LlmClient. Combiné au découpage par phrase, l'assistant parle dès la première phrase générée.

3.2 Live API Gemini — audio natif bidirectionnel

Ce que c'est. Aujourd'hui : trois maillons distincts (Whisper → LLM → Gemini TTS), trois allers-retours, et deux conversions qui perdent l'intonation et l'hésitation du visiteur. Le Live API les supprime : une connexion WebSocket permanente où l'on pousse le flux micro brut (PCM 16 kHz) et reçoit du flux audio de réponse (PCM 24 kHz), sans jamais passer par du texte.

Trois choses que l'architecture actuelle ne peut structurellement pas faire :

• le barge-in — le visiteur coupe la parole à l'assistant, qui s'arrête net ;
• la détection de fin de phrase côté serveur (VAD) — fin du timeout: 5 secondes en dur de _listenForFollowUp ;
• une latence conversationnelle de l'ordre de la seconde.

Les voix prébuilt sont de la même famille que celles utilisées aujourd'hui : Viva/Marco pourraient survivre à la bascule.

Comment on l'intégrerait. Le point dur n'est pas l'audio, c'est le tool calling. MyInfoMateLlmClient parle à manager-service, qui détient les outils (GetSectionDetail, RAG, contexte de visite). Le Live API supporte le function calling, mais il faut décider qui exécute :

• Option A — l'app se connecte directement à Gemini. Latence minimale, mais l'app porterait les définitions d'outils et rappellerait manager-service pour chacun. Et on ne met pas une clé Gemini dans un APK distribué à des visiteurs : il faut des jetons éphémères émis par le backend. Faisable, mais ça déplace de la logique métier dans le client — l'inverse de l'architecture actuelle.
• Option B — manager-service proxifie le WebSocket. L'app parle au backend, le backend parle à Gemini et exécute les outils là où ils vivent déjà. La clé reste au chaud, on garde la main sur le prompt et les stats. Mais c'est du relais audio bidirectionnel temps réel en C#, avec sessions, reconnexions et backpressure.

C'est l'option B qui a du sens ici, et c'est elle qui coûte cher.

Faisable ? Techniquement oui, sans obstacle bloquant. Trois réserves sérieuses :

1. ⚠️ Le modèle de coût change de nature. On ne paie plus à la requête mais à la session ouverte, et les jetons audio coûtent nettement plus cher que le texte. Un musée avec 80 visiteurs simultanés = 80 sessions live. À chiffrer avant toute décision technique — les tarifs ne sont pas connus ici, à vérifier et non à supposer.
2. ⚠️ Sessions à durée limitée, avec reprise à gérer. Sur un réseau mobile de visiteur dans un bâtiment en pierre, c'est du vrai travail de robustesse.
3. ⛔ Les modèles Live sont en preview. Construire une fonction vendue à des clients sur une API preview, après l'historique de bascule ElevenLabs → Gemini, serait imprudent.

Verdict : piste V2 réelle, à ouvrir par un spike chiffré d'une journée — connecter, mesurer la latence réelle, mesurer le coût d'une session de 5 minutes — avant tout engagement.

3.3 Le reste

• Barge-in / AEC sur l'architecture actuelle, si le Live API n'est pas retenu.
• Extension au-delà de 4 langues (cf. §1.6 pour le coût réel).

---

Références

• mymuseum-visitapp/lib/Services/Glasses/voice_orchestrator.dart
• mymuseum-visitapp/lib/Services/Glasses/engines/impl/gemini_tts_engine.dart
• mymuseum-visitapp/lib/Services/voice_controller.dart — _buildTtsEngine
• mymuseum-visitapp/lib/constants.dart — kGeminiTtsVoice, kGeminiTtsPrompt
• v1-plan.md §5 — les lunettes Ray-Ban sont en V1 depuis le 2026-08-12
• DOCS/rayban-meta-integration.md