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