Dépannage

Parcourir la doc dans l’ordre : Installation → Utilisation → Connexion et flux. Pour tester sans intégrer : Playground SDK.

Erreurs courantes

Microphone refusé

Code : microphone_denied
Cause : permission refusée ou bloquée par le navigateur / l’OS.
Solution : autoriser le micro pour le site, recharger si besoin.

Contexte non sécurisé

Code : insecure_context
Cause : pas de HTTPS (hors localhost).
Solution : servir l’app en HTTPS en production.

Erreur audio worklet

Code : audio_worklet_error
Cause : audio-processor.js introuvable, mauvaise URL, ou blocage réseau/CORS.
Solution : copier node_modules/@ephia/transcribe-sdk/dist/audio-processor.js vers public/ (ou équivalent) ; vérifier audioProcessorUrl. Voir Installation.

WebSocket

Codes : websocket_error, websocket_auth_error
Cause : serveur injoignable, pare-feu, ou token invalide / non autorisé (souvent code 1008 côté serveur).
Solution : vérifier le token (clés API), la connectivité, et en dev local la base WS (voir Connexion et flux pour NEXT_PUBLIC_WS_URL et l’origine par défaut).

Token manquant

Code : token_missing (surtout en usages avancés avec useStreamingV2 / connect).
Solution : fournir token sur le bouton ou dans la config du hook.

`useTranscription` toujours vide

Cause : absence de TranscriptionProvider, ou provider sans TranscriptionButton qui publie l’état, ou composant qui lit le hook hors du sous-arbre enveloppé.
Solution : envelopper l’arbre avec le provider et monter un bouton (ou utiliser onStateChange sur le bouton sans contexte).

Avertissements serveur (`streamingWarning`)

Le champ streamingWarning n’est pas une erreur bloquante : il signale par ex. un fallback de preset, un échec de relecture finale, ou une fermeture WebSocket pendant la finalisation (ws_closed_while_finalizing). Affichez-le à l’utilisateur si besoin ; les chunks peuvent tout de même contenir du texte final.

Code	Signification
`end_user_id_missing_deprecated`	L’`endUserId` n’est pas renseigné. La transcription fonctionne, mais ce champ deviendra obligatoire.
`prompt_preset_not_found`	Le preset demandé n’existe pas → fallback `default`.
`prompt_preset_inactive`	Le preset demandé est inactif → fallback `default`.
`prompt_default_inactive`	Le preset `default` est inactif → prompt minimal serveur.
`prompt_default_missing`	Le preset `default` est manquant → prompt minimal serveur.
`vad_preset_not_found`	Le preset VAD demandé n’existe pas → fallback `default`.
`vad_default_missing`	Le preset VAD `default` est manquant → valeurs serveur par défaut.
`reformat_preset_not_found`	Le preset de relecture demandé n’existe pas → sortie iso (sans LLM).
`reformat_preset_inactive`	Le preset de relecture est inactif → sortie iso.
`reformat_preset_empty_prompt`	Le preset de relecture n’a pas de prompt → sortie iso.
`reformat_timeout`	La relecture finale a dépassé le délai → annulée.
`reformat_failed`	La relecture finale a échoué → indisponible.

Codes d’erreur SDK (`TranscriptionErrorCode`)

Code	Contexte	Solution / Détail
`insecure_context`	Page servie en HTTP hors localhost	Passer en HTTPS (certificat valide requis pour getUserMedia).
`microphone_denied`	Permission micro refusée par l'utilisateur ou l'OS	Autoriser le micro dans les paramètres du navigateur/site ; recharger.
`microphone_not_found`	Aucun périphérique audio détecté	Brancher un micro ; vérifier les paramètres système.
`microphone_error`	Autre erreur d'accès au micro (occupé, etc.)	Fermer les autres apps utilisant le micro ; réessayer.
`audio_worklet_error`	Échec de chargement du worklet (404, CORS, etc.)	Copier audio-processor.js dans les assets statiques ; vérifier audioProcessorUrl.
`token_missing`	Connexion WS sans token fourni	Passer token au TranscriptionButton ou dans la config useStreamingV2.
`websocket_error`	Fermeture WS anormale (hors 1008) ou onerror	Vérifier la connectivité réseau ; consulter les logs navigateur.
`websocket_auth_error`	Code 1008 ou raison contenant "auth"	Vérifier que le token est valide et non révoqué ; vérifier les clés API.
`unknown`	Erreur non classée	Contacter le support avec le sessionId et les logs.

Erreurs d’authentification côté backend (WebSocket)

Lors de l’ouverture du WebSocket, le serveur peut fermer la connexion avec le code 1008 et un message de raison. Voici les cas possibles :

Message de raison (tronqué)	Cause
`Missing authentication token (API key or JWT required)`	Aucun token fourni dans la query ou le header `Authorization`.
`Invalid API key`	Clé `ep_live_*` inconnue ou révoquée.
`Invalid token format. Expected API key (ep_live_...) or JWT`	Format de token non reconnu.
`Invalid JWT token`	JWT invalide ou expiré.
`No organization associated with this token.`	Le token JWT n’est associé à aucune organisation.
`Requested organization is not accessible for this user`	L’organisation demandée n’est pas accessible.
`end_user_id is too long (max 128 chars).`	L’identifiant utilisateur dépasse 128 caractères.
`Playground master key requires user_jwt.`	Master key sans `user_jwt` associé.
`Authentication failed`	Erreur d’authentification générique.

Checklist de diagnostic rapide

Avant de contacter le support :

La page est en HTTPS (ou localhost)
Le navigateur a autorisé le microphone
Le fichier audio-processor.js est accessible à l’URL attendue
Le token est valide et non expiré
L’**endUserId** est renseigné (recommandé, sera bientôt obligatoire)
Le WebSocket n’est pas bloqué par un pare-feu entreprise
La variable NEXT_PUBLIC_WS_URL est correctement configurée en dev local (si besoin)

Liens utiles

Exemples Index