Hoppa till navigering

JavaScript SDK

Scribe: tal-till-text-transkribering i realtid i JavaScript

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

Installation

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

Använd ElevenLabs färdighet för tal till text för att transkribera ljud från din AI-kodningsassistent:

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 bör du överväga hooken useScribe, som har inbyggd hantering av tillstånd och livscykel.

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_v3_live",
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 token för engångsanvändning 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

EgenskapTypStandardBeskrivning
tokenstringToken för engångsanvändning för WebSocket-autentisering.
modelIdstringModell-ID (t.ex. "scribe_v3_live").
baseUristring"wss://api.elevenlabs.io"Anpassad WebSocket-bas-URI.
commitStrategyCommitStrategy"manual""manual" eller "vad".
vadSilenceThresholdSecsnumber1.5Sekunder av tystnad innan VAD sparar (0.3–3.0).
vadThresholdnumber0.4VAD-känslighet (0.1–0.9, lägre är känsligare).
minSpeechDurationMsnumber100Minsta talvaraktighet i ms (50–2000).
minSilenceDurationMsnumber100Minsta tystnadsvaraktighet i ms (50–2000).
languageCodestringISO-639-1- eller ISO-639-3-språkkod. Lämna tomt för automatisk identifiering.
includeTimestampsbooleanfalseTa 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_v3_live",
microphone: {
deviceId: "optional-device-id",
echoCancellation: true,
noiseSuppression: true,
autoGainControl: true,
},
});
EgenskapTypBeskrivning
deviceIdstringID för en specifik mikrofonenhet.
echoCancellationbooleanAktivera ekoreducering.
noiseSuppressionbooleanAktivera brusreducering.
autoGainControlbooleanAktivera automatisk nivåkontroll.

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_v3_live",
audioFormat: AudioFormat.PCM_16000,
sampleRate: 16000,
});
EgenskapTypBeskrivning
audioFormatAudioFormatLjudkodningsformat (t.ex. AudioFormat.PCM_16000).
sampleRatenumberSamplingsfrekvens 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_v3_live",
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_v3_live",
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 bara skickas i en sessions första ljudsegment. Om det skickas i efterföljande segment uppstår ett fel.

commit()

Spara den aktuella transkriberingen manuellt. Behövs bara 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 som konstanter i enumen RealtimeEvents.

Transkriberingshändelser

HändelseDataBeskrivning
SESSION_STARTED{ session_id: string }Scribe-session startad.
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 tidsangivelser 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ändelseDataBeskrivning
OPENEventWebSocket-anslutning öppnad.
CLOSEEventWebSocket-anslutning stängd.
ERRORError | EventAllmänt fel.

Felhändelser

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

HändelseBeskrivning
AUTH_ERRORAutentiseringsfel.
QUOTA_EXCEEDEDAnvändningskvoten har överskridits.
COMMIT_THROTTLEDCommit-begäran har begränsats.
TRANSCRIBER_ERRORFel i transkriberingsmotorn.
UNACCEPTED_TERMSAnvändarvillkoren har inte godkänts.
RATE_LIMITEDHastighetsbegränsad.
INPUT_ERROROgiltigt inmatningsformat.
QUEUE_OVERFLOWBearbetningskön är full.
RESOURCE_EXHAUSTEDServerresurserna är fullt utnyttjade.
SESSION_TIME_LIMIT_EXCEEDEDMaximal sessionstid har uppnåtts.
CHUNK_SIZE_EXCEEDEDLjudsegmentet är för stort.
INSUFFICIENT_AUDIO_ACTIVITYInte tillräckligt med ljudaktivitet för att behålla anslutningen.

Commit-strategier

Styr när transkriberingar sparas:

import { Scribe, CommitStrategy } from '@elevenlabs/client';
// Manual (default): you control when to commit
const connection = Scribe.connect({
token,
modelId: 'scribe_v3_live',
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_v3_live',
microphone: { echoCancellation: true },
commitStrategy: CommitStrategy.VAD,
});

Mer information finns i Transkriptioner och commit-strategier.

Fullständigt exempel

Här är ett fullständigt exempel som transkriberar mikrofonljud med VAD-baserad commit-strategi:

import { Scribe, RealtimeEvents, CommitStrategy } from "@elevenlabs/client";
async function startTranscription() {
const token = await fetchToken();
const connection = Scribe.connect({
token,
modelId: "scribe_v3_live",
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);