📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados na Especialização em Android Nativo. Recomendado revisar antes de iniciar.

🎵 P17: Anime Soundboard (MediaPlayer & Áudio)

v1.0 — Android Nativo, Kotlin, MediaPlayer, AudioManager, Gestão de Audio Focus, Efeitos Sonoros e Grade Interativa

Série Prática Android Clássico — Projeto 17 de 21

P16: Alerta Gotham com Broadcast & Alarmes

➡️ P17 (este): Anime Soundboard com MediaPlayer

P18: Radar de Habilidades com Canvas 2D

P19: Banco de Wakanda com MVVM & Room

P20: Alliance Battle com Finite State Machine

🏛️ Visão Geral & Arquitetura Visual

O projeto Anime Soundboard aborda a reprodução e controle avançado de áudio contínuo no Android utilizando a classe nativa MediaPlayer. A aplicação implementa uma mesa de efeitos sonoros temáticos (frases clássicas de animes lendários), gerenciando concorrência de reprodução, requisição e liberação correta de Foco de Áudio (AudioManager.requestAudioFocus) para pausar músicas de outros aplicativos respeitosamente e encerramento preventivo de instâncias para evitar vazamentos de memória de hardware.

Fluxo Visual do Anime Soundboard com MediaPlayer

📁 Estrutura de Pastas Anti-Colisão

Os gerenciadores de áudio, recursos sonoros e interfaces residem na subpasta canônica mobile-android-kotlin/:

catalogo_projetos/android_p17_soundboard_audio/
├── assets/
│   ├── mockup_soundboard_fluxo.svg
│   ├── screenshot_01_soundboard_grid.svg
│   ├── screenshot_02_soundboard_playing.svg
│   └── screenshot_03_soundboard_goku.svg
├── mobile-android-kotlin/
│   ├── app/
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── java/br/com/curso/soundboard/
│   │   │       │   ├── audio/
│   │   │       │   │   └── SoundManager.kt
│   │   │       │   └── MainActivity.kt
│   │   │       ├── res/
│   │   │       │   └── raw/
│   │   └── build.gradle
│   ├── gradle/
│   ├── build.gradle
│   ├── gradlew
│   ├── settings.gradle
│   └── README.md
└── index.md

🧑‍💼 Engenharia de Software & Especificação Formal

1. Histórias de Usuário (User Stories)

ID	Persona	Narrativa da Funcionalidade	Critério de Aceitação Principal	Prioridade
US-01	Fã de Anime / Usuário	Quero tocar em um botão da grade para disparar o efeito sonoro correspondente.	Reprodução imediata com animação visual de botão ativo.	Alta
US-02	Usuário	Quero que o app pause suavemente caso outro som seja acionado ou o usuário pare a reprodução.	Interrupção imediata via `mediaPlayer.stop()` sem sobreposição indesejada.	Alta
US-03	Usuário com Fone	Quero que a reprodução pause automaticamente caso eu desconecte o fone de ouvido.	Tratamento do evento de broadcast `AudioManager.ACTION_AUDIO_BECOMING_NOISY`.	Alta
US-04	Desenvolvedor Mobile	Quero solicitar foco de áudio transiente para não interromper permanentemente podcasts do usuário.	Uso de `AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK`.	Média
US-05	Engenheiro de Performance	Quero que o `MediaPlayer` seja liberado (`release()`) sempre que a Activity for destruída.	Prevenção total de vazamento de codecs de áudio no hardware.	Baixa

2. Requisitos do Sistema

Requisitos Funcionais (RF)

RF-01: Exibir grade responsiva com botões ilustrados para cada clipe de áudio.
RF-02: Instanciar e orquestrar MediaPlayer.create(context, resId) de forma dinâmica.
RF-03: Solicitar foco de áudio através de AudioFocusRequestCompat.
RF-04: Configurar ouvinte setOnCompletionListener para restaurar o estado visual do botão após o fim do clipe.
RF-05: Interromper reprodução em andamento caso o usuário selecione outro clipe da grade.

Requisitos Não-Funcionais (RNF)

RNF-01 (Liberação de Recursos): Invocação mandatória de mediaPlayer?.release() e atribuição de referência nula.
RNF-02 (Latência de Disparo): Tempo entre o toque e a emissão do som inferior a 50ms.
RNF-03 (Formatos Otimizados): Uso de formatos de alta fidelidade e compactação eficiente (.ogg Vorbis / Opus).
RNF-04 (Compatibilidade de Versão): Suporte estável desde Android API 21 até Android API 34.
RNF-05 (Boa Convivência de Áudio): Liberação imediata do foco de áudio ao término do efeito.

3. Diagrama de Casos de Uso

flowchart TD
    User([fa:fa-user Usuário / Fã])
    AudioManager[(fa:fa-sliders AudioManager Focus)]
    PlayerEngine[(fa:fa-play MediaPlayer Engine)]

    subgraph AppSoundboard ["🎵 Anime Soundboard (mobile-android-kotlin)"]
        UC01["Selecionar Som na Grade"]
        UC02["Solicitar Foco de Áudio"]
        UC03["Interromper Som Anterior"]
        UC04["Reproduzir Clipe Escolhido"]
        UC05["Liberar Recursos no Fechamento"]
    end

    User --> UC01
    UC01 --> UC02
    UC02 --> AudioManager
    UC02 --> UC03
    UC03 --> PlayerEngine
    UC03 --> UC04
    UC04 --> PlayerEngine
    User --> UC05
    UC05 --> PlayerEngine

4. Matriz de Rastreabilidade (RTM)

ID Requisito	História de Usuário	Artefato de Código	Teste de Aceitação
RF-01	US-01	`mobile-android-kotlin/app/src/main/res/layout/activity_main.xml`	`testSoundboardGridLayout()`
RF-02	US-01	`mobile-android-kotlin/app/.../SoundManager.kt`	`testMediaPlayerInstanceCreated()`
RF-03	US-04	`mobile-android-kotlin/app/.../SoundManager.kt`	`testAudioFocusRequestGranted()`
RF-04	US-01, US-02	`mobile-android-kotlin/app/.../SoundManager.kt`	`testOnCompletionListenerFired()`
RF-05	US-02	`mobile-android-kotlin/app/.../SoundManager.kt`	`testStopPreviousSoundBeforeNew()`

🛠️ Implementação Guiada (`SoundManager.kt`)

ℹ️ O trecho de código que ficava aqui não correspondia ao código do projeto e foi retirado. Consulte os arquivos em mobile-android-kotlin.

🚀 Como Executar no Laboratório

1. Navegue até a subpasta do projeto

cd catalogo_projetos/android_p17_soundboard_audio/mobile-android-kotlin

2. Compile e instale no dispositivo com som

./gradlew installDebug

🏁 Matriz de Checkpoints de Conclusão

Checkpoint	Meta Técnica	Critério de Aceite	Status
CP-01	Instanciação MediaPlayer	Carregamento de arquivos `.ogg` a partir do diretório `raw/`	`PASS ✅`
CP-02	Controle de Concorrência	Um único áudio reproduzido por vez sem cacofonia	`PASS ✅`
CP-03	Gestão de Audio Focus	Solicitação e liberação correta do canal de som	`PASS ✅`
CP-04	Tratamento de Desconexão	Pausa automática ao desconectar o fone de ouvido	`PASS ✅`
CP-05	Suíte de Testes Automatizados	Testes de unidade do gerenciador de áudio aprovados	`PASS ✅`