> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # SDK de JavaScript > **Info** > > Para obtener una visión general de Scribe y sus funciones, consulta la [visión general de Voz a Texto ](/docs/es/capabilities/speech-to-text). Para ver guías de uso paso a paso, consulta [streaming del lado del cliente](/docs/es/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming). ## Instalación ```shell npm install @elevenlabs/client # or yarn add @elevenlabs/client # or pnpm install @elevenlabs/client ``` > **Tip** > > Usa la [skill de voz a texto de ElevenLabs](https://github.com/elevenlabs/skills/tree/main/speech-to-text) para transcribir audio desde tu asistente de programación con IA: > > ```bash > npx skills add elevenlabs/skills --skill speech-to-text > ``` > **Note** > > Esta biblioteca se puede usar en cualquier proyecto basado en JavaScript. Si usas React, considera el > [hook `useScribe`](/docs/es/eleven-api/resources/libraries/scribe-stt/react-scribe), que proporciona > gestión de estado y control del ciclo de vida integrados. ## Uso Este es un ejemplo funcional mínimo que se conecta a Scribe y registra los resultados de la transcripción: ```js 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(); ``` ## Obtener un token Scribe requiere un token de un solo uso para la autenticación. Crea una ruta de API en tu servidor: ```js // 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 }); }); ``` > **Warning** > > Tu clave de API de ElevenLabs es confidencial. No la expongas nunca al cliente. Genera siempre el token en > el servidor. ```js // Client const fetchToken = async () => { const response = await fetch("/scribe-token"); const { token } = await response.json(); return token; }; ``` ## Opciones de conexión `Scribe.connect()` acepta opciones de micrófono u opciones de audio manual. Ambas comparten un conjunto común de opciones básicas. ### Opciones básicas | Propiedad | Tipo | Predeterminado | Descripción | | --------------------------- | ---------------- | --------------------------- | ---------------------------------------------------------------------------------------------- | | **token** | `string` | | Token de un solo uso para la autenticación de WebSocket. | | **modelId** | `string` | | ID del modelo (por ejemplo, `"scribe_v2_realtime"`). | | **baseUri** | `string` | `"wss://api.elevenlabs.io"` | URI base personalizada de WebSocket. | | **commitStrategy** | `CommitStrategy` | `"manual"` | `"manual"` o `"vad"`. | | **vadSilenceThresholdSecs** | `number` | `1.5` | Segundos de silencio antes de que VAD confirme (0.3-3.0). | | **vadThreshold** | `number` | `0.4` | Sensibilidad de VAD (0.1-0.9; los valores menores son más sensibles). | | **minSpeechDurationMs** | `number` | `100` | Duración mínima de voz en ms (50-2000). | | **minSilenceDurationMs** | `number` | `100` | Duración mínima de silencio en ms (50-2000). | | **languageCode** | `string` | | Código de idioma ISO-639-1 o ISO-639-3. Déjalo vacío para la detección automática. | | **includeTimestamps** | `boolean` | `false` | Recibe marcas de tiempo por palabra mediante el evento `COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS`. | ### Opciones de micrófono Pasa un objeto `microphone` para transmitir audio directamente desde el micrófono del usuario. La conexión gestiona `getUserMedia` y la codificación de audio automáticamente. ```js const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", microphone: { deviceId: "optional-device-id", echoCancellation: true, noiseSuppression: true, autoGainControl: true, }, }); ``` | Propiedad | Tipo | Descripción | | -------------------- | --------- | ------------------------------------------- | | **deviceId** | `string` | ID del dispositivo de micrófono específico. | | **echoCancellation** | `boolean` | Activa la cancelación de eco. | | **noiseSuppression** | `boolean` | Activa la supresión de ruido. | | **autoGainControl** | `boolean` | Activa el control automático de ganancia. | ### Opciones de audio manual Pasa `audioFormat` y `sampleRate` para enviar datos de audio manualmente mediante `connection.send()`. ```js import { AudioFormat } from "@elevenlabs/client"; const connection = Scribe.connect({ token, modelId: "scribe_v2_realtime", audioFormat: AudioFormat.PCM_16000, sampleRate: 16000, }); ``` | Propiedad | Tipo | Descripción | | --------------- | ------------- | ------------------------------------------------------------------------ | | **audioFormat** | `AudioFormat` | Formato de codificación de audio (por ejemplo, `AudioFormat.PCM_16000`). | | **sampleRate** | `number` | Frecuencia de muestreo en Hz. Debe coincidir con `audioFormat`. | #### Enumeración AudioFormat ```typescript 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 micrófono Transmite audio directamente desde el micrófono del usuario: ```js 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 de audio manual (transcripción de archivos) Transcribe archivos de audio pregrabados enviando los datos de audio manualmente: ```js 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()` devuelve una instancia de `RealtimeConnection` con los siguientes métodos. ### on(event, listener) Registra un listener de eventos. Consulta [Eventos](#events) para conocer los tipos de eventos disponibles. ```js connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => { console.log("Committed:", data.text); }); ``` ### off(event, listener) Elimina un listener de eventos registrado anteriormente. ```js const handler = (data) => console.log(data.text); connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, handler); // Later connection.off(RealtimeEvents.COMMITTED_TRANSCRIPT, handler); ``` ### send(data) Envía datos de audio a Scribe (solo en modo de audio manual). ```js 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 }); ``` > **Warning** > > El campo `previousText` solo se puede enviar en el primer fragmento de audio de una sesión. Enviarlo en > fragmentos posteriores provoca un error. ### commit() Confirma manualmente la transcripción actual. Solo es necesario al usar `CommitStrategy.MANUAL`. ```js connection.commit(); ``` ### close() Cierra la conexión WebSocket y libera recursos (flujo del micrófono, contexto de audio). ```js connection.close(); ``` ## Eventos Registra listeners de eventos mediante `connection.on(event, listener)`. Todos los eventos están disponibles como constantes en la enumeración `RealtimeEvents`. ### Eventos de transcripción | Evento | Datos | Descripción | | ---------------------------------------- | --------------------------------------------------------------- | --------------------------------------------- | | **SESSION_STARTED** | `{ session_id: string }` | Sesión de Scribe iniciada. | | **PARTIAL_TRANSCRIPT** | `{ text: string }` | Resultado de transcripción provisional. | | **COMMITTED_TRANSCRIPT** | `{ text: string }` | Resultado de transcripción finalizado. | | **COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS** | `{ text: string; language_code?: string; words?: WordsItem[] }` | Resultado finalizado con tiempos por palabra. | El tipo `WordsItem` contiene información de tiempo por palabra: ```typescript 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 conexión | Evento | Datos | Descripción | | --------- | ---------------- | --------------------------- | | **OPEN** | `Event` | Conexión WebSocket abierta. | | **CLOSE** | `Event` | Conexión WebSocket cerrada. | | **ERROR** | `Error \| Event` | Error genérico. | ### Eventos de error Todos los eventos de error reciben `{ error: string }`. | Evento | Descripción | | ------------------------------- | --------------------------------------------------------------- | | **AUTH_ERROR** | Error de autenticación. | | **QUOTA_EXCEEDED** | Cuota de uso superada. | | **COMMIT_THROTTLED** | Solicitud de confirmación limitada. | | **TRANSCRIBER_ERROR** | Error del motor de transcripción. | | **UNACCEPTED_TERMS** | Términos de servicio no aceptados. | | **RATE_LIMITED** | Límite de frecuencia alcanzado. | | **INPUT_ERROR** | Formato de entrada no válido. | | **QUEUE_OVERFLOW** | Cola de procesamiento llena. | | **RESOURCE_EXHAUSTED** | Recursos del servidor al límite. | | **SESSION_TIME_LIMIT_EXCEEDED** | Se ha alcanzado el tiempo máximo de sesión. | | **CHUNK_SIZE_EXCEEDED** | Fragmento de audio demasiado grande. | | **INSUFFICIENT_AUDIO_ACTIVITY** | No hay suficiente actividad de audio para mantener la conexión. | ## Estrategias de confirmación Controla cuándo se confirman las transcripciones: ```js 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 más información, consulta [Transcripciones y estrategias de confirmación](/docs/es/eleven-api/guides/how-to/speech-to-text/realtime/transcripts-and-commit-strategies). ## Ejemplo completo Este es un ejemplo completo que transcribe audio del micrófono con una estrategia de confirmación basada en VAD: ```js 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); ```