matterbridge-example-camera 0.0.5 → 0.0.6-dev-20260721-4f7106a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -28,6 +28,23 @@ If you like this project and find it useful, please consider giving it a star on
28
28
 
29
29
  <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
30
30
 
31
+ ## [0.0.6] - Dev branch
32
+
33
+ ## [0.0.6] - Dev branch
34
+
35
+ ### Added
36
+
37
+ - [floodlight camera]: Add the Floodlight Camera device type. It is a composed device: the root endpoint carries Basic Information and, unless disabled, Power Source; the mandatory Camera child endpoint and the mandatory On/Off Light child endpoint required by Matter specs 1.6.0 chapter 16.2 are both created automatically by the constructor, the Camera child with the same CameraAvStreamManagement/WebRtcTransportProvider wiring as the standalone `Camera` device; `addLight()` adds further On/Off Light child endpoints beyond the mandatory one.
38
+ - [platform]: Register a Floodlight Camera example device in `onStart`, and verify it's registered in `onConfigure`.
39
+ - [tests]: Add `vitest/devices/floodlightCamera.test.ts` covering default options, custom `lightOptions`, camera identify, power source variants, additional tagged lights, and custom stream usages; extend `vitest/module.test.ts` with the Floodlight Camera "device not registered" `onConfigure` error path.
40
+
41
+ ### Fixed
42
+
43
+ - [webrtc]: `provideIceCandidates` unconditionally skipped every mDNS host ICE candidate (`*.local`), so a peer that only offers mDNS-obfuscated candidates (the Chromium/Edge default) left the werift peer connection with zero usable remote candidates — signaling succeeded but the stream stayed black. werift-ice already resolves `.local` candidates via a real multicast DNS query before pairing them, so candidates are no longer skipped and that resolution is allowed to run; the per-candidate apply timeout is bumped from 2000ms to 5000ms to leave headroom for the mDNS round trip. Verified against a real Edge client: the mDNS candidate resolved and applied in 98ms and video streamed correctly. See the new "Known limitation: Firefox may only offer a link-local address on a non-HTTPS page" note in the README for a related, separate client-side issue this does not fix.
44
+ - [snapshot]: README asset docs still described the pre-#15 `camera-color-test-*.jpeg` names; `CaptureSnapshot` now reads `camera-color-{640-480,1280-720,1920-1080}.jpeg`. Also documented why all three calibration cards are kept under the ~65535-byte Matter message-size ceiling (AES-CCM's 13-byte nonce) and why it can't be worked around by tuning TCP.
45
+
46
+ <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
47
+
31
48
  ## [0.0.5] - 2026-07-20
32
49
 
33
50
  ### Added
package/README.md CHANGED
@@ -89,6 +89,15 @@ Features:
89
89
  - Configurable Power Source cluster type: Rechargeable, Replaceable, Battery, Wired, or None to omit the Power Source cluster entirely.
90
90
  - Deviation from the Matter specification: the CameraAvStreamManagement ImageControl feature is also enabled, even though the specification only allows it when Video or Snapshot is present, to work around a matter.js bug where the ImageRotation/ImageFlipHorizontal/ImageFlipVertical "at least one shall be present" choice conformance is enforced unconditionally instead of only when ImageControl is enabled (see the JSDoc in `src/devices/audioDoorbell.ts`).
91
91
 
92
+ ### Floodlight Camera
93
+
94
+ Features:
95
+
96
+ - A composite device type, always defined via endpoint composition: the root endpoint exposes Basic Information and, unless disabled, a Power Source cluster; the mandatory Camera child endpoint and the mandatory On/Off Light child endpoint required by the Matter specification for this device type are both created automatically by the constructor. The Camera child is wired the same way as the standalone Camera device (CameraAvStreamManagement with the Video, Audio, Snapshot and ImageControl features, and the WebRtcTransportProvider cluster and WebRtcTransportRequestor client). Each light gets its own Identify and OnOff (Lighting feature) cluster servers.
97
+ - Exposes `addLight()` to add further On/Off Light child endpoints beyond the mandatory one, with an optional tagList for disambiguation when more than one light is present.
98
+ - Configurable Power Source cluster type on the root endpoint: Rechargeable, Replaceable, Battery, Wired, or None to omit the Power Source cluster entirely.
99
+ - The Camera child endpoint's Identify and CameraAvStreamManagement configuration can be customized via the `cameraOptions` constructor option, using the same fields and defaults as the standalone Camera device. The mandatory light's name, tagList, and initial state can be customized via the `lightOptions` constructor option.
100
+
92
101
  ## WebRTC test video injection
