Ir para a navegação

SDK JavaScript

Scribe: transcrição de voz em tempo real em JavaScript

Para uma visão geral do Scribe e seus recursos, consulte a visão geral do Speech to Text . Para guias de uso passo a passo, consulte streaming no lado do cliente .

Instalação

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

Use a skill de Speech to Text da ElevenLabs para transcrever áudio com seu assistente de programação com IA:

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

Esta biblioteca pode ser usada em qualquer projeto baseado em JavaScript. Se você usa React, considere o hook useScribe, que oferece gerenciamento de estado e controle de ciclo de vida integrados.

Uso

Veja um exemplo mínimo funcional que se conecta ao Scribe e registra os resultados da transcrição:

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

Como obter um token

O Scribe exige um token de uso único para autenticação. Crie um endpoint de API no seu servidor:

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

Sua chave de API da ElevenLabs é sensível. Nunca a exponha ao cliente. Sempre gere o token no servidor.

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

Opções de conexão

Scribe.connect() aceita opções de microfone ou opções de áudio manual. Ambas compartilham um conjunto comum de opções básicas.

Opções básicas

PropriedadeTipoPadrãoDescrição
tokenstringToken de uso único para autenticação WebSocket.
modelIdstringID do modelo (por exemplo, "scribe_v3_live").
baseUristring"wss://api.elevenlabs.io"URI base personalizada do WebSocket.
commitStrategyCommitStrategy"manual""manual" ou "vad".
vadSilenceThresholdSecsnumber1.5Segundos de silêncio antes de o VAD confirmar (0.3-3.0).
vadThresholdnumber0.4Sensibilidade do VAD (0.1-0.9; quanto menor, mais sensível).
minSpeechDurationMsnumber100Duração mínima de fala em ms (50-2000).
minSilenceDurationMsnumber100Duração mínima de silêncio em ms (50-2000).
languageCodestringCódigo de idioma ISO-639-1 ou ISO-639-3. Deixe vazio para detecção automática.
includeTimestampsbooleanfalseReceba marcações de tempo por palavra pelo evento COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS.

Opções de microfone

Passe um objeto microphone para transmitir áudio diretamente do microfone do usuário. A conexão gerencia getUserMedia e a codificação de áudio automaticamente.

const connection = Scribe.connect({
token,
modelId: "scribe_v3_live",
microphone: {
deviceId: "optional-device-id",
echoCancellation: true,
noiseSuppression: true,
autoGainControl: true,
},
});
PropriedadeTipoDescrição
deviceIdstringID específico do dispositivo de microfone.
echoCancellationbooleanAtiva o cancelamento de eco.
noiseSuppressionbooleanAtiva a supressão de ruído.
autoGainControlbooleanAtiva o controle automático de ganho.

Opções de áudio manual

Passe audioFormat e sampleRate para enviar dados de áudio manualmente por meio de connection.send().

import { AudioFormat } from "@elevenlabs/client";
const connection = Scribe.connect({
token,
modelId: "scribe_v3_live",
audioFormat: AudioFormat.PCM_16000,
sampleRate: 16000,
});
PropriedadeTipoDescrição
audioFormatAudioFormatFormato de codificação de áudio (por exemplo, AudioFormat.PCM_16000).
sampleRatenumberTaxa de amostragem em Hz. Deve corresponder a audioFormat.

Enum AudioFormat

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

Modo microfone

Transmita áudio diretamente do microfone do usuário:

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

Modo de áudio manual (transcrição de arquivo)

Transcreva arquivos de áudio pré-gravados enviando os dados de áudio manualmente:

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() retorna uma instância de RealtimeConnection com os seguintes métodos.

on(event, listener)

Registre um listener de evento. Consulte Eventos para ver os tipos de evento disponíveis.

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

off(event, listener)

Remova um listener de evento registrado anteriormente.

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

send(data)

Envie dados de áudio para o Scribe (somente no modo de áudio manual).

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

O campo previousText só pode ser enviado no primeiro bloco de áudio de uma sessão. Enviá-lo em blocos subsequentes resulta em erro.

commit()

Confirme manualmente a transcrição atual. Necessário apenas ao usar CommitStrategy.MANUAL.

connection.commit();

close()

Feche a conexão WebSocket e libere recursos (stream do microfone, contexto de áudio).

connection.close();

Eventos

Registre listeners de evento usando connection.on(event, listener). Todos os eventos estão disponíveis como constantes no enum RealtimeEvents.

Eventos de transcrição

EventoDadosDescrição
SESSION_STARTED{ session_id: string }Sessão do Scribe iniciada.
PARTIAL_TRANSCRIPT{ text: string }Resultado provisório da transcrição.
COMMITTED_TRANSCRIPT{ text: string }Resultado finalizado da transcrição.
COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS{ text: string; language_code?: string; words?: WordsItem[] }Resultado finalizado com tempo por palavra.

O tipo WordsItem contém informações de tempo por palavra:

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
}

Eventos de conexão

EventoDadosDescrição
OPENEventConexão WebSocket aberta.
CLOSEEventConexão WebSocket fechada.
ERRORError | EventErro genérico.

Eventos de erro

Todos os eventos de erro recebem { error: string }.

EventoDescrição
AUTH_ERRORErro de autenticação.
QUOTA_EXCEEDEDCota de uso excedida.
COMMIT_THROTTLEDSolicitação de confirmação limitada.
TRANSCRIBER_ERRORErro do mecanismo de transcrição.
UNACCEPTED_TERMSTermos de serviço não aceitos.
RATE_LIMITEDLimite de taxa atingido.
INPUT_ERRORFormato de entrada inválido.
QUEUE_OVERFLOWFila de processamento cheia.
RESOURCE_EXHAUSTEDRecursos do servidor no limite.
SESSION_TIME_LIMIT_EXCEEDEDTempo máximo da sessão atingido.
CHUNK_SIZE_EXCEEDEDBloco de áudio grande demais.
INSUFFICIENT_AUDIO_ACTIVITYAtividade de áudio insuficiente para manter a conexão.

Estratégias de confirmação

Controle quando as transcrições são confirmadas:

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

Para mais detalhes, consulte Transcrições e estratégias de confirmação.

Exemplo completo

Veja um exemplo completo que transcreve áudio do microfone com uma estratégia de confirmação baseada em VAD:

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