[Matter] Support des clusters MediaPlayback, KeypadInput et LevelControl pour les appareils média

Bonjour à tous !

Je viens de tester le nouveau système Matterbridge AI Plugin Factory
de Pierre-Gilles pour intégrer mon Freebox Player Delta (Devialet)
dans Gladys via Matter.

Le plugin généré fonctionne très bien côté Matterbridge :
:white_check_mark: Authentification via validation sur l’écran Freebox
:white_check_mark: Découverte automatique du player
:white_check_mark: Device visible dans Gladys via Matter

Le plugin expose correctement les clusters Matter suivants :

  • OnOff
  • LevelControl (volume)
  • MediaPlayback (play/pause/stop/next/prev)
  • KeypadInput (télécommande virtuelle)

Mais côté Gladys, seul le cluster OnOff est reconnu
(comme « commutateur »), et il ne fonctionne pas non plus
car le on/off d’un lecteur média est différent d’une ampoule.

Est-il possible d’ajouter le support des clusters suivants
dans l’intégration Matter de Gladys ?

  • MediaPlayback → play, pause, stop, next, previous
  • KeypadInput → envoi de touches (ok, back, home,
    up, down, left, right)
  • LevelControl dans un contexte média → volume
    (pas luminosité)
  • OnOff pour un lecteur média → power on/off
    (différent d’une lampe)

Ce serait une avancée énorme pour tous les utilisateurs
qui ont des appareils médias (TV, lecteurs, box TV…)
et qui utilisent Matterbridge pour les intégrer.

Le plugin Freebox est disponible ici pour ceux qui veulent tester :

Merci !

Oui, c’est tout à fait possible ! Et c’est totalement l’idée de Matter, je veux tout couvrir à 100% dans Gladys pour qu’ensuite toutes les intégrations « non-Matter » puissent être faites dans Matterbridge.

Je regarderai dès que je peux, sinon si quelqu’un veut faire une PR, il est le bienvenu :blush:

Update — PR soumise + cartographie des clusters Matter manquants

Bonjour à tous !

Petite mise à jour sur mon aventure Matter/Matterbridge,
en toute transparence : je ne suis pas développeur du tout.
Je m’appuie sur Claude (IA d’Anthropic) et l’éditeur Cursor
pour m’aider à comprendre le code et contribuer.
Sans eux je n’aurais jamais pu faire ce qui suit :slightly_smiling_face:

Ce qui s’est passé depuis mon post initial

Suite au retour de Pierre-Gilles disant qu’une PR était
bienvenue, on s’est lancés. Voilà le résultat :

:backhand_index_pointing_right: PR #2533 soumise sur le repo Gladys :

Elle ajoute le support de trois clusters Matter manquants :

  • MediaPlayback → play, pause, stop
  • KeypadInput → navigation (haut/bas/gauche/droite/ok/retour)
  • LevelControl (sans lighting) → volume

Tout ça pour que les appareils médias bridgés via Matterbridge
(TV, box, lecteurs…) exposent de vraies fonctionnalités
dans Gladys, pas juste un commutateur.

Le bot CodeRabbit a déjà fait une review automatique avec
deux nitpicks mineurs que je suis en train de corriger.

Cartographie des clusters Matter manquants

En creusant le sujet, j’ai fait une comparaison entre
toutes les features disponibles en MQTT et leur couverture
côté Matter. Résultat : environ 50% des features Gladys
n’ont pas encore de cluster Matter.

Priorités hautes (clusters Matter standards, bien documentés) :

  • DoorLock → LOCK (serrures)
  • PowerSource → BATTERY (niveau batterie)
  • SmokeCoAlarm → SMOKE_SENSOR + CO_SENSOR
  • BooleanState → OPENING_SENSOR (capteurs d’ouverture)

Priorités moyennes :

  • ColorControl temperature → couleur de blanc (chaud/froid)
  • FanControl → mode ventilation/clim
  • CarbonDioxideConcentration → CO2_SENSOR

Features qui n’existent nulle part encore :light_bulb:
En réfléchissant plus loin, il y a des usages que ni MQTT
ni Matter ne couvrent aujourd’hui dans Gladys :

  • Valve/irrigation (le cluster Matter ValveConfigAndControl
    existe déjà !)
  • Compteur eau/gaz (consommation en m³)
  • Niveau de réservoir (cuve fioul, piscine)
  • Présence humaine radar mmWave (plus précis qu’un PIR)

Question pour la communauté

