# Script de Reunião de Passagem - Sofya Transcription Library

## Visão Geral da Reunião
**Duração**: 30-45 minutos
**Projeto**: Sofya Transcription Library (v0.0.18-beta.2)
**Tipo**: Biblioteca JavaScript/TypeScript para transcrição de áudio em tempo real

---

## 1. Visão Geral do Projeto (5 min)

### O Que É Isso (Esclarecimento Importante!)
- **NÃO é um app Electron + React** - É uma biblioteca JavaScript pura
- Biblioteca de transcrição de áudio em tempo real baseada em navegador
- Pode ser integrada em qualquer aplicação web (incluindo apps Electron)
- Distribuída como pacote NPM com bundle UMD

### Funcionalidades Principais
- **Suporte Multi-Provider**: Oracle AI Speech, backends baseados em Whisper, STT com VAD
- **Streaming em Tempo Real**: Transcrição contínua baseada em WebSocket
- **Suporte a Idiomas**: Inglês, Português, Espanhol + multilíngue
- **Adição Recente**: Diarização de falantes (identifica diferentes speakers)
- **Utilitários de Áudio**: Captura áudio de elementos HTML `<video>` ou `<audio>`

### Caso de Uso Principal
Usuário fornece MediaStream → Biblioteca transcreve em tempo real → Emite texto + info do falante

---

## 2. Arquitetura (10 min)

### Padrão de Alto Nível: Adapter + Factory
```
SofyaTranscriber (Facade)
    ↓
TranscriptionServiceFactory
    ↓
Provider Adapters (Strategy Pattern)
    ├── OracleTranscriptionAdapter
    ├── WhisperTranscriptionAdapter
    └── WhisperVadTranscriptionAdapter (DESABILITADO)
```

### Arquivos-Chave para Conhecer
- `src/services/transcription/SofyaTranscriber.ts` - Facade da API pública principal
- `src/services/transcription/TranscriptionServiceFactory.ts` - Seleção de provider + lógica de fallback
- `src/services/transcription/adapters/` - Implementações específicas de providers
- `src/libs/oci-aispeech-realtime-web/` - Integração com Oracle Cloud
- `src/libs/speech-audio-resampler/` - Reamostragem de áudio customizada com filtros FIR

### Dois Modos de Conexão

**Modo 1: Autenticação por API Key** (Recomendado)
1. Usuário fornece API key
2. Biblioteca chama serviço de autenticação: `https://api.reasoner.alpha.sofya.ai/v1/sdk/providers`
3. Recebe lista de providers + endpoints + credenciais
4. Tenta cada provider/endpoint com fallback automático
5. Emite evento `ready` quando conectado

**Modo 2: Conexão Direta com Provider**
- Usuário fornece URL do endpoint + credenciais diretamente
- Bypassa o serviço de autenticação
- Sem fallback automático

### API Baseada em Eventos
A biblioteca usa event emitters (não promises) porque:
- Stream contínuo de resultados (não one-shot)
- `recognizing` - Resultados parciais de alta frequência
- `recognized` - Transcrições finais
- `recognized_diarization` - Segmentos de speakers (NOVO)
- `error`, `stopped`, `connected`

---

## 3. Mudanças Recentes Críticas (5 min)

### OBRIGATÓRIO SABER: Breaking Changes no Trabalho Atual

**1. `stopTranscription()` Agora é Async**
- Commit: `47080c9`
- Retorna `Promise<void>` agora
- **Por quê**: Precisa aguardar transcrição final do backend
- **Impacto**: Integrações existentes precisam de `await transcriber.stopTranscription()`

**2. Diarização de Falantes Adicionada**
- PR 1143, Commit: `21e2348`
- Novo evento `recognized_diarization`
- Emite array: `{speaker: string, sentence: string, start: number, end: number}[]`
- Apenas no adapter Whisper

**3. Adapter VAD Desabilitado**
- `WhisperVadTranscriptionAdapter` completamente comentado
- Removida dependência `@ricky0123/vad-web`
- Todos os providers Whisper agora usam adapter básico
- **Razão provável**: VAD adicionou complexidade/problemas de latência

**4. Pause Agora Finaliza Resultados**
- Commit: `90c4a1d`
- `pauseTranscription()` envia `{action: "finish"}` para WebSocket
- Garante que resultados parciais sejam finalizados antes de pausar

### Status Atual do Git
- Mudanças não commitadas em vários arquivos
- `sofya.transcription-0.0.18-beta.2.tgz` - Pacote construído e pronto
- Essas mudanças provavelmente precisam de testes antes de publicar

---

## 4. Áreas Complexas/Frágeis (10 min)

### 1. Cadeia de Fallback de Providers ⚠️ FRÁGIL
**Localização**: `SofyaTranscriber.ts:72-129`

**Como Funciona**:
```
for cada provider:
  for cada endpoint:
    try conectar
    if sucesso: return (sai da função inteira)
    if falha: continue para próximo endpoint
  if todos endpoints falharem: continue para próximo provider
if todos providers falharem: throw error
```

