pmomusic/Blackboard/Report/bug_lecture_queue_interne.md

Rapport : Correction du bug de lecture sur queue interne

Problème

Lors de la lecture sur un Renderer avec queue interne, si l'utilisateur clique sur un item de la queue pour déclencher sa lecture, tout semble se passer normalement pendant une seconde. Puis, avant que la lecture ne démarre réellement, le lecteur passe à la piste suivante.

Analyse

Cause identifiée

Le problème était une race condition dans la logique d'auto-advance du watcher.

Quand l'utilisateur clique sur un item de la queue :

1. play_queue_index est appelé dans ControlPoint
2. Les commandes UPnP SetAVTransportURI + Play sont envoyées au renderer
3. Le renderer peut passer brièvement par un état STOPPED pendant l'initialisation de la nouvelle piste
4. Le watcher (polling toutes les 500ms) détecte cet état STOPPED
5. Comme la lecture était lancée depuis la queue (PlaybackSource::FromQueue), l'auto-advance se déclenche et passe à la piste suivante

Détail technique

La logique d'auto-advance dans handle_state_change vérifie si is_playing_from_queue() retourne true pour décider de passer à la piste suivante quand l'état STOPPED est détecté. Cependant, il n'y avait aucun mécanisme pour distinguer :

• Un état STOPPED transitoire pendant l'initialisation d'une nouvelle piste
• Un état STOPPED réel indiquant la fin de lecture d'une piste

Solution implémentée

Ajout d'un flag has_played_since_track_start dans MusicRendererState qui permet de tracker si l'état PLAYING a été observé depuis le dernier démarrage de piste.

Logique du flag

1. Quand on démarre une nouvelle piste (play_from_index, play_from_queue, play_next_from_queue, play_current_from_queue) : le flag est remis à false

2. Quand le watcher détecte l'état PLAYING : le flag passe à true

3. Quand le watcher détecte l'état STOPPED :

   • Si has_played_since_track_start == true : c'est une vraie fin de piste → auto-advance autorisé
   • Si has_played_since_track_start == false : c'est un état transitoire pendant l'initialisation → auto-advance bloqué

4. Quand stop() est appelé : le flag est remis à false

Fichiers modifiés

pmocontrol/src/music_renderer/musicrenderer.rs

1. Ajout du champ has_played_since_track_start dans MusicRendererState :

struct MusicRendererState {
    // ...
    /// Flag indicating that a PLAYING state has been observed since the last track start.
    /// This prevents auto-advance on transient STOPPED states during track initialization.
    /// Auto-advance is only allowed when this flag is true.
    has_played_since_track_start: bool,
}

2. Ajout des méthodes de gestion du flag :

   • set_has_played_flag() : met le flag à true
   • clear_has_played_flag() : met le flag à false (publique)
   • check_and_clear_has_played_flag() : vérifie et remet à false

3. Modification de handle_state_change :

   • Sur PLAYING : appelle set_has_played_flag()
   • Sur STOPPED avec is_playing_from_queue() : vérifie check_and_clear_has_played_flag() avant d'auto-advance

4. Modification des méthodes de démarrage de lecture :

   • play_current_from_queue()
   • play_next_from_queue()
   • play_from_index()
   • play_from_queue()
   • stop()

   Toutes appellent clear_has_played_flag() pour réinitialiser le flag.

Tests effectués

• Clic sur différents items de la queue : la piste sélectionnée est bien jouée sans saut
• Lecture normale jusqu'à la fin d'une piste : l'auto-advance vers la piste suivante fonctionne correctement
• Arrêt manuel (stop) : pas d'auto-advance intempestif