[Matter] Soporte para los clusters MediaPlayback, KeypadInput y LevelControl en dispositivos multimedia

¡Hola a todos!

Acabo de probar el nuevo sistema Matterbridge AI Plugin Factory de Pierre-Gilles para integrar mi Freebox Player Delta (Devialet) en Gladys a través de Matter.

El plugin generado funciona muy bien en Matterbridge:
:white_check_mark: Autenticación mediante validación en la pantalla de Freebox
:white_check_mark: Detección automática del reproductor
:white_check_mark: Dispositivo visible en Gladys a través de Matter

El plugin expone correctamente los siguientes clústeres Matter:

  • OnOff
  • LevelControl (volumen)
  • MediaPlayback (reproducir/pausa/detener/siguiente/anterior)
  • KeypadInput (teclado virtual)

Pero en Gladys, solo se reconoce el clúster OnOff
(como « interruptor »), y además no funciona
porque el encendido/apagado de un reproductor multimedia es diferente al de una bombilla.

¿Es posible agregar el soporte de los siguientes clústeres
en la integración Matter de Gladys?

  • MediaPlayback → reproducir, pausa, detener, siguiente, anterior
  • KeypadInput → envío de teclas (ok, atrás, inicio,
    arriba, abajo, izquierda, derecha)
  • LevelControl en un contexto multimedia → volumen
    (no luminosidad)
  • OnOff para un reproductor multimedia → encendido/apagado
    (diferente de una lámpara)

Sería un gran avance para todos los usuarios
que tienen dispositivos multimedia (TV, reproductores, cajas TV…)
y que utilizan Matterbridge para integrarlos.

El plugin de Freebox está disponible aquí para quienes quieran probarlo:

¡Gracias!

¡Sí, es totalmente posible! Y esa es la idea de Matter, quiero cubrirlo todo al 100% en Gladys para que luego todas las integraciones «no-Matter» puedan hacerse en Matterbridge.

Lo miraré en cuanto pueda, si no, si alguien quiere hacer una PR, es bienvenido :blush:

Actualización — PR enviada + mapeo de los clusters Matter faltantes

¡Hola a todos!

Pequeña actualización sobre mi aventura Matter/Matterbridge,
en toda transparencia: no soy desarrollador en absoluto.
Me apoyo en Claude (IA de Anthropic) y en el editor Cursor
para ayudarme a entender el código y contribuir.
Sin ellos nunca habría podido hacer lo siguiente :slightly_smiling_face:

Lo que ha pasado desde mi publicación inicial

Tras la respuesta de Pierre-Gilles diciendo que una PR era
bienvenida, nos lanzamos. Este es el resultado:

:backhand_index_pointing_right: PR #2533 enviada al repositorio de Gladys:

Añade el soporte de tres clusters Matter faltantes:

  • MediaPlayback → play, pause, stop
  • KeypadInput → navegación (arriba/abajo/izquierda/derecha/ok/volver)
  • LevelControl (sin iluminación) → volumen

Todo esto para que los dispositivos multimedia puenteados a través de Matterbridge
(TV, box, reproductores…) expongan funciones reales
en Gladys, no solo un interruptor.

El bot CodeRabbit ya ha hecho una revisión automática con
dos observaciones menores que estoy corrigiendo.

Mapeo de los clusters Matter faltantes

Al profundizar en el tema, he hecho una comparación entre
todas las funciones disponibles en MQTT y su cobertura
en Matter. Resultado: aproximadamente el 50% de las funciones de Gladys
aún no tienen un cluster Matter.

Prioridades altas (clusters Matter estándar, bien documentados):

  • DoorLock → LOCK (cerraduras)
  • PowerSource → BATTERY (nivel de batería)
  • SmokeCoAlarm → SMOKE_SENSOR + CO_SENSOR
  • BooleanState → OPENING_SENSOR (sensores de apertura)

Prioridades medias:

  • ColorControl temperature → color de blanco (cálido/fría)
  • FanControl → modo ventilación/clim
  • CarbonDioxideConcentration → CO2_SENSOR

