matterbridge-example-camera 0.0.8-dev-20260726-2ea4814 → 0.0.8-dev-20260726-dffb00d

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
@@ -36,12 +36,14 @@ If you like this project and find it useful, please consider giving it a star on
36
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
37
  - [platform]: Rename the `generator` config property to `videoGenerator`.
38
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.
39
+ - [docs]: Document the `rtsp` video generator, the renamed config properties, the `auto`/fixed `videoResolution` precedence, and the previously undocumented `videoBitrate` property (with suggested per-resolution values) in the README and schema, with example configurations.
40
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
+ - [webrtc]: Add `WeriftWebRtcSession.closeAll()`, a static helper that closes every active session (peer connection plus any injected ffmpeg generators). `onShutdown` now calls it so a graceful platform shutdown cleans up leftover WebRTC sessions itself instead of relying solely on the `process.on('exit', ...)` fallback.
42
+ - [tests]: Add `closeAll` coverage in `vitest/webrtc/weriftSession.test.ts`, covering closing all active sessions and the no-active-sessions case.
41
43
 
42
44
  ### Fixed
43
45
 
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.
46
+ - [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` at the time of this fix, before `videoResolution` defaulted to `auto`), the fallback — and therefore the requested resolution — was never reached.
45
47
 
46
48
  ## [0.0.7] - 2026-07-25
47
49
 
package/README.md CHANGED
@@ -186,7 +186,7 @@ So, to let either Intercom 1 or Intercom 2 start a call, on the fabric they shar
186
186
 
187
187
  With both directions in place, either Intercom can call the other; a call initiated the other way only needs its own binding/ACL pair, already covered above since both were set up symmetrically.
188
188
 
189
- ## WebRTC test video injection
189
+ ## WebRTC video injection
190
190
 
191
191
  `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.
192
192
 
@@ -198,7 +198,7 @@ The platform configuration controls WebRTC video injection with these properties
198
198
 
199
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
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.
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. Since the encoder always uses `-preset ultrafast -tune zerolatency` for low-latency live view (lower compression efficiency than slower presets), suggested values are higher than typical streaming guides: ~800 for `640x480`, ~2000 for `1280x720`, ~2500 for `1920x1080`.
202
202
 
203
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.
204
204
 
@@ -231,6 +231,19 @@ Example, capturing from a real Windows webcam at 720p with a higher bitrate:
231
231
  }
232
232
  ```
233
233
 
234
+ Finding your camera's RTSP url for `videoSource` when `videoGenerator` is `rtsp`:
235
+
236
+ - The general format is `rtsp://<username>:<password>@<camera-ip>:<port>/<path>`.
237
+ - `username`/`password` are the camera's own local admin account (set in its web UI or during first setup), not a cloud/app account.
238
+ - `camera-ip` is its LAN IP — check your router's DHCP client list, the camera's own app, or an IP scanner.
239
+ - `port` is almost always `554` unless changed in the camera's settings.
240
+ - `path` is vendor/model-specific and varies the most — check the camera's manual or web UI's RTSP settings page, or query it with an ONVIF tool (e.g. ONVIF Device Manager) for the exact `GetStreamUri` result. Some common examples:
241
+ - Hikvision/Ezviz-style: `/ch1/main` (main stream) or `/ch1/sub` (substream, lower resolution)
242
+ - Dahua: `/cam/realmonitor?channel=1&subtype=0`
243
+ - Reolink: `/h264Preview_01_main`
244
+
245
+ Verify the url works standalone before adding it to the config, e.g. `ffprobe rtsp://admin:password@192.168.1.100:554/ch1/main`, or open it in VLC via "Open Network Stream". Note that the url (with credentials in plaintext) ends up stored in Matterbridge's plugin config on disk, like any other password-bearing config value.
246
+
234
247
  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
248
 
