> 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. # JavaScript SDK > **Info** > > Einen Überblick über Scribe und seine Funktionen finden Sie in der [Speech-to-Text- Übersicht](/docs/de/capabilities/speech-to-text). Schritt-für-Schritt-Anleitungen finden Sie unter [Clientseitiges Streaming](/docs/de/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** > > Verwenden Sie den [ElevenLabs-Speech-to-Text-Skill](https://github.com/elevenlabs/skills/tree/main/speech-to-text), um Audio mit Ihrem KI-Coding-Assistenten zu transkribieren: > > ```bash > npx skills add elevenlabs/skills --skill speech-to-text > ``` > **Note** > > Diese Bibliothek kann in jedem JavaScript-basierten Projekt verwendet werden. Wenn Sie React verwenden, nutzen Sie den > [`useScribe`-Hook](/docs/de/eleven-api/resources/libraries/scribe-stt/react-scribe), der integrierte > Statusverwaltung und Lifecycle-Handling bietet. ## Verwendung Hier ist ein minimales funktionierendes Beispiel, das eine Verbindung zu Scribe herstellt und Transkriptionsergebnisse protokolliert: ```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(); ``` ## Token abrufen Scribe benötigt zur Authentifizierung ein Einmal-Token. Erstellen Sie einen API-Endpunkt auf Ihrem Server: ```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** > > Ihr ElevenLabs API-Key ist vertraulich. Geben Sie ihn niemals an den Client weiter. Generieren Sie das Token immer auf > dem Server. ```js // Client const fetchToken = async () => { const response = await fetch("/scribe-token"); const { token } = await response.json(); return token; }; ``` ## Verbindungsoptionen `Scribe.connect()` akzeptiert entweder Mikrofonoptionen oder manuelle Audiooptionen. Beide verwenden gemeinsame Basisoptionen. ### Basisoptionen | Eigenschaft | Typ | Standard | Beschreibung | | --------------------------- | ---------------- | --------------------------- | ------------------------------------------------------------------------------------------ | | **token** | `string` | | Einmal-Token für die WebSocket-Authentifizierung. | | **modelId** | `string` | | Modell-ID (z. B. `"scribe_v2_realtime"`). | | **baseUri** | `string` | `"wss://api.elevenlabs.io"` | Benutzerdefinierte WebSocket-Basis-URI. | | **commitStrategy** | `CommitStrategy` | `"manual"` | `"manual"` oder `"vad"`. | | **vadSilenceThresholdSecs** | `number` | `1.5` | Sekunden Stille, bevor VAD übernimmt (0.3-3.0). | | **vadThreshold** | `number` | `0.4` | VAD-Empfindlichkeit (0.1-0.9, niedrigere Werte sind empfindlicher). | | **minSpeechDurationMs** | `number` | `100` | Minimale Sprechdauer in ms (50-2000). | | **minSilenceDurationMs** | `number` | `100` | Minimale Stilledauer in ms (50-2000). | | **languageCode** | `string` | | ISO-639-1- oder ISO-639-3-Sprachcode. Für automatische Erkennung leer lassen. | | **includeTimestamps** | `boolean` | `false` | Zeitstempel auf Wortebene über das Event `COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS` empfangen. | ### Mikrofonoptionen Übergeben Sie ein `microphone`-Objekt, um Audio direkt vom Mikrofon des Nutzers zu streamen. Die Verbindung verarbeitet `getUserMedia` und die Audiokodierung automatisch. ```js const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", microphone: { deviceId: "optional-device-id", echoCancellation: true, noiseSuppression: true, autoGainControl: true, }, }); ``` | Eigenschaft | Typ | Beschreibung | | -------------------- | --------- | --------------------------------------------- | | **deviceId** | `string` | ID eines bestimmten Mikrofongeräts. | | **echoCancellation** | `boolean` | Echounterdrückung aktivieren. | | **noiseSuppression** | `boolean` | Rauschunterdrückung aktivieren. | | **autoGainControl** | `boolean` | Automatische Verstärkungsregelung aktivieren. | ### Manuelle Audiooptionen Übergeben Sie `audioFormat` und `sampleRate`, um Audiodaten manuell über `connection.send()` zu senden. ```js import { AudioFormat } from "@elevenlabs/client"; const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", audioFormat: AudioFormat.PCM_16000, sampleRate: 16000, }); ``` | Eigenschaft | Typ | Beschreibung | | --------------- | ------------- | -------------------------------------------------------- | | **audioFormat** | `AudioFormat` | Audiokodierungsformat (z. B. `AudioFormat.PCM_16000`). | | **sampleRate** | `number` | Abtastrate in Hz. Muss mit `audioFormat` übereinstimmen. | #### AudioFormat-Enum ```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", } ``` ## Mikrofonmodus Streamen Sie Audio direkt vom Mikrofon des Nutzers: ```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(); }); } ``` ## Manueller Audiomodus (Dateitranskription) Transkribieren Sie vorab aufgezeichnete Audiodateien, indem Sie die Audiodaten manuell senden: ```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()` gibt eine `RealtimeConnection`-Instanz mit den folgenden Methoden zurück. ### on(event, listener) Registriert einen Event-Listener. Verfügbare Event-Typen finden Sie unter [Events](#events). ```js connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { console.log("Committed:", data.text); }); ``` ### off(event, listener) Entfernt einen zuvor registrierten Event-Listener. ```js const handler = (data) => console.log(data.text); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, handler); // Later connection.off(RealtimeEvents.COMMITTED_TRANSCRIPT, handler); ``` ### send(data) Sendet Audiodaten an Scribe (nur im manuellen Audiomodus). ```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** > > Das Feld `previousText` kann nur im ersten Audio-Chunk einer Sitzung gesendet werden. Das Senden in > nachfolgenden Chunks führt zu einem Fehler. ### commit() Übernimmt die aktuelle Transkription manuell. Nur erforderlich bei Verwendung von `CommitStrategy.MANUAL`. ```js connection.commit(); ``` ### close() Schließt die WebSocket-Verbindung und bereinigt Ressourcen (Mikrofonstream, Audiokontext). ```js connection.close(); ``` ## Events Registrieren Sie Event-Listener mit `connection.on(event, listener)`. Alle Events sind als Konstanten im Enum `RealtimeEvents` verfügbar. ### Transkriptions-Events | Event | Daten | Beschreibung | | ---------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- | | **SESSION_STARTED** | `{ session_id: string }` | Scribe-Sitzung gestartet. | | **PARTIAL_TRANSCRIPT** | `{ text: string }` | Vorläufiges Transkriptionsergebnis. | | **COMMITTED_TRANSCRIPT** | `{ text: string }` | Finalisiertes Transkriptionsergebnis. | | **COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS** | `{ text: string; language_code?: string; words?: WordsItem[] }` | Finalisiertes Ergebnis mit Zeitangaben auf Wortebene. | Der Typ `WordsItem` enthält Zeitinformationen auf Wortebene: ```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 } ``` ### Verbindungs-Events | Event | Daten | Beschreibung | | --------- | ---------------- | --------------------------------- | | **OPEN** | `Event` | WebSocket-Verbindung geöffnet. | | **CLOSE** | `Event` | WebSocket-Verbindung geschlossen. | | **ERROR** | `Error \| Event` | Allgemeiner Fehler. | ### Fehler-Events Alle Fehler-Events empfangen `{ error: string }`. | Event | Beschreibung | | ------------------------------- | -------------------------------------------------------------------- | | **AUTH_ERROR** | Authentifizierungsfehler. | | **QUOTA_EXCEEDED** | Nutzungskontingent überschritten. | | **COMMIT_THROTTLED** | Commit-Anfrage gedrosselt. | | **TRANSCRIBER_ERROR** | Fehler der Transkriptions-Engine. | | **UNACCEPTED_TERMS** | Nutzungsbedingungen nicht akzeptiert. | | **RATE_LIMITED** | Rate-Limit erreicht. | | **INPUT_ERROR** | Ungültiges Eingabeformat. | | **QUEUE_OVERFLOW** | Verarbeitungswarteschlange voll. | | **RESOURCE_EXHAUSTED** | Serverressourcen ausgelastet. | | **SESSION_TIME_LIMIT_EXCEEDED** | Maximale Sitzungsdauer erreicht. | | **CHUNK_SIZE_EXCEEDED** | Audio-Chunk zu groß. | | **INSUFFICIENT_AUDIO_ACTIVITY** | Nicht genügend Audioaktivität, um die Verbindung aufrechtzuerhalten. | ## Commit-Strategien Steuern Sie, wann Transkriptionen übernommen werden: ```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, }); ``` Weitere Details finden Sie unter [Transkripte und Commit-Strategien](/docs/de/eleven-api/guides/how-to/speech-to-text/realtime/transcripts-and-commit-strategies). ## Vollständiges Beispiel Hier ist ein vollständiges Beispiel, das Mikrofonaudio mit einer VAD-basierten Commit-Strategie transkribiert: ```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); ```