matterbridge-example-camera 0.0.7-dev-20260725-bcbe2ca → 0.0.8-dev-20260726-2ea4814

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,15 +28,40 @@ 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.7] - Dev branch
31
+ ## [0.0.8] - Dev branch
32
32
 
33
33
  ### Added
34
34
 
35
+ - [webrtc]: Add an `rtsp` video generator option that pulls from a real RTSP camera via `ffmpeg -rtsp_transport tcp -i <url>` instead of only the synthetic test pattern or a local webcam.
36
+ - [platform]: Rename the `webcam`/`webcamResolution`/`webcamBitrate` config properties to `videoSource`/`videoResolution`/`videoBitrate` (and the corresponding `MATTERBRIDGE_CAMERA_WEBCAM_*` env vars to `MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE`/`MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION`/`MATTERBRIDGE_CAMERA_VIDEO_BITRATE`), since `videoSource` now also holds the RTSP url for the `rtsp` generator.
37
+ - [platform]: Rename the `generator` config property to `videoGenerator`.
38
+ - [webrtc]: Add an `auto` value for `videoResolution` (now the default) that uses the controller's requested per-session resolution (the allocated video stream's `maxResolution`) instead of a fixed value; a fixed `videoResolution` still always wins over the controller's request. For `rtsp`, the resolved resolution (fixed or auto) is now applied to the injected track with an ffmpeg `scale` filter instead of being ignored.
39
+ - [docs]: Document the `rtsp` video generator, the renamed config properties, the `auto`/fixed `videoResolution` precedence, and the previously undocumented `videoBitrate` property in the README, with example configurations.
40
+ - [tests]: Add `rtsp` video source and `videoResolution` precedence (`auto` vs. fixed, webcam and rtsp) coverage in `vitest/webrtc/weriftSession.test.ts`; extend `vitest/module.test.ts` with the `videoGenerator` normalization test and a test for the `videoResolution` default of `auto`.
41
+
42
+ ### Fixed
43
+
44
+ - [webrtc]: The per-session requested webcam resolution (from a client's `CameraAvStreamManagement.VideoStreamAllocate`) was never actually applied: `buildFfmpegVideoInputArgs` read `MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION` directly before falling back to `getConfiguredVideoResolution(requestedResolution)`, and since the plugin always sets that env var (default `640x480`), the fallback — and therefore the requested resolution — was never reached.
45
+
46
+ ## [0.0.7] - 2026-07-25
47
+
48
+ ### Added
49
+
50
+ - [video doorbell]: Add the Video Doorbell device type (Matter 1.6.0 chapter 16.3). A composite device, always defined via endpoint composition: the root endpoint exposes Basic Information and, unless disabled, a Power Source cluster; the mandatory Camera child endpoint is wired the same way as the standalone `Camera` device, and the mandatory Doorbell child endpoint is wired the same way as the standalone `Doorbell` device. Exposes `addDoorbell()` to add further Doorbell child endpoints.
51
+ - [platform]: Register a Video Doorbell example device in `onStart`.
52
+ - [tests]: Add `vitest/devices/videoDoorbell.test.ts`; extend `vitest/module.test.ts` device-count assertions for the new device.
53
+ - [docs]: Document the Video Doorbell device type in the README.
35
54
  - [tests]: Add `vitest/webrtc/weriftSession.test.ts` coverage for the audio track injection path in `WeriftWebRtcSession`: an SDP answer without an injectable audio codec when the remote offer only supports PCMU, skipping non-audio transceivers when selecting the preferred audio codec, only adjusting the audio transceiver(s) that actually negotiated the preferred codec, the `MATTERBRIDGE_CAMERA_DISABLE_TEST_AUDIO=1` toggle, a missing ffmpeg dependency on the audio path, and not re-attaching a test-audio track on a subsequent `createAnswer`. `weriftSession.ts` is back to 100% statement/branch/function/line coverage. Also mark the audio generator's spawn-error handler, its catch block, and the unreachable `adjustedTransceivers === 0` branch in `preferAudioCodecOnTransceivers` as `v8 ignore`, mirroring the already-ignored video counterparts for the same reasons (child-process/werift-internals mocking, and a mimeType that's always found on at least one transceiver).
55
+ - [ptz camera]: Add the PTZ Camera device type. Same device type and Camera AV Stream Management/WebRtcTransportProvider wiring as the standalone `Camera` device, plus the Camera AV Settings User Level Management cluster with the MechanicalPan, MechanicalTilt and MechanicalZoom features, implementing the `MPTZSetPosition` (absolute move, rejecting out-of-range pan/tilt/zoom with a ConstraintError) and `MPTZRelativeMove` (relative move, clamped to the configured range) commands.
56
+ - [behaviors]: Add `src/behaviors/cameraAvSettingsUserLevelManagementServer.ts` with `MatterbridgeCameraAvSettingsUserLevelManagementServer`.
57
+ - [platform]: Register a PTZ Camera example device in `onStart`.
58
+ - [tests]: Add `vitest/behaviors/cameraAvSettingsUserLevelManagementServer.test.ts`; extend `vitest/module.test.ts` device-count assertions for the new device.
59
+ - [docs]: Document the PTZ Camera device type in the README.
36
60
  - [platform]: Add log of config.
37
61
  - [platform]: Add animation interval in 10 phases.
38
62
  - [doorbell]: Add use of cluster client Chime of Server Doorbell in the animation. It needs the Server Doorbell and Server Chime to be paired and a binding in Matter Server dashboard from Server Doorbell Chime client cluster to Server Chime Chime server cluster: [bindings](screenshots/bindings.png).
39
63
  - [chip-test]: Add full shell script to run the chip tests.
64
+ - [platform]: Set the software version (plugin version) and hardware version (Matterbridge version) on each device in `addDevice()` before registration, so the BasicInformation/BridgedDeviceBasicInformation Firmware and Hardware fields no longer stay stuck at the default `1.0.0`.
40
65
 
41
66
  ### Changed
42
67
 
@@ -49,6 +74,7 @@ If you like this project and find it useful, please consider giving it a star on
49
74
  - [chime]: Fix behavior when enabled is false. All chip tests pass.
50
75
  - [webrtc]: `createAnswer()` no longer calls `ensureTestAudioTrack()` when the remote offer negotiated no injectable audio codec (e.g. PCMU-only). Previously it still ran with an `undefined` codec and silently defaulted to Opus/payload type 111, injecting RTP the peer never negotiated.
