Référence SDK
Exports publics (barrel src/index.ts)
Composants : TranscriptionButton, TranscriptionProvider.
Hooks : useTranscription, useStreamingV2, useTranscribeLive.
Constantes : STREAMING_LIVE_PATH, AUDIO_NORMALIZATION_CONFIG, EPHIA_TRANSCRIBE_INFO_URL.
Types : TranscriptionButtonProps, TranscriptionButtonTheme, TranscriptionButtonVariant, TranscriptionButtonSize, TranscriptionButtonCustomColors, TranscriptionContextValue, ChunkData, TranscriptionState, StreamingStats, RecorderPhase, TranscriptionErrorCode, MicrophonePermissionState, VadSettings, StreamingWarning, StreamingV2Config, TranscribeLiveConfig, AudioNormalizationConfig, StreamingProtocol, TranscribeGroqLogEntry, SessionConfidenceWordRow.
TranscriptionButtonProps (détail)
| Prop | Type | Requis | Défaut | Description |
|---|---|---|---|---|
token | string | Oui | — | Clé API Ephia. Sans token, bouton désactivé. |
endUserId | string | Non | — | Identifiant utilisateur final (recommandé, sera obligatoire). |
projectId | string | Non | — | Rattachement projet. |
streamingUrl | string | Non | auto | URL WebSocket complète. |
streamingUrlBase | string | Non | localhost→ws://localhost:8765 ; sinon wss://platform-api.ephia.app | Origine WS sans chemin. |
audioProcessorUrl | string | Non | '/audio-processor.js' | URL du worklet audio. |
promptPresetId | string | Non | — | prompt_preset_id en query. |
vadPresetId | string | Non | — | vad_preset_id en query. |
reformatPresetId | string | Non | — | reformat_preset_id en query. |
model | 'default' | 'vox' | Non | 'default' | Modèle final médical. |
interimStreaming | boolean | Non | false | interim_streaming=true/false. |
finalReformat | boolean | Non | true | final_reformat=true/false (compat). |
preserveIncomingAfterStop | boolean | Non | false | Conserve les events après stopRecording(). |
theme | 'light' | 'dark' | Non | 'dark' | Thème visuel. |
variant | 'minimal' | 'standard' | Non | 'minimal' | standard = icône + barre de volume. |
size | 'S' | 'M' | 'L' | Non | 'M' | Échelle du bouton. |
logoSrc | string | Non | '/ephia_logo_light.svg' | Logo (SVG inline si contient ephia_logo). |
colors | { primary: string; secondary: string } | Non | — | Couleurs custom CSS (inversion auto en light). |
onStateChange | (state: TranscriptionState) => void | Non | — | Callback changement d’état. |
useStreamingV2(config)
Pour construire votre propre interface (sans TranscriptionButton), passez un objet StreamingV2Config :
| Champ | Obligatoire | Description |
|---|---|---|
url | Oui | URL du endpoint streaming (le hook y ajoute token, session_id si besoin, et les entrées de vadSettings). |
token | Oui | Clé API ; sans token à la connexion → token_missing. |
audioProcessorUrl | Non | Worklet (défaut : /audio-processor.js). |
currentSessionNum | Non | Numéro de session côté client (propagé dans ChunkData.session_num). |
customPrompt | Non | Si défini au moment de l’ouverture : envoi JSON { type: 'set_prompt', custom_prompt } après l’ouverture du WS. |
vadSettings | Non | Objet dont chaque paire clé/valeur est ajoutée à la query string. |
endUserId | Non | Identifiant utilisateur final (transmis en query end_user_id). |
projectId | Non | Identifiant projet (transmis en query project_id). |
protocol | Non | 'streaming_legacy' (défaut) ou 'transcribe_v1'. |
userJwt | Non | JWT utilisateur (playground + org_id). |
orgId | Non | ID organisation. |
recordingOrigin | Non | 'playground' | 'platform' | 'sdk' (auto-détecté si absent). |
preserveIncomingAfterStop | Non | Garde les events après arrêt jusqu’à final_sync. |
burstStartMs / cursorPositionMs | Non | Position curseur pour reprise (protocol transcribe_v1). |
nextSentenceIndex / nextSegmentIndex | Non | Index phrase VAD (protocol transcribe_v1). |
Note : le hook crée un AudioContext avec sampleRate: 16000. Le type StreamingV2Config peut déclarer d’autres champs ; pour interimStreaming sans TranscriptionButton, reportez les paramètres attendus dans la query de url (comme le fait le bouton pour interim_streaming / final_reformat).
Le retour du hook expose les mêmes champs utiles qu’un TranscriptionState : chunks, phase, isArming, isRecording, isProcessing, isConnected, volume, speechProb, isSpeech, erreurs, streamingWarning, debugMessages, sessionId, lastSpeechStartTimestamp, startRecording, stopRecording, clear, connect, prepareAudio, prepareTransport, stats.
Phases (RecorderPhase)
| Phase | Sens |
|---|---|
idle | Repos. |
preparing_audio | Initialisation micro + worklet. |
connecting_ws | Ouverture WebSocket. |
arming | Armement après action utilisateur. |
ready | Pipeline prêt ; premier envoi audio en cours ou imminent. |
recording | Streaming audio actif. |
stopping | Fin de parole côté client. |
finalizing | Attente finalisation serveur (final_sync). |
error | Erreur. |
ChunkData (aperçu)
id,text,status(interim|final),isMedicalCorrection,seq- Optionnel :
timestamp_ms,duration_ms session_num: index de session côté client
StreamingStats (aperçu)
framesCaptured,framesSent,framesSkipped,batchesSent,keepalivesSent,bytesSavedByBatching
Protocole WebSocket (aperçu)
Entrées (JSON) gérées par le SDK : session_info, speech_start, transcript_interim, transcript_final, session_reformat_final, warning, final_sync, pong.
Sorties : trames binaires PCM 16 bits ; JSON end_of_speech, ack_finish (réponse à final_sync), ping, éventuellement set_prompt si customPrompt est défini.
Normalisation audio
AUDIO_NORMALIZATION_CONFIG est exporté par le paquet ; la normalisation de crête est appliquée sur le Float32Array entrant dans le hook avant conversion en PCM 16 bits.