> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # SDK JavaScript > **Info** > > Pour une présentation de Scribe et de ses capacités, consultez la [présentation de Speech to Text ](/docs/fr/capabilities/speech-to-text). Pour des guides d’utilisation étape par étape, consultez le [streaming côté client](/docs/fr/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming). ## Installation ```shell npm install @elevenlabs/client # or yarn add @elevenlabs/client # or pnpm install @elevenlabs/client ``` > **Tip** > > Utilisez la [compétence Speech to Text d’ElevenLabs](https://github.com/elevenlabs/skills/tree/main/speech-to-text) pour transcrire de l’audio depuis votre assistant de programmation IA : > > ```bash > npx skills add elevenlabs/skills --skill speech-to-text > ``` > **Note** > > Cette bibliothèque peut être utilisée dans tout projet basé sur JavaScript. Si vous utilisez React, envisagez le > [hook `useScribe`](/docs/fr/eleven-api/resources/libraries/scribe-stt/react-scribe), qui fournit une gestion intégrée > de l’état et du cycle de vie. ## Utilisation Voici un exemple minimal fonctionnel qui se connecte à Scribe et affiche les résultats de transcription : ```js import { Scribe, RealtimeEvents } from "@elevenlabs/client"; const token = await fetchTokenFromServer(); const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", microphone: { echoCancellation: true, noiseSuppression: true, }, }); connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => { console.log("Partial:", data.text); }); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { console.log("Committed:", data.text); }); // Later, close the connection connection.close(); ``` ## Obtenir un jeton Scribe nécessite un jeton à usage unique pour l’authentification. Créez un point de terminaison API sur votre serveur : ```js // Node.js server app.get("/scribe-token", yourAuthMiddleware, async (req, res) => { const response = await fetch("https://api.elevenlabs.io/v1/single-use-token/realtime_scribe", { method: "POST", headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY, }, }); const data = await response.json(); res.json({ token: data.token }); }); ``` > **Warning** > > Votre clé API ElevenLabs est sensible. Ne l’exposez jamais au client. Générez toujours le jeton sur > le serveur. ```js // Client const fetchToken = async () => { const response = await fetch("/scribe-token"); const { token } = await response.json(); return token; }; ``` ## Options de connexion `Scribe.connect()` accepte des options de microphone ou des options audio manuelles. Les deux partagent un ensemble commun d’options de base. ### Options de base | Propriété | Type | Valeur par défaut | Description | | --------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------------------------------- | | **token** | `string` | | Jeton à usage unique pour l’authentification WebSocket. | | **modelId** | `string` | | ID du modèle (par exemple, `"scribe_v2_realtime"`). | | **baseUri** | `string` | `"wss://api.elevenlabs.io"` | URI de base WebSocket personnalisée. | | **commitStrategy** | `CommitStrategy` | `"manual"` | `"manual"` ou `"vad"`. | | **vadSilenceThresholdSecs** | `number` | `1.5` | Secondes de silence avant validation par VAD (0.3-3.0). | | **vadThreshold** | `number` | `0.4` | Sensibilité du VAD (0.1-0.9, plus basse signifie plus sensible). | | **minSpeechDurationMs** | `number` | `100` | Durée minimale de parole en ms (50-2000). | | **minSilenceDurationMs** | `number` | `100` | Durée minimale de silence en ms (50-2000). | | **languageCode** | `string` | | Code de langue ISO-639-1 ou ISO-639-3. Laissez vide pour la détection automatique. | | **includeTimestamps** | `boolean` | `false` | Recevez les horodatages au niveau des mots via l’événement `COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS`. | ### Options de microphone Transmettez un objet `microphone` pour diffuser l’audio directement depuis le microphone de l’utilisateur. La connexion gère automatiquement `getUserMedia` et l’encodage audio. ```js const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", microphone: { deviceId: "optional-device-id", echoCancellation: true, noiseSuppression: true, autoGainControl: true, }, }); ``` | Propriété | Type | Description | | -------------------- | --------- | ------------------------------------------- | | **deviceId** | `string` | ID d’un périphérique microphone spécifique. | | **echoCancellation** | `boolean` | Active l’annulation d’écho. | | **noiseSuppression** | `boolean` | Active la réduction du bruit. | | **autoGainControl** | `boolean` | Active le contrôle automatique du gain. | ### Options audio manuelles Transmettez `audioFormat` et `sampleRate` pour envoyer manuellement des données audio via `connection.send()`. ```js import { AudioFormat } from "@elevenlabs/client"; const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", audioFormat: AudioFormat.PCM_16000, sampleRate: 16000, }); ``` | Propriété | Type | Description | | --------------- | ------------- | --------------------------------------------------------------------- | | **audioFormat** | `AudioFormat` | Format d’encodage audio (par exemple, `AudioFormat.PCM_16000`). | | **sampleRate** | `number` | Fréquence d’échantillonnage en Hz. Doit correspondre à `audioFormat`. | #### Énumération AudioFormat ```typescript enum AudioFormat { PCM_8000 = "pcm_8000", PCM_16000 = "pcm_16000", PCM_22050 = "pcm_22050", PCM_24000 = "pcm_24000", PCM_44100 = "pcm_44100", PCM_48000 = "pcm_48000", ULAW_8000 = "ulaw_8000", } ``` ## Mode microphone Diffusez l’audio directement depuis le microphone de l’utilisateur : ```js import { Scribe, RealtimeEvents } from "@elevenlabs/client"; async function transcribeFromMicrophone() { const token = await fetchToken(); const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", microphone: { echoCancellation: true, noiseSuppression: true, autoGainControl: true, }, }); connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => { document.getElementById("live").textContent = data.text; }); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { const el = document.createElement("p"); el.textContent = data.text; document.getElementById("transcripts").appendChild(el); document.getElementById("live").textContent = ""; }); document.getElementById("stop").addEventListener("click", () => { connection.close(); }); } ``` ## Mode audio manuel (transcription de fichier) Transcrivez des fichiers audio préenregistrés en envoyant manuellement les données audio : ```js import { Scribe, RealtimeEvents, AudioFormat } from "@elevenlabs/client"; async function transcribeFile(file) { const token = await fetchToken(); const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", audioFormat: AudioFormat.PCM_16000, sampleRate: 16000, }); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { console.log("Transcript:", data.text); }); // Decode audio file const arrayBuffer = await file.arrayBuffer(); const audioContext = new AudioContext({ sampleRate: 16000 }); const audioBuffer = await audioContext.decodeAudioData(arrayBuffer); // Convert to PCM16 const channelData = audioBuffer.getChannelData(0); const pcmData = new Int16Array(channelData.length); for (let i = 0; i < channelData.length; i++) { const sample = Math.max(-1, Math.min(1, channelData[i])); pcmData[i] = sample < 0 ? sample * 32768 : sample * 32767; } // Send in chunks const chunkSize = 4096; for (let offset = 0; offset < pcmData.length; offset += chunkSize) { const chunk = pcmData.slice(offset, offset + chunkSize); const bytes = new Uint8Array(chunk.buffer); const base64 = btoa(String.fromCharCode(...bytes)); connection.send({ audioBase64: base64 }); await new Promise((resolve) => setTimeout(resolve, 50)); } // Commit and close connection.commit(); } ``` ## RealtimeConnection `Scribe.connect()` renvoie une instance `RealtimeConnection` avec les méthodes suivantes. ### on(event, listener) Enregistrez un écouteur d’événements. Consultez [Événements](#events) pour connaître les types d’événements disponibles. ```js connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { console.log("Committed:", data.text); }); ``` ### off(event, listener) Supprimez un écouteur d’événements précédemment enregistré. ```js const handler = (data) => console.log(data.text); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, handler); // Later connection.off(RealtimeEvents.COMMITTED_TRANSCRIPT, handler); ``` ### send(data) Envoyez des données audio à Scribe (mode audio manuel uniquement). ```js connection.send({ audioBase64: base64AudioChunk, commit: false, // Optional: commit immediately sampleRate: 16000, // Optional: override sample rate previousText: "Previous transcription text", // Optional: context from a previous transcription }); ``` > **Warning** > > Le champ `previousText` ne peut être envoyé que dans le premier fragment audio d’une session. Son envoi dans > les fragments suivants génère une erreur. ### commit() Validez manuellement la transcription actuelle. Nécessaire uniquement avec `CommitStrategy.MANUAL`. ```js connection.commit(); ``` ### close() Fermez la connexion WebSocket et libérez les ressources (flux du microphone, contexte audio). ```js connection.close(); ``` ## Événements Enregistrez des écouteurs d’événements à l’aide de `connection.on(event, listener)`. Tous les événements sont disponibles sous forme de constantes dans l’énumération `RealtimeEvents`. ### Événements de transcription | Événement | Données | Description | | ---------------------------------------- | --------------------------------------------------------------- | ---------------------------------------- | | **SESSION_STARTED** | `{ session_id: string }` | Session Scribe démarrée. | | **PARTIAL_TRANSCRIPT** | `{ text: string }` | Résultat de transcription provisoire. | | **COMMITTED_TRANSCRIPT** | `{ text: string }` | Résultat de transcription finalisé. | | **COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS** | `{ text: string; language_code?: string; words?: WordsItem[] }` | Résultat finalisé avec minutage par mot. | Le type `WordsItem` contient les informations de minutage au niveau des mots : ```typescript interface WordsItem { text?: string; // Word text start?: number; // Start time in seconds end?: number; // End time in seconds type?: "word" | "spacing"; // Token type speaker_id?: string; // Speaker identifier } ``` ### Événements de connexion | Événement | Données | Description | | --------- | ---------------- | ---------------------------- | | **OPEN** | `Event` | Connexion WebSocket ouverte. | | **CLOSE** | `Event` | Connexion WebSocket fermée. | | **ERROR** | `Error \| Event` | Erreur générique. | ### Événements d’erreur Tous les événements d’erreur reçoivent `{ error: string }`. | Événement | Description | | ------------------------------- | -------------------------------------------------------- | | **AUTH_ERROR** | Erreur d’authentification. | | **QUOTA_EXCEEDED** | Quota d’utilisation dépassé. | | **COMMIT_THROTTLED** | Requête de validation limitée. | | **TRANSCRIBER_ERROR** | Erreur du moteur de transcription. | | **UNACCEPTED_TERMS** | Conditions d’utilisation non acceptées. | | **RATE_LIMITED** | Limite de débit atteinte. | | **INPUT_ERROR** | Format d’entrée non valide. | | **QUEUE_OVERFLOW** | File de traitement pleine. | | **RESOURCE_EXHAUSTED** | Ressources serveur à pleine capacité. | | **SESSION_TIME_LIMIT_EXCEEDED** | Durée maximale de session atteinte. | | **CHUNK_SIZE_EXCEEDED** | Fragment audio trop volumineux. | | **INSUFFICIENT_AUDIO_ACTIVITY** | Activité audio insuffisante pour maintenir la connexion. | ## Stratégies de validation Contrôlez le moment où les transcriptions sont validées : ```js import { Scribe, CommitStrategy } from '@elevenlabs/client'; // Manual (default): you control when to commit const connection = Scribe.connect({ token, modelId: 'scribe_v2_realtime', audioFormat: AudioFormat.PCM_16000, sampleRate: 16000, commitStrategy: CommitStrategy.MANUAL, }); // Send audio, then commit when ready connection.send({ audioBase64: chunk }); connection.commit(); // Voice Activity Detection: Scribe detects silences and commits automatically const connection = Scribe.connect({ token, modelId: 'scribe_v2_realtime', microphone: { echoCancellation: true }, commitStrategy: CommitStrategy.VAD, }); ``` Pour en savoir plus, consultez [Transcriptions et stratégies de validation](/docs/fr/eleven-api/guides/how-to/speech-to-text/realtime/transcripts-and-commit-strategies). ## Exemple complet Voici un exemple complet qui transcrit l’audio du microphone avec une stratégie de validation basée sur le VAD : ```js import { Scribe, RealtimeEvents, CommitStrategy } from "@elevenlabs/client"; async function startTranscription() { const token = await fetchToken(); const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", commitStrategy: CommitStrategy.VAD, microphone: { echoCancellation: true, noiseSuppression: true, }, }); connection.on(RealtimeEvents.SESSION_STARTED, (data) => { console.log("Session started:", data.session_id); }); connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => { document.getElementById("live").textContent = data.text; }); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { const el = document.createElement("p"); el.textContent = data.text; document.getElementById("transcripts").appendChild(el); document.getElementById("live").textContent = ""; }); connection.on(RealtimeEvents.ERROR, (error) => { console.error("Scribe error:", error); }); // Stop button document.getElementById("stop").addEventListener("click", () => { connection.close(); }); } document.getElementById("start").addEventListener("click", startTranscription); ```