51
76
  - [tests]: Fix `vitest/behaviors/webRtcTransportProviderServer.test.ts` session reuse that broke under werift 0.24.1's stricter signaling-state validation: `provideOffer`/`provideAnswer` on an "existing session" test now use dedicated sessions instead of layering a media-less fake re-offer/answer onto the same real, already-negotiated session 1, which used to silently work only because of werift 0.23.0's laxer validation.
77
+ - [webrtc]: `provideIceCandidates` applied ICE candidates one at a time and only returned once every one of them had finished (up to a 5s mDNS resolution/apply timeout, each). A browser offers one host candidate per local network interface, and an interface with no multicast route to the Matterbridge host (e.g. an inactive VPN/virtual adapter) always runs out that timeout — so candidates were stacking up to 5-10s of dead time onto every `ProvideIceCandidates` call, even though a candidate on a reachable interface routinely resolved in milliseconds. Candidates are now applied concurrently, and the command responds as soon as they're recorded instead of waiting for their application to finish (matching how `SolicitOffer`/`ProvideOffer` already invoke Offer/Answer on the peer without blocking their own response) — application results are still logged, just in the background. Diagnosed against a real Edge client.
52
78
 
53
79
  <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
54
80
 
package/README.md CHANGED
@@ -80,6 +80,18 @@ Supported by:
80
80
 
81
81
  - [Matterserver dashboard](screenshots/matterserver-camera.png)
82
82
 
83
+ ### PTZ Camera
84
+
85
+ Features:
86
+
87
+ - Same device type and Camera AV Stream Management setup as Camera (Video, Audio, Snapshot and ImageControl features, plus the WebRtcTransportProvider cluster and a WebRtcTransportRequestor client).
88
+ - Additionally exposes the Camera AV Settings User Level Management cluster with the MechanicalPan, MechanicalTilt and MechanicalZoom features, so a controller can move the camera to an absolute pan/tilt/zoom position (`MPTZSetPosition`) or by a relative delta (`MPTZRelativeMove`). The MechanicalPresets and DigitalPtz features are not part of this example.
89
+ - `MPTZSetPosition` rejects an absolute pan, tilt, or zoom value outside of the configured range with a ConstraintError.
90
+ - `MPTZRelativeMove` adds the pan/tilt/zoom delta directly to the current position, clamping the result to the configured range instead of rejecting it, since a relative move is expected to just stop at the mechanical limit.
91
+ - Configurable pan (`panMin`/`panMax`), tilt (`tiltMin`/`tiltMax`) and zoom (`zoomMax`) ranges, and initial `mptzPosition`. Defaults: pan -170° to 170°, tilt -20° to 90°, zoom 1 to 10, starting position `{ pan: 0, tilt: 0, zoom: 1 }`.
92
+ - Optional Identify cluster support, with configurable identify time and type. Set to Identify.IdentifyType.None to omit the cluster entirely.
93
+ - Configurable Power Source cluster type: Rechargeable, Replaceable, Battery, Wired, or None to omit the Power Source cluster entirely.
94
+
83
95
  ### Snapshot Camera
84
96
 
85
97
  Features:
@@ -117,6 +129,15 @@ Features:
117
129
  - Configurable Power Source cluster type on the root endpoint: Rechargeable, Replaceable, Battery, Wired, or None to omit the Power Source cluster entirely.
118
130
  - 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.
119
131
 
132
+ ### Video Doorbell
133
+
134
+ Features:
135
+
136
+ - 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 Doorbell 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). The Doorbell child is wired the same way as the standalone Doorbell device (Switch cluster with the MomentarySwitch feature only, Identify cluster always created, and the required Chime client cluster added automatically via `addChimeClient`).
137
+ - Exposes `addDoorbell()` to add further Doorbell child endpoints beyond the mandatory one, with an optional tagList for disambiguation when more than one doorbell is present.
138
+ - Configurable Power Source cluster type on the root endpoint: Rechargeable, Replaceable, Battery, Wired, or None to omit the Power Source cluster entirely.
139
+ - 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 doorbell's name, tagList, and identify configuration can be customized via the `doorbellOptions` constructor option.
140
+
120
141
  ### Intercom
121
142
 
122
143
  Features:
@@ -171,15 +192,19 @@ With both directions in place, either Intercom can call the other; a call initia
171
192
 
172
193
  The platform configuration controls WebRTC video injection with these properties:
173
194
 
174
- - `generator` is required and accepts `none`, `test`, or `webcam`. It defaults to `none`, which negotiates the video transceiver without attaching a track. `test` injects a synthetic moving test pattern, while `webcam` captures from the configured local webcam.
175
- - `webcam` is optional and has no default. It contains the OS-specific ffmpeg device identifier — e.g. `/dev/video0` on Linux (v4l2), an avfoundation index such as `0` on macOS, or a device name such as `Integrated Camera` on Windows (dshow). Selecting the `webcam` generator without this property falls back to the test pattern with a warning.
176
- - `webcamResolution` is required and accepts `640x480`, `1280x720`, or `1920x1080`. It defaults to `640x480`. The actual achievable frame rate depends on the webcam and can be much lower than 30 FPS at higher resolutions (check with `v4l2-ctl -d <device> --list-formats-ext` on Linux).
195
+ - `videoGenerator` is required and accepts `none`, `test`, `webcam`, or `rtsp`. It defaults to `none`, which negotiates the video transceiver without attaching a track. `test` injects a synthetic moving test pattern, `webcam` captures from the configured local webcam, and `rtsp` pulls from the RTSP url configured in `videoSource`.
196
+
197
+ - `videoSource` is optional and has no default. For the `webcam` generator it contains the OS-specific ffmpeg device identifier — e.g. `/dev/video0` on Linux (v4l2), an avfoundation index such as `0` on macOS, or a device name such as `Integrated Camera` on Windows (dshow). For the `rtsp` generator it instead holds the RTSP url, e.g. `rtsp://user:password@host:554/path`. Selecting the `webcam` or `rtsp` generator without this property falls back to the test pattern with a warning.
177
198
 
