pmomusic/Blackboard/Done/shuffle_play.md

Rapport Final : Implémentation du Shuffle de la Queue de Lecture

Résumé

Implémentation complète de la fonctionnalité de shuffle (mélange aléatoire) de la queue de lecture pour les Music Renderers dans PMOMusic. Cette fonctionnalité permet de randomiser l'ordre des morceaux dans la queue et de redémarrer la lecture depuis le premier morceau.

Au-delà de la fonctionnalité shuffle, ce travail a permis d'améliorer l'architecture en centralisant l'émission des événements SSE dans le MusicRenderer plutôt que dans le ControlPoint.

Travail effectué

Étape 1 : Implémentation de la méthode shuffle dans MusicRenderer

Fichier modifié : pmocontrol/src/music_renderer/musicrenderer.rs

Ajout de la méthode shuffle_queue() qui implémente la stratégie suivante :

1. Détache la queue de lecture d'une playlist si celle-ci est attachée
2. Arrête la lecture en cours
3. Prend un snapshot de la queue actuelle
4. Randomise l'ordre des morceaux avec rand::seq::SliceRandom
5. Remplace la queue avec les items mélangés
6. Redémarre la lecture au premier morceau

Dépendances ajoutées :

• rand = "0.9" dans Cargo.toml (workspace)
• rand = { workspace = true } dans pmocontrol/Cargo.toml

Étape 2 : API REST et documentation OpenAPI

Fichiers modifiés :

• pmocontrol/src/pmoserver_ext.rs : Ajout du handler shuffle_queue
• pmocontrol/src/openapi.rs : Ajout du path dans la documentation OpenAPI

Endpoint créé :

POST /api/control/renderers/{renderer_id}/queue/shuffle

Réponses :

• 200 : Queue mélangée et lecture démarrée
• 400 : Queue vide
• 404 : Renderer non trouvé
• 504 : Timeout de la commande
• 500 : Erreur interne

Étape 3 : Interface Vue.js

Fichiers créés :

• pmoapp/webapp/src/components/pmocontrol/ShuffleControl.vue : Nouveau composant bouton shuffle

Fichiers modifiés :

• pmoapp/webapp/src/services/pmocontrol/api.ts : Ajout de la méthode shuffleQueue()
• pmoapp/webapp/src/components/unified/BottomTabBar.vue : Intégration du bouton shuffle à côté du timer

Design :

• Bouton circulaire avec icône Shuffle (lucide-vue-next)
• Style cohérent avec le bouton Timer existant
• Animation de chargement pendant l'exécution
• Responsive (taille réduite sur mobile)

Étape 4 : Émission automatique des événements SSE (Round 3)

Problème identifié : L'interface utilisateur ne se mettait pas à jour après un shuffle car aucun événement QueueUpdated n'était émis.

Solution implémentée : Le MusicRenderer stocke maintenant une référence optionnelle au RendererEventBus et émet automatiquement un événement QueueUpdated après chaque modification de la queue.

Fichiers modifiés :

Fichier	Modification
pmocontrol/src/music_renderer/musicrenderer.rs	Ajout du champ event_bus: Option<RendererEventBus>, constructeur from_renderer_info_with_bus(), méthode helper emit_queue_updated(), implémentation manuelle de Debug
pmocontrol/src/registry.rs	Passage du RendererEventBus lors de la création des renderers via from_renderer_info_with_bus()

Méthodes qui émettent désormais QueueUpdated :

• enqueue_items() - Ajout d'items à la queue
• sync_queue() - Synchronisation de la queue
• clear_queue() - Vidage de la queue
• replace_queue() - Remplacement complet de la queue (utilisé par shuffle_queue())
• play_next_from_queue() - Passage au morceau suivant
• play_from_index() - Lecture à un index spécifique

Étape 5 : Refactoring des émissions d'événements (Round 4)

Objectif : Centraliser les émissions d'événements dans le MusicRenderer et supprimer les émissions redondantes du ControlPoint.

Principe : Puisque le MusicRenderer a maintenant accès au RendererEventBus, il est plus cohérent et maintenable que les événements soient émis au niveau du renderer plutôt que dispersés dans le ControlPoint.

Événements QueueUpdated

Modifications dans ControlPoint - Suppression des émissions redondantes dans :

• clear_queue()
• enqueue_items_with_mode()
• shuffle_queue()
• play_next_from_queue()

Événements BindingChanged

Modifications dans MusicRenderer :

• set_playlist_binding() : Émet BindingChanged uniquement si le binding change réellement
• clear_playlist_binding() : Émet BindingChanged uniquement s'il y avait un binding à supprimer
• Ajout de la méthode helper emit_binding_changed()

Modifications dans ControlPoint :

• attach_queue_to_playlist_internal() : Suppression de l'émission manuelle de BindingChanged
• detach_playlist_binding() : Suppression de l'émission manuelle, utilisation de clear_playlist_binding() au lieu de set_playlist_binding(None)

Liste complète des fichiers modifiés

Fichier	Type de modification
Cargo.toml (workspace)	Ajout dépendance rand
pmocontrol/Cargo.toml	Ajout dépendance rand
pmocontrol/src/music_renderer/musicrenderer.rs	Ajout shuffle_queue(), event_bus, émission d'événements automatique
pmocontrol/src/control_point.rs	Suppression des émissions d'événements redondantes
pmocontrol/src/registry.rs	Passage du RendererEventBus lors de la création des renderers
pmocontrol/src/pmoserver_ext.rs	Ajout handler REST shuffle_queue
pmocontrol/src/openapi.rs	Ajout documentation OpenAPI
pmoapp/webapp/src/services/pmocontrol/api.ts	Ajout méthode API shuffleQueue()
pmoapp/webapp/src/components/unified/BottomTabBar.vue	Intégration du bouton shuffle

Fichiers créés

Fichier	Description
pmoapp/webapp/src/components/pmocontrol/ShuffleControl.vue	Composant Vue.js du bouton shuffle

Notes techniques

• La méthode shuffle_queue détache automatiquement la playlist liée pour éviter que la queue soit écrasée par une mise à jour de la playlist
• Le shuffle utilise rand::thread_rng() pour une génération aléatoire de qualité
• L'endpoint REST utilise le même pattern async que les autres commandes de transport (spawn_blocking + timeout)
• Le timeout utilisé est QUEUE_COMMAND_TIMEOUT (10 secondes)
• L'émission des événements SSE est automatique via le RendererEventBus intégré au MusicRenderer
• L'implémentation manuelle de Debug pour MusicRenderer est nécessaire car RendererEventBus n'implémente pas Debug
• Les événements ne sont émis que lorsqu'il y a un changement effectif (pas d'événement BindingChanged si le binding était déjà None)

Améliorations architecturales

Ce travail a posé les bases d'une meilleure architecture où le MusicRenderer est responsable de l'émission de ses propres événements. Une tâche de suivi a été créée (Blackboard/Todo/stateful_music_renderer.md) pour aller plus loin et rendre le MusicRenderer complètement stateful avec son propre thread de surveillance.