matterbridge-example-camera 0.0.4-dev-20260720-d558241 → 0.0.5

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,21 +28,25 @@ 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.5] - Dev branch
31
+ ## [0.0.5] - 2026-07-20
32
32
 
33
- ## Added
33
+ ### Added
34
34
 
35
35
  - [wirift]: Add codec negotiation and ffmpeg windows path.
36
36
  - [audio doorbell]: Add the Audio Doorbell device type with the required Identify, Switch (MomentarySwitch feature), Camera AV Stream Management (Audio feature), and WebRtcTransportProvider clusters, plus the Chime and WebRtcTransportRequestor client clusters, and Power Source support.
37
37
  - [clients]: Add `src/behaviors/clients.ts` with `addChimeClient`/`addWebRtcTransportRequestorClient` helpers, shared by `Doorbell`, `AudioDoorbell`, and `Camera`.
38
38
  - [tests]: Add `vitest/behaviors/clients.test.ts` covering `addChimeClient`/`addWebRtcTransportRequestorClient`, and assert in `doorbell.test.ts`, `camera.test.ts`, and `audioDoorbell.test.ts` that the required client clusters are registered in `MatterbridgeBindingServer`'s `clientList` and `type.clientClusters`.
39
+ - [platform]: Add a server Chime and Doorbell to test binding.
39
40
 
40
- ## Changed
41
+ ### Changed
41
42
 
42
43
  - [package]: Update dependencies.
43
44
  - [package]: Upgrade package.
44
45
  - [camera]: Use the shared `addWebRtcTransportRequestorClient` helper from `clients.ts` instead of a local duplicate.
45
46
  - [doorbell]: Use the shared `addChimeClient` helper from `clients.ts` instead of inline binding code.
47
+ - [devices]: `DoorbellOptions`, `AudioDoorbellOptions`, `ChimeOptions`, `CameraOptions`, and `SnapshotCameraOptions` now extend `MatterbridgeEndpointOptions`, forwarding `id`/`number`/`tagList`/`mode` to the underlying `MatterbridgeEndpoint` (`id` defaults to `${name}-${serial}` when not provided), and document the default value of each `identifyTime`/`identifyType`/`powerSourceType` option in JSDoc.
48
+ - [module]: Register the `AudioDoorbell` example device in `onStart` and verify it's registered in `onConfigure`, alongside the existing `Chime`, `Doorbell`, `SnapshotCamera`, and `Camera` example devices.
49
+ - [tests]: Add `vitest/module.test.ts` coverage for the `AudioDoorbell` and `Camera` "device not registered" `onConfigure` error paths, and for the `animationInterval` configuration option (periodic `animationHandler` execution, phase wraparound, and interval cleanup on shutdown).
46
50
 
47
51
  <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="80"></a>
48
52
 
package/README.md CHANGED
@@ -162,6 +162,16 @@ The `assets` directory contains deterministic three-second media fixtures for ex
162
162
  - `camera-color-640-480.jpeg`: 640×480 simplified ffmpeg-generated color-rectangle snapshot returned by the example's `CaptureSnapshot` command.
163
163
  - `camera-color-test-1920-1080.jpeg`, `camera-color-test-1280-720.jpeg`, `camera-color-test-960-540.jpeg`, `camera-color-test-640-480.jpeg`, and `camera-color-test-480-270.jpeg`: additional SMPTE color-bars snapshot fixtures.
164
164
 
165
+ #### Why the snapshot calibration cards stay under ~64 KB
166
+
167
+ All three calibration cards above are kept well under the Matter message size ceiling, which caps at **65535 bytes** for a single message and cannot be worked around by tuning TCP:
168
+
169
+ - Every Matter message is encrypted with AES-128-CCM, using a 13-byte nonce built from the security flags, message counter, and node ID (`Session.generateNonce`, part of the Matter message-security spec, not a matter.js choice).
170
+ - AES-CCM (RFC 3610 / NIST SP 800-38C) requires the nonce length `N` and the length-field size `L` to satisfy `N + L = 15` bytes for a 128-bit block cipher. With `N = 13`, that leaves `L = 2`.
171
+ - A 2-byte length field caps the plaintext of a single CCM-encrypted message at `2^16 - 1 = 65535` bytes — a cryptographic ceiling, not a networking one. matter.js's `DEFAULT_MAX_TCP_MESSAGE_SIZE` (64000) is just a round number kept safely under that limit.
172
+
173
+ A `CaptureSnapshot` response whose `data` field doesn't fit fails to send: the client gets a generic invoke failure instead of an image, since the encoder cannot represent the required plaintext length in the message header. `CameraAvStreamManagement.CaptureSnapshot` returns its image as a single field of a single command response, so it inherits this ceiling directly. Matter has a dedicated mechanism for transferring larger payloads — BDX (Bulk Data Exchange), used for OTA updates and diagnostic logs — which splits big content across a sequence of acknowledged messages instead of one oversized one, but `CaptureSnapshot` doesn't use it.
174
+
165
175
  WebRTC media tracks transport encoded H.264 or Opus frames in RTP packets; they do not send an MP4, Ogg, or MPEG container directly. The current MP4 transfer deliberately uses the separate data-channel path. A future video-track test should parse the relevant elementary frames, packetize them as RTP, call werift's media track `writeRtp()`, and verify reception through `onTrack` and `onReceiveRtp`.