Funciones que no existen en ningún lado aún :light_bulb:
Al pensar más allá, hay usos que ni MQTT
ni Matter cubren hoy en Gladys:

  • Válvula/riego (el cluster Matter ValveConfigAndControl
    ¡ya existe!)
  • Contador de agua/gas (consumo en m³)
  • Nivel de depósito (tanque de combustible, piscina)
  • Presencia humana radar mmWave (más preciso que un PIR)

Pregunta para la comunidad

¿Hay funciones que os falten en Gladys
hoy en día? ¿Dispositivos que no podéis
integrar correctamente?

Y si algunos desarrolladores de verdad quieren retomar estos
clusters prioritarios, el camino está ahora marcado —
los dos archivos a modificar son
convertToGladysDevice.js y matter.setValue.js,
y el patrón es muy claro para seguir :slightly_smiling_face:

Hola @b3n.0 :slight_smile:

No sé si has visto en la PR, pero ejecutamos docenas de comprobaciones para asegurarnos de que la PR es buena: pruebas unitarias, linting, formato, cobertura de código, etc…

También hay que probar el cambio en condiciones reales antes de poder validarlo. No sé si ya has podido hacer esta parte.

Encontrarás en la PR una lista de verificación para completar antes de pasar al siguiente paso. Te invito a revisar los diferentes puntos y a avisarme una vez aplicados los correctivos y realizadas las verificaciones.

Si es demasiado complicado para ti, avísame y haré otra PR :slight_smile:

Hola @pierre-gilles :slightly_smiling_face:

Gracias por tu respuesta, he revisado la lista de verificación y aplicado las correcciones solicitadas con Cursor.

Prueba en condiciones reales: aún no, tengo que revolver en un armario para encontrar un viejo Raspberry, debo tener un RPi 2B, ¡con suerte lo soporte! ?

Genial, pero ten cuidado, tu PR modifica archivos fuera del alcance de tu PR (Scene.cy.js)

Es demasiado antigua, ya no hacemos builds para armv6 ^^

Puedes probarlo en tu máquina de desarrollo, no es necesario ejecutarlo en un servidor remoto :slight_smile:

La PR se ha cerrado y se ha creado una nueva limitando el ámbito de la PR…

Las pruebas se han realizado, falta la prueba en condiciones reales:
npm run dev falla (aparentemente node.js demasiado reciente en mi máquina… ¿Es posible eso?)

Gracias por tu PR, pero tengo una pequeña pregunta, ¿has elegido usar una funcionalidad « Televisión » en Gladys? ¿En Matter, MediaPlayback está necesariamente vinculado a una televisión, o también se usa para la música?

¿Cómo se muestra este clúster en otros sistemas Matter? Por ejemplo, en iOS?

¡Sí! En la especificación Matter, MediaPlayback es un clúster genérico — no está reservado para las TV. Se utiliza tanto para las cajas de TV, los altavoces conectados, los reproductores de música, etc.

La especificación Matter distingue dos tipos de dispositivos principales:

  • « Casting Video Player » (TV, caja)
  • « Basic Audio Player » / « Speaker » (altavoces, reproductores de audio)

…pero ambos pueden utilizar MediaPlayback. Luego se añaden Channel, KeypadInput y LevelControl según el uso final.

Para la visualización en iOS Home, honestamente no lo sé — es una buena pregunta y no he tenido la oportunidad de probarlo.

Por lo tanto, tu pregunta sobre la elección de diseño:
¿Es mejor quedarse con la categoría TELEVISIÓN existente en Gladys (que ya tiene todos los tipos de reproducción/pausa/volumen/navegación), o utilizar MÚSICA, o crear algo más genérico?

Me remito completamente a tu juicio al respecto :slightly_smiling_face:

Hola @b3n.0,

Es realmente genial que quieras ayudar, y no te lo tomes a mal, eh :smiley:

El tema es que si solo transmites mis mensajes a Claude y me devuelves su respuesta, yo podría hacer lo mismo directamente por mi cuenta, así que el intermediario pierde un poco su interés :joy:

Lo que realmente busco es la parte que Claude no puede hacer por ti: responder a las preguntas que te he hecho. ¡Ese es el trabajo de un humano que conoce su contexto, y ahí es donde tú aportas un valor añadido real! :smiley:

Hola @pierre-gilles,

