Expose Matter cameras based on existing UI

[mkerstner]

Problem statement

Building upon #40 we aim to expose Matter cameras based on the existing UI and elements to eventually get en-par with existing camera integrations - well knowing that we are still facing certain limitations for Matter compliance from various Matter cameras tested so far (e.g. Aqara G350).

Generally, like always we should aim for a generic approach rather than a Matter specific one doing so and re-use what already is present for now. #120 aims to focus on further refinements in the UI and underlying technical foundation if required at a later stage.

In a first step, this opportunity should enable providing support for Matter cameras in Home Assistant and decouple further activities regarding potential UI improvements.

Community signals

• As mentioned in Matter is upgraded to 1.5.1 to enable Matter camera support #40
• In regards to the Works With Home Assistant program. Certifying cameras over Matter would expand the choice of camera vendors we have available in the WWHA program and thus also visibility for compliant products to our community

Scope & Boundaries

In scope

• Setup (keeping Make setting up Matter and adding devices more approachable #74 in mind)
• Live streaming (via Browser & Companion App)
• Screen capturing
• Panning & Tilting -> ideally full PTZ
• Automations

Not in scope

• 2-way audio
• Recording
• Advanced features (AI detection, etc.)

Foreseen solution

Ultimately, we aim for a first go at Matter camera support using the existing Home Assistant camera UI.

The technical groundwork is done by #40: matter.js supports Matter 1.5/1.5.1 data models and cluster support is in place. The following break down could serve as a further discussion basis if needed:

1. Matter camera entity mapping in Home Assistant Core
   Verify and complete the mapping of Matter 1.5.1 camera clusters to the camera entity domain in HA Core. This means confirming the Matter integration correctly exposes a discovered Matter camera as a camera entity, with the right capabilities advertised (stream support, PTZ if reported by the device). This is the prerequisite everything else builds on.

2. Live stream surfacing (Web)
   Wire the Matter camera's stream endpoint (RTSP/WebRTC, depending on what the device exposes via Matter 1.5.1 with TCP) into the existing HA camera more-info dialog and camera card. The goal is that a Matter camera renders exactly like an existing IP camera in the dashboard — no new UI, just correct plumbing. Confirm stream negotiation works via the HA web frontend.

3. Live stream surfacing (Companion Apps — Android & iOS)
   Ensure the Companion Apps on both platforms can render the camera stream from a Matter camera. This largely follows what already works for IP cameras, but needs validation with the Matter-specific stream delivery path. Particular attention to stream protocol fallback if TCP isn't fully resolved for all devices at this stage.

4. Screen capture / snapshot supportExpose the snapshot/still-image capture capability through the existing camera.snapshot service, mapped from the Matter camera's image capture cluster where available. This should align with how the camera card's snapshot button currently works.

5. PTZ support
   Map Matter's Pan/Tilt/Zoom cluster controls to the existing HA PTZ service calls (camera.pan, camera.tilt, camera.zoom). For first iteration, surface whatever the device advertises — don't assume full PTZ. The UI PTZ controls in the more-info dialog should appear only when the camera entity reports PTZ support, which is already how it works for existing cameras.

6. Automations
   Confirm that Matter camera entities trigger correctly in automations — specifically the camera entity state changes (streaming, idle) and any motion/occupancy-related events the Matter camera exposes via its clusters. This likely reuses existing automation tooling with no new UI work needed.

7. Setup flow alignment with Make setting up Matter and adding devices more approachable #74
   Run through the Matter device addition flow specifically with a camera device type and identify any gaps versus adding a simpler Matter device (light, switch). Cameras are more complex — they may require TCP to be functional, and users need a clear signal if the setup completed but the stream isn't available yet. Feed any gaps back into Make setting up Matter and adding devices more approachable #74's scope (troubleshooting signals, error states in the Companion app pairing flow).

8. Compatibility testing across devices
   Testing needs to account for the already-observed pattern that Matter cameras may not fully comply with the Matter camera spec in practice. The Aqara G350 is a documented case. Testing should be structured to distinguish between three outcomes per device: full support, partial support (graceful degradation), and hard failures. Any limitations that can't be resolved in this cycle should be clearly documented and fed into Refine the camera UI and introduce card zooming #120 as known gaps, rather than treated as blockers for shipping.

This also has a downstream effect on step 1 (entity mapping) — when mapping Matter camera clusters to the camera entity, the implementation should be tolerant of devices that advertise capabilities they don't fully implement, rather than assuming spec compliance. Defensive capability negotiation from the start will reduce breakage across the inevitably varied device landscape.

9. Documentation
   Update the Matter integration docs to reflect camera support: what works, what's currently out of scope (2-way audio, recording, AI detection), and any known limitations (e.g. TCP-dependent features on devices that don't yet support it).

Risks & open questions

• Being the first iteration identifying missing / misaligned tech requirements along the way

Appetite

Medium - 1 cycle

Execution issues

No response

Decision log

Date	Decision	Outcome

[mkerstner]

@Apollon77 @matthiasdebaat This would be the opportunity on Matter cameras in a first iteration using existing plumbing and UI.

#120 Would follow thereafter focusing on having a refined view on Matter camera capabilities and additional requirements to surface them in the UI.

[mkerstner]

@TimoPtr @bgoncal fyi - First iteration opportunity on Matter cameras with existing UI and plumbing. #120 would target next iteration thinking about potential UI and architecture improvements if needed.

[bgoncal]

@mkerstner Is it expected that the UI will be done in the apps or frontend?

[mkerstner]

@mkerstner Is it expected that the UI will be done in the apps or frontend?

Can't comment on the best implementation approach here but looping in @abmantis as we've had a general chat about this without going into any specifics. I think that needs an implementation approach alignment.

[abmantis]

@mkerstner Is it expected that the UI will be done in the apps or frontend?

Exposing Matter cameras should have no frontend/mobile changes, or does it? I would assume that's just adding the camera platform to the Matter integration and it would work like any other integration.

Regarding the UI improvements in #120 I would say those should be done in frontend, when possible. Things like zooming the card (not the camera) should work like the graph cards: you can pinch on mobile or ctrl+scroll on web.

[mkerstner]

@abmantis I can't comment on the technical aspects on that - but maybe @Apollon77 can as he's mainly working on that from #40. I would assume no frontend/mobile changes

Regarding the zooming: Thanks for clarifying that. Let's move that discussion in the proper opportunity #120 as this one here merely aims to replicate what we already have for Matter cameras. For sure, if the discussion is Matter camera related let's do it here. This way everyone can easily follow.

[stu88-arch]

Great to see matter camera support on the roadmap :-) Looking forward to support for this after buying the new Aqara 350 and can't use it well outside their app currently!

Does the "Advanced features (AI detection, etc.)" which is mentioned as out of scope, include tracking native AI detection events from capable camera hardware? Or is it referring to AI detection capabilities within HA itself?

I thought implementing native detections would be relatively simple to implement e.g.

• Matter has a data structure for triggering events based on the native AI detections of the camera (?)
• HA could ingest these and trigger as per existing Motion sensor style events (as with existing camera integrations e.g. Google Nest which can trigger Person, Motion events etc)

...but might be oversimplifying this :)

[mkerstner]

@stulowes88-arch Thanks for the feedback :)

We put that one out of scope as we want to further shape what could be included here. Let's not forget that ideally it's not "just" about Matter cameras but we're aiming to further refine generic camera UI and capabilities (starting with e.g. #120 and #163).

For the Matter camera's perspective in general we aim to start based on this opportunity here. That should provide a sound foundation to iterate upon going forward. Of course, we're happy for anyone to contribute to progressing further!