Voice SDK

El KoIA Voice SDK es un cliente de voz web para integración con agentes KoIA. Este SDK permite crear experiencias de voz interactivas usando la plataforma KoIA con soporte completo de TypeScript.

Funcionalidades

• ✅ Solo audio: Optimizado para experiencias de voz sin video
• 🎙️ Cancelación de ruido: Procesamiento de audio avanzado integrado
• 📱 Soporte móvil: Funciona en dispositivos móviles y de escritorio
• 🔊 Control de dispositivos: Gestión de micrófonos y altavoces
• 📊 Analytics en tiempo real: Eventos de volumen, habla y calidad de red
• 🎯 TypeScript: Completamente tipado para mejor experiencia de desarrollo
• 🔄 Orientado a eventos: Sistema robusto de eventos para control completo

Instalación

Via npm

npm install @ko-ia/voice-sdk

Via yarn

yarn add @ko-ia/voice-sdk

Via pnpm

pnpm add @ko-ia/voice-sdk

Uso Básico

Importación

import KoiaVoiceClient, { 
  KoiaVoiceConfig, 
  KoiaAgentOverrides,
  KOIA_VOICE_EVENTS 
} from '@ko-ia/voice-sdk';

// o importación alternativa
import { createKoiaVoiceClient } from '@ko-ia/voice-sdk';

Configuración Inicial

const config: KoiaVoiceConfig = {
  apiToken: 'tu-token-api-koia',
  baseUrl: 'https://api.ko-ia.com', // opcional, por defecto para dev
  audioConfig: {
    enableNoiseCancellation: true,
    enableEchoCancellation: true,
    startAudioOff: false
  },
  advanced: {
    avoidEval: true,
    alwaysIncludeMicInPermissionPrompt: false
  }
};

const voiceClient = new KoiaVoiceClient(config);

Ejemplo Completo

import KoiaVoiceClient, { 
  KoiaVoiceConfig, 
  KOIA_VOICE_EVENTS 
} from '@ko-ia/voice-sdk';

// Configuración
const config: KoiaVoiceConfig = {
  apiToken: 'tu-token-aquí',
  audioConfig: {
    enableNoiseCancellation: true,
    startAudioOff: false
  }
};

// Crear cliente
const client = new KoiaVoiceClient(config);

// Oyentes de eventos
client.on(KOIA_VOICE_EVENTS.CALL_START, () => {
  console.log('¡Sesión de voz iniciada!');
});

client.on(KOIA_VOICE_EVENTS.MESSAGE, (message) => {
  console.log('Mensaje recibido:', message);
});

client.on(KOIA_VOICE_EVENTS.VOLUME_LEVEL, (level) => {
  console.log('Nivel de volumen:', level);
});

client.on(KOIA_VOICE_EVENTS.ERROR, (error) => {
  console.error('Error:', error);
});

client.on(KOIA_VOICE_EVENTS.CALL_END, () => {
  console.log('Sesión finalizada');
});

// Iniciar sesión
async function iniciarSesion() {
  try {
    const session = await client.startVoiceSession('tu-id-agente');
    console.log('Sesión creada:', session);
  } catch (error) {
    console.error('Error al iniciar:', error);
  }
}

// Controles durante la sesión
function controlarSesion() {
  // Hacer que el agente hable
  client.speakText('¡Hola! ¿Cómo puedo ayudarte hoy?');
  
  // Silenciar/activar micrófono
  client.setMicrophoneEnabled(false); // silenciar
  client.setMicrophoneEnabled(true);  // activar
  
  // Enviar mensaje de texto
  client.sendMessage({
    role: 'user',
    content: 'Este es un mensaje de texto'
  });
  
  // Verificar estado
  console.log('Sesión activa:', client.isSessionActive());
  console.log('Micrófono activo:', client.isMicrophoneEnabled());
}

// Finalizar sesión
function finalizarSesion() {
  client.endVoiceSession();
}

// Inicializar
iniciarSesion();

Referencia de la API

KoiaVoiceClient

Constructor

new KoiaVoiceClient(config: KoiaVoiceConfig)

Métodos Principales

startVoiceSession(agentId: string, overrides?: KoiaAgentOverrides): Promise<KoiaVoiceSession>

Inicia una nueva sesión de voz con el agente especificado.

const session = await client.startVoiceSession('agent-123', {
  customInstructions: 'Sé más formal en las respuestas',
  voiceSettings: {
    speed: 1.1,
    volume: 0.8
  }
});

endVoiceSession(): void

Finaliza la sesión de voz actual.

client.endVoiceSession();

speakText(text: string, options?: SpeakOptions): void

