Koia Voice SDK

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 a TypeScript.

Características

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

Instalação

Via npm (quando publicado)

# npm
npm install @koia/voice-sdk

# yarn
yarn add @koia/voice-sdk

# pnpm
pnpm add @koia/voice-sdk

Instalação Local (desenvolvimento)

Opção 1: Link Local (Recomendado)

No diretório do SDK:

# Instalar dependências e compilar
npm install
npm run build

# Criar link global
npm link

No seu projeto:

# Usar o SDK linkado
npm link @koia/voice-sdk

Opção 2: Instalação por Caminho

# Instalar diretamente do diretório local
npm install file:caminho/para/sdk-voice-web-client

# Exemplo:
npm install file:../sdk-voice-web-client

Opção 3: Import Direto

Após compilar (npm run build), importe diretamente:

// Import do arquivo compilado
import KoiaVoiceClient from './caminho/para/dist/index.js';

Uso Básico

Importação

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

// ou importação alternativa
import { createKoiaVoiceClient } from '@koia/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 '@koia/voice-sdk';

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

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

// Event listeners
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 encerrada');
});

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

// Controles durante a sessão
function controlarSessao() {
  // Fazer o agente falar
  client.speakText('Olá! Como posso ajudar você 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());
}

// Encerrar sessão
function encerrarSessao() {
  client.endVoiceSession();
}

// Iniciar
iniciarSessao();

API Reference

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

Encerra 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 isActive = client.isMicrophoneEnabled();

isSessionActive(): boolean

Verifica se há uma sessão ativa.

const isActive = 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;
}

Desenvolvimento

Estrutura do Projeto

sdk-voice-web-client/
├── src/
│   └── index.ts          # Código principal do SDK
├── dist/                 # Build compilado
├── package.json         # Configurações do projeto
├── tsconfig.json        # Configurações TypeScript
└── README.md           # Esta documentação

Scripts de Desenvolvimento

# Compilar o projeto
npm run build

# Modo de desenvolvimento (watch)
npm run dev

# Limpar arquivos de build
npm run clean

Build

O projeto usa tsup para build:

npm run build

Gera arquivos nos formatos ESM e CJS em dist/:

• dist/index.js (ESM)
• dist/index.d.ts (declarações TypeScript)

Suporte

• 📧 Email: [email protected]
• 📚 Documentação: docs.ko-ia.com
• 🐛 Issues: GitLab Issues

Licença

MIT © Koia

Autor

Koia - Plataforma de agentes de voz inteligentes