# Ouvido Upgrade • Documentação

## 1. Propósito Geral
Ouvido Upgrade é uma plataforma completa de treino auditivo que concentra modos de ouvido absoluto, relativo, ritmo e ferramentas auxiliares em uma interface única. O aplicativo propõe sessões curtas, gamificadas e com reforço visual para acelerar o aprendizado musical, mantendo histórico, estatísticas e XP por usuário.

## 2. Trilhas e Modos
### 2.1 Ouvido Absoluto
- **Pitch Learn**: toca uma nota por vez, com controle de oitava/timbre, e o usuário responde na grade de notas; há revisão automática de erros e desbloqueio gradual de oitavas.
- **Pitch Quiz**: semelhante ao Learn, porém sem pistas visuais e com foco em recuperação ativa.
- **Review Erros**: fila das notas erradas mais recentes para repetição espaçada.
- **Learn Pitch (voz/instrumento)**: o app toca a nota alvo, o usuário canta/toca e o detector avalia o acerto, registrando XP e avançando para novas notas.
- **Pitch Reference / Diapasão**: modo livre, permite sustentar notas de 0,5s até 10 minutos.

### 2.2 Ouvido Relativo
- **Interval Learn/Quiz**: apresenta intervalos melódicos ou harmônicos com feedback visual, desbloqueando intervalos conforme a precisão melhora.
- **Chord ID**: reconhecimento de tríades/tétrades com reprodução bloqueada/arpejada.
- **Progressões (básicas e avançadas)**: identifica sequências harmônicas populares (I-IV-V, ii-V-I, progressões de rock/blues/J-Rock).
- **Key Detection**: descobre o tom geral de uma progressão tocada.

### 2.3 Ritmo
- **Metronome Sync**: mede o atraso/adiantamento do clique do usuário em relação ao metrônomo.
- **Subdivisions Grid**: executa padrões em colcheias, tercinas, quintinas e variações para treinar consistência.
- **Pattern Recall**: o app toca um padrão e o usuário replica; o sistema quantiza e calcula correspondência.

### 2.4 Ferramentas
- **Afinador Inteligente**: visualiza frequência, nota detectada, cents e confiança; perfeito para voz/instrumento.
- **Biblioteca de Acordes**: gera acordes e inversões dinamicamente, mostra diagramas para piano/guitarra/ukulele e toca cada acorde com timbre realista.
- **Teclado de Referência**: piano virtual de várias oitavas para tocar referências rápidas.
- **Pitch Reference/Diapasão**: já descrito acima, usado como drone ou referência longa.

## 3. Fluxo de Sessão
1. **Escolha do modo**: ao clicar em qualquer modo (exceto os livres), surge um modal com descrição, “como usar” e duração configurada. Confirmar inicia a sessão automaticamente.
2. **Sessão ativa**: o painel superior mostra o modo, o tempo restante e o status. Acertos registram XP e alimentam estatísticas.
3. **Pausa/retomada**: é possível pausar (cronômetro congela) e retomar a partir do ponto interrompido.
4. **Troca de modo**: mudar de modo durante a sessão dispara um alerta e encerra/registrar os resultados antes de carregar o próximo.
5. **Modos livres**: afinador, diapasão, teclado e biblioteca operam fora do fluxo de sessão e não alteram o cronograma nem a gamificação.

## 4. Gamificação e Persistência
- **Perfis locais**: múltiplos usuários podem ser criados; cada um possui XP, nível, histórico e configurações próprias.
- **XP e leaderboard**: ao finalizar sessões com tentativas válidas o usuário acumula XP; o leaderboard local mostra até cinco perfis com maior pontuação.
- **Estatísticas**: painel com total de sessões, precisão global e data da última atividade.
- **Histórico**: lista das últimas sessões com porcentagem de acertos e XP ganho.
- **Configurações por usuário**: tempo de sessão, instrumento padrão, tema visual, subdivisão alvo, agressividade da dificuldade, variação de oitavas e habilitação de assistências visuais.

## 5. Experiência Visual e Sonora
- A camada VisualEngine usa o canvas para exibir formas e cores associadas às notas, reforçando o feedback multimodal.
- O sistema de áudio cria síntese polifônica para notas, intervalos e progressões, além de timbres especiais para feedback de acerto/erro.
- O modo Biblioteca pode tocar acordes com timbre de piano realista, fornecendo experiências auditivas mais próximas de instrumentos acústicos.
- O afinador e o modo Learn Pitch usam a entrada de microfone para comparar frequências em tempo real e mostrar detalhes de cents/clarity.

## 6. Ferramentas em Detalhe
- **Afinador**: solicita acesso ao microfone, processa a frequência detectada, mostra centragem em cents e muda mensagens conforme estabilidade/confiança; ideal para voz, violão ou qualquer instrumento acústico.
- **Learn Pitch**: combina reprodução da nota alvo com detecção imediata do usuário. Quando o usuário acerta dentro de ±15 cents, o modo contabiliza como “correto” e avança automaticamente para a próxima nota.
- **Diapasão**: interface simples com seleção de oitava e duração, permitindo drones longos (até 10 minutos) para exercícios de foco ou referência de tom.
- **Biblioteca de Acordes**: apresenta nome do acorde, notas, graus, diagramas para teclado e instrumentos de corda, opções de inversão e botões para tocar em bloco ou arpejado.

## 7. Web App e Offline
- O app inclui `manifest.json` e `sw.js`, permitindo instalação como Web App (PWA) em navegadores modernos.
- O service worker cacheia os principais arquivos (HTML, CSS, JS, ícones), garantindo funcionamento offline após o primeiro acesso.
- Ícones `icon-192.png` e `icon-512.png` são placeholders e podem ser substituídos por artes oficiais sem alterar o fluxo.

## 8. Analytics e PWA
- O código embute o snippet do Google Analytics (gtag) para acompanhar uso básico.
- O manifesto define nome curto, tema e start_url `./index.html`, assegurando que o app abra sempre na interface principal quando instalado.

## 9. Assinatura e Versão
- O rodapé exibe, em linha única: “Desenvolvido por Flavio Fernandes (eusouoflavio.com.br) • Hospedado e apoiado por idagencia.com.br • Versão 1.0 • Documentação”.
- Esse link leva a este arquivo, garantindo transparência sobre a versão atual e fornecendo contexto para quem instalar o app como PWA.

## 10. Roadmap sugerido
- Painel interno “Sobre” com changelog automático.
- Exportação de resultados em CSV/JSON e sincronização futura com um backend.
- Presets customizados de exercícios que podem ser compartilhados entre usuários.