Hace que el agente hable un texto específico.

client.speakText('¡Hola, mundo!', {
  endSessionAfter: false,
  interruptionsEnabled: true
});

sendMessage(message: KoiaMessagePayload): void

Envía un mensaje de texto al agente.

client.sendMessage({
  role: 'user',
  content: '¿Cómo está el tiempo hoy?',
  timestamp: new Date().toISOString()
});

setMicrophoneEnabled(enabled: boolean): void

Controla el estado del micrófono.

client.setMicrophoneEnabled(false); // silenciar
client.setMicrophoneEnabled(true);  // activar

isMicrophoneEnabled(): boolean

Verifica si el micrófono está activo.

const estaActivo = client.isMicrophoneEnabled();

isSessionActive(): boolean

Verifica si hay una sesión activa.

const estaActiva = client.isSessionActive();

Métodos de Dispositivos de Audio

getAudioDevices(): Promise<{microphones: MediaDeviceInfo[], speakers: MediaDeviceInfo[]}>

Obtiene lista de dispositivos de audio disponibles.

const devices = await client.getAudioDevices();
console.log('Micrófonos:', devices.microphones);
console.log('Altavoces:', devices.speakers);

setAudioInputDevice(deviceId: string): Promise<void>

Establece el dispositivo de entrada de audio.

await client.setAudioInputDevice('device-id-123');

setAudioOutputDevice(deviceId: string): Promise<void>

Establece el dispositivo de salida de audio.

await client.setAudioOutputDevice('device-id-456');

Métodos de Diagnóstico

getDiagnosticInfo(): any

Obtiene información de diagnóstico de la sesión.

const diagnostics = client.getDiagnosticInfo();
console.log('Diagnósticos:', diagnostics);

getNetworkStats(): any

Obtiene estadísticas de red de la sesión actual.

const stats = client.getNetworkStats();
console.log('Estadísticas de red:', stats);

Eventos

El SDK emite varios eventos que puedes escuchar:

// Eventos de sesión
client.on('call-start', () => {});
client.on('call-end', () => {});

// Eventos de audio
client.on('speech-start', () => {});
client.on('speech-end', () => {});
client.on('volume-level', (level: number) => {});

// Eventos de mensaje
client.on('message', (message: any) => {});

// Eventos de error
client.on('error', (error: any) => {});

// Eventos de red
client.on('network-quality-change', (event: any) => {});
client.on('network-connection', (event: any) => {});

// Eventos de progreso
client.on('call-start-progress', (event: CallStartProgressEvent) => {});
client.on('call-start-success', (event: CallStartSuccessEvent) => {});
client.on('call-start-failed', (event: CallStartFailedEvent) => {});

Tipos TypeScript

KoiaVoiceConfig

interface KoiaVoiceConfig {
  apiToken: string;
  baseUrl?: string;
  audioConfig?: {
    enableNoiseCancellation?: boolean;
    enableEchoCancellation?: boolean;
    audioSource?: boolean;
    startAudioOff?: boolean;
  };
  advanced?: {
    avoidEval?: boolean;
    alwaysIncludeMicInPermissionPrompt?: boolean;
  };
}

KoiaAgentOverrides

interface KoiaAgentOverrides {
  customInstructions?: string;
  voiceSettings?: {
    speed?: number;
    pitch?: number;
    volume?: number;
    voiceId?: string;
  };
  variables?: Record<string, any>;
  responseConfig?: {
    maxTokens?: number;
    temperature?: number;
    enableInterruptions?: boolean;
  };
}

KoiaMessagePayload

interface KoiaMessagePayload {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp?: string;
}

Ejemplos Prácticos

Ejemplo 1: Chat de Voz Simple

import KoiaVoiceClient from '@ko-ia/voice-sdk';

const client = new KoiaVoiceClient({
  apiToken: 'tu-token-koia'
});

async function iniciarChatVoz() {
  // Configurar eventos
  client.on('call-start', () => {
    console.log('¡Chat de voz iniciado!');
    actualizarUI('Conectado');
  });

  client.on('message', (message) => {
    mostrarMensaje(message.content, 'asistente');
  });

  client.on('speech-start', () => {
    actualizarUI('Escuchando...');
  });

  client.on('speech-end', () => {
    actualizarUI('Procesando...');
  });

  // Iniciar sesión
  await client.startVoiceSession('agente-soporte');
}

Ejemplo 2: Control de Dispositivos

