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 +17 -0
- package/README.md +15 -0
- package/dist/behaviors/webRtcTransportProviderServer.js +2 -8
- package/dist/devices/floodlightCamera.js +76 -0
- package/dist/module.js +10 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
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(
|
|
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);
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "matterbridge-example-camera",
|
|
3
|
-
"version": "0.0.
|
|
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.
|
|
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",
|