**Problemas**:
- Loops profundamente aninhados com retornos antecipados
- Falhas silenciosas (apenas `console.warn`)
- Sem lógica de retry para erros de rede transitórios
- Ordem dos providers importa mas não está documentada
- Código inalcançável: statement `continue` na linha 105

**Fique Atento**: Usuários reportando "não consegue conectar" podem estar atingindo exaustão de fallback

---

### 2. Lógica de Fallback de Áudio ⚠️ ALTA COMPLEXIDADE
**Localização**: `speech-audio-streamer.ts:158-178` (adapter Oracle)

**O Que Faz**:
```
Tenta 16kHz → Falha → Tenta 48kHz → Falha → Tenta 44.1kHz → Desiste
```

**Problemas**:
- Usa `ScriptProcessorNode` **deprecado** (deveria usar AudioWorklet)
- Pirâmide de try-catch aninhados (difícil de debugar)
- Tamanhos de buffer diferentes para diferentes taxas
- Sem logging de qual taxa teve sucesso
- Específico do navegador - caminhos diferentes em dispositivos diferentes

**Por Que Importa**: Relatos de bugs como "funciona no Chrome mas não no Safari" provavelmente aqui

---

### 3. Race Condition no Stop do WebSocket ⚠️ FRÁGIL
**Localização**: `WhisperTranscriptionAdapter.ts:stopTranscription()`

**O Fluxo**:
```typescript
1. Envia {action: "finish"} para WebSocket
2. Aguarda resultado final OU timeout após 5 segundos
3. Se timeout: emite transcrição parcial como final
4. Fecha WebSocket
```

**Race Conditions**:
- WebSocket pode fechar antes da mensagem final chegar
- Múltiplas mensagens podem chegar durante cleanup
- Timeout de 5s é arbitrário

**Impacto no Usuário**: Em backends lentos, usuários veem transcrições incompletas marcadas como "final"

**Código para Revisar**:
```typescript
const timeout = setTimeout(() => {
  if (!resolved) {
    if (this.tempPartialTranscription?.length) {
      this.emit("recognized", this.tempPartialTranscription); // Parcial como final!
    }
    cleanup();
    resolve();
  }
}, 5000);
```

---

### 4. Complexidade da Reamostragem de Áudio
**Localização**: `src/libs/speech-audio-resampler/`

**O Que Faz**:
- Converte 44.1kHz ou 48kHz → 16kHz (requerido pelos serviços STT)
- Usa filtros FIR com janelamento Lanczos
- Algoritmos diferentes para decimação inteira vs fracionária

**Por Que é Complexo**:
- Mantém buffer de filtro através de chunks para continuidade
- Primeiro frame tratado diferentemente
- Lógica complexa de slicing de buffer propensa a erros off-by-one

**Boas Notícias**: Bem testado, estável, não deve precisar mexer a menos que bugs sejam reportados

---

### 5. Código AudioWorklet Inline
**Localização**: `WhisperTranscriptionAdapter.ts:62-76`

**O Problema**:
```typescript
const workletCode = `
  class RealtimeAudioProcessor extends AudioWorkletProcessor {
    // ... worklet inteiro como string
  }
`;
const blob = new Blob([workletCode], {type: "application/javascript"});
const workletURL = URL.createObjectURL(blob);
```

**Problemas**:
- Sem verificação de sintaxe em tempo de compilação
- Difícil de debugar (sem source maps para blob URLs)
- Quebra em ambientes com CSP (Content Security Policy) estrito
- Código duplicado no adapter VAD comentado

**Melhor**: Deveria ser arquivo `.js` separado importado como módulo

---

### 6. Duplicação de Mapeamento de Idiomas
**Localizações**:
- `TranscriptionServiceFactory.ts:7-17`
- `WhisperTranscriptionAdapter.ts:125-136`

Mesma função `languageSelector()` copiada e colada. Risco de divergência se uma for atualizada e a outra não.

---

## 5. Build & Testes (5 min)

### Processo de Build
```bash
npm run build
```

**Passos**:
1. `tsc --declaration` - Compila TS para JS + gera arquivos `.d.ts`
2. `webpack` - Empacota em formato UMD (`dist/bundle.js`)
3. Output: `dist/bundle.js` + definições TypeScript

**Formato UMD**: Funciona no navegador (script tag), AMD e CommonJS

**Alerta de Erro de Digitação**: Biblioteca exportada como `SofyaTrancription` (faltando 's' em Transcription)

### Testes Locais
```bash
npm run local-test  # Cria arquivo .tgz
```

Use o arquivo `.tgz` para testar em outro projeto antes de publicar.

### Status dos Testes
- Jest configurado mas **NÃO EXISTEM ARQUIVOS DE TESTE**
- Todos os testes são manuais de integração
- Sem testes unitários, sem cobertura

**Recomendação**: Adicionar testes para lógica de fallback e gerenciamento de estado do WebSocket

---

## 6. Pegadinhas de Integração (5 min)

### Pegadinha 1: Deve Aguardar Evento `ready`
```typescript
// ERRADO
const transcriber = new SofyaTranscriber({apiKey: "..."});
transcriber.startTranscription(mediaStream); // ERRO! Ainda não está pronto

// CORRETO
const transcriber = new SofyaTranscriber({apiKey: "..."});
transcriber.on('ready', () => {
  transcriber.startTranscription(mediaStream); // AGORA funciona
});
```

