Avatar Stream SDK

SDK TypeScript para streaming sincronizado de áudio e vídeo de avatar em tempo real.

Instalação

npm install @avatar/stream-sdk

Uso Básico

import { AvatarStreamSDK } from '@avatar/stream-sdk';

const canvas = document.getElementById('canvas') as HTMLCanvasElement;

const avatar = new AvatarStreamSDK({
  wsUrl: 'ws://localhost:8080/ws',
  canvas,
  onStatusChange: (status) => console.log('Status:', status),
  onMetricsUpdate: (metrics) => {
    console.log(`FPS: ${metrics.currentFps}`);
    console.log(`Video: ${metrics.videoDuration}s`);
    console.log(`Audio: ${metrics.audioDuration}s`);
    console.log(`Sync: ${metrics.syncDiff}s`);
  },
  onComplete: (summary) => {
    console.log(`Concluído: ${summary.totalFrames} frames`);
  },
});

// Conectar
await avatar.connect();

// Gerar fala
await avatar.generate('Olá, mundo!', 'tara');

// Parar
avatar.stop();

// Desconectar
avatar.disconnect();

Configuração

Opção	Tipo	Default	Descrição
`wsUrl`	`string`	-	URL do WebSocket (obrigatório)
`canvas`	`HTMLCanvasElement`	-	Elemento canvas (obrigatório)
`targetFps`	`number`	`25`	FPS alvo de renderização
`audioSampleRate`	`number`	`24000`	Sample rate do áudio
`minFramesBuffer`	`number`	`10`	Frames mínimos antes do playback
`minAudioChunks`	`number`	`2`	Chunks de áudio mínimos

Callbacks

onStatusChange(status: StreamStatus)

Status possíveis:

disconnected - Desconectado
connecting - Conectando
connected - Conectado, pronto
generating - Gerando conteúdo
buffering - Recebendo dados
playing - Reproduzindo
completed - Concluído
error - Erro

onMetricsUpdate(metrics: StreamMetrics)

Métricas em tempo real:

interface StreamMetrics {
  framesReceived: number;     // Frames recebidos
  framesRendered: number;     // Frames renderizados
  bufferSize: number;         // Frames no buffer
  bytesReceived: number;      // Bytes recebidos
  videoDuration: number;      // Duração do vídeo (s)
  audioDuration: number;      // Duração do áudio (s)
  syncDiff: number;           // Diferença audio-video (s)
  currentFps: number;         // FPS atual
  bandwidthKBps: number;      // Bandwidth (KB/s)
  audioChunksReceived: number;// Chunks de áudio
  firstFrameLatencyMs: number | null;   // Latência 1º frame
  playbackLatencyMs: number | null;     // Latência playback
}

onFirstFrame(latencyMs: number)

Chamado quando o primeiro frame é recebido.

onPlaybackStart(latencyMs: number)

Chamado quando o playback inicia (áudio + vídeo sincronizados).

onComplete(summary: StreamSummary)

Chamado quando o stream termina:

interface StreamSummary {
  totalFrames: number;     // Total de frames
  durationSeconds: number; // Duração total
  totalBytes: number;      // Bytes transferidos
  videoDuration: number;   // Duração vídeo
  audioDuration: number;   // Duração áudio
  finalSyncDiff: number;   // Sync final
}

onError(error: Error)

Chamado em caso de erro.

Métodos

connect(): Promise

Conecta ao servidor WebSocket.

disconnect(): void

Desconecta do servidor.

generate(text: string, voice?: string): Promise

Gera fala para o texto. Vozes disponíveis: tara, leah, jess, leo, dan.

stop(): void

Para a geração atual.

getStatus(): StreamStatus

Retorna o status atual.

getMetrics(): StreamMetrics

Retorna as métricas atuais.

isConnected(): boolean

Verifica se está conectado.

isPlaying(): boolean

Verifica se está reproduzindo.

Protocolo Binário

O SDK usa WebSocket binário para eficiência:

Frame: [0x01][index:4][size:4][jpeg_data]
Audio: [0x02][sample_rate:4][size:4][pcm_data]
Audio Chunk: [0x03][index:4][is_last:1][size:4][pcm_data]

Build

npm install
npm run build

Desenvolvimento

npm run dev  # Watch mode
npm run lint # Type check