Media — Video Spec — v0.1

Normative cross-surface spec para video I/O em apps Koder. Implementação obrigatória via widgets KoderVideo* em engines/sdk/koder_kit (Flutter) e koder_web_kit (JS) — nunca rolar video_player upstream ou <video> raw local. Codec layer via engines/kodec (canônica) ou Koda port (shadow-active).

Scope

Aplica-se a todo app Koder que grave, reproduza, ou faça screen-capture de vídeo: call recording, tutorial in-app, attachment de vídeo em chat, demo em landing, screen-share em ferramenta de dev, upload de vídeo de produto.

Surfaces cobertas: Flutter mobile (Android + iOS), Flutter desktop (Linux + macOS + Windows), Flutter web ou templ+HTMX, TV (playback; gravação fora de escopo em TV). CLI/TUI exigem path arg + delegam ao desktop player externo.

1 — MUST: expose "Vídeo" toggle group in Settings

Sub-seção "Vídeo" do agrupamento "Mídia" em Settings; deve conter, na ordem:

1. Câmera (media.video.camera) — gate à camera
2. Microfone para vídeo (media.video.mic) — gate ao mic durante gravação
3. Compartilhar tela (media.video.screen) — gate ao screen-capture
4. Resolução máxima (media.video.max_height) — dropdown 480 / 720 / 1080 / 2160
5. Qualidade (media.video.bitrate_mbps) — slider 1-20 Mbps

Compartilha media.image.camera quando ambos coexistem (camera permission é granted ao app, não ao sub-uso); cada toggle controla uso, não permissão de SO.

2 — MUST: defaults seguros em fresh install

Quando qualquer toggle for OFF em runtime, o app deve parar qualquer capture ativo + liberar handles + dismiss screen-share dialog.

3 — MUST: privacidade + recording indicator

• NUNCA auto-upload de gravação (user confirma antes do POST)
• NUNCA screen-capture em background sem user-visible indicator
• NUNCA keep camera open em background além de 5 s pós-leave
• Recording indicator obrigatório: dot vermelho + timer + título da janela alterado para ● Recording — <app>; em mobile, system status bar fica vermelho (iOS) / mostra ícone (Android)
• EXIF/metadata strip equivalente para vídeo (camera serial, GPS de container MP4); media.video.strip_metadata = true default

4 — MUST: widget surface no koder_kit

KoderVideoRef: {uri, mime, durationMs, width, height, sizeBytes, hasAudio, codec, koderUserId?, workspaceId?}.

5 — MUST: format support

Decode (via engines/kodec): H.264, HEVC (HEIC pipeline), AV1, VP9 — container MP4, WebM, MOV.

Encode (default): H.264 + AAC + MP4 container. HEVC e AV1 são opt-in quando suportado pela surface (iOS encoder, browser MediaRecorder com codec hint).

Upload size cap: 500 MB pós-compress. Exceder → erro <APP>-VIDEO-SIZE-001 com sugestão de bitrate menor ou trim.

Compression knob: media.video.bitrate_mbps (§2) controla output; duração + resolução + bitrate determinam tamanho. App deve estimar size pré-encode e avisar se ultrapassar cap.

6 — MUST: error surface

7 — Observability

• Counters: media.video.recorded, media.video.uploaded, media.video.upload_error, media.video.screen_captured
• Latency histograms: media.video.encode_ms, media.video.upload_ms, media.video.first_frame_ms (playback)
• Não emitir métricas que vazem conteúdo (transcript, frames, file path) — apenas counters + latência + dimensões anonimizadas (resolução, codec, duration)

8 — Adoption checklist (per app)

• Importa KoderMediaSettingsTile (sub-seção Vídeo visível)
• Usa KoderVideoPlayer/KoderVideoRecorder/KoderScreenCapture (nunca video_player upstream raw)
• Defaults da §2 respeitados em fresh install
• Recording indicator obrigatório (§3)
• Codec layer via engines/kodec (ou Koda port quando flipped)
• Error map da §6 implementado
• Upload path respeita multi-tenancy/contract.kmd

Non-normative — referências

• Sibling specs: specs/media/image.kmd (camera shared), specs/media/audio.kmd (mic + recording indicator paralelo), specs/media/document.kmd
• Codec engine: engines/kodec/ (canônica, Rust); Koda port em engines/lang/koda/lib/{mp4,mp3,wav}.kd (shadow-active per Flipping Point em CLAUDE.md)
• Implementation surface: engines/sdk/koder_kit/lib/src/media/
• Voice precedent (mic + privacy contract): specs/voice/wake-word.kmd