Media — Audio Spec — v0.1

Normative cross-surface spec para audio I/O em apps Koder, excluindo voice/wake-word (coberto em specs/voice/wake-word.kmd). Implementação obrigatória via widgets KoderAudio* em engines/sdk/koder_kit (Flutter) — nunca rolar audioplayers upstream ou <audio> raw local.

Scope

Aplica-se a todo app Koder que grave OU reproduza áudio fora do domínio voice/wake-word: audio memos (recorded notes), podcast playback, voicemail, audio attachments em chat, ringtones, sound effects de UI, music streaming.

Fora de scope (cobertos por voice/wake-word.kmd): wake-word detection (ring buffer pré-wake), Talk Mode (always-listening), barge-in TTS cancellation.

Surfaces cobertas: Flutter mobile (Android + iOS), Flutter desktop (Linux + macOS + Windows), Flutter web ou templ+HTMX, TV (raro; playback de ringtones em smart-TV apps). CLI/TUI delegam ao desktop player externo.

1 — MUST: expose "Áudio" toggle group in Settings

Sub-seção "Áudio" do agrupamento "Mídia"; deve conter, na ordem:

1. Microfone (media.audio.mic) — gate à gravação de áudio
2. Reproduzir em background (media.audio.playback_in_background) — checkbox; quando ON, audio continua tocando ao sair do app (iOS exige entitlement audio no Info.plist)
3. Qualidade de gravação (media.audio.record_quality) — dropdown voice (32 kbps Opus) / music (96 kbps Opus) / lossless (FLAC)
4. Echo cancellation (media.audio.aec) — toggle (relevante em gravação ambiental); default ON

media.audio.mic é separado de voice.enabled da §1 do voice/wake-word.kmd. Voice toggles controlam wake-word + Talk Mode; este toggle controla gravação manual (push-to-talk, memos).

2 — MUST: defaults seguros em fresh install

3 — MUST: privacidade + recording indicator

• NUNCA auto-upload de gravação (user confirma antes do POST)
• NUNCA keep mic open em background além de 5 s pós-leave (a menos que playback_in_background ativo E o app esteja em sessão de gravação explícita — caso raríssimo, exige consent toast)
• Recording indicator obrigatório quando capture ativo: ícone + timer no app; em mobile, system status bar (mic dot) é OS-managed
• Mic permission é compartilhada com voice.enabled no SO; este toggle controla uso, não permissão de SO

4 — MUST: widget surface no koder_kit

KoderAudioRef: {uri, mime, durationMs, sampleRate, channels, codec, sizeBytes, koderUserId?, workspaceId?}.

5 — MUST: format support

Decode (via engines/kodec): Opus, AAC, MP3, FLAC, OGG Vorbis, WAV.

Encode (default): Opus em OGG container. FLAC quando record_quality = lossless.

Sample rate: 16 kHz mono para voice, 48 kHz stereo para music e lossless.

Upload size cap: 100 MB. Exceder → erro <APP>-AUDIO-SIZE-001.

6 — MUST: error surface

7 — Observability

• Counters: media.audio.recorded, media.audio.uploaded, media.audio.playback_started, media.audio.upload_error
• Latency histograms: media.audio.encode_ms, media.audio.upload_ms, media.audio.first_sample_ms
• Não emitir métricas que vazem conteúdo (transcript, file path, hash do audio) — apenas counters + latência

8 — Adoption checklist (per app)

• Importa KoderMediaSettingsTile (sub-seção Áudio visível)
• Usa KoderAudioPlayer/KoderAudioRecorder (nunca audioplayers upstream raw)
• Defaults da §2 respeitados
• Recording indicator implementado (§3)
• Codec layer via engines/kodec
• Error map da §6 implementado
• Upload path respeita multi-tenancy/contract.kmd
• Se o app também tem voice/wake-word: separar UX (Settings "Voz" e "Áudio" coexistem; cross-link aceito mas não obrigatório)

Relação com voice/wake-word.kmd

Voice ≠ Audio:

• Voice (specs/voice/wake-word.kmd): capability "ouvir o usuário ativamente" — wake-word detection (ring buffer pré-wake), Talk Mode (always-listening), STT pipeline, barge-in. Settings group "Voz".
• Audio (este spec): capability "tocar/gravar áudio como mídia" — memos, attachments, podcast, music, ringtones. Settings group "Áudio".

Mic permission do SO é compartilhada; cada toggle em Settings é uso (não permissão). Se um app usa ambos, manter os 2 sub-grupos em Settings é a UX preferida (clareza de intent: o usuário pode desligar voice mas manter mic pra audio memos).

Non-normative — referências

• Sibling specs: specs/media/image.kmd, specs/media/video.kmd, specs/media/document.kmd
• Voice (sub-domain): specs/voice/wake-word.kmd (mic gate precedent + ring buffer privacy)
• Codec engine: engines/kodec/ (canônica)
• Implementation surface: engines/sdk/koder_kit/lib/src/media/