Por supuesto, no me lo tomo a mal. Sé que tengo limitaciones para ayudar en este tipo de temas :slightly_smiling_face:

Me lancé a esta PR principalmente para poder probar los plugins que había solicitado a la matterbridge-ai-plugin-factory, especialmente para el Freebox Player y la Yoto de mis hijos. Pensé que, de paso, también podría beneficiar al proyecto.

En ambos casos, estamos hablando de funcionalidades que no están cubiertas por Matter en Gladys hoy en día.

Por lo tanto, intenté arreglármelas con Cursor. Pero, efectivamente, me faltan muchas nociones, incluso el vocabulario. Sigo intentando pedir a las IA explicaciones lo más didácticas posible, pero no cubre todo: aún estoy muy lejos de dominar el tema.

Y si, desde tu punto de vista, te exige más trabajo en la revisión que hacer las modificaciones tú mismo, lo entiendo completamente. En mi trabajo como arquitecto, a menudo paso más tiempo explicando a alguien cómo dibujar un detalle que dibujándolo yo mismo :slightly_smiling_face:

Si para ti es más trabajo revisar que hacerlo tú mismo, lo entiendo, en mi trabajo de arquitecto me pasa a menudo que paso más tiempo explicando cómo dibujar un detalle que dibujándolo yo mismo.

Es como tú lo sientes :slightly_smiling_face:

Francamente, con Cursor, incluso sin ser desarrollador de profesión, creo que es posible hacer muy buenas PR sobre funcionalidades específicas.

Por otro lado, esto no elimina todo el trabajo previo: mirar lo que hacen los líderes del mercado (evita reinventar la rueda), reflexionar sobre la experiencia del usuario y luego probar realmente que funciona bien y que es agradable de usar. Estas partes, la IA no las hace realmente por ti, es ahí donde tu aportación es más importante.

Si tienes la motivación de llevar un desarrollo de principio a fin, desde la idea hasta las pruebas, me ayudas muchísimo. Y además, tendrás mucho más rápido las funcionalidades que te interesan en Gladys :grinning_face_with_smiling_eyes:

Y sí, era realmente la base de mi motivación.

Ahora entiendo bien que debo poder llegar hasta el final de las pruebas. En eso aún debo avanzar…

Hola @pierre-gilles,

He mirado un poco por ahí, y es principalmente en HA donde hay pistas…

Por lo tanto, veo tres enfoques posibles:

  1. Un widget único que se adapte automáticamente a las funciones del dispositivo (canales, aplicaciones, control remoto, volumen, etc.).
  2. Varios widgets especializados según el tipo de reproductor (audio, video, casting…). >>> Es la opción de HA si lo he entendido bien
  3. Una versión adaptativa, ligera en móvil y más completa en escritorio.

Personalmente, me gusta la primera…

Pregunta rápida, no tengo Sonos en casa pero ¿he entendido bien:

  • ¿El widget de música existente solo sirve para Sonos?
  • ¿Gladys ya ve los grupos de Sonos existentes, pero no permite crearlos o modificarlos???

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

Lista de funciones de un widget multimedia « universal » identificadas hasta ahora:

:bullseye: FUNCIONES PRINCIPALES (Todos los dispositivos)

Control de reproducción

✅ play() - Iniciar reproducción
✅ pause() - Pausar
✅ stop() - Detener
✅ next() - Siguiente canción/programa
✅ previous() - Canción/programa anterior

Línea de tiempo / Progreso

✅ seek(position) - Saltar a una posición
✅ displayTimeline() - Mostrar barra de progreso
✅ displayTimeElapsed() - Mostrar tiempo transcurrido (15:45)
✅ displayTimeRemaining() - Mostrar tiempo restante (-14:15)

Control de volumen

✅ setVolume(0-100) - Ajustar volumen
✅ increaseVolume() - Aumentar volumen
✅ decreaseVolume() - Disminuir volumen
✅ mute() - Silenciar
✅ unmute() - Restaurar sonido
✅ displayVolumeLevel() - Mostrar % de volumen

Gestión de energía

✅ powerOn() - Encender el dispositivo
✅ powerOff() - Apagar el dispositivo
✅ togglePower() - Alternar encendido/apagado
✅ displayPowerStatus() - Mostrar estado de energía