178
- A real client's resolution/quality picker (e.g. in Home Assistant) takes precedence over `webcamResolution`: it allocates a video stream with `CameraAvStreamManagement.VideoStreamAllocate` before soliciting or providing a WebRTC offer, and `MatterbridgeWebRtcTransportProviderServer` looks up that stream's `maxResolution` to select the webcam capture resolution for the session. `webcamResolution` is used when no matching allocated stream is found, or when the requested resolution isn't one of the three supported above.
199
+ - `videoResolution` is required and accepts `auto`, `640x480`, `1280x720`, or `1920x1080`. It defaults to `auto`, which uses the resolution requested by the controller for the session (see below), falling back to `640x480` when no request is available or it names an unsupported resolution. A fixed resolution always wins over what the controller requested. The actual achievable frame rate depends on the webcam and can be much lower than 30 FPS at higher resolutions (check with `v4l2-ctl -d <device> --list-formats-ext` on Linux).
200
+
201
+ - `videoBitrate` is required and accepts a number (the target encoder bitrate in kbps). It defaults to `1000`. It applies to the `webcam` and `rtsp` sources only; the `test` pattern is always encoded at a fixed 1000 kbps regardless of this setting.
202
+
203
+ With `videoResolution: "auto"`, a real client's resolution/quality picker (e.g. in Home Assistant) drives the capture/output resolution: it allocates a video stream with `CameraAvStreamManagement.VideoStreamAllocate` before soliciting or providing a WebRTC offer, and `MatterbridgeWebRtcTransportProviderServer` looks up that stream's `maxResolution` to select the resolution for the session. For `webcam` this is the capture resolution passed to ffmpeg; for `rtsp` the camera keeps streaming at its own native resolution and ffmpeg scales it to match.
179
204
 
180
205
  Requires `ffmpeg` to be installed. The resolver checks the system command and common installation directories on Linux, macOS, and Windows.
181
206
 
182
- Use ffmpeg itself to list the available capture devices and find the right value for `webcam`:
207
+ Use ffmpeg itself to list the available capture devices and find the right value for `videoSource`:
183
208
 
184
209
  - Linux (v4l2): `v4l2-ctl --list-devices` (from `v4l-utils`), or `ls /dev/video*`.
185
210
  - macOS (avfoundation): `ffmpeg -f avfoundation -list_devices true -i dummy` — video devices are listed with their index, e.g. `[0] FaceTime HD Camera`; use that index (e.g. `0`) as the device value.
@@ -189,19 +214,40 @@ Example configuration for a real Linux webcam at 720p:
189
214
 
190
215
  ```json
191
216
  {
192
- "generator": "webcam",
193
- "webcam": "/dev/video0",
194
- "webcamResolution": "1280x720"
217
+ "videoGenerator": "webcam",
218
+ "videoSource": "/dev/video0",
219
+ "videoResolution": "1280x720"
195
220
  }
196
221
  ```
197
222
 
198
- Example, capturing from a real Windows webcam at 720p:
223
+ Example, capturing from a real Windows webcam at 720p with a higher bitrate:
199
224
 
