ReferênciaBibliotecas e SDKsScribe (STT)

SDK JavaScript

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

Para uma visão geral do Scribe e dos seus recursos, consulte a visão geral do Speech to Text . Para guias de uso passo a passo, consulte streaming do 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 do 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_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();

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 é confidencial. 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 manuais de áudio. 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_v2_realtime").
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 da fala em ms (50-2000).
minSilenceDurationMsnumber100Duração mínima do 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 timestamps 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_v2_realtime",
  microphone: {
    deviceId: "optional-device-id",
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});
PropriedadeTipoDescrição
deviceIdstringID do dispositivo de microfone específico.
echoCancellationbooleanAtiva o cancelamento de eco.
noiseSuppressionbooleanAtiva a supressão de ruído.
autoGainControlbooleanAtiva o controle automático de ganho.

Opções manuais de áudio

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_v2_realtime",
  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 de 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_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();
  });
}

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

Transcreva arquivos de áudio pré-gravados enviando 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_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() retorna uma instância de RealtimeConnection com os seguintes métodos.

on(event, listener)

Registre um ouvinte 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 ouvinte 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 ao Scribe (somente no modo manual de áudio).

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 trecho de áudio de uma sessão. Enviá-lo em trechos posteriores causa um erro.

commit()

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

connection.commit();

close()

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

connection.close();

Eventos

Registre ouvintes de eventos 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 parcial 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 marcações 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 de capacidade.
SESSION_TIME_LIMIT_EXCEEDEDTempo máximo da sessão atingido.
CHUNK_SIZE_EXCEEDEDTrecho de áudio muito grande.
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_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,
});

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