JavaScript SDK | ElevenLabs Documentation

För en översikt över Scribe och dess funktioner, se översikten över Speech to Text . För stegvisa användarguider, se streaming på klientsidan .

Installation

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

Använd ElevenLabs speech-to-text skill för att transkribera ljud från din AI-kodassistent:

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

Det här biblioteket kan användas i alla JavaScript-baserade projekt. Om du använder React kan du överväga useScribe hook, som erbjuder inbyggd tillståndshantering och hantering av livscykeln.

Användning

Här är ett minimalt fungerande exempel som ansluter till Scribe och loggar transkriberingsresultat:

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

Hämta en token

Scribe kräver en engångstoken för autentisering. Skapa en API-slutpunkt på din 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 });
});

Din ElevenLabs API-nyckel är känslig. Exponera den aldrig för klienten. Generera alltid token på servern.

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

Anslutningsalternativ

Scribe.connect() accepterar antingen mikrofonalternativ eller manuella ljudalternativ. Båda delar en gemensam uppsättning grundalternativ.

Grundalternativ

Egenskap	Typ	Standard	Beskrivning
token	`string`		Engångstoken för WebSocket-autentisering.
modelId	`string`		Modell-ID (t.ex. `"scribe_v2_realtime"`).
baseUri	`string`	`"wss://api.elevenlabs.io"`	Anpassad WebSocket-bas-URI.
commitStrategy	`CommitStrategy`	`"manual"`	`"manual"` eller `"vad"`.
vadSilenceThresholdSecs	`number`	`1.5`	Sekunder av tystnad innan VAD verkställer (0.3-3.0).
vadThreshold	`number`	`0.4`	VAD-känslighet (0.1-0.9, lägre är känsligare).
minSpeechDurationMs	`number`	`100`	Minsta talvaraktighet i ms (50-2000).
minSilenceDurationMs	`number`	`100`	Minsta tystnadsvaraktighet i ms (50-2000).
languageCode	`string`		ISO-639-1- eller ISO-639-3-språkkod. Lämna tomt för automatisk identifiering.
includeTimestamps	`boolean`	`false`	Ta emot tidsstämplar på ordnivå via händelsen `COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS`.

Mikrofonalternativ

Skicka ett microphone-objekt för att strömma ljud direkt från användarens mikrofon. Anslutningen hanterar getUserMedia och ljudkodning automatiskt.

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

Egenskap	Typ	Beskrivning
deviceId	`string`	ID för specifik mikrofonenhet.
echoCancellation	`boolean`	Aktivera ekoreducering.
noiseSuppression	`boolean`	Aktivera brusreducering.
autoGainControl	`boolean`	Aktivera automatisk gainkontroll.

Manuella ljudalternativ

Skicka audioFormat och sampleRate för att skicka ljuddata manuellt via connection.send().

import { AudioFormat } from "@elevenlabs/client";
const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  sampleRate: 16000,
});

Egenskap	Typ	Beskrivning
audioFormat	`AudioFormat`	Ljudkodningsformat (t.ex. `AudioFormat.PCM_16000`).
sampleRate	`number`	Samplingsfrekvens i Hz. Måste matcha `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",
}

Mikrofonläge

Strömma ljud direkt från användarens mikrofon:

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

Manuellt ljudläge (filtranskribering)

Transkribera förinspelade ljudfiler genom att skicka ljuddata manuellt:

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() returnerar en RealtimeConnection-instans med följande metoder.

on(event, listener)

Registrera en händelselyssnare. Se Händelser för tillgängliga händelsetyper.

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

off(event, listener)

Ta bort en tidigare registrerad händelselyssnare.

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

send(data)

Skicka ljuddata till Scribe (endast manuellt ljudläge).

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

Fältet previousText kan endast skickas i en sessions första ljudchunk. Om det skickas i efterföljande chunkar uppstår ett fel.

commit()

Verkställ den aktuella transkriberingen manuellt. Behövs endast när du använder CommitStrategy.MANUAL.

connection.commit();

close()

Stäng WebSocket-anslutningen och frigör resurser (mikrofonström, ljudkontext).

connection.close();

Händelser

Registrera händelselyssnare med connection.on(event, listener). Alla händelser finns tillgängliga som konstanter i RealtimeEvents-enumen.

Transkriberingshändelser

Händelse	Data	Beskrivning
SESSION_STARTED	`{ session_id: string }`	Scribe-sessionen har startat.
PARTIAL_TRANSCRIPT	`{ text: string }`	Tillfälligt transkriberingsresultat.
COMMITTED_TRANSCRIPT	`{ text: string }`	Slutligt transkriberingsresultat.
COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS	`{ text: string; language_code?: string; words?: WordsItem[] }`	Slutligt resultat med tid på ordnivå.

Typen WordsItem innehåller tidsinformation på ordnivå:

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
}

Anslutningshändelser

Händelse	Data	Beskrivning
OPEN	`Event`	WebSocket-anslutningen öppnad.
CLOSE	`Event`	WebSocket-anslutningen stängd.
ERROR	`Error \| Event`	Allmänt fel.

Felhändelser

Alla felhändelser tar emot { error: string }.

Händelse	Beskrivning
AUTH_ERROR	Autentiseringsfel.
QUOTA_EXCEEDED	Användningskvoten har överskridits.
COMMIT_THROTTLED	Verkställandebegäran har begränsats.
TRANSCRIBER_ERROR	Fel i transkriberingsmotorn.
UNACCEPTED_TERMS	Användarvillkoren har inte godkänts.
RATE_LIMITED	Hastighetsbegränsad.
INPUT_ERROR	Ogiltigt inmatningsformat.
QUEUE_OVERFLOW	Bearbetningskön är full.
RESOURCE_EXHAUSTED	Serverresurserna är fullt utnyttjade.
SESSION_TIME_LIMIT_EXCEEDED	Maximal sessionstid har uppnåtts.
CHUNK_SIZE_EXCEEDED	Ljudchunken är för stor.
INSUFFICIENT_AUDIO_ACTIVITY	Inte tillräcklig ljudaktivitet för att behålla anslutningen.

Verkställandestrategier

Styr när transkriberingar verkställs:

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

Mer information finns i Transkript och verkställandestrategier.

Komplett exempel

Här är ett komplett exempel som transkriberar mikrofonljud med VAD-baserad verkställandestrategi:

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