Y a-t-il des features qui vous manquent dans Gladys
aujourd’hui ? Des appareils que vous n’arrivez pas
à intégrer correctement ?

Et si des vrais développeurs veulent reprendre ces
clusters prioritaires, le chemin est maintenant balisé —
les deux fichiers à modifier sont
convertToGladysDevice.js et matter.setValue.js,
et le pattern est très clair à suivre :slightly_smiling_face:

Salut @b3n.0 :slight_smile:

Je ne sais pas si tu as vu dans la PR, mais on exécute des dizaines de checks pour vérifier que la PR est bonne : tests unitaires, linting, formattage, code coverage, etc…

Il faut également tester la modification en conditions réelles avant de pouvoir la valider. Je ne sais pas si tu as déjà pu faire cette partie ?

Tu trouveras dans la PR une checklist à compléter avant de passer à l’étape suivante. Je t’invite à parcourir les différents points et à me faire signe une fois les correctifs appliqués et les vérifications effectuées.

Si c’est trop compliqué pour toi, tiens moi au courant et je referais une PR :slight_smile:

Salut @pierre-gilles :slightly_smiling_face:

Merci pour ton retour, j’ai bien parcouru la checklist et appliqué les correctifs demandés à l’aide de Cursor.

Test en conditions réelles : pas encore, je dois fouiller dans un placard pour retrouver un vieux Raspberry, je dois avoir une vieux RPi 2B, en espérant qu’il supporte !?

Top, par contre tu feras attention ta PR modifie des fichiers en dehors du scope de ta PR (Scene.cy.js)

C’est trop vieux, on ne fait plus de build armv6 ^^

Tu peux tester sur ta machine de dev par contre, pas besoin forcément de le lancer en déporté :slight_smile:

La PR a été fermée et une nouvelle créée en limitant au scope de la PR…

Les tests ont été passés, manque le test en condition réel :
npm run dev échoue (apparemment node.js trop récent sur ma machine… C’est possible ça ?)

Merci pour ta PR, par contre petite question, tu as fais le choix d’utiliser une fonctionnalité « Télévision » dans Gladys, est-ce que dans Matter, MediaPlayback est forcément lié à une télévision, ou c’est aussi utilisé par la musique ?

Comment ce cluster est affiché sur d’autres systèmes Matter ? sur iOS par exemple?

Et oui … ! Dans la spec Matter, MediaPlayback est un cluster
générique — il n’est pas réservé aux TV. Il est utilisé aussi bien
par les box TV, les enceintes connectées, les lecteurs musicaux, etc.

La spec Matter distingue deux device types principaux :

  • « Casting Video Player » (TV, box)
  • « Basic Audio Player » / « Speaker » (enceintes, lecteurs audio)

…mais les deux peuvent utiliser MediaPlayback.
S’ajoute ensuite Channel, KeypadInput et LevelControl suivant l’usage final.

Pour l’affichage dans iOS Home, honnêtement je ne sais pas —
c’est une bonne question et je n’ai pas eu l’occasion de tester.

Du coup ta question sur le choix de design :
vaut-il mieux rester sur la catégorie TELEVISION existante dans Gladys
(qui a déjà tous les types play/pause/volume/navigation), ou utiliser
MUSIC, ou créer quelque chose de plus générique ?

Je m’en remets complètement à ton jugement là-dessus :slightly_smiling_face:

Salut @b3n.0,

C’est vraiment cool de vouloir aider, et prend pas mal mon retour hein :smiley:

Le truc c’est que si tu transmets juste mes messages à Claude et que tu me renvoies sa réponse, je pourrais faire la même chose de mon côté directement, donc l’intermédiaire perd un peu de son intérêt :joy:

Ce que je cherche vraiment, c’est la partie que Claude ne peut pas faire à ta place : répondre aux questions que je t’ai posées ! C’est le travail d’un humain qui connaît son contexte, et c’est là où tu as une vraie valeur ajoutée :smiley:

Salut @pierre-gilles,

Évidemment, je ne le prends pas mal. Je sais bien que je suis limité pour aider sur ce genre de sujets :slightly_smiling_face:

Je me suis lancé dans cette PR surtout pour pouvoir tester les plugins que j’avais demandés à la matterbridge-ai-plugin-factory, notamment pour le Freebox Player et la Yoto de mes enfants. Je me suis dit qu’au passage ça pourrait aussi profiter au projet.

Dans les deux cas, on est sur des fonctionnalités qui ne sont pas couvertes par Matter dans Gladys aujourd’hui.

