88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# PR-005: Host Audio Fallible Init and Headless Tolerance
|
|
|
|
## Briefing
|
|
|
|
O host desktop atual assume que audio de saida esta sempre disponivel e funcional. Em ambientes headless, CI, VMs remotas ou sistemas sem device compativel, a inicializacao usa `expect(...)` e encerra o processo.
|
|
|
|
Este PR torna a pilha de audio tolerante a falhas de infraestrutura. O runtime deve continuar operando sem audio quando o host nao puder inicializar a saida sonora.
|
|
|
|
## Problema
|
|
|
|
- `default_output_device()` pode retornar `None`.
|
|
- `build_output_stream(...)` pode falhar por formato/configuracao.
|
|
- `stream.play()` pode falhar por indisponibilidade do backend.
|
|
- Todas essas falhas hoje derrubam o binario com `panic!`.
|
|
|
|
## Escopo
|
|
|
|
- Trocar inicializacao panica por API fallible.
|
|
- Permitir degradacao controlada para "sem audio".
|
|
- Manter telemetria/log suficiente para diagnostico.
|
|
- Cobrir o fluxo em testes de unidade onde viavel.
|
|
|
|
## Fora de Escopo
|
|
|
|
- Rework do mixer.
|
|
- Selecao automatica de formatos de audio mais sofisticada.
|
|
- Hot-reload de device de audio.
|
|
- Simulacao de audio em buffer offline.
|
|
|
|
## Abordagem
|
|
|
|
1. Mudar `HostAudio::init` para retornar `Result<(), HostAudioError>` ou tipo equivalente.
|
|
2. Representar explicitamente o estado "audio indisponivel":
|
|
- `producer = None`
|
|
- `stream = None`
|
|
- stats continuam funcionando sem crash.
|
|
3. No chamador, registrar aviso e seguir execucao sem audio.
|
|
4. Garantir que `send_commands` e `update_stats` sejam no-op seguros quando o audio nao estiver ativo.
|
|
|
|
## Algoritmo
|
|
|
|
### Inicializacao
|
|
|
|
1. Buscar `default_output_device`.
|
|
2. Se nao existir:
|
|
- retornar erro de inicializacao controlado.
|
|
3. Tentar construir `StreamConfig` e `build_output_stream`.
|
|
4. Se falhar:
|
|
- retornar erro controlado sem panicar.
|
|
5. Tentar `play()`.
|
|
6. Se falhar:
|
|
- retornar erro controlado sem panicar.
|
|
7. Apenas em caso de sucesso preencher `producer`, `perf_consumer` e `_stream`.
|
|
|
|
### Degradacao
|
|
|
|
1. O host chama `init`.
|
|
2. Se `Ok`, audio ativo.
|
|
3. Se `Err`, loga a falha e continua sem audio.
|
|
4. O loop principal segue responsivo e funcional.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- O runtime nao entra em `panic!` quando nao existe device de audio.
|
|
- O runtime nao entra em `panic!` quando `build_output_stream` falha.
|
|
- O runtime nao entra em `panic!` quando `play()` falha.
|
|
- `send_commands` e `update_stats` continuam seguros sem stream ativo.
|
|
- O host continua executando cartridge em modo sem audio.
|
|
- Logs deixam claro por que o audio foi desativado.
|
|
|
|
## Tests
|
|
|
|
- Introduzir testes de unidade para o estado sem audio:
|
|
- `send_commands` nao falha quando `producer` e `None`;
|
|
- `update_stats` nao falha quando `perf_consumer` e `None`.
|
|
- Se a estrutura atual permitir injecao de dependencia:
|
|
- testar caminho `no output device`;
|
|
- testar falha na criacao do stream;
|
|
- testar falha no `play`.
|
|
- Se injecao ainda nao existir, criar uma camada minima de abstracao para tornar esses cenarios testaveis sem depender do hardware real.
|
|
- Rodar:
|
|
- `cargo test -p prometeu-host-desktop-winit`
|
|
- `cargo test --workspace`
|
|
|
|
## Risco
|
|
|
|
Baixo. A mudanca principal e de robustez operacional. O maior cuidado e nao esconder a falha completamente; o modo sem audio precisa ser explicito em logs.
|