Vai alla navigazione
RiferimentoLibrerie e SDKScribe (STT)

SDK JavaScript

Scribe: trascrizione vocale in tempo reale in JavaScript

Per una panoramica di Scribe e delle sue funzionalità, consulta la panoramica di Speech to Text . Per guide dettagliate sull’utilizzo, consulta lo streaming lato client.

Installazione

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

Usa la skill Speech to Text di ElevenLabs per trascrivere l’audio dal tuo assistente di programmazione IA:

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

Questa libreria può essere utilizzata in qualsiasi progetto basato su JavaScript. Se usi React, considera l’ hook useScribe, che offre la gestione integrata dello stato e del ciclo di vita.

Utilizzo

Ecco un esempio minimo funzionante che si connette a Scribe e registra i risultati della trascrizione:

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

Ottenere un token

Scribe richiede un token monouso per l’autenticazione. Crea un endpoint API sul tuo 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 });
});

La tua chiave API ElevenLabs è sensibile. Non esporla mai al client. Genera sempre il token sul server.

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

Opzioni di connessione

Scribe.connect() accetta opzioni per il microfono o opzioni audio manuali. Entrambe condividono un insieme comune di opzioni di base.

Opzioni di base

ProprietàTipoPredefinitoDescrizione
tokenstringToken monouso per l’autenticazione WebSocket.
modelIdstringID del modello (ad es. "scribe_v2_realtime").
baseUristring"wss://api.elevenlabs.io"URI di base WebSocket personalizzato.
commitStrategyCommitStrategy"manual""manual" o "vad".
vadSilenceThresholdSecsnumber1.5Secondi di silenzio prima che VAD esegua il commit (0.3-3.0).
vadThresholdnumber0.4Sensibilità VAD (0.1-0.9, valori più bassi sono più sensibili).
minSpeechDurationMsnumber100Durata minima del parlato in ms (50-2000).
minSilenceDurationMsnumber100Durata minima del silenzio in ms (50-2000).
languageCodestringCodice lingua ISO-639-1 o ISO-639-3. Lascia vuoto per il rilevamento automatico.
includeTimestampsbooleanfalseRicevi timestamp a livello di parola tramite l’evento COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS.

Opzioni del microfono

Passa un oggetto microphone per trasmettere l’audio direttamente dal microfono dell’utente. La connessione gestisce automaticamente getUserMedia e la codifica audio.

const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  microphone: {
    deviceId: "optional-device-id",
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});
ProprietàTipoDescrizione
deviceIdstringID di uno specifico dispositivo microfono.
echoCancellationbooleanAbilita la cancellazione dell’eco.
noiseSuppressionbooleanAbilita la soppressione del rumore.
autoGainControlbooleanAbilita il controllo automatico del guadagno.

Opzioni audio manuali

Passa audioFormat e sampleRate per inviare manualmente dati audio tramite connection.send().

import { AudioFormat } from "@elevenlabs/client";
const connection = Scribe.connect({
  token,
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  sampleRate: 16000,
});
ProprietàTipoDescrizione
audioFormatAudioFormatFormato di codifica audio (ad es. AudioFormat.PCM_16000).
sampleRatenumberFrequenza di campionamento in Hz. Deve corrispondere 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",
}

Modalità microfono

Trasmetti l’audio direttamente dal microfono dell’utente:

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

Modalità audio manuale (trascrizione di file)

Trascrivi file audio preregistrati inviando manualmente dati audio:

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() restituisce un’istanza di RealtimeConnection con i seguenti metodi.

on(event, listener)

Registra un listener di eventi. Consulta Eventi per i tipi di evento disponibili.

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

off(event, listener)

Rimuovi un listener di eventi registrato in precedenza.

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

send(data)

Invia dati audio a Scribe (solo modalità audio manuale).

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

Il campo previousText può essere inviato solo nel primo chunk audio di una sessione. Se lo invii nei chunk successivi, si verifica un errore.

commit()

Esegui manualmente il commit della trascrizione corrente. Necessario solo quando usi CommitStrategy.MANUAL.

connection.commit();

close()

Chiudi la connessione WebSocket e libera le risorse (stream del microfono, contesto audio).

connection.close();

Eventi

Registra listener di eventi con connection.on(event, listener). Tutti gli eventi sono disponibili come costanti nell’enum RealtimeEvents.

Eventi di trascrizione

EventoDatiDescrizione
SESSION_STARTED{ session_id: string }Sessione Scribe avviata.
PARTIAL_TRANSCRIPT{ text: string }Risultato della trascrizione provvisorio.
COMMITTED_TRANSCRIPT{ text: string }Risultato della trascrizione finalizzato.
COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS{ text: string; language_code?: string; words?: WordsItem[] }Risultato finalizzato con temporizzazione a livello di parola.

Il tipo WordsItem contiene informazioni sulla temporizzazione a livello di parola:

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
}

Eventi di connessione

EventoDatiDescrizione
OPENEventConnessione WebSocket aperta.
CLOSEEventConnessione WebSocket chiusa.
ERRORError | EventErrore generico.

Eventi di errore

Tutti gli eventi di errore ricevono { error: string }.

EventoDescrizione
AUTH_ERRORErrore di autenticazione.
QUOTA_EXCEEDEDQuota di utilizzo superata.
COMMIT_THROTTLEDRichiesta di commit limitata.
TRANSCRIBER_ERRORErrore del motore di trascrizione.
UNACCEPTED_TERMSTermini di servizio non accettati.
RATE_LIMITEDLimite di frequenza raggiunto.
INPUT_ERRORFormato di input non valido.
QUEUE_OVERFLOWCoda di elaborazione piena.
RESOURCE_EXHAUSTEDRisorse del server al limite della capacità.
SESSION_TIME_LIMIT_EXCEEDEDTempo massimo della sessione raggiunto.
CHUNK_SIZE_EXCEEDEDChunk audio troppo grande.
INSUFFICIENT_AUDIO_ACTIVITYAttività audio insufficiente per mantenere la connessione.

Strategie di commit

Controlla quando vengono eseguiti i commit delle trascrizioni:

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

Per maggiori dettagli, consulta Trascrizioni e strategie di commit.

Esempio completo

Ecco un esempio completo che trascrive l’audio del microfono con una strategia di commit basata su 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);