> 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**
>
> Voor een overzicht van Scribe en de mogelijkheden ervan, zie het [overzicht van Speech to Text ](/docs/nl/capabilities/speech-to-text). Zie voor stapsgewijze gebruikshandleidingen [streaming aan de clientzijde ](/docs/nl/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming).

## Installatie

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

> **Tip**
>
> Gebruik de [ElevenLabs speech-to-text-skill](https://github.com/elevenlabs/skills/tree/main/speech-to-text) om audio te transcriberen met je AI-codingassistent:
>
> ```bash
> npx skills add elevenlabs/skills --skill speech-to-text
> ```

> **Note**
>
> Deze bibliotheek kan worden gebruikt in elk project op basis van JavaScript. Als je React gebruikt, overweeg dan de
> [`useScribe` hook](/docs/nl/eleven-api/resources/libraries/scribe-stt/react-scribe), die ingebouwd
> statebeheer en lifecycleafhandeling biedt.

## Gebruik

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

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

## Een token verkrijgen

Scribe vereist een token voor eenmalig gebruik voor authenticatie. Maak een API-endpoint op je 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**
>
> Je ElevenLabs API-sleutel is gevoelig. Stel deze nooit bloot aan de client. Genereer het token altijd op
> de server.

```js
// 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

| Property                    | Type             | Standaardwaarde             | Beschrijving                                                                                 |
| --------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------------------------- |
| **token**                   | `string`         |                             | Token voor eenmalig gebruik voor WebSocket-authenticatie.                                    |
| **modelId**                 | `string`         |                             | Model-ID (bijv. `"scribe_v2_realtime"`).                                                     |
| **baseUri**                 | `string`         | `"wss://api.elevenlabs.io"` | Aangepaste basis-URI voor WebSocket.                                                         |
| **commitStrategy**          | `CommitStrategy` | `"manual"`                  | `"manual"` of `"vad"`.                                                                       |
| **vadSilenceThresholdSecs** | `number`         | `1.5`                       | Seconden stilte voordat VAD commit (0.3-3.0).                                                |
| **vadThreshold**            | `number`         | `0.4`                       | VAD-gevoeligheid (0.1-0.9, lager is gevoeliger).                                             |
| **minSpeechDurationMs**     | `number`         | `100`                       | Minimale spraakduur in ms (50-2000).                                                         |
| **minSilenceDurationMs**    | `number`         | `100`                       | Minimale stilteduur in ms (50-2000).                                                         |
| **languageCode**            | `string`         |                             | ISO-639-1- of ISO-639-3-taalcode. Laat leeg voor automatische detectie.                      |
| **includeTimestamps**       | `boolean`        | `false`                     | Ontvang 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.

```js
const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  microphone: {
    deviceId: "optional-device-id",
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});
```

| Property             | Type      | Beschrijving                            |
| -------------------- | --------- | --------------------------------------- |
| **deviceId**         | `string`  | ID van een specifiek microfoonapparaat. |
| **echoCancellation** | `boolean` | Schakel echo-onderdrukking in.          |
| **noiseSuppression** | `boolean` | Schakel ruisonderdrukking in.           |
| **autoGainControl**  | `boolean` | Schakel automatische gain control in.   |

### Handmatige audio-opties

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

```js
import { AudioFormat } from "@elevenlabs/client";

const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  sampleRate: 16000,
});
```

| Property        | Type          | Beschrijving                                            |
| --------------- | ------------- | ------------------------------------------------------- |
| **audioFormat** | `AudioFormat` | Audiocoderingsformaat (bijv. `AudioFormat.PCM_16000`).  |
| **sampleRate**  | `number`      | Sample rate in Hz. Moet overeenkomen met `audioFormat`. |

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

## Microfoonmodus

Stream audio rechtstreeks vanaf de microfoon van de gebruiker:

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

## Handmatige audiomodus (bestandstranscriptie)

Transcribeer vooraf opgenomen audiobestanden door audiogegevens handmatig te versturen:

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

### on(event, listener)

Registreer een event listener. Zie [Events](#events) voor beschikbare eventtypen.

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

### off(event, listener)

Verwijder een eerder geregistreerde 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)

Verstuur audiogegevens naar Scribe (alleen handmatige 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**
>
> 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`.

```js
connection.commit();
```

### close()

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

```js
connection.close();
```

## Events

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

### Transcriptie-events

| Event                                       | Gegevens                                                        | Beschrijving                                    |
| ------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
| **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:

```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
}
```

### Verbindings-events

| Event     | Gegevens         | Beschrijving                   |
| --------- | ---------------- | ------------------------------ |
| **OPEN**  | `Event`          | WebSocket-verbinding geopend.  |
| **CLOSE** | `Event`          | WebSocket-verbinding gesloten. |
| **ERROR** | `Error \| Event` | Algemene fout.                 |

### Fout-events

Alle fout-events ontvangen `{ error: string }`.

| Event                              | Beschrijving                                              |
| ---------------------------------- | --------------------------------------------------------- |
| **AUTH\_ERROR**                    | Authenticatiefout.                                        |
| **QUOTA\_EXCEEDED**                | Gebruiksquotum overschreden.                              |
| **COMMIT\_THROTTLED**              | Commitrequest beperkt.                                    |
| **TRANSCRIBER\_ERROR**             | Fout in transcriptie-engine.                              |
| **UNACCEPTED\_TERMS**              | Servicevoorwaarden niet geaccepteerd.                     |
| **RATE\_LIMITED**                  | Rate limit bereikt.                                       |
| **INPUT\_ERROR**                   | Ongeldige invoerindeling.                                 |
| **QUEUE\_OVERFLOW**                | Verwerkingswachtrij vol.                                  |
| **RESOURCE\_EXHAUSTED**            | Serverresources hebben hun capaciteit bereikt.            |
| **SESSION\_TIME\_LIMIT\_EXCEEDED** | Maximale sessieduur bereikt.                              |
| **CHUNK\_SIZE\_EXCEEDED**          | Audiochunk te groot.                                      |
| **INSUFFICIENT\_AUDIO\_ACTIVITY**  | Niet genoeg audioactiviteit om de verbinding te behouden. |

## Commitstrategieën

Bepaal wanneer transcripties worden gecommit:

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

Zie [Transcripten en commitstrategieën](/docs/nl/eleven-api/guides/how-to/speech-to-text/realtime/transcripts-and-commit-strategies) voor meer details.

## Volledig voorbeeld

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

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