Connexion et flux

Paquet @ephia/transcribe-sdk · test interactif Playground.

Dans la plupart des cas, vous n’avez pas besoin de coder une URL WebSocket : le SDK la construit à partir du contexte d’exécution (page en localhost vs application déployée) et y ajoute le token, les presets et les options de flux.

URL par défaut

Si vous ne passez ni streamingUrl ni une base explicite inattendue :

Le SDK détermine une origine de base (streamingUrlBase implicite) :
- Sur localhost / 127.0.0.1 : ws://localhost:8765, sauf si la variable NEXT_PUBLIC_WS_URL (build Next) est définie — alors cette valeur (sans slash final) remplace l’origine en local.
- Hors localhost dans le navigateur : wss://platform-api.ephia.app.
- En SSR sans window : NEXT_PUBLIC_WS_URL si déf ; sinon en NODE_ENV === 'development' → ws://localhost:8765 ; sinon → wss://platform-api.ephia.app.
Il concatène le chemin /api/v2/streaming/live (constante STREAMING_LIVE_PATH du package).
Il ajoute en query : presets (prompt_preset_id, vad_preset_id, reformat_preset_id si props renseignées), interim_streaming, final_reformat, model, puis le hook ajoute le token et éventuellement session_id pour reprise de session. Si un endUserId est fourni, il est aussi passé en query (end_user_id).

NEXT_PUBLIC_WS_URL ne doit contenir que l’origine (schéma + hôte), pas le chemin du endpoint streaming — utile quand votre poste de dev pointe vers une autre origine WebSocket qu’en production.

Options de streaming (cosmétique / protocole)

Prop	Défaut	Effet
`interimStreaming`	`false`	`true` : le client et le serveur traitent les transcriptions intermédiaires (brouillons) par segment. `false` : comportement final d’abord côté protocole — moins de mises à jour « temps réel » sur l’API ; l’UI peut rester fluide selon votre rendu.
`finalReformat`	`true`	Envoyé en query pour compatibilité (`final_reformat`). La relecture finale réelle est pilotée par le serveur et les presets (`reformat_preset_id`).
`model`	`'default'`	`'vox'` active le modèle final médical Ephia Vox.
`preserveIncomingAfterStop`	`false`	Si `true`, conserve les chunks et accepte les events après `stopRecording()` jusqu’au `final_sync`.

Événement `session_reformat_final`

Lorsque la relecture finale (LLM) aboutit, le serveur peut envoyer un message dédié. Le SDK peut alors remplacer tous les chunks par un seul segment final agrégé.

Avertissements serveur (`streamingWarning`)

Le champ streamingWarning n’est pas une erreur bloquante : il signale un problème de configuration résolu par le serveur. Exemples :

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`.
`vad_preset_not_found`	Le preset VAD demandé n’existe pas → fallback `default`.
`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.

En cas d’avertissement, le SDK remplit useTranscription().streamingWarning (code, message, et champs optionnels presetType, requested, fallback). Les chunks peuvent tout de même contenir du texte final.

URL entièrement personnalisée

streamingUrl : URL WebSocket complète (query incluse si besoin). Le README du paquet indique un usage avancé lorsque vous assemblez vous-même les paramètres. Le hook useStreamingV2 ajoute notamment le token via URLSearchParams à l’ouverture.

streamingUrlBase : fournissez uniquement l’origine (et éventuellement un préfixe si votre gateway le impose), sans la query complète — le SDK ajoute /api/v2/streaming/live et les paramètres issus des props du bouton.

Résumé

Production classique : token + endUserId + éventuellement les slugs de presets suffisent.
Dev local particulier : NEXT_PUBLIC_WS_URL pour surcharger l’origine en local uniquement.
Intégration spéciale : streamingUrl ou streamingUrlBase.

Presets : Presets. API hook bas niveau : Référence SDK.

Latence perçue et audio

Comme indiqué dans le README du paquet :

Tant que le WebSocket n’est pas prêt, l’audio est mis en buffer puis réinjecté à l’ouverture.
L’interface peut passer en « en enregistrement » sans attendre la fin complète de l’initialisation micro ; l’envoi effectif suit le pipeline une fois prêt.
Une coupure des tout premiers instants peut aussi venir du VAD côté serveur (délai de détection, pré-buffer), pas seulement du client.

Utilisation Apparence