story-generator/docs/gravacao-audio.md

Sistema de Gravação de Áudio

Visão Geral

O sistema de gravação de áudio permite aos alunos gravar suas leituras para análise posterior, com integração ao Modo Foco e recursos de acessibilidade.

Componentes

1. AudioRecorder

Componente principal responsável pela gravação de áudio.

Props

interface AudioRecorderProps {
  storyId: string;
  studentId: string;
  onAudioUploaded: (audioUrl: string) => void;
  onRecordingStart?: () => void;
  onRecordingStop?: () => void;
  focusModeActive?: boolean;
  onFocusModeToggle?: () => void;
}

2. Estados de Gravação

• Não Iniciado: Exibe botão "Iniciar Gravação"
• Gravando: Exibe botão "Parar Gravação"
• Gravado: Exibe opções de ouvir e enviar
• Enviando: Exibe indicador de progresso

Funcionalidades

1. Controle de Gravação

• Início/parada de gravação
• Feedback visual do estado atual
• Integração com Modo Foco
• Controle de permissões do microfone

2. Processamento de Áudio

• Formato: WebM
• Armazenamento temporário em Blob
• Conversão e compressão antes do upload
• Validação de qualidade

3. Upload e Armazenamento

• Upload para Supabase Storage
• Geração de URLs públicas
• Organização por aluno/história
• Backup e cache

4. Integração com Modo Foco

• Ativação automática do Modo Foco
• Desativação ao finalizar gravação
• Sincronização de estados
• Transições suaves

Fluxo de Gravação

1. Início da Gravação

const startRecording = async () => {
  // 1. Ativar Modo Foco
  if (!focusModeActive && onFocusModeToggle) {
    onFocusModeToggle();
  }

  // 2. Solicitar permissões
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });

  // 3. Configurar gravador
  mediaRecorderRef.current = new MediaRecorder(stream);

  // 4. Iniciar gravação
  mediaRecorderRef.current.start();
};

2. Finalização da Gravação

const stopRecording = () => {
  // 1. Parar gravação
  mediaRecorderRef.current?.stop();

  // 2. Liberar recursos
  mediaRecorderRef.current?.stream.getTracks().forEach(track => track.stop());

  // 3. Desativar Modo Foco
  if (focusModeActive && onFocusModeToggle) {
    onFocusModeToggle();
  }
};

3. Upload do Áudio

const uploadAudio = async () => {
  // 1. Preparar arquivo
  const filePath = `${studentId}/${storyId}/${fileId}.webm`;

  // 2. Fazer upload
  await supabase.storage
    .from('recordings')
    .upload(filePath, audioBlob);

  // 3. Obter URL pública
  const { publicUrl } = supabase.storage
    .from('recordings')
    .getPublicUrl(filePath);

  // 4. Criar registro
  await supabase
    .from('story_recordings')
    .insert({
      id: fileId,
      story_id: storyId,
      student_id: studentId,
      audio_url: publicUrl
    });
};

Tratamento de Erros

1. Permissões

• Verificação de disponibilidade do microfone
• Solicitação de permissões do usuário
• Feedback claro em caso de negação

2. Gravação

• Monitoramento de qualidade
• Detecção de silêncio
• Limite de duração
• Feedback de volume

3. Upload

• Retry em caso de falha
• Limpeza de arquivos temporários
• Validação de formato
• Feedback de progresso

Considerações de Segurança

• Validação de tipos de arquivo
• Sanitização de nomes de arquivo
• Controle de acesso por usuário
• Expiração de URLs temporárias

Próximas Melhorias

1. Adicionar visualização de forma de onda
2. Implementar edição básica de áudio
3. Melhorar feedback de qualidade
4. Adicionar suporte a mais formatos
5. Implementar detecção de ruído