Información del dispositivo

✅ displayDeviceName() - Mostrar nombre del dispositivo
✅ displayStatus() - Mostrar estado (Reproduciendo, Pausado, Detenido)
✅ displayCurrentSource() - Mostrar fuente actual

:musical_note: FUNCIONES DE REPRODUCTOR DE AUDIO (Yoto, Sonos, etc.)

Visualización de metadatos

✅ displayArtwork() - Mostrar portada del álbum
✅ displayArtist() - Mostrar nombre del artista
✅ displayTitle() - Mostrar título de la canción
✅ displayAlbum() - Mostrar nombre del álbum
✅ displayDuration() - Mostrar duración total

Características de audio opcionales

✅ shuffle() - Modo aleatorio
✅ repeat() - Modo repetición
✅ like() - Gusta la canción (♥)
✅ dislike() - No gusta
✅ showQueue() - Mostrar cola de reproducción

:television: FUNCIONES DE REPRODUCTOR DE VIDEO (Freebox Player, TV, etc.)

Visualización de video

✅ displayVideoOutput() - Mostrar video
✅ displayThumbnail() - Mostrar miniatura
✅ displayChannelLogo() - Mostrar logo del canal
✅ displayProgramTitle() - Mostrar título del programa

Controles específicos de video

✅ fastForward() - Avance rápido
✅ rewind() - Retroceso rápido
✅ frameByFrame() - Avance fotograma a fotograma
✅ subtitles() - Activar/desactivar subtítulos
✅ audioTracks() - Cambiar pista de audio

:television: FUNCIONES DE CANALES DE TV

Selección de canal

✅ setChannel(channelId) - Cambiar de canal (TMC, TF1, etc.)
✅ displayCurrentChannel() - Mostrar canal actual
✅ displayChannelNumber() - Mostrar número (34)
✅ displayChannelName() - Mostrar nombre (TMC)
✅ displayChannelLogo() - Mostrar logo
✅ nextChannel() - Canal siguiente (+)
✅ previousChannel() - Canal anterior (-)

Acceso rápido a canales

✅ renderQuickAccessButtons() - [TF1] [france2] [TMC] [france3]
✅ setFavoriteChannel(channelId) - Marcar como favorito
✅ removeFavoriteChannel(channelId) - Eliminar de favoritos
✅ showAllChannels() - Modal con todos los canales (62+)
✅ searchChannel(name) - Buscar un canal

EPG (Guía de programación electrónica)

✅ displayCurrentProgram() - Mostrar programa actual
✅ displayProgramTitle() - Título del programa (NCIS Los Angeles)
✅ displayProgramTime() - Horario (15:45 - 16:30)
✅ displayProgramDescription() - Sinopsis del programa
✅ displayNextPrograms() - Mostrar próximos programas
✅ displayProgramDuration() - Duración del programa

:clapper_board: FUNCIONES DE SERVICIOS DE TRANSMISIÓN / APPS

Lanzador de aplicaciones

✅ launchApp(appId) - Lanzar una app (Netflix, Disney+, etc.)
✅ displayAvailableApps() - Mostrar lista de apps disponibles
✅ displayCurrentApp() - Mostrar app actual
✅ closeApp() - Cerrar app
✅ switchApp(appId) - Cambiar a otra app

Servicios de transmisión

✅ launchNetflix()
✅ launchDisneyPlus()
✅ launchAmazonPrime()
✅ launchAppleTV()
✅ launchYouTube()
✅ launchSpotify()
✅ launchAllApps() - Ver todas las apps

Hola @b3n.0.

Gracias por este trabajo de exploración, es exactamente lo que necesitaba para decidir. Aquí está lo que propongo.

Sobre las 3 aproximaciones: nos quedamos con la 1

Un widget único que se adapta a las capacidades del dispositivo. Un pequeño punto al pasar: Home Assistant en realidad hace lo mismo. No tiene varios widgets especializados, tiene una sola entidad media_player y una sola tarjeta que muestra/oculta los controles según las supported_features del dispositivo. El precedente del mercado va en tu dirección :slightly_smiling_face:

