Voice SDK

O KoIA Voice SDK é um cliente de voz web para integração com agentes KoIA. Este SDK permite criar experiências de voz interativas usando a plataforma KoIA com suporte completo ao TypeScript.

Funcionalidades

• ✅ Apenas áudio: Otimizado para experiências de voz sem vídeo
• 🎙️ Cancelamento de ruído: Processamento de áudio avançado integrado
• 📱 Suporte móvel: Funciona em dispositivos móveis e desktop
• 🔊 Controle de dispositivos: Gerenciamento de microfones e alto-falantes
• 📊 Analytics em tempo real: Eventos de volume, fala e qualidade de rede
• 🎯 TypeScript: Totalmente tipado para melhor experiência de desenvolvimento
• 🔄 Orientado a eventos: Sistema robusto de eventos para controle completo

Instalação

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

Importação

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

// ou importação alternativa
import { createKoiaVoiceClient } from '@ko-ia/voice-sdk';

Configuração Inicial

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

const voiceClient = new KoiaVoiceClient(config);

Exemplo Completo

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

// Configuração
const config: KoiaVoiceConfig = {
  apiToken: 'seu-token-aqui',
  audioConfig: {
    enableNoiseCancellation: true,
    startAudioOff: false
  }
};

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

// Ouvintes de eventos
client.on(KOIA_VOICE_EVENTS.CALL_START, () => {
  console.log('Sessão de voz iniciada!');
});

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

client.on(KOIA_VOICE_EVENTS.VOLUME_LEVEL, (level) => {
  console.log('Nível de volume:', level);
});

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

client.on(KOIA_VOICE_EVENTS.CALL_END, () => {
  console.log('Sessão finalizada');
});

// Iniciar sessão
async function iniciarSessao() {
  try {
    const session = await client.startVoiceSession('seu-id-agente');
    console.log('Sessão criada:', session);
  } catch (error) {
    console.error('Erro ao iniciar:', error);
  }
}

// Controles durante a sessão
function controlarSessao() {
  // Fazer agente falar
  client.speakText('Olá! Como posso ajudá-lo hoje?');
  
  // Silenciar/ativar microfone
  client.setMicrophoneEnabled(false); // silenciar
  client.setMicrophoneEnabled(true);  // ativar
  
  // Enviar mensagem de texto
  client.sendMessage({
    role: 'user',
    content: 'Esta é uma mensagem de texto'
  });
  
  // Verificar status
  console.log('Sessão ativa:', client.isSessionActive());
  console.log('Microfone ativo:', client.isMicrophoneEnabled());
}

// Finalizar sessão
function finalizarSessao() {
  client.endVoiceSession();
}

// Inicializar
iniciarSessao();

Referência da API

KoiaVoiceClient

Construtor

new KoiaVoiceClient(config: KoiaVoiceConfig)

Métodos Principais

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

Inicia uma nova sessão de voz com o agente especificado.

const session = await client.startVoiceSession('agent-123', {
  customInstructions: 'Seja mais formal nas respostas',
  voiceSettings: {
    speed: 1.1,
    volume: 0.8
  }
});

endVoiceSession(): void

Finaliza a sessão de voz atual.

client.endVoiceSession();

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

Faz o agente falar um texto específico.

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

sendMessage(message: KoiaMessagePayload): void

Envia uma mensagem de texto para o agente.

client.sendMessage({
  role: 'user',
  content: 'Como está o tempo hoje?',
  timestamp: new Date().toISOString()
});

setMicrophoneEnabled(enabled: boolean): void

Controla o estado do microfone.

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

isMicrophoneEnabled(): boolean

Verifica se o microfone está ativo.

const estaAtivo = client.isMicrophoneEnabled();

isSessionActive(): boolean

Verifica se há uma sessão ativa.

const estaAtiva = client.isSessionActive();

Métodos de Dispositivos de Áudio

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

Obtém lista de dispositivos de áudio disponíveis.

