pluriwave/docs/audio-switching-notes.md

Notas de reproducción de radio con just_audio/audio_service

Referencia interna para futuras correcciones del reproductor de PluriWave. Este archivo está en docs/ y no se incluye en flutter.assets, por lo que no compila dentro de la app.

Hallazgos útiles

• AudioPlayer.play() no debe esperarse como si fuera “arrancar y terminar” en un stream de radio en vivo. Según la documentación de just_audio, el Future de play() completa cuando la reproducción termina, se pausa o se detiene. En una radio en vivo puede quedar vivo hasta que otra acción lo interrumpa.
• Para streams en vivo, la UI debe depender de playerStateStream: loading/buffering para spinner, ready + playing para estado en directo.
• El ejemplo de radio de just_audio configura sesión de audio y escucha errores de playback. Conviene tratar el cambio de emisora como una operación transaccional: parar fuente anterior, asignar fuente nueva y arrancar sin bloquear el flujo principal.
• En audio_service, si se cambia de fuente desde playMediaItem, hay que evitar que errores tardíos de la fuente anterior limpien la emisora nueva. Es una carrera típica cuando se hace stop() y enseguida se carga otro stream.

Decisión aplicada en PluriWave

• Mantener setUrl(...) porque era la ruta que conectaba correctamente la primera emisora en esta app.
• Serializar cambios de emisora con una cola interna para que no se solapen stop/setUrl/play.
• Usar una revisión incremental para que solo la última solicitud pueda actualizar estado/errores.
• Ejecutar play() sin await, porque en radios en vivo su Future no representa “ya arrancó”, sino “terminó/pausó/detuvo”.
• Proteger EstadoRadio.reproducir con revisión para que una reproducción vieja que termine tarde no aplique presets/clicks encima de la emisora nueva.

Intento descartado

• Se probó setAudioSource(..., preload: false) siguiendo una interpretación más transaccional del API, pero en PluriWave rompió incluso la primera conexión. Queda descartado salvo que se acompañe de logs nativos que justifiquen retomarlo.

Fuentes consultadas

• just_audio AudioPlayer.play() API: https://pub.dev/documentation/just_audio/latest/just_audio/AudioPlayer/play.html
• just_audio AudioPlayer API general: https://pub.dev/documentation/just_audio/latest/just_audio/AudioPlayer-class.html
• Ejemplo de radio en vivo de just_audio: https://gist.github.com/scysys/7f700cd49f09ba788021504e8d3477aa
• Discusión sobre cambiar fuente con audio_service + just_audio: https://stackoverflow.com/questions/70526156/changing-audio-source-in-audio-service-and-just-audio-flutter