@ephia/transcribe-sdk

SDK React pour la transcription vocale Ephia : bouton d’enregistrement, flux temps réel, contexte React (Provider + useTranscription).

Installation

npm install @ephia/transcribe-sdk

Prérequis

• Contexte sécurisé (HTTPS ou localhost) pour l’accès au microphone.
• Importer les styles du SDK (obligatoire) : @ephia/transcribe-sdk/dist/styles.css
• Fichier audio-processor.js (obligatoire) : le SDK charge par défaut /audio-processor.js. Vous devez donc servir ce fichier depuis vos assets statiques.

Installer le worklet audio-processor.js

Après npm install, copiez le worklet depuis node_modules vers vos assets statiques.

• Vite / CRA / tout projet avec dossier public/ :

cp node_modules/@ephia/transcribe-sdk/dist/audio-processor.js public/audio-processor.js

• Next.js :

cp node_modules/@ephia/transcribe-sdk/dist/audio-processor.js public/audio-processor.js

Si vous ne pouvez pas copier de fichier, vous pouvez aussi héberger ce worklet ailleurs et passer audioProcessorUrl.

Utilisation

1. Enveloppez votre app (ou la partie qui utilise la transcription) avec TranscriptionProvider.
2. Passez un token (clé API) au TranscriptionButton. Créez une clé sur plateform.ephia.app/api-keys.
3. Utilisez useTranscription() pour lire l’état (chunks, isRecording, etc.) où vous voulez dans l’arbre.

import { TranscriptionProvider, TranscriptionButton, useTranscription } from '@ephia/transcribe-sdk';
import '@ephia/transcribe-sdk/dist/styles.css';

function MyApp() {
  return (
    <TranscriptionProvider>
      <TranscriptionButton token="YOUR_API_TOKEN" />
      <TranscriptDisplay />
    </TranscriptionProvider>
  );
}

function TranscriptDisplay() {
  const { chunks } = useTranscription();
  return <div>{chunks.map(c => <p key={c.id}>{c.text}</p>)}</div>;
}

Next.js (App Router)

Le bouton utilise le micro, donc il doit être rendu côté client. Dans Next.js, placez-le dans un composant avec :

"use client";

Props principales

• token (requis) : clé API Ephia.
• streamingUrlBase : URL de base WebSocket (défaut : NEXT_PUBLIC_WS_URL, sinon ws://localhost:8765 sur localhost, sinon wss://api-platform.ephia.app).
• audioProcessorUrl : URL du worklet (défaut : /audio-processor.js).
• interimStreaming : si true, transcriptions intermédiaires Whisper ; si false, attente du final par segment (défaut : false).
• finalReformat : si true, après la fin de dictée le serveur envoie un texte unique reformatté (Groq) via l’événement WebSocket session_reformat_final, puis final_sync comme d’habitude. Les chunks sont alors remplacés par un seul chunk session_reformat_final (défaut : false).
• theme, variant, size : apparence du bouton.

Relecture finale et warnings

• En cas d’échec ou de timeout de la relecture, le serveur peut envoyer un message warning : le SDK expose le dernier événement dans useTranscription().streamingWarning (code, message), sans passer par error. Les segments finaux restent disponibles dans chunks tant que le remplacement par session_reformat_final n’a pas eu lieu.

Exemple “prod” pour le WebSocket

<TranscriptionButton
  token="YOUR_API_TOKEN"
  streamingUrlBase="wss://api-platform.ephia.app"
/>

Dépannage (rapide)

• Erreur / 404 sur /audio-processor.js : copiez bien node_modules/@ephia/transcribe-sdk/dist/audio-processor.js vers public/audio-processor.js (ou passez audioProcessorUrl).
• Micro bloqué : utilisez HTTPS (ou http://localhost) et acceptez la permission micro dans le navigateur.
• WebSocket KO : vérifiez streamingUrlBase (doit être ws:// en local, wss:// en prod) et que votre backend expose bien /api/v2/streaming/live.
• Bouton “sans style” : vérifiez l’import @ephia/transcribe-sdk/dist/styles.css.

Licence

Propriétaire. Voir le fichier LICENSE fourni avec le package.