Du coup, j’ai essayé de m’en sortir avec Cursor. Mais effectivement, il me manque encore beaucoup de notions, ne serait-ce que le vocabulaire. J’essaie toujours de demander aux IA des explications les plus didactiques possible, mais ça ne comble pas tout : je suis encore très loin de maîtriser le sujet.

Et si, de ton point de vue, ça te demande finalement plus de travail en review que de faire les modifications toi-même, je le comprends complètement. Dans mon métier d’architecte, il m’arrive régulièrement de passer plus de temps à expliquer à quelqu’un comment dessiner un détail que de le dessiner moi-même :slightly_smiling_face:

Si pour toi cest pkus de boulot en review que de le faire toi même je comprends, dans mon métier d’architecte il m’arrive a passer plus de temps à expliquer comment dessiner un détail que de le dessiner moi même !

C’est comme tu le sens :slightly_smiling_face:

Franchement, avec Cursor, même sans être développeur de métier, je pense qu’il est possible de faire de très bonnes PR sur des fonctionnalités ciblées.

Par contre, ça n’enlève pas tout le travail en amont : regarder ce qui se fait chez les leaders du marché (ça évite de réinventer la roue), réfléchir à l’expérience utilisateur, puis tester concrètement que ça fonctionne bien et que c’est agréable à utiliser. Ces parties-là, l’IA ne les fait pas vraiment à ta place, c’est là que ton apport est le plus important.

Si tu as la motivation de porter un développement de bout en bout, de l’idée jusqu’aux tests, ça m’aide énormément. Et en plus, tu auras beaucoup plus rapidement les fonctionnalités qui t’intéressent dans Gladys :grinning_face_with_smiling_eyes:

Et oui, c’était vraiment la base de ma motivation.

Maintenant je comprends bien qu’il faut que je puisse aller jusqu’au bout des tests. La dessus je dois encore avancer…

Salut @pierre-gilles,

J’ai regardé un peu ailleurs, et c’est principalement chez HA que l’on a des pistes…

Du coup, je vois trois approches possibles :

  1. Un widget unique qui s’adapte automatiquement aux fonctionnalités du device (chaînes, applications, télécommande, volume, etc.).
  2. Plusieurs widgets spécialisés selon le type de lecteur (audio, vidéo, casting…). >>> C’est le choix de HA si j’ai bien compris
  3. Une version adaptative, légère sur mobile et plus complète sur desktop.

Perso, je trouve la première bien…

Petite question, je n’ai pas de Sonos chez moi mais ai-je bien compris :

  • Le widget musique existant ne sert que pour Sonos ?
  • Gladys voit déjà les groupes Sonos existants, mais ne permet pas de les créer ou de les modifier ???

Base : 4 Matter clusters (OnOff, MediaPlayback, LevelControl, KeypadInput)

Liste de fonctionnalités d’un widget média « universel » repérées pour le moment :

:bullseye: CORE FUNCTIONS (Tous les Devices)

Playback Control

✅ play() - Démarrer la lecture
✅ pause() - Mettre en pause
✅ stop() - Arrêter
✅ next() - Chanson/programme suivant
✅ previous() - Chanson/programme précédent

Timeline / Progress

✅ seek(position) - Sauter à une position
✅ displayTimeline() - Afficher barre de progression
✅ displayTimeElapsed() - Afficher temps écoulé (15:45)
✅ displayTimeRemaining() - Afficher temps restant (-14:15)

Volume Control

✅ setVolume(0-100) - Régler le volume
✅ increaseVolume() - Augmenter le volume
✅ decreaseVolume() - Diminuer le volume
✅ mute() - Couper le son
✅ unmute() - Rétablir le son
✅ displayVolumeLevel() - Afficher le % de volume

Power Management

✅ powerOn() - Allumer l'appareil
✅ powerOff() - Éteindre l'appareil
✅ togglePower() - Basculer on/off
✅ displayPowerStatus() - Afficher état power

Device Info

✅ displayDeviceName() - Afficher nom device
✅ displayStatus() - Afficher l'état (Playing, Paused, Stopped)
✅ displayCurrentSource() - Afficher source actuelle

:musical_note: AUDIO PLAYER FUNCTIONS (Yoto, Sonos, etc.)

Metadata Display

✅ displayArtwork() - Afficher la couverture album
✅ displayArtist() - Afficher le nom de l'artiste
✅ displayTitle() - Afficher le titre de la chanson
✅ displayAlbum() - Afficher le nom de l'album
✅ displayDuration() - Afficher la durée totale