### Pegadinha 2: Parar é Async (NOVO!)
```typescript
// CÓDIGO ANTIGO (QUEBRADO)
transcriber.stopTranscription();
cleanup(); // Pode perder últimos resultados!

// CÓDIGO NOVO
await transcriber.stopTranscription();
cleanup(); // Seguro - todos resultados recebidos
```

### Pegadinha 3: Resultados Parciais no Timeout
- Ao parar, se backend não responder em 5s:
- Biblioteca emite transcrição parcial como "final"
- Usuário vê frase incompleta sem indicação de que está truncada

### Pegadinha 4: Mapeamento de Código de Idioma
- Input: códigos BCP-47 (`en-US`, `pt-BR`, `es-ES`)
- Backend Whisper espera: palavras em inglês (`english`, `portuguese`, `spanish`)
- Mapeamento tem perdas - cuidado ao adicionar novos idiomas

---

## 7. Considerações de Segurança (3 min)

### Manipulação de API Key
- Enviada para `https://api.reasoner.alpha.sofya.ai/v1/sdk/providers`
- Transmitida em headers (boa prática)
- Considerar rotação/expiração de chaves em produção

### Segurança do WebSocket
- Deveria usar WSS (WebSocket seguro)
- Sem validação explícita de certificado no código

### Problemas de CSP (Content Security Policy)
- Blob URLs para AudioWorklet requerem: `worker-src blob:` e `script-src blob:`
- Pode quebrar em ambientes com CSP estrito
- Considerar isso para clientes enterprise

---

## 8. Prioridades Ativas & Próximos Passos (3 min)

### O Que Está em Andamento
Baseado no git status:
- Finalização da remoção do VAD
- Bump de versão para `0.0.18-beta.2`
- Mudanças na config do Webpack (desconhecidas)
- Pacote construído pronto para teste

### Próximos Passos Recomendados

**Imediato**:
1. Testar pacote `.tgz` em ambiente de staging
2. Verificar eventos de diarização funcionando corretamente
3. Testar que `stopTranscription()` async não quebra integrações existentes

**Curto Prazo**:
1. Adicionar testes unitários (especialmente para lógica de fallback)
2. Mover AudioWorklet para arquivo separado (compatibilidade CSP)
3. Adicionar logging/telemetria à cadeia de fallback
4. Documentar ordem de prioridade dos providers

**Médio Prazo**:
1. Substituir `ScriptProcessorNode` por AudioWorklet no adapter Oracle
2. Adicionar lógica de reconexão do WebSocket
3. Considerar deduplicar função de mapeamento de idiomas
4. Adicionar timeout na chamada de autenticação

**Débito Técnico**:
- Corrigir erro de digitação: `SofyaTrancription` → `SofyaTranscription`
- Remover código do adapter VAD comentado
- Adicionar testes de integração

---

## 9. Documentação Principal

### Arquivos para Ler
- `README.md` - Documentação principal da biblioteca
- `docs/CONNECTION_MODE.md` - Estratégias de conexão
- `docs/ERROR_HANDLING.md` - Padrões de tratamento de erros

### CI/CD
- `azure-pipelines.yml` - Publicação npm automatizada no Azure DevOps
- Dispara em mudanças de versão

---

## 10. Questões a Abordar

### Antes de Você Ir
1. Existem problemas conhecidos com a feature de diarização?
2. Por que o VAD foi removido? Performance? Precisão? Complexidade?
3. Qual é o timeline para publicar 0.0.18-beta.2?
4. Existem problemas pendentes de clientes que eu devo saber?
5. Qual é o processo de suporte se integrações quebrarem após mudança de stop async?

### Durante Minha Ausência
- Monitorar pipelines do Azure para falhas de build
- Verificar problemas relacionados a CSP de clientes
- Ficar atento a relatos de "falha de conexão" (lógica de fallback)
- Problemas de áudio específicos do Safari (fallback de sample rate)

---

## Resumo: A Versão de Um Minuto

**O Que É**: Biblioteca JavaScript para transcrição de áudio em tempo real via WebSocket para serviços STT em nuvem

**Arquitetura**: Padrão Adapter com fallback automático de provider

**Mudanças Recentes**:
- Stop agora é async (BREAKING)
- Adicionada diarização de falantes
- Removido adapter VAD

**Fique Atento Para**:
- Cadeia de fallback de providers é frágil
- Stop do WebSocket tem race condition com timeout de 5s
- Usa ScriptProcessorNode deprecado no caminho Oracle
- Sem testes - todo QA é manual

**Status Atual**: v0.0.18-beta.2 pronto para teste, mudanças não commitadas no git

**Seu Trabalho**: Testar beta, lidar com problemas de suporte, considerar adicionar testes para áreas frágeis

---

## Informações de Contato
- Desenvolvedor original: [Seu nome/contato]
- Documentação: `./documentation/` + `./docs/`
- Issues: [Link para rastreador de issues se aplicável]

Boa sorte! Entre em contato se precisar de algo.