const devices = await client.getAudioDevices();
console.log('Microfones:', devices.microphones);
console.log('Alto-falantes:', devices.speakers);

setAudioInputDevice(deviceId: string): Promise<void>

Define o dispositivo de entrada de áudio.

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

setAudioOutputDevice(deviceId: string): Promise<void>

Define o dispositivo de saída de áudio.

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

Métodos de Diagnóstico

getDiagnosticInfo(): any

Obtém informações de diagnóstico da sessão.

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

getNetworkStats(): any

Obtém estatísticas de rede da sessão atual.

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

Eventos

O SDK emite vários eventos que você pode escutar:

// Eventos de sessão
client.on('call-start', () => {});
client.on('call-end', () => {});

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

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

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

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

// Eventos de progresso
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;
}

Exemplos Práticos

Exemplo 1: Chat de Voz Simples

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

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

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

  client.on('message', (message) => {
    exibirMensagem(message.content, 'assistente');
  });

  client.on('speech-start', () => {
    atualizarUI('Ouvindo...');
  });

  client.on('speech-end', () => {
    atualizarUI('Processando...');
  });

  // Iniciar sessão
  await client.startVoiceSession('agente-suporte');
}

Exemplo 2: Controle de Dispositivos

async function configurarDispositivos() {
  // Listar dispositivos disponíveis
  const devices = await client.getAudioDevices();
  
  // Criar seletores 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 mudança
  micSelect.onchange = (e) => {
    client.setAudioInputDevice(e.target.value);
  };
  
  speakerSelect.onchange = (e) => {
    client.setAudioOutputDevice(e.target.value);
  };
}

Exemplo 3: Interface com Controles

<!DOCTYPE html>
<html>
<head>
    <title>Interface de Voz KoIA</title>
</head>
<body>
    <div id="voice-interface">
        <h1>Assistente de Voz KoIA</h1>
        
        <div id="status">Desconectado</div>
        
        <div id="controls">
            <button id="start-btn">Iniciar Conversa</button>
            <button id="end-btn" disabled>Finalizar</button>
            <button id="mute-btn" disabled>Silenciar</button>
        </div>
        
        <div id="devices">
            <label>Microfone:</label>
            <select id="mic-select"></select>
            
            <label>Alto-falante:</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: 'seu-token-aqui'
        });

        // Referências 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');

        // Ouvintes de eventos do 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);
        });

        // Ouvintes de eventos dos botões
        startBtn.onclick = () => {
            client.startVoiceSession('seu-id-agente');
        };

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

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

        // Configurar dispositivos na inicialização
        async function init() {
            const devices = await client.getAudioDevices();
            // ... código de configuração de dispositivos
        }

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

Solução de Problemas

Permissões de Microfone

Certifique-se de que sua aplicação tem permissão para usar o microfone:

// Verificar permissões
navigator.permissions.query({ name: 'microphone' })
  .then((result) => {
    if (result.state === 'denied') {
      console.warn('Permissão de microfone negada');
    }
  });

Problemas de Conexão

client.on('error', (error) => {
  switch (error.type) {
    case 'network':
      console.error('Erro de rede:', error.message);
      // Tentar reconectar
      break;
    case 'auth':
      console.error('Erro de autenticação:', error.message);
      // Verificar token
      break;
    case 'device':
      console.error('Erro de dispositivo:', error.message);
      // Verificar dispositivos de áudio
      break;
  }
});

Debug e Diagnósticos

// Obter informações de diagnóstico
const diagnostics = client.getDiagnosticInfo();
console.log('Diagnósticos:', diagnostics);

// Estatísticas de rede
const networkStats = client.getNetworkStats();
console.log('Rede:', networkStats);

Suporte

• 📧 Email: support@ko-ia.com
• 📚 Documentação: docs.ko-ia.com
• 🐛 Issues: Entre em contato com o suporte

Licença

MIT © KoIA