Optional Audio Features

✅ shuffle() - Mode aléatoire
✅ repeat() - Mode répétition
✅ like() - Aimer la chanson (♥)
✅ dislike() - Ne pas aimer
✅ showQueue() - Afficher la queue de lecture

:television: VIDEO PLAYER FUNCTIONS (Freebox Player, TV, etc.)

Video Display

✅ displayVideoOutput() - Afficher la vidéo
✅ displayThumbnail() - Afficher la miniature
✅ displayChannelLogo() - Afficher le logo chaîne
✅ displayProgramTitle() - Afficher le titre du programme

Video-Specific Controls

✅ fastForward() - Avance rapide
✅ rewind() - Retour rapide
✅ frameByFrame() - Avance image par image
✅ subtitles() - Activer/désactiver les sous-titres
✅ audioTracks() - Changer la piste audio

:television: TV CHANNELS FUNCTIONS

Channel Selection

✅ setChannel(channelId) - Changer de chaîne (TMC, TF1, etc.)
✅ displayCurrentChannel() - Afficher la chaîne actuelle
✅ displayChannelNumber() - Afficher le numéro (34)
✅ displayChannelName() - Afficher le nom (TMC)
✅ displayChannelLogo() - Afficher le logo
✅ nextChannel() - Chaîne suivante (+)
✅ previousChannel() - Chaîne précédente (-)

Channel Quick Access

✅ renderQuickAccessButtons() - [TF1] [france2] [TMC] [france3]
✅ setFavoriteChannel(channelId) - Marquer comme favori
✅ removeFavoriteChannel(channelId) - Retirer des favoris
✅ showAllChannels() - Modal avec toutes les chaînes (62+)
✅ searchChannel(name) - Chercher une chaîne

EPG (Electronic Program Guide)

✅ displayCurrentProgram() - Afficher le programme en cours
✅ displayProgramTitle() - Titre du programme (NCIS Los Angeles)
✅ displayProgramTime() - Horaire (15:45 - 16:30)
✅ displayProgramDescription() - Synopsis du programme
✅ displayNextPrograms() - Afficher les prochains programmes
✅ displayProgramDuration() - Durée du programme

:clapper_board: STREAMING SERVICES / APPS FUNCTIONS

Application Launcher

✅ launchApp(appId) - Lancer une app (Netflix, Disney+, etc.)
✅ displayAvailableApps() - Afficher liste des apps disponibles
✅ displayCurrentApp() - Afficher l'app actuelle
✅ closeApp() - Fermer l'app
✅ switchApp(appId) - Switcher vers une autre app

Streaming Services

✅ launchNetflix()
✅ launchDisneyPlus()
✅ launchAmazonPrime()
✅ launchAppleTV()
✅ launchYouTube()
✅ launchSpotify()
✅ launchAllApps() - Voir toutes les apps

Salut @b3n.0 !

Merci pour ce travail d’exploration, c’est exactement ce dont j’avais besoin pour trancher. Voici ce que je propose.

Sur les 3 approches : on part sur la 1

Un widget unique qui s’adapte aux capacités de l’appareil. Petit point au passage : c’est aussi ce que fait Home Assistant en réalité. Il n’a pas plusieurs widgets spécialisés, il a une seule entité media_player et une seule carte qui affiche/masque les contrôles selon les supported_features de l’appareil. Le précédent du marché va donc dans ton sens :slightly_smiling_face:

L’approche 3 (mobile/desktop) n’est pas une alternative : c’est du responsive, et ça vient naturellement avec la grille du dashboard.

La spec que je propose

En creusant le code existant, je me suis rendu compte qu’on a déjà deux modèles média qui se recouvrent : la catégorie music (utilisée par Sonos, avec état de lecture) et la catégorie television (30 types, utilisée uniquement par les télécommandes créées à la main via Broadlink/MQTT). Plutôt que d’en créer un troisième ou de tout fusionner, je propose de donner à chacune un rôle net :

  • music = le lecteur média (tout ce qui a un état : lecture, volume). C’est là que Matter se branche. Bénéfice immédiat : ta Freebox et ta Yoto apparaîtront dans le même widget que Sonos, qui sera renommé « Lecteur média » et rendu adaptatif.
  • television = la télécommande (touches sans état : flèches, OK, retour). C’est là que Matter KeypadInput se branche. Bonus sympa : la section « télécommande » du widget marchera du coup aussi pour les télécommandes infrarouge Broadlink existantes, pas seulement pour Matter.
  • Power : cluster OnOff vers switch.