200
225
  ```json
201
226
  {
202
- "generator": "webcam",
203
- "webcam": "Integrated Camera",
204
- "webcamResolution": "1280x720"
227
+ "videoGenerator": "webcam",
228
+ "videoSource": "Integrated Camera",
229
+ "videoResolution": "1280x720",
230
+ "videoBitrate": 2000
231
+ }
232
+ ```
233
+
234
+ Example, pulling from a real RTSP camera, scaled to a fixed 1280x720 and re-encoded at `videoBitrate` (the camera's own frame rate is kept):
235
+
236
+ ```json
237
+ {
238
+ "videoGenerator": "rtsp",
239
+ "videoSource": "rtsp://admin:password@192.168.1.100:554/ch1/main",
240
+ "videoResolution": "1280x720"
241
+ }
242
+ ```
243
+
244
+ Example, pulling from a real RTSP camera and scaling to whatever resolution the controller requests for the session:
245
+
246
+ ```json
247
+ {
248
+ "videoGenerator": "rtsp",
249
+ "videoSource": "rtsp://admin:password@192.168.1.100:554/ch1/main",
250
+ "videoResolution": "auto"
205
251
  }
206
252
  ```
207
253
 
@@ -219,6 +265,12 @@ The fix is on the browser side, not in this plugin: disable mDNS obfuscation of
219
265
  - **Chrome**: the same flag is at `chrome://flags/#enable-webrtc-hide-local-ips-with-mdns`.
220
266
  - **Firefox**: open `about:config` and set `media.peerconnection.ice.obfuscate_host_addresses` to `false`. Note this alone may not be enough — per the Firefox limitation above, Firefox can still fall back to a useless link-local address on a non-secure-context page even with this preference disabled, so the page also needs to be served over HTTPS or via `localhost`.
221
267
 
268
+ ### Known limitation: a client with an unreachable network interface can slow down ICE negotiation logging
269
+
270
+ A browser gathers one host ICE candidate per local network interface it sees, mDNS-obfuscated or not. When one of those interfaces has no multicast route to the machine running Matterbridge — a disconnected VPN adapter, a Hyper-V/WSL virtual switch, a second NIC on an unrelated subnet — werift-ice's mDNS resolution for that candidate's `*.local` name can never succeed, and takes the full per-candidate apply timeout (5s, see `ICE_CANDIDATE_APPLY_TIMEOUT_MS` in `src/behaviors/webRtcTransportProviderServer.ts`) to give up on it.
271
+
272
+ Candidates are applied concurrently, not one after another, so this doesn't compound: a candidate on a reachable interface succeeds in a few milliseconds without waiting behind a sibling candidate that's doomed to time out. `provideIceCandidates` also responds to the peer as soon as the candidates are recorded, rather than waiting for their application to finish — the same reason `SolicitOffer`/`ProvideOffer` already invoke Offer/Answer on the peer without blocking their own response — so an unreachable interface no longer delays the Matter command itself, only the background log entry for that specific candidate. If a stream is slow to start or intermittently fails specifically on a machine with multiple network interfaces/VPNs, this is the mechanism to check first (grep the Matterbridge log for `ICE candidate apply timeout`).
273
+
222
274
  ## Werift integration test
223
275
 
224
276
  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`.
@@ -0,0 +1,37 @@
1
+ import { MatterbridgeServer } from 'matterbridge/behaviors';
2
+ import { CameraAvSettingsUserLevelManagementServer } from 'matterbridge/matter/behaviors';
3
+ import { CameraAvSettingsUserLevelManagement } from 'matterbridge/matter/clusters';
4
+ import { Status, StatusResponseError } from 'matterbridge/matter/types';
5
+ function clamp(value, min, max) {
6
+ return Math.min(Math.max(value, min), max);
7
+ }
8
+ export class MatterbridgeCameraAvSettingsUserLevelManagementServer extends CameraAvSettingsUserLevelManagementServer.with(CameraAvSettingsUserLevelManagement.Feature.MechanicalPan, CameraAvSettingsUserLevelManagement.Feature.MechanicalTilt, CameraAvSettingsUserLevelManagement.Feature.MechanicalZoom) {
9
+ mptzSetPosition(request) {
10
+ const device = this.endpoint.stateOf(MatterbridgeServer);
11
+ const { pan, tilt, zoom } = request;
12
+ if (pan !== undefined && (pan < this.state.panMin || pan > this.state.panMax)) {
13
+ throw new StatusResponseError(`Pan ${pan} is outside of the supported range [${this.state.panMin}, ${this.state.panMax}]`, Status.ConstraintError);
14
+ }
15
+ if (tilt !== undefined && (tilt < this.state.tiltMin || tilt > this.state.tiltMax)) {
16
+ throw new StatusResponseError(`Tilt ${tilt} is outside of the supported range [${this.state.tiltMin}, ${this.state.tiltMax}]`, Status.ConstraintError);
17
+ }
18
+ if (zoom !== undefined && (zoom < 1 || zoom > this.state.zoomMax)) {
19
+ throw new StatusResponseError(`Zoom ${zoom} is outside of the supported range [1, ${this.state.zoomMax}]`, Status.ConstraintError);
20
+ }
21
+ this.state.mptzPosition = {
22
+ pan: pan ?? this.state.mptzPosition.pan,
23
+ tilt: tilt ?? this.state.mptzPosition.tilt,
24
+ zoom: zoom ?? this.state.mptzPosition.zoom,
25
+ };
26
+ device.log.info(`Set mechanical PTZ position to pan ${this.state.mptzPosition.pan}°, tilt ${this.state.mptzPosition.tilt}°, zoom ${this.state.mptzPosition.zoom} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
27
+ }
28
+ mptzRelativeMove(request) {
29
+ const device = this.endpoint.stateOf(MatterbridgeServer);
30
+ const current = this.state.mptzPosition;
31
+ const pan = request.panDelta === undefined ? current.pan : clamp((current.pan ?? 0) + request.panDelta, this.state.panMin, this.state.panMax);
32
+ const tilt = request.tiltDelta === undefined ? current.tilt : clamp((current.tilt ?? 0) + request.tiltDelta, this.state.tiltMin, this.state.tiltMax);
33
+ const zoom = request.zoomDelta === undefined ? current.zoom : clamp((current.zoom ?? 1) + request.zoomDelta, 1, this.state.zoomMax);
34
+ this.state.mptzPosition = { pan, tilt, zoom };
35
+ device.log.info(`Moved mechanical PTZ position by pan ${request.panDelta ?? 0}°, tilt ${request.tiltDelta ?? 0}°, zoom ${request.zoomDelta ?? 0} to pan ${pan}°, tilt ${tilt}°, zoom ${zoom} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
36
+ }
37
+ }
@@ -218,27 +218,36 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
218
218
  if (!this.state.currentSessions.some((session) => session.id === request.webRtcSessionId)) {
219
219
  throw new StatusResponseError(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: webRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
220
220
  }
221
- device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: received ${request.iceCandidates.length} ICE candidate(s) for session ${request.webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
221
+ const endpointLabel = `${this.endpoint.maybeId}.${this.endpoint.maybeNumber}`;
222
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: received ${request.iceCandidates.length} ICE candidate(s) for session ${request.webRtcSessionId} (endpoint ${endpointLabel})`);
222
223
  const webRtcPeer = this.internal.sessions.get(request.webRtcSessionId);
223
224
  if (webRtcPeer) {
224
- for (const [index, candidate] of request.iceCandidates.entries()) {
225
+ void Promise.allSettled(request.iceCandidates.map(async (candidate, index) => {
225
226
  const startedAt = Date.now();
226
227
  device.log.debug(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: applying ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
227
228
  `(mid=${candidate.sdpMid ?? 'null'}, mLine=${candidate.sdpmLineIndex ?? 'null'}, endOfCandidates=${candidate.candidate.trim() === ''}) ` +
228
- `(endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
229
+ `(endpoint ${endpointLabel})`);
229
230
  try {
230
- await Promise.race([
231
- webRtcPeer.addIceCandidate(candidate.candidate, candidate.sdpMid, candidate.sdpmLineIndex),
232
- new Promise((_resolve, reject) => setTimeout(() => reject(new Error(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: ICE candidate apply timeout after ${ICE_CANDIDATE_APPLY_TIMEOUT_MS}ms`)), ICE_CANDIDATE_APPLY_TIMEOUT_MS)),
233
- ]);
231
+ let timeout;
232
+ try {
233
+ await Promise.race([
234
+ webRtcPeer.addIceCandidate(candidate.candidate, candidate.sdpMid, candidate.sdpmLineIndex),
235
+ new Promise((resolve, reject) => {
236
+ timeout = setTimeout(() => reject(new Error(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: ICE candidate apply timeout after ${ICE_CANDIDATE_APPLY_TIMEOUT_MS}ms`)), ICE_CANDIDATE_APPLY_TIMEOUT_MS);
237
+ }),
238
+ ]);
239
+ }
240
+ finally {
241
+ clearTimeout(timeout);
242
+ }
234
243
  device.log.debug(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: applied ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
235
- `in ${Date.now() - startedAt}ms (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
244
+ `in ${Date.now() - startedAt}ms (endpoint ${endpointLabel})`);
236
245
  }
237
246
  catch (error) {
238
247
  device.log.warn(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: failed ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} after ${Date.now() - startedAt}ms ` +
239
- `(endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}): ${String(error)}`);
248
+ `(endpoint ${endpointLabel}): ${String(error)}`);
240
249
  }
241
- }
250
+ }));
242
251
  }
243
252
  }
244
253
  async endSession(request) {
@@ -1,16 +1,17 @@
1
1
  import { camera, MatterbridgeEndpoint, powerSource } from 'matterbridge';
2
- import { CameraAvStreamManagement, Identify } from 'matterbridge/matter/clusters';
2
+ import { CameraAvSettingsUserLevelManagement, CameraAvStreamManagement, Identify } from 'matterbridge/matter/clusters';
3
3
  import { StreamUsage, ThreeLevelAuto } from 'matterbridge/matter/types';
4
+ import { MatterbridgeCameraAvSettingsUserLevelManagementServer } from '../behaviors/cameraAvSettingsUserLevelManagementServer.js';
4
5
  import { MatterbridgeCameraAvStreamManagementServer } from '../behaviors/cameraAvStreamManagementServer.js';
5
6
  import { addWebRtcTransportRequestorClient } from '../behaviors/clients.js';
6
7
  import { MatterbridgeWebRtcTransportProviderServer } from '../behaviors/webRtcTransportProviderServer.js';
7
8
  export class Camera extends MatterbridgeEndpoint {
8
9
  constructor(name, serial, options = {}) {
9
- const { identifyTime = 0, identifyType = Identify.IdentifyType.None, powerSourceType = 'Wired', 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 = [
10
+ const { identifyTime = 0, identifyType = Identify.IdentifyType.None, powerSourceType = 'Wired', ptz = false, 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 = [
10
11
  { resolution: { width: 640, height: 480 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
11
12
  { resolution: { width: 1280, height: 720 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
12
13
  { resolution: { width: 1920, height: 1080 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
13
- ], allocatedSnapshotStreams = [], id, number, tagList, mode, } = options;
14
+ ], allocatedSnapshotStreams = [], panMin = -170, panMax = 170, tiltMin = -20, tiltMax = 90, zoomMax = 10, mptzPosition = { pan: 0, tilt: 0, zoom: 1 }, id, number, tagList, mode, } = options;
14
15
  super(powerSourceType === 'None' ? [camera] : [camera, powerSource], { id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`, number, tagList, mode });
15
16
  if (identifyType !== Identify.IdentifyType.None) {
16
17
  this.createDefaultIdentifyClusterServer(identifyTime, identifyType);
@@ -49,6 +50,8 @@ export class Camera extends MatterbridgeEndpoint {
49
50
  snapshotCapabilities,
50
51
  allocatedSnapshotStreams,
51
52
  });
53
+ if (ptz)
54
+ createDefaultCameraAvSettingsUserLevelManagementClusterServer(this, { panMin, panMax, tiltMin, tiltMax, zoomMax, mptzPosition });
52
55
  createDefaultWebRtcTransportProviderClusterServer(this);
53
56
  addWebRtcTransportRequestorClient(this);
54
57
  this.addRequiredClusters();
@@ -73,6 +76,13 @@ export function createDefaultCameraAvStreamManagementClusterServer(endpoint, opt
73
76
  });
74
77
  return endpoint;
75
78
  }
79
+ export function createDefaultCameraAvSettingsUserLevelManagementClusterServer(endpoint, options) {
80
+ endpoint.behaviors.require(MatterbridgeCameraAvSettingsUserLevelManagementServer.with(CameraAvSettingsUserLevelManagement.Feature.MechanicalPan, CameraAvSettingsUserLevelManagement.Feature.MechanicalTilt, CameraAvSettingsUserLevelManagement.Feature.MechanicalZoom), {
81
+ ...options,
82
+ movementState: CameraAvSettingsUserLevelManagement.PhysicalMovement.Idle,
83
+ });
84
+ return endpoint;
85
+ }
76
86
  export function createDefaultWebRtcTransportProviderClusterServer(endpoint) {
77
87
  endpoint.behaviors.require(MatterbridgeWebRtcTransportProviderServer, { currentSessions: [] });
78
88
  return endpoint;
@@ -0,0 +1,76 @@
1
+ import { camera, doorbell, MatterbridgeEndpoint, powerSource, videoDoorbell } 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 { addChimeClient, addWebRtcTransportRequestorClient } from '../behaviors/clients.js';
6
+ import { createDefaultCameraAvStreamManagementClusterServer, createDefaultWebRtcTransportProviderClusterServer } from './camera.js';
7
+ export class VideoDoorbell extends MatterbridgeEndpoint {
8
+ constructor(name, serial, options = {}) {
9
+ const { powerSourceType = 'Wired', cameraOptions = {}, doorbellOptions = {}, id, number, tagList, mode } = options;
10
+ super(powerSourceType === 'None' ? [videoDoorbell] : [videoDoorbell, powerSource], {
11
+ id: id ?? `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}`,
12
+ number,
13
+ tagList,
14
+ mode,
15
+ });
16
+ this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Matterbridge Video Doorbell');
17
+ switch (powerSourceType) {
18
+ case 'Rechargeable':
19
+ this.createDefaultPowerSourceRechargeableBatteryClusterServer();
20
+ break;
21
+ case 'Replaceable':
22
+ this.createDefaultPowerSourceReplaceableBatteryClusterServer();
23
+ break;
24
+ case 'Battery':
25
+ this.createDefaultPowerSourceBatteryClusterServer();
26
+ break;
27
+ case 'Wired':
28
+ this.createDefaultPowerSourceWiredClusterServer();
29
+ break;
30
+ case 'None':
31
+ break;
32
+ }
33
+ fireAndForget(this.addFixedLabel('composed', 'VideoDoorbell'), this.log, 'Error adding composed label to video doorbell');
34
+ this.addRequiredClusters();
35
+ const { identifyTime: cameraIdentifyTime = 0, identifyType: cameraIdentifyType = 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 = [
36
+ { resolution: { width: 640, height: 480 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
37
+ { resolution: { width: 1280, height: 720 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
38
+ { resolution: { width: 1920, height: 1080 }, maxFrameRate: 10, imageCodec: CameraAvStreamManagement.ImageCodec.Jpeg, requiresEncodedPixels: false },
39
+ ], allocatedSnapshotStreams = [], } = cameraOptions;
40
+ const cameraChild = this.addChildDeviceType('Camera', camera, {});
41
+ cameraChild.log.logName = 'Camera';
42
+ if (cameraIdentifyType !== Identify.IdentifyType.None) {
43
+ cameraChild.createDefaultIdentifyClusterServer(cameraIdentifyTime, cameraIdentifyType);
44
+ }
45
+ createDefaultCameraAvStreamManagementClusterServer(cameraChild, {
46
+ maxContentBufferSize,
47
+ maxNetworkBandwidth,
48
+ supportedStreamUsages,
49
+ streamUsagePriorities,
50
+ maxConcurrentEncoders,
51
+ maxEncodedPixelRate,
52
+ videoSensorParams,
53
+ minViewportResolution,
54
+ rateDistortionTradeOffPoints,
55
+ currentFrameRate,
56
+ viewport,
57
+ microphoneCapabilities,
58
+ snapshotCapabilities,
59
+ allocatedSnapshotStreams,
60
+ });
61
+ createDefaultWebRtcTransportProviderClusterServer(cameraChild);
62
+ addWebRtcTransportRequestorClient(cameraChild);
63
+ cameraChild.addRequiredClusters();
64
+ const { name: doorbellName = 'Doorbell', tagList: doorbellTagList = [], identifyTime = 0, identifyType = Identify.IdentifyType.None } = doorbellOptions;
65
+ this.addDoorbell(doorbellName, doorbellTagList, identifyTime, identifyType);
66
+ }
67
+ addDoorbell(name, tagList = [], identifyTime = 0, identifyType = Identify.IdentifyType.None) {
68
+ const doorbellChild = this.addChildDeviceType(name, doorbell, tagList.length > 0 ? { tagList } : {});
69
+ doorbellChild.log.logName = name;
70
+ doorbellChild.createDefaultIdentifyClusterServer(identifyTime, identifyType);
71
+ doorbellChild.createDefaultMomentarySwitchClusterServer();
72
+ addChimeClient(doorbellChild);
73
+ doorbellChild.addRequiredClusters();
74
+ return doorbellChild;
75
+ }
76
+ }
package/dist/module.js CHANGED
@@ -3,8 +3,10 @@ import { inspect } from 'node:util';
3
3
  import { MatterbridgeDynamicPlatform } from 'matterbridge';
4
4
  import { MatterbridgeBindingServer } from 'matterbridge/behaviors';
5
5
  import { RESET } from 'matterbridge/logger';
6
+ import { UINT16_MAX, UINT32_MAX } from 'matterbridge/matter';
6
7
  import { ChimeClient } from 'matterbridge/matter/behaviors';
7
8
  import { Identify, Chime as ChimeCluster, PowerSource } from 'matterbridge/matter/clusters';
9
+ import { isValidNumber, parseVersionString } from 'matterbridge/utils';
8
10
  import { AudioDoorbell } from './devices/audioDoorbell.js';
9
11
  import { Camera } from './devices/camera.js';
10
12
  import { Chime } from './devices/chime.js';
@@ -12,6 +14,7 @@ import { Doorbell } from './devices/doorbell.js';
12
14
  import { FloodlightCamera } from './devices/floodlightCamera.js';
13
15
  import { Intercom } from './devices/intercom.js';
14
16
  import { SnapshotCamera } from './devices/snapshotCamera.js';
17
+ import { VideoDoorbell } from './devices/videoDoorbell.js';
15
18
  export default function initializePlugin(matterbridge, log, config) {
16
19
  return new ExampleMatterbridgeCameraPlatform(matterbridge, log, config);
17
20
  }
@@ -28,25 +31,25 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
28
31
  this.log.info(`Initializing platform ${this.config.name}...`);
29
32
  this.config.whiteList ??= [];
30
33
  this.config.blackList ??= [];
31
- this.config.generator ??= 'none';
32
- this.config.webcamResolution ??= '640x480';
33
- this.config.webcamBitrate ??= 1000;
34
+ this.config.videoGenerator ??= 'none';
35
+ this.config.videoResolution ??= 'auto';
36
+ this.config.videoBitrate ??= 1000;
34
37
  this.config.animationInterval ??= 60;
35
38
  this.config.debug ??= false;
36
39
  this.config.unregisterOnShutdown ??= false;
37
- process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE = this.config.generator;
38
- if (this.config.webcam === undefined)
39
- delete process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE;
40
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE = this.config.videoGenerator;
41
+ if (this.config.videoSource === undefined)
42
+ delete process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE;
40
43
  else
41
- process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE = this.config.webcam;
42
- process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION = this.config.webcamResolution;
43
- process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE = String(this.config.webcamBitrate);
44
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE = this.config.videoSource;
45
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION = this.config.videoResolution;
46
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE = String(this.config.videoBitrate);
44
47
  this.log.debug(`Platform ${this.config.name} config:\n${RESET}${inspect(this.config, { depth: 10, colors: true })}`);
45
48
  this.log.debug(`Platform ${this.config.name} environment variables:\n${RESET}${inspect({
46
49
  MATTERBRIDGE_CAMERA_VIDEO_SOURCE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE,
47
- MATTERBRIDGE_CAMERA_WEBCAM_DEVICE: process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE,
48
- MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION: process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION,
49
- MATTERBRIDGE_CAMERA_WEBCAM_BITRATE: process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE,
50
+ MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE,
51
+ MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION: process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION,
52
+ MATTERBRIDGE_CAMERA_VIDEO_BITRATE: process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE,
50
53
  }, { depth: 10, colors: true })}`);
51
54
  this.log.info(`Platform ${this.config.name} initialized successfully`);
52
55
  }
@@ -87,6 +90,13 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
87
90
  await this.addDevice(exampleSnapshotCamera);
88
91
  const exampleCamera = new Camera('Camera', 'CAMERA-001');
89
92
  await this.addDevice(exampleCamera);
93
+ const examplePtzCamera = new Camera('PTZ Camera', 'PTZCAMERA-001', {
94
+ identifyTime: 5,
95
+ identifyType: Identify.IdentifyType.VisibleIndicator,
96
+ powerSourceType: 'Wired',
97
+ ptz: true,
98
+ });
99
+ await this.addDevice(examplePtzCamera);
90
100
  const exampleFloodlightCamera = new FloodlightCamera('Floodlight Camera', 'FLOODLIGHTCAMERA-001', {
91
101
  powerSourceType: 'Wired',
92
102
  cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator },
@@ -99,6 +109,11 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
99
109
  powerSourceType: 'Replaceable',
100
110
  });
101
111
  await this.addDevice(exampleIntercom1);
112
+ const exampleVideoDoorbell = new VideoDoorbell('Video Doorbell', 'VIDEODOORBELL-001', {
113
+ powerSourceType: 'Wired',
114
+ cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator },
115
+ });
116
+ await this.addDevice(exampleVideoDoorbell);
102
117
  const serverChime = new Chime('Server Chime', 'SERVER-CHIME-001', {
103
118
  identifyTime: 5,
104
119
  identifyType: Identify.IdentifyType.AudibleBeep,
@@ -128,9 +143,6 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
128
143
  const exampleChime = this.getDeviceById('Chime-CHIME-001');
129
144
  await exampleChime?.setCluster(PowerSource, { batChargeLevel: PowerSource.BatChargeLevel.Ok, batPercentRemaining: 150, batQuantity: 2, batReplacementDescription: 'AA' }, exampleChime.log);
130
145
  await exampleChime?.setCluster(ChimeCluster, { enabled: true, selectedChime: 0 }, exampleChime.log);
131
- const exampleIntercom1 = this.getDeviceById('Intercom1-INTERCOM1-001');
132
- if (!exampleIntercom1)
133
- throw new Error(`Intercom device not found. Please ensure the device is registered before configuration.`);
134
146
  const serverChime = this.getDeviceById('ServerChime-SERVER-CHIME-001');
135
147
  await serverChime?.setCluster(PowerSource, { batChargeLevel: PowerSource.BatChargeLevel.Ok, batPercentRemaining: 150, batVoltage: 2900, batReplacementNeeded: false }, serverChime.log);
136
148
  await serverChime?.setCluster(ChimeCluster, { enabled: true, selectedChime: 0 }, serverChime.log);
@@ -142,6 +154,14 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
142
154
  }
143
155
  async addDevice(device) {
144
156
  if (device.serialNumber && device.deviceName) {
157
+ device.softwareVersion = parseVersionString(this.version);
158
+ device.softwareVersionString = this.version === '' ? 'Unknown' : this.version;
159
+ device.hardwareVersion = parseVersionString(this.matterbridge.matterbridgeVersion);
160
+ device.hardwareVersionString = this.matterbridge.matterbridgeVersion;
161
+ device.softwareVersion = isValidNumber(device.softwareVersion, 0, UINT32_MAX) ? device.softwareVersion : undefined;
162
+ device.softwareVersionString = device.softwareVersionString.slice(0, 64);
163
+ device.hardwareVersion = isValidNumber(device.hardwareVersion, 0, UINT16_MAX) ? device.hardwareVersion : undefined;
164
+ device.hardwareVersionString = device.hardwareVersionString.slice(0, 64);
145
165
  this.setSelectDevice(device.serialNumber, device.deviceName);
146
166
  if (this.validateDevice([device.deviceName, device.serialNumber]))
147
167
  await this.registerDevice(device);
@@ -169,38 +169,39 @@ export class WeriftWebRtcSession {
169
169
  this.log.debug('No preferred injectable audio codec (Opus) negotiated on any audio transceiver');
170
170
  return undefined;
171
171
  }
172
- static SUPPORTED_WEBCAM_RESOLUTIONS = ['640x480', '1280x720', '1920x1080'];
172
+ static SUPPORTED_VIDEO_RESOLUTIONS = ['640x480', '1280x720', '1920x1080'];
173
173
  static DEFAULT_BITRATE_KBPS = 1000;
174
- getConfiguredWebcamBitrate() {
175
- const configured = process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE;
174
+ getConfiguredVideoBitrate() {
175
+ const configured = process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE;
176
176
  if (!configured)
177
177
  return WeriftWebRtcSession.DEFAULT_BITRATE_KBPS;
178
178
  const bitrateKbps = Number(configured);
179
179
  if (!Number.isFinite(bitrateKbps) || bitrateKbps <= 0) {
180
- this.log.warn(`Invalid MATTERBRIDGE_CAMERA_WEBCAM_BITRATE "${configured}"; falling back to ${WeriftWebRtcSession.DEFAULT_BITRATE_KBPS}kbps`);
180
+ this.log.warn(`Invalid MATTERBRIDGE_CAMERA_VIDEO_BITRATE "${configured}"; falling back to ${WeriftWebRtcSession.DEFAULT_BITRATE_KBPS}kbps`);
181
181
  return WeriftWebRtcSession.DEFAULT_BITRATE_KBPS;
182
182
  }
183
183
  return bitrateKbps;
184
184
  }
185
- getConfiguredWebcamResolution(requestedResolution) {
186
- const [defaultResolution] = WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS;
185
+ getConfiguredVideoResolution(requestedResolution) {
186
+ const [defaultResolution] = WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS;
187
+ const configured = process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION;
188
+ if (configured && configured !== 'auto') {
189
+ if (WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.includes(configured)) {
190
+ this.log.debug(`Using configured MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION ${configured}`);
191
+ return configured;
192
+ }
193
+ this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION "${configured}" (supported: ${WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.join(', ')}, auto); falling back to ${defaultResolution}`);
194
+ return defaultResolution;
195
+ }
187
196
  if (requestedResolution) {
188
- if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requestedResolution)) {
189
- this.log.debug(`Using requested webcam capture resolution ${requestedResolution}`);
197
+ if (WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.includes(requestedResolution)) {
198
+ this.log.debug(`Using requested video stream resolution ${requestedResolution} (MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION=auto)`);
190
199
  return requestedResolution;
191
200
  }
192
- this.log.warn(`Requested video stream resolution "${requestedResolution}" is not supported for webcam capture (supported: ${WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.join(', ')}); falling back to MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION`);
193
- }
194
- const requested = process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION;
195
- if (!requested) {
196
- this.log.debug(`Using default webcam capture resolution ${defaultResolution}`);
201
+ this.log.warn(`Requested video stream resolution "${requestedResolution}" is not supported (supported: ${WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.join(', ')}); falling back to ${defaultResolution}`);
197
202
  return defaultResolution;
198
203
  }
199
- if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requested)) {
200
- this.log.debug(`Using MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION ${requested}`);
201
- return requested;
202
- }
203
- this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION "${requested}" (supported: ${WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.join(', ')}); falling back to ${defaultResolution}`);
204
+ this.log.debug(`No requested video stream resolution available; using default ${defaultResolution} (MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION=auto)`);
204
205
  return defaultResolution;
205
206
  }
206
207
  getConfiguredVideoSource() {
@@ -209,9 +210,10 @@ export class WeriftWebRtcSession {
209
210
  case 'none':
210
211
  case 'test':
211
212
  case 'webcam':
213
+ case 'rtsp':
212
214
  return source;
213
215
  default:
214
- this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_SOURCE "${source}" (supported: test, webcam, none); falling back to none`);
216
+ this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_SOURCE "${source}" (supported: test, webcam, rtsp, none); falling back to none`);
215
217
  return 'none';
216
218
  }
217
219
  }
@@ -225,13 +227,18 @@ export class WeriftWebRtcSession {
225
227
  this.log.debug(`Test pattern params: resolution=640x480, description="${testPatternInput.description}", bitrateKbps=${testPatternInput.bitrateKbps}`);
226
228
  return testPatternInput;
227
229
  }
228
- const device = process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE;
230
+ const device = process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE;
229
231
  if (!device) {
230
- this.log.warn('MATTERBRIDGE_CAMERA_VIDEO_SOURCE=webcam requires MATTERBRIDGE_CAMERA_WEBCAM_DEVICE to be set; falling back to the synthetic test video');
232
+ this.log.warn(`MATTERBRIDGE_CAMERA_VIDEO_SOURCE=${videoSource} requires MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE to be set; falling back to the synthetic test video`);
231
233
  return testPatternInput;
232
234
  }
233
- const resolution = process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION ?? this.getConfiguredWebcamResolution(requestedResolution);
234
- const bitrateKbps = this.getConfiguredWebcamBitrate();
235
+ const resolution = this.getConfiguredVideoResolution(requestedResolution);
236
+ const bitrateKbps = this.getConfiguredVideoBitrate();
237
+ if (videoSource === 'rtsp') {
238
+ const description = `RTSP camera (${device}, ${resolution})`;
239
+ this.log.debug(`RTSP capture params: url=${device}, resolution=${resolution}, description="${description}", bitrateKbps=${bitrateKbps}`);
240
+ return { args: ['-rtsp_transport', 'tcp', '-i', device, '-vf', `scale=${resolution.replace('x', ':')}`], description, bitrateKbps };
241
+ }
235
242
  const description = `local webcam (${device}, ${resolution})`;
236
243
  this.log.debug(`Webcam capture params: device=${device}, resolution=${resolution}, description="${description}", bitrateKbps=${bitrateKbps}`);
237
244
  switch (process.platform) {
@@ -3,9 +3,9 @@
3
3
  "type": "DynamicPlatform",
4
4
  "whiteList": [],
5
5
  "blackList": [],
6
- "generator": "none",
7
- "webcamResolution": "640x480",
8
- "webcamBitrate": 1000,
6
+ "videoGenerator": "none",
7
+ "videoResolution": "auto",
8
+ "videoBitrate": 1000,
9
9
  "animationInterval": 60,
10
10
  "debug": false,
11
11
  "unregisterOnShutdown": false
@@ -2,7 +2,7 @@
2
2
  "title": "Matterbridge example camera plugin",
3
3
  "description": "matterbridge-example-camera v. 1.0.0 by https://github.com/Luligu",
4
4
  "type": "object",
5
- "required": ["generator", "webcamResolution"],
5
+ "required": ["videoGenerator", "videoResolution"],
6
6
  "properties": {
7
7
  "name": {
8
8
  "description": "Plugin Name",
@@ -42,28 +42,28 @@
42
42
  "type": "number",
43
43
  "default": 60
44
44
  },
45
- "generator": {
45
+ "videoGenerator": {
46
46
  "title": "Video Generator",
47
- "description": "Select the WebRTC video source: none disables track injection, test generates a synthetic moving test pattern, and webcam captures from the configured local webcam.",
47
+ "description": "Select the WebRTC video generator: none disables track injection, test generates a synthetic moving test pattern, webcam captures from the configured local webcam, and rtsp pulls from the RTSP url configured in Video Source.",
48
48
  "type": "string",
49
- "enum": ["none", "test", "webcam"],
49
+ "enum": ["none", "test", "webcam", "rtsp"],
50
50
  "default": "none"
51
51
  },
52
- "webcam": {
53
- "title": "Webcam Device",
54
- "description": "OS-specific ffmpeg webcam identifier, such as /dev/video0 on Linux, 0 on macOS, or Integrated Camera on Windows.",
52
+ "videoSource": {
53
+ "title": "Video Source",
54
+ "description": "OS-specific ffmpeg webcam identifier, such as /dev/video0 on Linux, 0 on macOS, or Integrated Camera on Windows. When Video Generator is rtsp, this holds the RTSP url instead, e.g. rtsp://user:password@host:554/path.",
55
55
  "type": "string"
56
56
  },
57
- "webcamResolution": {
58
- "title": "Webcam Resolution",
59
- "description": "Resolution used when capturing from the configured webcam.",
57
+ "videoResolution": {
58
+ "title": "Video Resolution",
59
+ "description": "Resolution used when capturing from the configured webcam or RTSP camera. auto uses the resolution requested by the controller (the allocated video stream's maxResolution) instead of a fixed value.",
60
60
  "type": "string",
61
- "enum": ["640x480", "1280x720", "1920x1080"],
62
- "default": "640x480"
61
+ "enum": ["auto", "640x480", "1280x720", "1920x1080"],
62
+ "default": "auto"
63
63
  },
64
- "webcamBitrate": {
65
- "title": "Webcam Bitrate",
66
- "description": "Target encoder bitrate (kbps) used when capturing from the configured webcam, regardless of resolution.",
64
+ "videoBitrate": {
65
+ "title": "Video Bitrate",
66
+ "description": "Target encoder bitrate (kbps) used when capturing from the configured webcam or RTSP camera, regardless of resolution.",
67
67
  "type": "number",
68
68
  "default": 1000
69
69
  },
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.7-dev-20260725-bcbe2ca",
3
+ "version": "0.0.8-dev-20260726-2ea4814",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "matterbridge-example-camera",
9
- "version": "0.0.7-dev-20260725-bcbe2ca",
9
+ "version": "0.0.8-dev-20260726-2ea4814",
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.7-dev-20260725-bcbe2ca",
3
+ "version": "0.0.8-dev-20260726-2ea4814",
4
4
  "description": "Matterbridge camera example plugin",
5
5
  "author": "https://github.com/Luligu",
6
6
  "license": "Apache-2.0",