La aproximación 3 (móvil/escritorio) no es una alternativa: es responsive, y viene naturalmente con la cuadrícula del dashboard.

La especificación que propongo

Al profundizar en el código existente, me di cuenta de que ya tenemos dos modelos de medios que se superponen: la categoría music (usada por Sonos, con estado de reproducción) y la categoría television (30 tipos, usada únicamente por los controles remotos creados manualmente a través de Broadlink/MQTT). En lugar de crear un tercero o fusionar todo, propongo dar a cada uno un rol claro:

  • music = el reproductor de medios (todo lo que tiene un estado: reproducción, volumen). Es aquí donde se conecta Matter. Beneficio inmediato: tu Freebox y tu Yoto aparecerán en el mismo widget que Sonos, que será renombrado « Reproductor de medios » y hecho adaptativo.
  • television = el control remoto (teclas sin estado: flechas, OK, retroceso). Es aquí donde se conecta Matter KeypadInput. Bonus agradable: la sección « control remoto » del widget funcionará también para los controles remotos infrarrojos Broadlink existentes, no solo para Matter.
  • Power: clúster OnOff hacia switch.

Y aprovecharemos para modernizar el modelo. Hoy, la reproducción está representada por varias características separadas (play, pause, playback_state…). Desde entonces, Gladys ha ganado los supported_options: la posibilidad para una característica de anunciar la lista de valores que soporta, dispositivo por dispositivo (ya se usa para los modos de climatización). Lo usaremos aquí:

  • Una sola característica playback_state, controlable: su valor es el estado actual (reproducción / pausa / stop), sincronizado en tiempo real, y modificarlo envía el comando correspondiente. Sus supported_options listan los estados que tu dispositivo puede alcanzar, construidos automáticamente desde lo que el dispositivo declara (del lado de Matter, cada dispositivo publica la lista exacta de comandos que acepta a través del atributo AcceptedCommandList).
  • El widget muestra exactamente los botones play/pause/stop que el dispositivo soporta, con el estado activo resaltado, sin codificar nada fijo por marca o protocolo. Es el equivalente del supported_features de Home Assistant, pero en datos.
  • next y previous siguen siendo características separadas: son impulsos sin estado, no estados.
  • En las escenas, « poner el reproductor en reproducción » se convertirá en una verdadera asignación de estado, más natural que un « presionar botón ».

El mapeo completo de Matter:

Cluster Matter Característica Gladys
MediaPlayback music/playback_state controlable, opciones desde AcceptedCommandList, estado en tiempo real a través del atributo CurrentState
MediaPlayback (Next/Previous si soportados) music/next, music/previous
LevelControl (dispositivo de medios) music/volume normalizado 0 a 100
KeypadInput television/up, down, left, right, enter, return
OnOff switch/binary

Dos puntos a los que me aferro particularmente:

  1. El retorno de estado. El estado de reproducción será leído al inicio y seguido por suscripción. Sin esto, el widget « adivina » el estado y se desincroniza tan pronto como se usa el control remoto real. Es el tipo de detalle que marca la diferencia entre una integración que funciona en una demostración y una integración agradable a diario.
  2. La normalización del volumen 0 a 100. Matter habla en 0 a 254, Sonos en 0 a 100. Al normalizar en la frontera del servicio, « volumen a 30 » significa lo mismo en una escena sin importar el protocolo. Es eso lo que hace a Gladys agnóstica del protocolo.

Para los usuarios existentes de Sonos, una migración convertirá automáticamente las antiguas características play/pause a este nuevo modelo, nada que hacer de su parte.

Sobre tu gran lista de funcionalidades

Hay que reducirla, por una razón factual: Matter MediaPlayback no expone ninguna metadato. No hay título, no hay artista, no hay portada. Y el EPG no existe en Matter. El gran widget con artwork no puede ser alimentado por Matter hoy. Los canales y el lanzamiento de aplicaciones tienen clústeres (Channel, ApplicationLauncher) pero casi ningún dispositivo real los implementa. Solo los tocaríamos si tu plugin Freebox los expone y podemos probar en la realidad.

