interface/sdk/README.md

# Avatar Stream SDK

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

## Instalação

```bash
npm install @avatar/stream-sdk
```

## Uso Básico

```typescript
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:

```typescript
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:

```typescript
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<void>

Conecta ao servidor WebSocket.

### disconnect(): void

Desconecta do servidor.

### generate(text: string, voice?: string): Promise<void>

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

```bash
npm install
npm run build
```

## Desenvolvimento

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