SDK Javascript
Visión general
El skd en javascript es un cliente liviano para interactuar con la api de Speaqr en tiempo real. Facilita al programador el acceso a los métodos de la api dándole resueltas ciertas funcionalidades. Es compatible con entornos de navegador y de Node.jsEl paquete esta publicado en npm.Para usar el SDK necesitas un api key válido. Para obtenerlo ponte en contacto con nostros a través del formulario de contratación.Instalación
Vía npm
npm install @speaqr/javascript-sdk
Vía cdn
<script src="https://unpkg.com/@speaqr/javascript-sdk@latest/dist/sdk.min.js"></script>
Descargar los archivos
sdk.jssdk.min.js
Instanciar la clase
El SDK de Speaqr se puede instanciar y utilizar en diversos entornos, como navegadores, Node.js y módulos importados desde un CDN. A continuación, se explican las diferentes formas de inicializarlo en función del entorno.En el paquete de npm tienes ejemplos con lenguajes concretos en la carpeta:dist/examples/howInstantiateSdk
Navegadores (Usando CDN)
El SDK está disponible a través de un CDN para ser utilizado directamente en el navegador, sin necesidad de instalación previa.
<html>
<script src="https://unpkg.com/@speaqr/javascript-sdk@latest/dist/sdk.min.js"></script>
<script src="https://my_code.js"></script>
</html>
// my_code.js
const sdk = new SpeaqrSDK({
apiKey: "YOUR_API_KEY",
showLogs: true
});
Node.js
En un entorno Node.js, puedes instalar el SDK mediante npm e importarlo con require o import según tu configuración.
// Using CommonJS (require)
const SpeaqrSDK = require("@speaqr/javascript-sdk");
const sdk = new SpeaqrSDK({
apiKey: "YOUR_API_KEY",
showLogs: true
});
TypeScript
Si trabajas en un entorno TypeScript, el SDK incluye definiciones de tipo(index.d.ts)
que facilitan el uso del SDK con un tipado fuerte.
import { SpeaqrSDK } from "@speaqr/javascript-sdk";
const sdk = new SpeaqrSDK({
apiKey: "YOUR_API_KEY",
showLogs: true
});
Entornos Módulos ES (ESM)
Si trabajas en un entorno compatible con módulos ES, como navegadores modernos o un entorno de desarrollo con soporte de ESM, puedes usarimport.
import SpeaqrSDK from "https://unpkg.com/@speaqr/javascript-sdk@latest/dist/sdk.min.js";
const sdk = new SpeaqrSDK({
apiKey: "YOUR_API_KEY",
showLogs: true
});
RequireJS
El SDK es compatible con sistemas de carga como RequireJS.
<html>
<script data-main="app" src="https://requirejs.org/docs/release/2.3.6/minified/require.js"></script>
<script src="https://my_code.js"></script>
</html>
// my_code.js
require(["https://unpkg.com/@speaqr/javascript-sdk@latest/dist/sdk.min.js"],
function(SpeaqrSDK) {
const sdk = new SpeaqrSDK({
apiKey: "YOUR_API_KEY",
showLogs: true
});
Constructores y destrucción
La claseSpeaqrSDK
incluye dos formas de instanciación: un constructor síncrono y un método estático asíncrono create
. Además, proporciona el método destroy()
para liberar recursos cuando ya no se necesita la instancia del SDK.Constructor síncrono
Este constructor crea una instancia del SDK de forma inmediata. Requiere que el api key sea proporcionado, pero no realiza validaciones al momento de la inicialización.Parámetros
Ejemplo
const sdk = new SpeaqrSDK({
apiKey: "YOUR_API_KEY",
showLogs: true
});
Constructor asíncrono
Este método estático devuelve una promesa que resuelve con una instancia del SDK, validando el api key antes de completar la inicialización.Parámetros
Ejemplo
try {
const sdk = await SpeaqrSDK.create({
apiKey: "YOUR_API_KEY",
showLogs: true
});
console.log("SDK initialized:", sdk);
} catch (error) {
console.error("Error initializing SDK:", error);
}
Método destroy()
(liberación de recursos)
El SDK proporciona el método destroy() para liberar recursos cuando la instancia ya no es necesaria. El método es asíncrono y devuelve una promesa. Este método:- Cierra conexiones de sockets activas.
- Elimina listeners de eventos registrados.
- Libera referencias internas para evitar pérdidas de memoria.
- Anula todos los métodos del SDK para prevenir usos no deseados después de la destrucción.
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
// SDK use
sdk.languages()
.then((languages) => console.log("Supported languages:", languages))
.catch((error) => console.error(error));
//When the SDK is no longer needed
await sdk.destroy();
Si intentas llamar un método después de haber destruido la instancia, se lanzará un error:
sdk.languages(); // Error: Method "languages" cannot be called after the SDK instance has been destroyed.
Propiedades
La clase SpeaqrSDK contiene varias propiedades accesibles que permiten configurar y obtener información sobre el estado del SDK.apiKey
Almacena el api key utilizado para autenticar las solicitudes a la api de Speaqr.Acceso
get apiKey(): string;
set apiKey(apiKey: string);
Ejemplo
// Get the current API key
console.log("Current API key:", sdk.apiKey);
// Set a new API key
sdk.apiKey = "NEW_API_KEY";
logs
Indica si los logs del SDK están habilitados en la consola.Acceso
get logs(): boolean;
set logs(show: boolean);
Ejemplo
// Enable logs
sdk.logs = true;
// Check if logs are enabled
console.log("Logs enabled:", sdk.logs);
socketOpened
Indica si la conexión de sockets está abierta.Acceso
get socketOpened(): boolean;
Ejemplo
// Check if the socket connection is open
if (sdk.socketOpened) {
console.log("Socket is currently open.");
} else {
console.log("Socket is closed.");
}
Métodos
El SDK proporciona varios métodos para interactuar con la api de Speaqr en batch. A continuación, se detallan sus usos y configuraciones.languajes
Obtiene la lista de idiomas soportados por el SDK para transcripción, traducción y síntesis de voz.Sintaxis
languages(): Promise<{
id: string;
name: string;
}[]>;
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
// Fetch the list of supported languages
sdk.languages()
.then((languages) => {
console.log("Supported languages:", languages);
})
.catch((error) => {
console.error("Error fetching languages:", error);
});
Respuesta
Este método devuelve una promesa que se resuelve con un array de objetos, donde cada objeto representa un idioma soportado. El id del idioma será devuelto en ISO3, y el nombre del idioma en inglés.
voices
Obtiene la lista de voces disponibles para la síntesis de voz (TTS) en un idioma. Opcionalmente se puede filtrar el resultado por género de voz, modo de respuesta y/o motor de voz.Por este medio se puede saber si una configuración de idioma, género, modo de respuesta y motor puede ser realizada, ya que no para todas las combinaciones existen voces.Sintaxis
voices(
language: string,
mode?: 'block' | 'streaming',
voiceGender?: 'F' | 'M',
voiceEngine?: Array<'standard' | 'neural' | 'generative'>
): Promise<{
uuid: string;
language: string;
gender: VoiceGender;
engines: Array<'standard' | 'neural' | 'generative'>;
modes: Array<'block' | 'streaming'>;
}[]>;
Parámetros
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
// Fetch the list of available voices for English (UK) with a block mode
sdk.voices('en-gb', 'block')
.then( (response) => {
divResponse.innerText = JSON.stringify(response, null, 4);
})
.catch( (err) => {
alert('An error occurred while requesting available voices.');
});
Respuesta
file
Procesa un Blob que contenga una onda de audio y realiza la operación especificada enmode
. El resultado dependerá del modo seleccionado y se devolverá en una promesa.Sintaxis
file(params: {
mode?: 'sts' | 'stt' | 'stt+translation';
languageIdSource?: string;
languageIdTarget?: string;
voiceGender?: 'F' | 'M';
file: Blob;
}): Promise<{
transcription: string
languageIdSource: string
translation?: string
languageIdTarget?: string
file?: {
type: string
data: ArrayBuffer
}
}>;
Parámetros
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
// Process an audio file with speech-to-text and translation
sdk.file({
mode: "stt+translation",
file: audioBlob,
languageIdTarget: "en-us"
})
.then((result) => {
console.log("Processing result:", result);
})
.catch((error) => {
console.error("Error processing file:", error);
});
Respuesta
El resultado de file
dependerá del mode
utilizado. Una respuesta con mode=sts
llevaría todos los campos. El campo file.data
es un ArrayBuffer
en formato mp3.
Errores
Comunicación con sockets
El SDK de Speaqr permite la comunicación en tiempo real mediante sockets. Estos métodos permiten enviar y recibir datos de audio y texto sin necesidad de esperar una respuesta bloqueante, mejorando la latencia y optimizando la interacción con la api.Flujo de uso
El uso de los sockets en el SDK sigue el siguiente flujo:- Inicializar la configuración de la sesión con
socketsInstance
. - Configurar la escucha de respuestas con
socketsAddListener
. - Abrir la conexión con
socketsOpen
. - Enviar datos mediante
socketSendText
osocketsSendStream
. - Cerrar la conexión cuando ya no se necesite con
socketsClose
.
Manejo de Socket.IO
El SDK de Speaqr utiliza Socket.IO para la comunicación en tiempo real. Para garantizar la compatibilidad en todos los entornos, en caso de quesocket.io-client
no este presente, maneja automáticamente su carga de la siguiente manera:Detección del entorno
Antes de inicializar una conexión de sockets (al llamar asocketsInstance
), el SDK verifica el entorno en el que se está ejecutando:- Si está en un navegador, intenta cargar
socket.io-client
desde una CDN. - Si está en Node.js, intenta importar
socket.io-client
desde los módulos instalados (require("socket.io-client")
). - Si no puede cargar
socket.io-client
, lanza un error indicando que debe instalarse manualmente.
#loadSocketIO() {
return new Promise((resolve, reject) => {
//We check if we are in a browser
if (
typeof document !== 'undefined' &&
typeof document.nodeType !== 'undefined' &&
typeof window !== 'undefined' &&
window.document === document &&
document.nodeType === 9
){
//Browser
this.#loadSocketIOBrowser()
.then( resolve )
.catch( reject );
}else{
//We check if we are in Node
if (
typeof process !== 'undefined' &&
typeof process.versions !== 'undefined' &&
typeof process.versions.node !== 'undefined'
){
this.#loadSocketIONode()
.then( resolve )
.catch( reject );
}else{
reject('Socket IO cannot be loaded dynamically. You must instantiate it in your project.');
}
}
});
}
Carga dinámica en navegadores
Si el SDK detecta que está en un navegador eio
no está definido, carga socket.io-client
desde la CDN de Socket.IO. Si socket.io-client
ya está disponible en el navegador, el SDK no lo vuelve a cargar. La función del SDK que se encarga de la carga es:
// static #SOCKETIO_SRC = 'https://cdn.socket.io/4.8.1/socket.io.min.js';
// static #SOCKETIO_INTEGRITY = 'sha384-mkQ3/7FUtcGyoppY6bz/PORYoGqOl7/aSUMn2ymDOJcapfS6PHqxhRTMh1RR0Q6+';
#loadSocketIOBrowser() {
return new Promise((resolve, reject) => {
if (typeof io!='undefined'){ //If it is already present we do not load it
resolve();
return;
}
const script = document.createElement('script');
script.src = SpeaqrSDK.#SOCKETIO_SRC;
script.integrity = SpeaqrSDK.#SOCKETIO_INTEGRITY;
script.crossOrigin = 'anonymous';
// When the script is loaded successfully
script.onload = () => resolve();
// En caso de error durante la carga
script.onerror = () => reject(new Error(`Failed to load script ${script.src}`));
// We add the script to the document
document.head.appendChild(script);
});
}
Carga dinámica en Node.js
Si el SDK detecta que esta en un entorno Node.js yglobalThis.io
no esta definido, intenta importar socket.io-client
directamente. Si no puede importarlo lanzará un error indicando que debe instalarse manualmente. La función que se encarga de la importación es:
#loadSocketIONode() {
return new Promise((resolve, reject) => {
if (typeof globalThis.io !== 'undefined') {
resolve();
return;
}
try {
const { io } = require('socket.io-client');
globalThis.io = io;
resolve();
} catch (error) {
reject(new Error(`Failed to load socket.io-client on Node. Please install with "npm install socket.io-client". Error: ${error}`));
}
});
}
Para evitar problemas
Si trabajas en Node.js, instala manualmentesocket.io-client
. Así evitarás que el SDK falle si intenta importarlo y no lo encuentra.
npm install socket.io-client
Si trabajas en un navegador con restricciones de red (firewalls, CSP), asegúrate de que tu entorno permite cargar scripts desde https://cdn.socket.io/
. Si no, instala socket.io-client
manualmente en tu proyecto y cárgalo antes de inicializar el SDK.socketsInstance
Configura una instancia de sockets para la comunicación en tiempo real con la API. Este método debe llamarse antes de abrir la conexión consocketsOpen()
. Devuelve una promesa que se resuelve cuando se ha instanciado Socket.io
.Dependiendo de la funcionalidad que se quiera, se elegirá el espacio de combres adecuado, stt, translator, tts o sts.Sintaxis
socketsInstance(
namespace: 'stt' | 'translator' | 'tts' | 'sts',
params: 'STTSocketParams' | 'TranslatorSocketParams' | 'TTSSocketParams' | 'STSSocketParams'
): Promise<void>;
STT
Parámetros
Ejemplo
Configurar una sesión de socket en tiempo real para transcribir audio.
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("stt", {
languageIdSource: "en-us",
sendAudio: {
broadcastVia: "chunk"
}
});
TRANSLATOR
Parámetros
Ejemplo
Configurar una sesión de socket en tiempo real para la traducción.
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("translator", {
languageIdSource: "en-us",
languageIdTarget: "es-es",
});
TTS
Parámetros
Ejemplo
Configurar una sesión de socket en tiempo real para sintetizar audio a partir de un texto.
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("tts", {
languageIdTarget: "en-us",
receiveAudio: {
obtainVia: "chunk"
}
});
STS
Parámetros
Ejemplo
Configurar una sesión de socket en tiempo real speech-to-speech
.
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("sts", {
languageIdSource: "en-us",
languageIdTarget: "en-us",
sendAudio: {
broadcastVia: "chunk"
},
receiveAudio: {
obtainVia: "chunk"
}
});
socketsOpen
Abre la conexión de sockets previamente configurada consocketsInstance()
. Si no se ha llamado a socketsInstance
se obtendrá un error. Este método devuelve una promesa que se resuelve con un boleano, o con la url para recibir el audio por streaming si receiveAudio.obtainVia = url
.Sintaxis
socketsOpen(): Promise<boolean | string>;
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("sts", {
languageIdSource: "en-us",
languageIdTarget: "en-us",
sendAudio: {
broadcastVia: "chunk"
},
receiveAudio: {
obtainVia: "chunk"
}
})
.then( () => {
//We establish the connection with the sockets
sdk.socketsOpen()
.then( (response) => {
//Open sockets
console.log(response);
})
.catch( (err) => {
console.error('An error occurred while connecting to the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while instantiating to the sockets.', err);
});
socketsClose
Devuelve una promesa que se resuelve cuando se cierra la conexión de sockets establecida consocketsOpen
. Si no se ha llamado a socketsInstance
se obtendrá un error. Si no se ha llamado a socketsOpen
este método no realiza ninguna acción y resolverá igualmente la promesa.Sintaxis
socketsClose(): Promise<void>;
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("sts", {
languageIdSource: "en-us",
languageIdTarget: "en-us",
sendAudio: {
broadcastVia: "chunk"
},
receiveAudio: {
obtainVia: "chunk"
}
})
.then( () => {
//We establish the connection with the sockets
sdk.socketsOpen()
.then( (response) => {
//Open sockets
console.log(response);
// We close the sockets
sdk.socketsClose()
.then( () => {
console.log('sockets are closed');
})
.catch( (err) => {
console.error('There was an error closing the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while connecting to the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while instantiating to the sockets.', err);
});
socketsAddListener
Suscribe un listener a un evento específico de la conexión de sockets. Esto permite recibir datos en tiempo real. Si no se ha llamado asocketsInstance
se obtendrá un error.Sintaxis
socketsAddListener(
eventType: 'connected' | 'start' | 'error' | 'result' | 'endSynth',
listener: (data: any) => void
): void;
Parámetros
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("sts", {
languageIdSource: "en-us",
languageIdTarget: "en-us",
sendAudio: {
broadcastVia: "chunk"
},
receiveAudio: {
obtainVia: "chunk"
}
})
.then( () => {
// We subscribe to events
sdk.socketsAddListener('result', (data) => {
console.log(data);
});
sdk.socketsAddListener('error', (error) => {
console.error(error);
});
//We establish the connection with the sockets
sdk.socketsOpen()
.then( (response) => {
//Open sockets
console.log(response);
// We close the sockets
sdk.socketsClose()
.then( () => {
console.log('sockets are closed');
})
.catch( (err) => {
console.error('There was an error closing the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while connecting to the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while instantiating to the sockets.', err);
});
Respuesta
Dependiendo del evento la respuesta obtenida será diferente. A continuación se detallan para cada uno de ellos.connected
Este evento no devuelve el objeto con el que se instanciaron los sockets.
start
Devuelve un boleano o la url para recibir el audio por streaming sireceiveAudio.obtainVia = url
.result
Los campos del objeto que se recibe dependerá con que espacio de nombres se instanciaron los sockets. A continuación un objeto parasts
que contiene todos los campos posibles.
endSynth
Recibe el texto del que se ha terminado la síntexis de audio.
error
Este evento recibe un objeto con distintas descripciones de errores que pudierán ocurrir, bien por fallos en programación de instanciar los modos de uso, como en los datos que se intentan procesar. Se listan los posibles errores de ejecución.Errores
disconnect
Recibe una cadena con el motivo de la desconexión. Por ejemplo:"io client disconnect" o "transport close"
socketsRemoveListener
Elimina un listener de un evento y función específica a las que previamente se había suscrito consocketAddListener
. Si no se había hecho el socketAddListener
a ese tipo de evento y/o a esa función, se obtendrá un error. Si no se ha llamado a socketsInstance
se obtendrá un error.Sintaxis
socketsRemomveListener(
eventType: 'connected' | 'start' | 'error' | 'result' | 'disconnect',
listener: (data: any) => void
): void;
Parámetros
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("sts", {
languageIdSource: "en-us",
languageIdTarget: "en-us",
sendAudio: {
broadcastVia: "chunk"
},
receiveAudio: {
obtainVia: "chunk"
}
})
.then( () => {
// We subscribe to events
sdk.socketsAddListener('result', evt_result);
sdk.socketsAddListener('start', (status) => {
console.log(status);
// Once the connection is established, I unsubscribe from "result"
sdk.socketsRemoveListener('result', evt_result);
});
//We establish the connection with the sockets
sdk.socketsOpen()
.then( (response) => {
//Open sockets
console.log(response);
// We close the sockets
sdk.socketsClose()
.then( () => {
console.log('sockets are closed');
})
.catch( (err) => {
console.error('There was an error closing the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while connecting to the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while instantiating to the sockets.', err);
});
// Function for the "result" event
function evt_result(data){
console.log(data);
}
socketsSendText
Envía un texto para ser procesado y devuelve una promesa, que se resuelve con la estado del envío recibido de los sockets. Si los sockets no están abiertos se producirá un error. Si ocurre un error será rechazada informando del error.Sintaxis
socketsSendText(text: string): Promise<boolean>;
Parámetros
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance('translator', {
languageIdSource:'en-gb',
languageIdTarget:'fr-fr',
})
.then( () => {
// We subscribe to events. Here we will receive the translation
sdk.socketsAddListener('result', (data) => {
console.log(data);
});
// We establish the connection with the sockets
sdk.socketsOpen()
.then( (response) => {
//Open sockets
console.log(response);
//I send the text to process
sdk.socketsSendText('Hello, world. How are you today?')
.then( response => console.log('Send status', response))
.catch( respose => console.error('Send status', response));
})
.catch( (err) => {
console.error('An error occurred while connecting to the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while instantiating to the sockets.', err);
});
socketsSendStream
Envía un fragmento de audio para procesarlo y devuelve una promesa, que se resuelve con la estado del envío recibido de los sockets. Si los sockets no están abiertos se producirá un error. Si ocurre un error será rechazada informando del error.Sintaxis
socketsSendStream(data: ArrayBuffer | Blob): Promise<boolean>;
Parámetros
Ejemplo
const apiKey='xxxxx'; //Your valid apiKey
sdk = await SpeaqrSDK.create({apiKey, showLogs:true});
sdk.socketsInstance("sts", {
languageIdSource: "en-us",
languageIdTarget: "en-us",
sendAudio: {broadcastVia: "chunk"},
receiveAudio: {obtainVia: "chunk", codec: 'mp3', sampleRate: 16000}
})
.then( () => {
//We subscribe to events. Here we will receive the translation
sdk.socketsAddListener('result', result => console.log(result));
sdk.socketsAddListener('start', (status) => {
console.log(status);
// Once the connection is established, I unsubscribe from "result"
sdk.socketsRemoveListener('result', evt_result);
});
//We establish the connection with the sockets
sdk.socketsOpen()
.then(async (response) => {
//Open sockets
console.log(response);
await start();
console.log('Speak now!!!!');
})
.catch( (err) => {
console.error('An error occurred while connecting to the sockets.', err);
});
})
.catch( (err) => {
console.error('An error occurred while instantiating to the sockets.', err);
});
// Start capturing and processing microphone audio
const start = async () => {
navigator.mediaDevices.getUserMedia({ audio: true })
.then(stream => {
mediaRecorder = new MediaRecorder(stream);
mediaRecorder.ondataavailable = ondataavailable;
mediaRecorder.start(500);
})
.catch(error => {
console.error("Error starting recording:", error);
});
}
// Here you receive each audio fragment in a Blob
const ondataavailable = (event) => {
if (!sdk.socketOpened) return;
if (event.data && event.data.size > 0) {
const audioChunk = event.data;
sdk.socketsSendStream(audioChunk);
}
};
Esta página web usa cookies
Las cookies de este sitio web se usan para personalizar el contenido y analizar el tráfico.
Puedes encontrar los detalles de las mismas en la sección Politica de privacidad