async function configurarDispositivos() {
  // Listar dispositivos disponibles
  const devices = await client.getAudioDevices();
  
  // Crear selectores de dispositivos
  const micSelect = document.getElementById('mic-select');
  const speakerSelect = document.getElementById('speaker-select');
  
  devices.microphones.forEach(mic => {
    const option = document.createElement('option');
    option.value = mic.deviceId;
    option.text = mic.label;
    micSelect.appendChild(option);
  });
  
  devices.speakers.forEach(speaker => {
    const option = document.createElement('option');
    option.value = speaker.deviceId;
    option.text = speaker.label;
    speakerSelect.appendChild(option);
  });
  
  // Configurar eventos de cambio
  micSelect.onchange = (e) => {
    client.setAudioInputDevice(e.target.value);
  };
  
  speakerSelect.onchange = (e) => {
    client.setAudioOutputDevice(e.target.value);
  };
}

Ejemplo 3: Interfaz con Controles

<!DOCTYPE html>
<html>
<head>
    <title>Interfaz de Voz KoIA</title>
</head>
<body>
    <div id="voice-interface">
        <h1>Asistente de Voz KoIA</h1>
        
        <div id="status">Desconectado</div>
        
        <div id="controls">
            <button id="start-btn">Iniciar Conversación</button>
            <button id="end-btn" disabled>Finalizar</button>
            <button id="mute-btn" disabled>Silenciar</button>
        </div>
        
        <div id="devices">
            <label>Micrófono:</label>
            <select id="mic-select"></select>
            
            <label>Altavoz:</label>
            <select id="speaker-select"></select>
        </div>
        
        <div id="volume-indicator">
            <div id="volume-bar"></div>
        </div>
        
        <div id="messages"></div>
    </div>

    <script type="module">
        import KoiaVoiceClient from '@ko-ia/voice-sdk';

        const client = new KoiaVoiceClient({
            apiToken: 'tu-token-aquí'
        });

        // Referencias DOM
        const statusDiv = document.getElementById('status');
        const startBtn = document.getElementById('start-btn');
        const endBtn = document.getElementById('end-btn');
        const muteBtn = document.getElementById('mute-btn');
        const volumeBar = document.getElementById('volume-bar');
        const messagesDiv = document.getElementById('messages');

        // Oyentes de eventos del cliente
        client.on('call-start', () => {
            statusDiv.textContent = 'Conectado';
            startBtn.disabled = true;
            endBtn.disabled = false;
            muteBtn.disabled = false;
        });

        client.on('call-end', () => {
            statusDiv.textContent = 'Desconectado';
            startBtn.disabled = false;
            endBtn.disabled = true;
            muteBtn.disabled = true;
        });

        client.on('volume-level', (level) => {
            volumeBar.style.width = `${level * 100}%`;
        });

        client.on('message', (message) => {
            const msgDiv = document.createElement('div');
            msgDiv.className = `message ${message.role}`;
            msgDiv.textContent = message.content;
            messagesDiv.appendChild(msgDiv);
        });

        // Oyentes de eventos de botones
        startBtn.onclick = () => {
            client.startVoiceSession('tu-id-agente');
        };

        endBtn.onclick = () => {
            client.endVoiceSession();
        };

        muteBtn.onclick = () => {
            const estaSilenciado = !client.isMicrophoneEnabled();
            client.setMicrophoneEnabled(estaSilenciado);
            muteBtn.textContent = estaSilenciado ? 'Activar' : 'Silenciar';
        };

        // Configurar dispositivos en la inicialización
        async function init() {
            const devices = await client.getAudioDevices();
            // ... código de configuración de dispositivos
        }

        init();
    </script>
</body>
</html>

Solución de Problemas

Permisos de Micrófono

Asegúrate de que tu aplicación tiene permiso para usar el micrófono:

// Verificar permisos
navigator.permissions.query({ name: 'microphone' })
  .then((result) => {
    if (result.state === 'denied') {
      console.warn('Permiso de micrófono denegado');
    }
  });

Problemas de Conexión

client.on('error', (error) => {
  switch (error.type) {
    case 'network':
      console.error('Error de red:', error.message);
      // Intentar reconectar
      break;
    case 'auth':
      console.error('Error de autenticación:', error.message);
      // Verificar token
      break;
    case 'device':
      console.error('Error de dispositivo:', error.message);
      // Verificar dispositivos de audio
      break;
  }
});

Debug y Diagnósticos

// Obtener información de diagnóstico
const diagnostics = client.getDiagnosticInfo();
console.log('Diagnósticos:', diagnostics);

// Estadísticas de red
const networkStats = client.getNetworkStats();
console.log('Red:', networkStats);

Soporte

• 📧 Email: support@ko-ia.com
• 📚 Documentación: docs.ko-ia.com
• 🐛 Issues: Contacta con el soporte

Licencia

MIT © KoIA