story-generator/docs/processamento-audio.md

Processamento de Áudio (Edge Function)

Visão Geral

O sistema de processamento de áudio é uma Edge Function que analisa gravações de leitura, fornecendo métricas detalhadas sobre fluência, pronúncia e compreensão.

Estrutura de Dados

AudioRecord

interface AudioRecord {
  id: string
  story_id: string
  student_id: string
  audio_url: string
  status: 'pending_analysis' | 'processing' | 'completed' | 'error'
  analysis: any
  created_at: string
  transcription: string | null
  processed_at: string | null
  error_message: string | null
  fluency_score: number | null
  pronunciation_score: number | null
  accuracy_score: number | null
  comprehension_score: number | null
  words_per_minute: number | null
  pause_count: number | null
  error_count: number | null
  self_corrections: number | null
  strengths: string[]
  improvements: string[]
  suggestions: string | null
}

Fluxo de Processamento

1. Recebimento da Requisição

• Validação inicial dos dados recebidos
• Configuração de CORS e headers
• Inicialização do logger

2. Processamento Principal

O processamento ocorre em etapas sequenciais:

1. Verificação e Atualização de Status

   • Verifica existência do registro
   • Cria registro se necessário
   • Atualiza status para 'processing'

2. Processamento do Áudio

   • Transcrição via Whisper API
   • Análise do texto transcrito

3. Análise da Leitura

   • Cálculo de métricas de fluência
   • Avaliação de pronúncia
   • Identificação de pontos fortes e melhorias

4. Atualização do Banco

   • Preparação dos dados de análise
   • Verificação pré-update
   • Atualização do registro
   • Verificação pós-update

Tratamento de Erros

1. Validação de Dados

if (!data?.record?.id || !data?.record?.audio_url) {
  throw new Error('Dados inválidos: ID ou URL do áudio ausentes')
}

2. Atualização de Status de Erro

• Em caso de falha, atualiza o registro com status 'error'
• Armazena mensagem de erro para diagnóstico
• Retorna resposta com detalhes do erro

Métricas Analisadas

Pontuações

• Fluência (0-100)
• Pronúncia (0-100)
• Precisão (0-100)
• Compreensão (0-100)

Métricas Quantitativas

• Palavras por minuto
• Contagem de pausas
• Contagem de erros
• Autocorreções

Feedback Qualitativo

• Pontos fortes identificados
• Áreas para melhoria
• Sugestões personalizadas

Logs e Monitoramento

Eventos Registrados

• Recebimento de requisição
• Atualizações de status
• Resultados de processamento
• Erros e exceções

Formato dos Logs

logger.info('event_name', 'Descrição do evento', {
  contextData: 'dados adicionais'
})

Considerações de Segurança

1. Autenticação

• Validação de tokens
• Verificação de permissões
• Controle de acesso por usuário

2. Dados Sensíveis

• Sanitização de inputs
• Validação de URLs
• Proteção contra injeção

3. Rate Limiting

• Controle de requisições
• Proteção contra sobrecarga
• Cache de resultados

Próximas Melhorias

1. Análise Avançada

   • Detecção de padrões de erro
   • Análise de entonação
   • Reconhecimento de emoção

2. Performance

   • Otimização de processamento
   • Cache distribuído
   • Processamento em lote

3. Feedback

   • Relatórios detalhados
   • Visualizações gráficas
   • Recomendações personalizadas

4. Integração

   • Webhooks para notificações
   • API para consultas em tempo real
   • Exportação de dados