93
102
 
94
103
  `WeriftWebRtcSession` (see `src/webrtc/weriftSession.ts`) wraps a real werift `RTCPeerConnection` for each WebRtcTransportProvider session (see `MatterbridgeWebRtcTransportProviderServer` in `src/behaviors/webRtcTransportProviderServer.ts`), so the session's SDP offer/answer and ICE candidates are handled by a real WebRTC peer connection instead of being just recorded. It can also inject a real ffmpeg-generated video track into the negotiated connection, so the end-to-end media path can be validated without a real camera capture pipeline.
@@ -110,6 +119,12 @@ Example, capturing from a real Linux webcam at 720p:
110
119
  MATTERBRIDGE_CAMERA_VIDEO_SOURCE=webcam MATTERBRIDGE_CAMERA_WEBCAM_DEVICE=/dev/video0 MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION=1280x720 npm start
111
120
  ```
112
121
 
122
+ ### Known limitation: Firefox may only offer a link-local address on a non-HTTPS page
123
+
124
+ `MatterbridgeWebRtcTransportProviderServer.provideIceCandidates` applies every ICE candidate it receives, including mDNS-obfuscated `*.local` host candidates (the Chromium/Edge default): werift-ice resolves those via a real multicast DNS query before pairing them, so no special handling is needed here.
125
+
126
+ This relies on the client machine actually offering a usable address in the first place. Firefox has been observed advertising only a non-routable IPv6 link-local (`fe80::...`) address — instead of its real LAN IP — when the WebRTC-consuming page is loaded over plain HTTP from a non-`localhost` origin (i.e. not a secure context: not `https://`, not `http://localhost`/`127.0.0.1`), even with `media.peerconnection.ice.obfuscate_host_addresses` disabled in `about:config`. A link-local address can never be reached by a remote peer, so the connection stays black-screen no matter how the candidate is resolved. Chromium-based browsers (Edge, Chrome) were unaffected under the same conditions. If a stream stays black specifically with Firefox, check whether the page serving the WebRTC client is a secure context (`window.isSecureContext` in devtools, or `about:webrtc` for the actual candidates gathered) before assuming a bug in this plugin — serving that page over HTTPS, or via `localhost`, is the fix.
127
+
113
128
  ## Werift integration test
114
129
 
115
130
  The `vitest/werift.test.ts` integration test creates local client and server peers and verifies SDP offer/answer negotiation, ICE candidate exchange, a bidirectional data-channel transfer, and connection teardown with `werift`.