Et on va en profiter pour moderniser le modèle. Aujourd’hui, la lecture est représentée par plusieurs features séparées (play, pause, playback_state…). Depuis, Gladys a gagné les supported_options : la possibilité pour une feature d’annoncer la liste des valeurs qu’elle supporte, appareil par appareil (c’est déjà utilisé pour les modes de climatisation). On va s’en servir ici :

  • Une seule feature playback_state, pilotable : sa valeur est l’état courant (lecture / pause / stop), synchronisée en temps réel, et la modifier envoie la commande correspondante. Ses supported_options listent les états que ton appareil sait atteindre, construites automatiquement depuis ce que l’appareil déclare (côté Matter, chaque appareil publie la liste exacte des commandes qu’il accepte via l’attribut AcceptedCommandList).
  • Le widget affiche donc exactement les boutons play/pause/stop que l’appareil supporte, avec l’état actif surligné, sans rien coder en dur par marque ou par protocole. C’est l’équivalent du supported_features de Home Assistant, mais en données.
  • next et previous restent des features séparées : ce sont des impulsions sans état, pas des états.
  • Dans les scènes, « mettre le lecteur en lecture » deviendra une vraie affectation d’état, plus naturelle qu’un « appui sur bouton ».

Le mapping Matter complet :

Cluster Matter Feature Gladys
MediaPlayback music/playback_state pilotable, options depuis AcceptedCommandList, état temps réel via l’attribut CurrentState
MediaPlayback (Next/Previous si supportés) music/next, music/previous
LevelControl (appareil média) music/volume normalisé 0 à 100
KeypadInput television/up, down, left, right, enter, return
OnOff switch/binary

Deux points auxquels je tiens particulièrement :

  1. Le retour d’état. L’état de lecture sera lu au démarrage et suivi par abonnement. Sans ça, le widget « devine » l’état et se désynchronise dès qu’on utilise la vraie télécommande. C’est le genre de détail qui fait la différence entre une intégration qui marche en démo et une intégration agréable au quotidien.
  2. La normalisation du volume 0 à 100. Matter parle en 0 à 254, Sonos en 0 à 100. En normalisant à la frontière du service, « volume à 30 » veut dire la même chose dans une scène quel que soit le protocole. C’est ça qui rend Gladys agnostique du protocole.

Pour les utilisateurs Sonos existants, une migration convertira automatiquement les anciennes features play/pause vers ce nouveau modèle, rien à faire de leur côté.

Sur ta grande liste de fonctionnalités

Il faut la dégonfler, pour une raison factuelle : Matter MediaPlayback n’expose aucune métadonnée. Pas de titre, pas d’artiste, pas de pochette. Et l’EPG n’existe pas du tout dans Matter. Le grand widget avec artwork ne peut donc pas être alimenté par Matter aujourd’hui. Les chaînes et le lancement d’applications ont bien des clusters (Channel, ApplicationLauncher) mais quasi aucun appareil réel ne les implémente. On n’y touchera que si ton plugin Freebox les expose et qu’on peut tester en vrai.

Donc phasage :

  1. Serveur : le nouveau modèle playback_state + la migration Sonos + le mapping Matter ci-dessus
  2. Front : évolution du widget Musique en « Lecteur média » adaptatif (chaque section ne s’affiche que si les features existent), et prise en charge des features à supported_options dans les scènes
  3. Plus tard, si des appareils réels le justifient : mute, position/seek, chaînes, applications, métadonnées côté Sonos

Tes questions Sonos

  • Oui, le widget musique est de fait Sonos-only : Google Cast et AirPlay n’exposent que la lecture de notifications, donc ils ne passent pas le filtre du widget.
  • Les groupes Sonos ne sont gérés nulle part aujourd’hui, ni en lecture ni en écriture. C’est un sujet à part entière, on le garde pour plus tard.

La suite

Pour l’implémentation, Claude Fable 5 va travailler sur le sujet de toute façon, le code n’est plus le goulot d’étranglement. Ce qui compte vraiment maintenant, c’est de valider la spec ci-dessus, parce que c’est elle qui déterminera si le résultat est bon.

Et c’est là que ton apport est le plus précieux :

  1. Valide (ou challenge) ce plan : est-ce que ça couvre bien tes cas d’usage Freebox et Yoto ?
  2. Les tests en conditions réelles quand ce sera prêt : tu es le seul à avoir ces appareils sous la main.

Dis-moi ce que tu en penses !