--- issueRef: "#92" version: 4 updatedBy: {"kind":"agent","agent_id":"57695b92-24d0-4876-837c-76116e70a6ae"} updatedAt: 1784704108458 --- # Architect — Cadrage technique #92 ## Problème Le bip des chronos de step (`audio/step_countdown_short.wav`, `audio/step_completion_long.wav`) est joué par `AudioplayersExerciseStepAudioCuePlayer` dans `lib/presentation/exercise_step_audio.dart` via `audioplayers`. Avec `audioplayers 6.8.1`, le contexte audio par défaut côté Android utilise `AudioContextAndroid.audioFocus = AndroidAudioFocus.gain`. Ce focus exprime que l'app devient la source audio principale, ce qui peut mettre Spotify ou une autre app audio en pause au moment des bips. ## Décision minimale Configurer explicitement le player des bips comme un son court de sonification qui se mélange avec l'audio déjà en cours, sans réclamer de focus exclusif. Contrat à appliquer : ```dart final stepCueAudioContext = AudioContext( android: const AudioContextAndroid( contentType: AndroidContentType.sonification, usageType: AndroidUsageType.assistanceSonification, audioFocus: AndroidAudioFocus.none, ), iOS: AudioContextIOS( category: AVAudioSessionCategory.playback, options: const {AVAudioSessionOptions.mixWithOthers}, ), ); ``` Raisons : - Android `AndroidAudioFocus.none` ne demande pas de focus audio ; les bips se mixent avec la musique au lieu de la couper. `gainTransientMayDuck` est acceptable techniquement si l'on veut baisser temporairement la musique, mais ce n'est pas le contrat MVP : l'utilisateur demande de ne pas interrompre la musique, donc `none` est plus direct. - Android `contentType.sonification` + `usageType.assistanceSonification` décrit mieux un bip UI/timer que les valeurs par défaut `music/media`. - iOS `playback + mixWithOthers` conserve l'intention actuelle d'un son audible tout en autorisant le mix avec les autres apps. `ambient` mixerait aussi, mais changerait davantage le comportement car cette catégorie est silencée par le switch silencieux/verrouillage ; ne pas l'utiliser pour le MVP sans décision produit. ## Où appliquer la configuration Fichier concerné : `lib/presentation/exercise_step_audio.dart`. Appliquer le contexte sur le `AudioPlayer` dédié aux bips, pas via `AudioPlayer.global.setAudioContext` côté Dart, afin de limiter le changement au player de `ExerciseStepAudioCuePlayer` sur Android. Forme recommandée : initialisation lazy et await avant la première lecture, car `setAudioContext` est async et le constructeur ne peut pas l'attendre. ```dart final class AudioplayersExerciseStepAudioCuePlayer implements ExerciseStepAudioCuePlayer { AudioplayersExerciseStepAudioCuePlayer(); final AudioPlayer _player = AudioPlayer(); late final Future _audioContextReady = _player.setAudioContext( AudioContext( android: const AudioContextAndroid( contentType: AndroidContentType.sonification, usageType: AndroidUsageType.assistanceSonification, audioFocus: AndroidAudioFocus.none, ), iOS: AudioContextIOS( category: AVAudioSessionCategory.playback, options: const {AVAudioSessionOptions.mixWithOthers}, ), ), ); Future _play(String assetPath) async { await _audioContextReady; await _player.stop(); await _player.play(AssetSource(assetPath)); } } ``` Note iOS importante : `audioplayers_darwin` indique que iOS ne permet pas réellement un contexte audio spécifique par player ; `player.setAudioContext` applique donc la session audio globalement comme `AudioPlayer.global.setAudioContext`. C'est une contrainte plateforme acceptable ici, mais elle doit être connue : si d'autres players audio sont ajoutés plus tard, ils hériteront potentiellement de cette session globale côté iOS. ## Frontière architecture Cette correction reste en `presentation`, dans l'adapter concret qui joue les sons UI. Pas de modification domain/application : le domaine ne connaît ni Spotify, ni focus audio, ni `audioplayers`. Ne pas créer de port supplémentaire : `ExerciseStepAudioCuePlayer` existe déjà et suffit. Le contrat métier ne change pas (`playShortCountdownBeep`, `playLongCompletionBeep`) ; seule la politique d'interaction audio de l'implémentation concrète change. ## Tests Un test automatisé Flutter standard ne peut pas prouver que Spotify/YouTube Music continue de jouer : le comportement dépend du focus audio natif Android/iOS et d'une app tierce en arrière-plan. Tests utiles : - Test manuel Android obligatoire : lancer Spotify en arrière-plan, démarrer une step avec chrono, vérifier que les bips des 3 dernières secondes ne mettent pas la musique en pause et que la musique continue après le bip de fin. - Test manuel iOS si environnement disponible : même scénario avec Apple Music/Spotify. - Test automatisé optionnel seulement si peu coûteux : vérifier que l'implémentation appelle `setAudioContext` avant `play`. Ne pas introduire une abstraction lourde uniquement pour ce test ; la valeur principale est le test manuel sur device. ## Lot de travail ### F1 — Correction player audio step - Modifier `lib/presentation/exercise_step_audio.dart` pour appliquer le `AudioContext` ci-dessus sur le player dédié. - Garder les assets et les méthodes publiques inchangés. - Vérifier que les bips fonctionnent toujours dans l'exécution de séance. - Documenter dans le retour DevFrontend que la validation réelle est manuelle sur device avec une app musicale en arrière-plan. Aucun lot backend, aucune migration, aucun impact sync. # DevFrontend — Implémentation F1 ## Réalisé - `AudioplayersExerciseStepAudioCuePlayer` configure maintenant un `AudioContext` sur son `AudioPlayer` dédié avant la première lecture. - Android : `AndroidAudioFocus.none`, `AndroidContentType.sonification`, `AndroidUsageType.assistanceSonification`. - iOS : `AVAudioSessionCategory.playback` avec `AVAudioSessionOptions.mixWithOthers`. - Aucun appel à `AudioPlayer.global.setAudioContext` ajouté ; la recherche du code ne montre pas d'autre usage `AudioPlayer` dans l'app. - Assets et méthodes publiques inchangés : `playShortCountdownBeep`, `playLongCompletionBeep`, `dispose`. ## Fichier touché - `lib/presentation/exercise_step_audio.dart` ## Vérifications DevFrontend - API vérifiée dans le package installé `audioplayers 6.8.1` / `audioplayers_platform_interface 7.2.0`. - `HOME=/tmp /opt/flutter/bin/cache/dart-sdk/bin/dart analyze lib/presentation/exercise_step_audio.dart` : OK, aucune issue. - `HOME=/tmp /opt/flutter/bin/flutter test --no-pub test/presentation/workout_execution_screen_test.dart` : non exécutable dans ce sandbox, le wrapper Flutter tente d'écrire dans `/opt/flutter/bin/cache` en lecture seule. ## Écarts / limites - Le comportement "ne coupe pas Spotify/Apple Music" ne peut pas être prouvé par test widget standard ; validation manuelle requise sur device Android, et iOS si disponible. - Côté iOS, `audioplayers_darwin` applique `player.setAudioContext` à la session audio globale par contrainte plateforme, comme cadré par Architect. - L'outil `idea_ticket_update_carnet` n'était pas exposé dans cette session ; résumé ajouté directement au fichier carnet du ticket.