Por lo tanto, fase:

  1. Servidor: el nuevo modelo playback_state + la migración Sonos + el mapeo Matter arriba
  2. Front: evolución del widget Música a « Reproductor de medios » adaptativo (cada sección solo se muestra si las características existen), y soporte para características con supported_options en las escenas
  3. Más tarde, si dispositivos reales lo justifican: mute, posición/seek, canales, aplicaciones, metadatos del lado de Sonos

Tus preguntas Sonos

  • Sí, el widget de música es de hecho solo para Sonos: Google Cast y AirPlay solo exponen la reproducción de notificaciones, por lo que no pasan el filtro del widget.
  • Los grupos Sonos no son gestionados en ningún lugar hoy, ni en lectura ni en escritura. Es un tema por sí mismo, lo guardamos para más tarde.

La siguiente

Para la implementación, Claude Fable 5 va a trabajar en el tema de todos modos, el código ya no es el cuello de botella. Lo que realmente importa ahora es validar la especificación anterior, porque es ella la que determinará si el resultado es bueno.

Y es ahí donde tu aportación es más valiosa:

  1. Valida (o desafía) este plan: ¿cubre bien tus casos de uso Freebox y Yoto?
  2. Las pruebas en condiciones reales cuando esté listo: eres el único que tiene estos dispositivos a mano.

Dime qué opinas.

Hola @pierre-gilles

bueno, la sobrecarga de trabajo antes de las vacaciones y luego las vacaciones en sí han acabado con mi tiempo disponible para responderte bien. ¡Lo siento!

y ahora muchas cosas han cambiado (¡incluso impresionante!) especialmente las integraciones externas [editar: Dashboard - Mise en page flexible : pouvoir mélanger les lignes à 1, 2 et 3 colonnes, eso también es enorme]… inicialmente buscaba agregar las características para un/algunos complementos Matter, ahora creo que los complementos tienen menos sentido y que es mejor orientarse hacia una/algunas integraciones, ¿me equivoco?

En principio :

, y por lo tanto este mostraría la categoría música y la categoría televisión al mismo tiempo si están disponibles? por lo tanto no entiendo :

después si reutilizamos televisión ya utilizado por Broadlink, no podemos tener :

la infrarroja no devuelve ningún estado (de hecho, es mi gran decepción en casa - tuve que montar escenas de vigilancia y condiciones según el consumo (a través de un enchufe) para alinear el estado de encendido/apagado de mi proyector - y desde mi regreso de vacaciones el servicio broadlink parece no funcionar más // voy a hacer un tema aparte después)

¿no habrá botones de reproducción, pausa, parada que de todos modos sean sin estado y, por lo tanto, permanezcan en televisión

quizás me he perdido…

Hola @b3n.0,

Sí, ahora son las integraciones externas las que hay que priorizar :wink:

Con las integraciones externas, tienes la libertad de hacer lo que quieras: probar nuevas ideas, experimentar, iterar, sin necesidad de pedirme mi opinión. ¡Justamente ese es el interés: la libertad total! :smiling_face_with_sunglasses:

Así que adelante, prueba, itera, mejora… ¡es exactamente para lo que están diseñadas!

gracias @pierre-gilles por tu respuesta, que es muy motivadora… pero a menos que esté completamente equivocado, la necesidad de los « endpoints » en gladys o, y es lo que insinuaba en mi último mensaje, una integración externa es capaz de cubrir las posibles carencias…

Me doy cuenta de que mi último mensaje es absolutamente incomprensible…

Pero al leer el tema sobre la posibilidad de que las integraciones declaren sus propios widgets, ya encuentro una respuesta a parte de mis interrogaciones.

Si entiendo bien, hoy en día no podemos realmente « conectar » en Gladys información o acciones que no existan en el núcleo de Gladys. Y, por consiguiente, tampoco podemos realmente mostrarlas en el panel de control o explotarlas en las escenas.

Precisamente ahí es donde me uno al tema de los widgets: si mañana una integración externa pudiera declarar sus propios datos, acciones y posiblemente disparadores, entonces podríamos tener una integración capaz de cubrir las posibles carencias del núcleo de Gladys, sin tener que añadir cada funcionalidad específica en Gladys.

Por lo tanto, creo que es más bien esta articulación entre el núcleo y las integraciones externas lo que intentaba entender en mi mensaje anterior.