@@ -5,6 +5,7 @@ import { EndpointNumber, FabricIndex, NodeId, StreamUsage, Status, StatusRespons
5
5
  import { WeriftWebRtcSession } from '../webrtc/weriftSession.js';
6
6
  import { MatterbridgeCameraAvStreamManagementServer } from './cameraAvStreamManagementServer.js';
7
7
  const DEFERRED_INVOKE_DELAY_MS = 250;
8
+ const ICE_CANDIDATE_APPLY_TIMEOUT_MS = 5000;
8
9
  export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportProviderServer {
9
10
  #invokeDeferred(action, description) {
10
11
  const device = this.endpoint.stateOf(MatterbridgeServer);
@@ -210,20 +211,13 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
210
211
  if (webRtcPeer) {
211
212
  for (const [index, candidate] of request.iceCandidates.entries()) {
212
213
  const startedAt = Date.now();
213
- const isMdnsHostCandidate = /\.local\s+\d+\s+typ\s+host\b/i.test(candidate.candidate);
214
- if (isMdnsHostCandidate) {
215
- device.log.debug(`Skipping mDNS host ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
216
- `(mid=${candidate.sdpMid ?? 'null'}, mLine=${candidate.sdpmLineIndex ?? 'null'}) ` +
217
- `(endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
218
- continue;
219
- }
220
214
  device.log.debug(`Applying ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
221
215
  `(mid=${candidate.sdpMid ?? 'null'}, mLine=${candidate.sdpmLineIndex ?? 'null'}, endOfCandidates=${candidate.candidate.trim() === ''}) ` +
222
216
  `(endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
223
217
  try {
224
218
  await Promise.race([
225
219
  webRtcPeer.addIceCandidate(candidate.candidate, candidate.sdpMid, candidate.sdpmLineIndex),
226
- new Promise((_resolve, reject) => setTimeout(() => reject(new Error('ICE candidate apply timeout after 2000ms')), 2000)),
220
+ new Promise((_resolve, reject) => setTimeout(() => reject(new Error(`ICE candidate apply timeout after ${ICE_CANDIDATE_APPLY_TIMEOUT_MS}ms`)), ICE_CANDIDATE_APPLY_TIMEOUT_MS)),
227
221
  ]);
228
222
  device.log.debug(`Applied ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
229
223
  `in ${Date.now() - startedAt}ms (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
@@ -0,0 +1,76 @@
1
+ import { camera, floodlightCamera, MatterbridgeEndpoint, onOffLight, powerSource } from 'matterbridge';
2
+ import { CameraAvStreamManagement, Identify } from 'matterbridge/matter/clusters';
3
+ import { StreamUsage } from 'matterbridge/matter/types';
4
+ import { fireAndForget } from 'matterbridge/utils';
5
+ import { addWebRtcTransportRequestorClient } from '../behaviors/clients.js';
6
+ import { createDefaultWebRtcTransportProviderClusterServer } from '../behaviors/webRtcTransportProviderServer.js';
7
+ import { createDefaultCameraAvStreamManagementClusterServer } from './camera.js';
8
+ export class FloodlightCamera extends MatterbridgeEndpoint {
9
+ constructor(name, serial, options = {}) {
10
+ const { powerSourceType = 'Wired', cameraOptions = {}, lightOptions = {}, id, number, tagList, mode } = options;
11
+ super(powerSourceType === 'None' ? [floodlightCamera] : [floodlightCamera, powerSource], {
12
+ id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`,
13
+ number,
14
+ tagList,
15
+ mode,
16
+ });
17
+ this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Floodlight Camera');
18
+ switch (powerSourceType) {
19
+ case 'Rechargeable':
20
+ this.createDefaultPowerSourceRechargeableBatteryClusterServer();
21
+ break;
22
+ case 'Replaceable':
23
+ this.createDefaultPowerSourceReplaceableBatteryClusterServer();
24
+ break;
25
+ case 'Battery':
26
+ this.createDefaultPowerSourceBatteryClusterServer();
27
+ break;
28
+ case 'Wired':
29
+ this.createDefaultPowerSourceWiredClusterServer();
30
+ break;
31
+ case 'None':
32
+ break;
33
+ }
34
+ fireAndForget(this.addFixedLabel('composed', 'FloodlightCamera'), this.log, 'Error adding composed label to floodlight camera');
35
+ this.addRequiredClusters();
36
+ const { identifyTime = 0, identifyType = Identify.IdentifyType.None, maxContentBufferSize = 4_194_304, maxNetworkBandwidth = 10_000_000, supportedStreamUsages = [StreamUsage.LiveView, StreamUsage.Recording], streamUsagePriorities = supportedStreamUsages, maxConcurrentEncoders = 1, maxEncodedPixelRate = 1920 * 1080 * 30, videoSensorParams = { sensorWidth: 1920, sensorHeight: 1080, maxFps: 30 }, minViewportResolution = { width: 640, height: 360 }, rateDistortionTradeOffPoints = [{ codec: CameraAvStreamManagement.VideoCodec.H264, resolution: { width: 1920, height: 1080 }, minBitRate: 1_000_000 }], currentFrameRate = 30, viewport = { x1: 0, y1: 0, x2: videoSensorParams.sensorWidth, y2: videoSensorParams.sensorHeight }, microphoneCapabilities = { maxNumberOfChannels: 1, supportedCodecs: [CameraAvStreamManagement.AudioCodec.Opus], supportedSampleRates: [48000], supportedBitDepths: [16] }, snapshotCapabilities = [
37
+ { resolution: { width: 640, height: 480 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
38
+ { resolution: { width: 1280, height: 720 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
39
+ { resolution: { width: 1920, height: 1080 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
40
+ ], allocatedSnapshotStreams = [], } = cameraOptions;
41
+ const cameraChild = this.addChildDeviceType('Camera', camera, {});
42
+ cameraChild.log.logName = 'Camera';
43
+ if (identifyType !== Identify.IdentifyType.None) {
44
+ cameraChild.createDefaultIdentifyClusterServer(identifyTime, identifyType);
45
+ }
46
+ createDefaultCameraAvStreamManagementClusterServer(cameraChild, {
47
+ maxContentBufferSize,
48
+ maxNetworkBandwidth,
49
+ supportedStreamUsages,
50
+ streamUsagePriorities,
51
+ maxConcurrentEncoders,
52
+ maxEncodedPixelRate,
53
+ videoSensorParams,
54
+ minViewportResolution,
55
+ rateDistortionTradeOffPoints,
56
+ currentFrameRate,
57
+ viewport,
58
+ microphoneCapabilities,
59
+ snapshotCapabilities,
60
+ allocatedSnapshotStreams,
61
+ });
62
+ createDefaultWebRtcTransportProviderClusterServer(cameraChild);
63
+ addWebRtcTransportRequestorClient(cameraChild);
64
+ cameraChild.addRequiredClusters();
65
+ const { name: lightName = 'Light', tagList: lightTagList = [], onOff: lightOnOff = false } = lightOptions;
66
+ this.addLight(lightName, lightTagList, lightOnOff);
67
+ }
68
+ addLight(name, tagList = [], onOff = false) {
69
+ const light = this.addChildDeviceType(name, onOffLight, tagList.length > 0 ? { tagList } : {});
70
+ light.log.logName = name;
71
+ light.createDefaultIdentifyClusterServer();
72
+ light.createDefaultOnOffClusterServer(onOff);
73
+ light.addRequiredClusters();
74
+ return light;
75
+ }
76
+ }
package/dist/module.js CHANGED
@@ -5,6 +5,7 @@ import { AudioDoorbell } from './devices/audioDoorbell.js';
5
5
  import { Camera } from './devices/camera.js';
6
6
  import { Chime } from './devices/chime.js';
7
7
  import { Doorbell } from './devices/doorbell.js';
8
+ import { FloodlightCamera } from './devices/floodlightCamera.js';
8
9
  import { SnapshotCamera } from './devices/snapshotCamera.js';
9
10
  export default function initializePlugin(matterbridge, log, config) {
10
11
  return new ExampleMatterbridgeCameraPlatform(matterbridge, log, config);
@@ -57,6 +58,12 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
57
58
  await this.registerDevice(exampleSnapshotCamera);
58
59
  const exampleCamera = new Camera('Camera', 'CAMERA-001');
59
60
  await this.registerDevice(exampleCamera);
61
+ const exampleFloodlightCamera = new FloodlightCamera('Floodlight Camera', 'FLOODLIGHTCAMERA-001', {
62
+ powerSourceType: 'Wired',
63
+ cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator },
64
+ lightOptions: { name: 'Floodlight' },
65
+ });
66
+ await this.registerDevice(exampleFloodlightCamera);
60
67
  const serverChime = new Chime('Server Chime', 'SERVER-CHIME-001', { mode: 'server' });
61
68
  await this.registerDevice(serverChime);
62
69
  const serverDoorbell = new Doorbell('Server Doorbell', 'SERVER-DOORBELL-001', { mode: 'server' });
@@ -83,6 +90,9 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
83
90
  const exampleCamera = this.getDeviceById('Camera-CAMERA-001');
84
91
  if (!exampleCamera)
85
92
  throw new Error(`Camera device not found. Please ensure the device is registered before configuration.`);
93
+ const exampleFloodlightCamera = this.getDeviceById('FloodlightCamera-FLOODLIGHTCAMERA-001');
94
+ if (!exampleFloodlightCamera)
95
+ throw new Error(`Floodlight camera device not found. Please ensure the device is registered before configuration.`);
86
96
  if (this.config.animationInterval > 0) {
87
97
  clearInterval(this.animationInterval);
88
98
  this.animationInterval = setInterval(() => void this.animationHandler(), this.config.animationInterval * 1000);
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.5",
3
+ "version": "0.0.6-dev-20260721-4f7106a",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "matterbridge-example-camera",
9
- "version": "0.0.5",
9
+ "version": "0.0.6-dev-20260721-4f7106a",
10
10
  "license": "Apache-2.0",
11
11
  "dependencies": {
12
12
  "node-ansi-logger": "3.3.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.5",
3
+ "version": "0.0.6-dev-20260721-4f7106a",
4
4
  "description": "Matterbridge camera example plugin",
5
5
  "author": "https://github.com/Luligu",
6
6
  "license": "Apache-2.0",