Skip to navigation
ReferentieBibliotheken & SDK'sScribe (STT)

JavaScript SDK

Scribe: realtime spraak-naar-teksttranscriptie in JavaScript

Voor een overzicht van Scribe en de mogelijkheden ervan, zie het overzicht van Speech to Text . Zie voor stapsgewijze gebruikshandleidingen streaming aan de clientzijde .

Installatie

npm install @elevenlabs/client
# or
yarn add @elevenlabs/client
# or
pnpm install @elevenlabs/client

Gebruik de ElevenLabs speech-to-text-skill om audio te transcriberen met je AI-codingassistent:

npx skills add elevenlabs/skills --skill speech-to-text

Deze bibliotheek kan worden gebruikt in elk project op basis van JavaScript. Als je React gebruikt, overweeg dan de useScribe hook, die ingebouwd statebeheer en lifecycleafhandeling biedt.

Gebruik

Hier is een minimaal werkend voorbeeld dat verbinding maakt met Scribe en transcriptieresultaten logt:

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();

Een token verkrijgen

Scribe vereist een token voor eenmalig gebruik voor authenticatie. Maak een API-endpoint op je server:

// 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 });
});

Je ElevenLabs API-sleutel is gevoelig. Stel deze nooit bloot aan de client. Genereer het token altijd op de server.

// Client
const fetchToken = async () => {
  const response = await fetch("/scribe-token");
  const { token } = await response.json();
  return token;
};

Verbindingsopties

Scribe.connect() accepteert microfoonopties of handmatige audio-opties. Beide delen een gemeenschappelijke set basisopties.

Basisopties

PropertyTypeStandaardwaardeBeschrijving
tokenstringToken voor eenmalig gebruik voor WebSocket-authenticatie.
modelIdstringModel-ID (bijv. "scribe_v2_realtime").
baseUristring"wss://api.elevenlabs.io"Aangepaste basis-URI voor WebSocket.
commitStrategyCommitStrategy"manual""manual" of "vad".
vadSilenceThresholdSecsnumber1.5Seconden stilte voordat VAD commit (0.3-3.0).
vadThresholdnumber0.4VAD-gevoeligheid (0.1-0.9, lager is gevoeliger).
minSpeechDurationMsnumber100Minimale spraakduur in ms (50-2000).
minSilenceDurationMsnumber100Minimale stilteduur in ms (50-2000).
languageCodestringISO-639-1- of ISO-639-3-taalcode. Laat leeg voor automatische detectie.
includeTimestampsbooleanfalseOntvang timestamps op woordniveau via de gebeurtenis COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS.

Microfoonopties

Geef een microphone-object door om audio rechtstreeks vanaf de microfoon van de gebruiker te streamen. De verbinding handelt getUserMedia en audiocodering automatisch af.

const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  microphone: {
    deviceId: "optional-device-id",
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});
PropertyTypeBeschrijving
deviceIdstringID van een specifiek microfoonapparaat.
echoCancellationbooleanSchakel echo-onderdrukking in.
noiseSuppressionbooleanSchakel ruisonderdrukking in.
autoGainControlbooleanSchakel automatische gain control in.

Handmatige audio-opties

Geef audioFormat en sampleRate door om audiogegevens handmatig te versturen via connection.send().

import { AudioFormat } from "@elevenlabs/client";
const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  sampleRate: 16000,
});
PropertyTypeBeschrijving
audioFormatAudioFormatAudiocoderingsformaat (bijv. AudioFormat.PCM_16000).
sampleRatenumberSample rate in Hz. Moet overeenkomen met audioFormat.

AudioFormat-enum

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",
}

Microfoonmodus

Stream audio rechtstreeks vanaf de microfoon van de gebruiker:

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();
  });
}

Handmatige audiomodus (bestandstranscriptie)

Transcribeer vooraf opgenomen audiobestanden door audiogegevens handmatig te versturen:

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() retourneert een RealtimeConnection-instance met de volgende methoden.

on(event, listener)

Registreer een event listener. Zie Events voor beschikbare eventtypen.

connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
  console.log("Committed:", data.text);
});

off(event, listener)

Verwijder een eerder geregistreerde event listener.

const handler = (data) => console.log(data.text);
connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, handler);
// Later
connection.off(RealtimeEvents.COMMITTED_TRANSCRIPT, handler);

send(data)

Verstuur audiogegevens naar Scribe (alleen handmatige audiomodus).

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
});

Het veld previousText kan alleen worden verstuurd in het eerste audiochunk van een sessie. Het versturen ervan in volgende chunks leidt tot een fout.

commit()

Commit de huidige transcriptie handmatig. Alleen nodig bij gebruik van CommitStrategy.MANUAL.

connection.commit();

close()

Sluit de WebSocket-verbinding en ruim resources op (microfoonstream, audiocontext).

connection.close();

Events

Registreer event listeners met connection.on(event, listener). Alle events zijn beschikbaar als constanten in de RealtimeEvents-enum.

Transcriptie-events

EventGegevensBeschrijving
SESSION_STARTED{ session_id: string }Scribe-sessie gestart.
PARTIAL_TRANSCRIPT{ text: string }Tussentijds transcriptieresultaat.
COMMITTED_TRANSCRIPT{ text: string }Definitief transcriptieresultaat.
COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS{ text: string; language_code?: string; words?: WordsItem[] }Definitief resultaat met timing op woordniveau.

Het type WordsItem bevat timinginformatie op woordniveau:

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
}

Verbindings-events

EventGegevensBeschrijving
OPENEventWebSocket-verbinding geopend.
CLOSEEventWebSocket-verbinding gesloten.
ERRORError | EventAlgemene fout.

Fout-events

Alle fout-events ontvangen { error: string }.

EventBeschrijving
AUTH_ERRORAuthenticatiefout.
QUOTA_EXCEEDEDGebruiksquotum overschreden.
COMMIT_THROTTLEDCommitrequest beperkt.
TRANSCRIBER_ERRORFout in transcriptie-engine.
UNACCEPTED_TERMSServicevoorwaarden niet geaccepteerd.
RATE_LIMITEDRate limit bereikt.
INPUT_ERROROngeldige invoerindeling.
QUEUE_OVERFLOWVerwerkingswachtrij vol.
RESOURCE_EXHAUSTEDServerresources hebben hun capaciteit bereikt.
SESSION_TIME_LIMIT_EXCEEDEDMaximale sessieduur bereikt.
CHUNK_SIZE_EXCEEDEDAudiochunk te groot.
INSUFFICIENT_AUDIO_ACTIVITYNiet genoeg audioactiviteit om de verbinding te behouden.

Commitstrategieën

Bepaal wanneer transcripties worden gecommit:

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,
});

Zie Transcripten en commitstrategieën voor meer details.

Volledig voorbeeld

Hier is een volledig voorbeeld dat microfoonaudio transcribeert met een op VAD gebaseerde commitstrategie:

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);