236
249
  ```json
@@ -300,6 +313,7 @@ Legend:
300
313
  - **ICE — Interactive Connectivity Establishment:** discovers and tests possible network paths between the peers. ICE candidates contain addresses and ports that may be used to establish the direct WebRTC connection.
301
314
  - **DTLS — Datagram Transport Layer Security:** authenticates the peers and encrypts communication over the selected UDP network path. WebRTC uses the negotiated DTLS connection to protect subsequent media and data transport.
302
315
  - **SCTP — Stream Control Transmission Protocol:** transports WebRTC data-channel messages over the secure DTLS connection. In this test, it carries `start-live-view` and `live-view-started` between the controller and camera.
316
+ - **RTSP — Real Time Streaming Protocol:** a separate, older protocol (not part of the WebRTC flow above) used to pull a live stream from a real IP camera. See the `rtsp` video generator earlier in this README: `ffmpeg` connects to the camera's RTSP url and re-encodes its stream into the WebRTC video track injected into this same peer connection.
303
317
 
304
318
  `createOffer()` and `createAnswer()` produce the SDP descriptions. Applying each local description gathers that peer's ICE candidates. After each peer receives the other peer's description and candidates, werift selects a network path, performs the DTLS handshake, and opens the SCTP data channel. The two control messages prove that data can travel in both directions. The camera peer then sends `assets/test-camera.mp4` to the controller in 16 KiB binary chunks; the test reconstructs it and compares its byte length and SHA-256 hash before closing both peers.
305
319
 
package/dist/module.js CHANGED
@@ -15,6 +15,7 @@ import { FloodlightCamera } from './devices/floodlightCamera.js';
15
15
  import { Intercom } from './devices/intercom.js';
16
16
  import { SnapshotCamera } from './devices/snapshotCamera.js';
17
17
  import { VideoDoorbell } from './devices/videoDoorbell.js';
18
+ import { WeriftWebRtcSession } from './webrtc/weriftSession.js';
18
19
  export default function initializePlugin(matterbridge, log, config) {
19
20
  return new ExampleMatterbridgeCameraPlatform(matterbridge, log, config);
20
21
  }
@@ -223,6 +224,8 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
223
224
  this.log.info(`Shutting down platform ${this.config.name} with reason: ${reason ?? 'No reason provided'}...`);
224
225
  clearInterval(this.animationInterval);
225
226
  this.animationInterval = undefined;
227
+ this.log.info('Shutdown: closing WebRTC sessions...');
228
+ await WeriftWebRtcSession.closeAll();
226
229
  if (this.config.unregisterOnShutdown)
227
230
  await this.unregisterAllDevices();
228
231
  this.log.info(`Platform ${this.config.name} shut down successfully`);
@@ -8,8 +8,11 @@ import { AnsiLogger, MAGENTA } from 'matterbridge/logger';
8
8
  import { RTCPeerConnection, RTCRtpCodecParameters, useH264, useOPUS, usePCMU, useVP8 } from 'werift';
9
9
  import { navigator } from 'werift/nonstandard';
10
10
  export class WeriftWebRtcSession {
11
+ static activeSessions = new Set();
12
+ static exitHandlerRegistered = false;
11
13
  peerConnection;
12
14
  log;
15
+ webRtcSessionId;
13
16
  testVideoGenerator;
14
17
  testVideoUdpDisposer;
15
18
  testVideoAttached = false;
@@ -17,6 +20,7 @@ export class WeriftWebRtcSession {
17
20
  testAudioUdpDisposer;
18
21
  testAudioAttached = false;
19
22
  constructor(webRtcSessionId) {
23
+ this.webRtcSessionId = webRtcSessionId;
20
24
  this.peerConnection = new RTCPeerConnection({ codecs: { audio: [useOPUS(), usePCMU()], video: [useH264(), useVP8()] } });
21
25
  this.log = new AnsiLogger({ logName: `WebRTC session ${webRtcSessionId}`, logLevel: "debug", logNameColor: MAGENTA, logTimestampFormat: 4 });
22
26
  this.peerConnection.iceGatheringStateChange.subscribe((state) => {
@@ -43,6 +47,19 @@ export class WeriftWebRtcSession {
43
47
  this.log.info(`Peer connection state: ${state}`);
44
48
  });
45
49
  this.log.debug(`Created RTCPeerConnection with codecs: audio=[OPUS, PCMU], video=[H264, VP8] for session ${webRtcSessionId}`);
50
+ WeriftWebRtcSession.activeSessions.add(this);
51
+ if (!WeriftWebRtcSession.exitHandlerRegistered) {
52
+ WeriftWebRtcSession.exitHandlerRegistered = true;
53
+ process.on('exit', () => {
54
+ for (const session of WeriftWebRtcSession.activeSessions) {
55
+ if (!session.testVideoGenerator && !session.testAudioGenerator)
56
+ continue;
57
+ session.log.info('Process exiting: killing leftover ffmpeg processes for this session');
58
+ session.testVideoGenerator?.kill('SIGTERM');
59
+ session.testAudioGenerator?.kill('SIGTERM');
60
+ }
61
+ });
62
+ }
46
63
  }
47
64
  summarizeSdp(sdp) {
48
65
  const mediaKinds = sdp
@@ -492,6 +509,13 @@ export class WeriftWebRtcSession {
492
509
  await this.peerConnection.close();
493
510
  this.cleanupTestVideoArtifacts();
494
511
  this.cleanupTestAudioArtifacts();
512
+ WeriftWebRtcSession.activeSessions.delete(this);
495
513
  this.log.info(`RTCPeerConnection closed (connectionState=${this.peerConnection.connectionState})`);
496
514
  }
515
+ static async closeAll() {
516
+ for (const session of WeriftWebRtcSession.activeSessions) {
517
+ session.log.info(`Closing session ${session.webRtcSessionId} as part of closeAll()`);
518
+ await session.close();
519
+ }
520
+ }
497
521
  }
@@ -63,7 +63,7 @@
63
63
  },
64
64
  "videoBitrate": {
65
65
  "title": "Video Bitrate",
66
- "description": "Target encoder bitrate (kbps) used when capturing from the configured webcam or RTSP camera, regardless of resolution.",
66
+ "description": "Target encoder bitrate (kbps) used when capturing from the configured webcam or RTSP camera, regardless of resolution. Default is 1000. Suggested values: ~800 for 640x480, ~2000 for 1280x720, ~2500 for 1920x1080.",
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.8-dev-20260726-2ea4814",
3
+ "version": "0.0.8-dev-20260726-dffb00d",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "matterbridge-example-camera",
9
- "version": "0.0.8-dev-20260726-2ea4814",
9
+ "version": "0.0.8-dev-20260726-dffb00d",
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.8-dev-20260726-2ea4814",
3
+ "version": "0.0.8-dev-20260726-dffb00d",
4
4
  "description": "Matterbridge camera example plugin",
5
5
  "author": "https://github.com/Luligu",
6
6
  "license": "Apache-2.0",