Dépannage

Guide de résolution des problèmes courants avec le SDK Ephia Transcribe.

Problèmes courants avec le SDK

”Je ne reçois aucun événement”

Cause probable :

• Le TranscriptionButton n’est pas monté sous un TranscriptionProvider
• Le token est manquant ou invalide
• Le microphone n’est pas autorisé

Solution :

1. Vérifier que TranscriptionProvider enveloppe bien l’arbre
2. Vérifier que TranscriptionButton reçoit bien un token valide
3. Vérifier que le navigateur a autorisé le microphone
4. Consulter error et errorCode via useTranscription()

”Mes textes changent”

Cause probable :

• Comportement normal des transcriptions intermédiaires (interimStreaming=true)
• Le segment intermédiaire évolue jusqu’à recevoir le statut final

Solution :

• Afficher visuellement la distinction entre interim et final
• Les chunks final sont confirmés ; utilisez isMedicalCorrection pour identifier les relectures

”La connexion WebSocket se ferme immédiatement”

Cause probable :

• Token API invalide ou expiré
• Erreur d’authentification (code 1008 côté serveur)
• endUserId trop long (> 128 caractères)

Solution :

1. Vérifier que le token API est valide sur la plateforme
2. Vérifier le format du token (ep_live_...)
3. Vérifier que endUserId ne dépasse pas 128 caractères
4. Consulter errorCode : websocket_auth_error indique un problème d’auth

”Je ne reçois que des transcriptions vides”

Cause probable :

• Qualité audio insuffisante
• Niveau sonore trop faible
• Le VAD ne détecte pas de parole

Solution :

1. Vérifier que le microphone fonctionne (tester avec une autre app)
2. Vérifier le niveau audio via volume dans useTranscription()
3. S’assurer que l’utilisateur parle assez fort et clairement
4. Réduire le bruit de fond

”La latence est trop élevée”

Cause probable :

• Connexion réseau lente ou instable
• interimStreaming=false sans feedback visuel
• Relecture finale activée (reformatPresetId) qui ajoute du délai

Solution :

1. Vérifier la connexion réseau
2. Activer interimStreaming pour du feedback temps réel
3. Désactiver reformatPresetId si la latence finale est problématique
4. Tester sur un réseau différent

Checklist de diagnostic

Avant de contacter le support, vérifiez :

• La page est en HTTPS (ou localhost)
• Le token est valide et non expiré
• Le navigateur a autorisé le microphone
• Le fichier audio-processor.js est accessible
• L’endUserId est renseigné (recommandé, sera obligatoire)
• Le composant est bien un Client Component ('use client') sous Next.js App Router
• TranscriptionProvider enveloppe bien le TranscriptionButton et le composant qui lit useTranscription()

Dépannage API directe (WebSocket vanilla)

Les guides de dépannage pour les intégrations WebSocket sans SDK (codes d’erreur HTTP, rate limits, formats audio bruts, etc.) seront disponibles prochainement. Pour l’instant, utilisez le SDK React @ephia/transcribe-sdk.

Contact support

Si le problème persiste après avoir suivi ce guide :

1. Consulter la FAQ
2. Consulter le dépannage SDK
3. Contacter le support à support@ephia.ai avec :
   • Le sessionId (si disponible)
   • Le code d’erreur (errorCode)
   • La version du SDK utilisée
   • Les logs navigateur (console + onglet Network)