166
176
 
167
177
  ## Chip tests
@@ -6,8 +6,13 @@ import { addChimeClient, addWebRtcTransportRequestorClient } from '../behaviors/
6
6
  import { createDefaultWebRtcTransportProviderClusterServer } from '../behaviors/webRtcTransportProviderServer.js';
7
7
  export class AudioDoorbell extends MatterbridgeEndpoint {
8
8
  constructor(name, serial, options = {}) {
9
- const { identifyTime = 0, identifyType = Identify.IdentifyType.None, powerSourceType = 'Wired', maxContentBufferSize = 65_536, maxNetworkBandwidth = 128_000, supportedStreamUsages = [StreamUsage.LiveView], streamUsagePriorities = supportedStreamUsages, microphoneCapabilities = { maxNumberOfChannels: 1, supportedCodecs: [CameraAvStreamManagement.AudioCodec.Opus], supportedSampleRates: [48000], supportedBitDepths: [16] }, } = options;
10
- super(powerSourceType === 'None' ? [audioDoorbell] : [audioDoorbell, powerSource], { id: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` });
9
+ const { identifyTime = 0, identifyType = Identify.IdentifyType.None, powerSourceType = 'Wired', maxContentBufferSize = 65_536, maxNetworkBandwidth = 128_000, supportedStreamUsages = [StreamUsage.LiveView], streamUsagePriorities = supportedStreamUsages, microphoneCapabilities = { maxNumberOfChannels: 1, supportedCodecs: [CameraAvStreamManagement.AudioCodec.Opus], supportedSampleRates: [48000], supportedBitDepths: [16] }, id, number, tagList, mode, } = options;
10
+ super(powerSourceType === 'None' ? [audioDoorbell] : [audioDoorbell, powerSource], {
11
+ id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`,
12
+ number,
13
+ tagList,
14
+ mode,
15
+ });
11
16
  this.createDefaultIdentifyClusterServer(identifyTime, identifyType);
12
17
  this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Audio Doorbell');
13
18
  switch (powerSourceType) {
@@ -10,8 +10,8 @@ export class Camera extends MatterbridgeEndpoint {
10
10
  { resolution: { width: 640, height: 480 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
11
11
  { resolution: { width: 1280, height: 720 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
12
12
  { resolution: { width: 1920, height: 1080 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
13
- ], allocatedSnapshotStreams = [], } = options;
14
- super(powerSourceType === 'None' ? [camera] : [camera, powerSource], { id: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` });
13
+ ], allocatedSnapshotStreams = [], id, number, tagList, mode, } = options;
14
+ super(powerSourceType === 'None' ? [camera] : [camera, powerSource], { id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`, number, tagList, mode });
15
15
  if (identifyType !== Identify.IdentifyType.None) {
16
16
  this.createDefaultIdentifyClusterServer(identifyTime, identifyType);
17
17
  }
@@ -8,8 +8,8 @@ export class Chime extends MatterbridgeEndpoint {
8
8
  chimeId: 0,
9
9
  name: 'Default Chime',
10
10
  },
11
- ], selectedChime = 0, enabled = true, } = options;
12
- super(powerSourceType === 'None' ? [chime] : [chime, powerSource], { id: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` });
11
+ ], selectedChime = 0, enabled = true, id, number, tagList, mode, } = options;
12
+ super(powerSourceType === 'None' ? [chime] : [chime, powerSource], { id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`, number, tagList, mode });
13
13
  if (identifyType !== Identify.IdentifyType.None) {
14
14
  this.createDefaultIdentifyClusterServer(identifyTime, identifyType);
15
15
  }
@@ -3,8 +3,8 @@ import { Identify } from 'matterbridge/matter/clusters';
3
3
  import { addChimeClient } from '../behaviors/clients.js';
4
4
  export class Doorbell extends MatterbridgeEndpoint {
5
5
  constructor(name, serial, options = {}) {
6
- const { identifyTime = 0, identifyType = Identify.IdentifyType.None, powerSourceType = 'Wired' } = options;
7
- super(powerSourceType === 'None' ? [doorbell] : [doorbell, powerSource], { id: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` });
6
+ const { identifyTime = 0, identifyType = Identify.IdentifyType.None, powerSourceType = 'Wired', id, number, tagList, mode } = options;
7
+ super(powerSourceType === 'None' ? [doorbell] : [doorbell, powerSource], { id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`, number, tagList, mode });
8
8
  this.createDefaultIdentifyClusterServer(identifyTime, identifyType);
9
9
  this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Doorbell');
10
10
  switch (powerSourceType) {
@@ -8,8 +8,13 @@ export class SnapshotCamera extends MatterbridgeEndpoint {
8
8
  { resolution: { width: 640, height: 480 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
9
9
  { resolution: { width: 1280, height: 720 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
10
10
  { resolution: { width: 1920, height: 1080 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
11
- ], maxNetworkBandwidth = 10000, supportedStreamUsages = [StreamUsage.Recording], allocatedSnapshotStreams = [], streamUsagePriorities = [StreamUsage.Recording], } = options;
12
- super(powerSourceType === 'None' ? [snapshotCamera] : [snapshotCamera, powerSource], { id: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` });
11
+ ], maxNetworkBandwidth = 10000, supportedStreamUsages = [StreamUsage.Recording], allocatedSnapshotStreams = [], streamUsagePriorities = [StreamUsage.Recording], id, number, tagList, mode, } = options;
12
+ super(powerSourceType === 'None' ? [snapshotCamera] : [snapshotCamera, powerSource], {
13
+ id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`,
14
+ number,
15
+ tagList,
16
+ mode,
17
+ });
13
18
  if (identifyType !== Identify.IdentifyType.None) {
14
19
  this.createDefaultIdentifyClusterServer(identifyTime, identifyType);
15
20
  }
package/dist/module.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import './patches/objectSchemaInjectFieldFix.js';
2
2
  import { MatterbridgeDynamicPlatform } from 'matterbridge';
3
3
  import { Identify, Chime as ChimeCluster, PowerSource } from 'matterbridge/matter/clusters';
4
+ import { AudioDoorbell } from './devices/audioDoorbell.js';
4
5
  import { Camera } from './devices/camera.js';
5
6
  import { Chime } from './devices/chime.js';
6
7
  import { Doorbell } from './devices/doorbell.js';
@@ -9,8 +10,12 @@ export default function initializePlugin(matterbridge, log, config) {
9
10
  return new ExampleMatterbridgeCameraPlatform(matterbridge, log, config);
10
11
  }
11
12
  export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatform {
13
+ config;
14
+ animationPhase = 0;
15
+ animationInterval;
12
16
  constructor(matterbridge, log, config) {
13
17
  super(matterbridge, log, config);
18
+ this.config = config;
14
19
  if (typeof this.verifyMatterbridgeVersion !== 'function' || !this.verifyMatterbridgeVersion('3.10.0')) {
15
20
  throw new Error(`This plugin requires Matterbridge version >= "3.10.0". Please update Matterbridge to the latest version in the frontend.`);
16
21
  }
@@ -38,7 +43,13 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
38
43
  powerSourceType: 'Replaceable',
39
44
  });
40
45
  await this.registerDevice(exampleDoorbell);
41
- const exampleSnapshotCamera = new SnapshotCamera('Snapshot Camera', 'SNAPSHOT-001', {
46
+ const exampleAudioDoorbell = new AudioDoorbell('Audio Doorbell', 'AUDIODOORBELL-001', {
47
+ identifyTime: 5,
48
+ identifyType: Identify.IdentifyType.VisibleIndicator,
49
+ powerSourceType: 'Replaceable',
50
+ });
51
+ await this.registerDevice(exampleAudioDoorbell);
52
+ const exampleSnapshotCamera = new SnapshotCamera('Snapshot Camera', 'SNAPSHOTCAMERA-001', {
42
53
  identifyTime: 5,
43
54
  identifyType: Identify.IdentifyType.VisibleIndicator,
44
55
  powerSourceType: 'Wired',
@@ -46,6 +57,10 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
46
57
  await this.registerDevice(exampleSnapshotCamera);
47
58
  const exampleCamera = new Camera('Camera', 'CAMERA-001');
48
59
  await this.registerDevice(exampleCamera);
60
+ const serverChime = new Chime('Server Chime', 'SERVER-CHIME-001', { mode: 'server' });
61
+ await this.registerDevice(serverChime);
62
+ const serverDoorbell = new Doorbell('Server Doorbell', 'SERVER-DOORBELL-001', { mode: 'server' });
63
+ await this.registerDevice(serverDoorbell);
49
64
  this.log.info(`Platform ${this.config.name} started successfully`);
50
65
  }
51
66
  async onConfigure() {
@@ -59,14 +74,31 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
59
74
  const exampleDoorbell = this.getDeviceById('Doorbell-DOORBELL-001');
60
75
  if (!exampleDoorbell)
61
76
  throw new Error(`Doorbell device not found. Please ensure the device is registered before configuration.`);
62
- const exampleSnapshotCamera = this.getDeviceById('SnapshotCamera-SNAPSHOT-001');
77
+ const exampleAudioDoorbell = this.getDeviceById('AudioDoorbell-AUDIODOORBELL-001');
78
+ if (!exampleAudioDoorbell)
79
+ throw new Error(`Audio doorbell device not found. Please ensure the device is registered before configuration.`);
80
+ const exampleSnapshotCamera = this.getDeviceById('SnapshotCamera-SNAPSHOTCAMERA-001');
63
81
  if (!exampleSnapshotCamera)
64
82
  throw new Error(`Snapshot camera device not found. Please ensure the device is registered before configuration.`);
83
+ const exampleCamera = this.getDeviceById('Camera-CAMERA-001');
84
+ if (!exampleCamera)
85
+ throw new Error(`Camera device not found. Please ensure the device is registered before configuration.`);
86
+ if (this.config.animationInterval > 0) {
87
+ clearInterval(this.animationInterval);
88
+ this.animationInterval = setInterval(() => void this.animationHandler(), this.config.animationInterval * 1000);
89
+ }
65
90
  this.log.info(`Platform ${this.config.name} configured successfully`);
66
91
  }
92
+ async animationHandler() {
93
+ this.animationPhase = this.animationPhase + 1;
94
+ this.animationPhase = this.animationPhase > 10 ? 0 : this.animationPhase;
95
+ this.log.info(`Platform ${this.config.name} animation phase: ${this.animationPhase}`);
96
+ }
67
97
  async onShutdown(reason) {
68
98
  await super.onShutdown(reason);
69
99
  this.log.info(`Shutting down platform ${this.config.name} with reason: ${reason ?? 'No reason provided'}...`);
100
+ clearInterval(this.animationInterval);
101
+ this.animationInterval = undefined;
70
102
  if (this.config.unregisterOnShutdown)
71
103
  await this.unregisterAllDevices();
72
104
  this.log.info(`Platform ${this.config.name} shut down successfully`);
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "matterbridge-example-camera",
3
+ "type": "DynamicPlatform",
4
+ "whiteList": [],
5
+ "blackList": [],
6
+ "animationInterval": 60,
7
+ "debug": false,
8
+ "unregisterOnShutdown": false
9
+ }
@@ -0,0 +1,58 @@
1
+ {
2
+ "title": "Matterbridge example camera plugin",
3
+ "description": "matterbridge-example-camera v. 1.0.0 by https://github.com/Luligu",
4
+ "type": "object",
5
+ "required": [],
6
+ "properties": {
7
+ "name": {
8
+ "description": "Plugin Name",
9
+ "type": "string",
10
+ "readOnly": true,
11
+ "ui:widget": "hidden"
12
+ },
13
+ "type": {
14
+ "description": "Plugin Type",
15
+ "type": "string",
16
+ "readOnly": true,
17
+ "ui:widget": "hidden"
18
+ },
19
+ "whiteList": {
20
+ "title": "White List",
21
+ "description": "Only the devices in the list will be exposed. If the list is empty, all the devices will be exposed.",
22
+ "type": "array",
23
+ "items": {
24
+ "type": "string"
25
+ },
26
+ "uniqueItems": true,
27
+ "selectFrom": "name"
28
+ },
29
+ "blackList": {
30
+ "title": "Black List",
31
+ "description": "The devices in the list will not be exposed. If the list is empty, no devices will be excluded.",
32
+ "type": "array",
33
+ "items": {
34
+ "type": "string"
35
+ },
36
+ "uniqueItems": true,
37
+ "selectFrom": "name"
38
+ },
39
+ "animationInterval": {
40
+ "title": "Animation Interval",
41
+ "description": "Interval to refresh the devices (in seconds). Use 0 to disable the animation.",
42
+ "type": "number",
43
+ "default": 60
44
+ },
45
+ "debug": {
46
+ "title": "Enable Debug",
47
+ "description": "Enable the debug for the plugin (development only)",
48
+ "type": "boolean",
49
+ "default": false
50
+ },
51
+ "unregisterOnShutdown": {
52
+ "title": "Unregister On Shutdown",
53
+ "description": "Unregister all devices on shutdown (development only)",
54
+ "type": "boolean",
55
+ "default": false
56
+ }
57
+ }
58
+ }
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.4-dev-20260720-d558241",
3
+ "version": "0.0.5",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "matterbridge-example-camera",
9
- "version": "0.0.4-dev-20260720-d558241",
9
+ "version": "0.0.5",
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.4-dev-20260720-d558241",
3
+ "version": "0.0.5",
4
4
  "description": "Matterbridge camera example plugin",
5
5
  "author": "https://github.com/Luligu",
6
6
  "license": "Apache-2.0",