matterbridge-example-camera 0.0.7 → 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
@@ -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.8] - Dev branch
32
+
33
+ ### Added
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 (with suggested per-resolution values) in the README and schema, 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
+ - [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.
43
+
44
+ ### Fixed
45
+
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.
47
+
31
48
  ## [0.0.7] - 2026-07-25
32
49
 
33
50
  ### Added
package/README.md CHANGED
@@ -186,21 +186,25 @@ 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
 
193
193
  The platform configuration controls WebRTC video injection with these properties:
194
194
 
195
- - `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.
196
- - `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.
197
- - `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`.
198
196
 
199
- 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.
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.
198
+
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. 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
+
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.
200
204
 
201
205
  Requires `ffmpeg` to be installed. The resolver checks the system command and common installation directories on Linux, macOS, and Windows.
202
206
 
203
- 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`:
204
208
 
205
209
  - Linux (v4l2): `v4l2-ctl --list-devices` (from `v4l-utils`), or `ls /dev/video*`.
206
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.
@@ -210,19 +214,53 @@ Example configuration for a real Linux webcam at 720p:
210
214
 
211
215
  ```json
212
216
  {
213
- "generator": "webcam",
214
- "webcam": "/dev/video0",
215
- "webcamResolution": "1280x720"
217
+ "videoGenerator": "webcam",
218
+ "videoSource": "/dev/video0",
219
+ "videoResolution": "1280x720"
220
+ }
221
+ ```
222
+
223
+ Example, capturing from a real Windows webcam at 720p with a higher bitrate:
224
+
225
+ ```json
226
+ {
227
+ "videoGenerator": "webcam",
228
+ "videoSource": "Integrated Camera",
229
+ "videoResolution": "1280x720",
230
+ "videoBitrate": 2000
231
+ }
232
+ ```
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
+
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):
248
+
249
+ ```json
250
+ {
251
+ "videoGenerator": "rtsp",
252
+ "videoSource": "rtsp://admin:password@192.168.1.100:554/ch1/main",
253
+ "videoResolution": "1280x720"
216
254
  }
217
255
  ```
218
256
 
219
- Example, capturing from a real Windows webcam at 720p:
257
+ Example, pulling from a real RTSP camera and scaling to whatever resolution the controller requests for the session:
220
258
 
221
259
  ```json
222
260
  {
223
- "generator": "webcam",
224
- "webcam": "Integrated Camera",
225
- "webcamResolution": "1280x720"
261
+ "videoGenerator": "rtsp",
262
+ "videoSource": "rtsp://admin:password@192.168.1.100:554/ch1/main",
263
+ "videoResolution": "auto"
226
264
  }
227
265
  ```
228
266
 
@@ -275,6 +313,7 @@ Legend:
275
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.
276
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.
277
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.
278
317
 
279
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.
280
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
  }
@@ -31,25 +32,25 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
31
32
  this.log.info(`Initializing platform ${this.config.name}...`);
32
33
  this.config.whiteList ??= [];
33
34
  this.config.blackList ??= [];
34
- this.config.generator ??= 'none';
35
- this.config.webcamResolution ??= '640x480';
36
- this.config.webcamBitrate ??= 1000;
35
+ this.config.videoGenerator ??= 'none';
36
+ this.config.videoResolution ??= 'auto';
37
+ this.config.videoBitrate ??= 1000;
37
38
  this.config.animationInterval ??= 60;
38
39
  this.config.debug ??= false;
39
40
  this.config.unregisterOnShutdown ??= false;
40
- process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE = this.config.generator;
41
- if (this.config.webcam === undefined)
42
- delete process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE;
41
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE = this.config.videoGenerator;
42
+ if (this.config.videoSource === undefined)
43
+ delete process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE;
43
44
  else
44
- process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE = this.config.webcam;
45
- process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION = this.config.webcamResolution;
46
- process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE = String(this.config.webcamBitrate);
45
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE = this.config.videoSource;
46
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION = this.config.videoResolution;
47
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE = String(this.config.videoBitrate);
47
48
  this.log.debug(`Platform ${this.config.name} config:\n${RESET}${inspect(this.config, { depth: 10, colors: true })}`);
48
49
  this.log.debug(`Platform ${this.config.name} environment variables:\n${RESET}${inspect({
49
50
  MATTERBRIDGE_CAMERA_VIDEO_SOURCE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE,
50
- MATTERBRIDGE_CAMERA_WEBCAM_DEVICE: process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE,
51
- MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION: process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION,
52
- MATTERBRIDGE_CAMERA_WEBCAM_BITRATE: process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE,
51
+ MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE,
52
+ MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION: process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION,
53
+ MATTERBRIDGE_CAMERA_VIDEO_BITRATE: process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE,
53
54
  }, { depth: 10, colors: true })}`);
54
55
  this.log.info(`Platform ${this.config.name} initialized successfully`);
55
56
  }
@@ -143,9 +144,6 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
143
144
  const exampleChime = this.getDeviceById('Chime-CHIME-001');
144
145
  await exampleChime?.setCluster(PowerSource, { batChargeLevel: PowerSource.BatChargeLevel.Ok, batPercentRemaining: 150, batQuantity: 2, batReplacementDescription: 'AA' }, exampleChime.log);
145
146
  await exampleChime?.setCluster(ChimeCluster, { enabled: true, selectedChime: 0 }, exampleChime.log);
146
- const exampleIntercom1 = this.getDeviceById('Intercom1-INTERCOM1-001');
147
- if (!exampleIntercom1)
148
- throw new Error(`Intercom device not found. Please ensure the device is registered before configuration.`);
149
147
  const serverChime = this.getDeviceById('ServerChime-SERVER-CHIME-001');
150
148
  await serverChime?.setCluster(PowerSource, { batChargeLevel: PowerSource.BatChargeLevel.Ok, batPercentRemaining: 150, batVoltage: 2900, batReplacementNeeded: false }, serverChime.log);
151
149
  await serverChime?.setCluster(ChimeCluster, { enabled: true, selectedChime: 0 }, serverChime.log);
@@ -226,6 +224,8 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
226
224
  this.log.info(`Shutting down platform ${this.config.name} with reason: ${reason ?? 'No reason provided'}...`);
227
225
  clearInterval(this.animationInterval);
228
226
  this.animationInterval = undefined;
227
+ this.log.info('Shutdown: closing WebRTC sessions...');
228
+ await WeriftWebRtcSession.closeAll();
229
229
  if (this.config.unregisterOnShutdown)
230
230
  await this.unregisterAllDevices();
231
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
@@ -169,38 +186,39 @@ export class WeriftWebRtcSession {
169
186
  this.log.debug('No preferred injectable audio codec (Opus) negotiated on any audio transceiver');
170
187
  return undefined;
171
188
  }
172
- static SUPPORTED_WEBCAM_RESOLUTIONS = ['640x480', '1280x720', '1920x1080'];
189
+ static SUPPORTED_VIDEO_RESOLUTIONS = ['640x480', '1280x720', '1920x1080'];
173
190
  static DEFAULT_BITRATE_KBPS = 1000;
174
- getConfiguredWebcamBitrate() {
175
- const configured = process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE;
191
+ getConfiguredVideoBitrate() {
192
+ const configured = process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE;
176
193
  if (!configured)
177
194
  return WeriftWebRtcSession.DEFAULT_BITRATE_KBPS;
178
195
  const bitrateKbps = Number(configured);
179
196
  if (!Number.isFinite(bitrateKbps) || bitrateKbps <= 0) {
180
- this.log.warn(`Invalid MATTERBRIDGE_CAMERA_WEBCAM_BITRATE "${configured}"; falling back to ${WeriftWebRtcSession.DEFAULT_BITRATE_KBPS}kbps`);
197
+ this.log.warn(`Invalid MATTERBRIDGE_CAMERA_VIDEO_BITRATE "${configured}"; falling back to ${WeriftWebRtcSession.DEFAULT_BITRATE_KBPS}kbps`);
181
198
  return WeriftWebRtcSession.DEFAULT_BITRATE_KBPS;
182
199
  }
183
200
  return bitrateKbps;
184
201
  }
185
- getConfiguredWebcamResolution(requestedResolution) {
186
- const [defaultResolution] = WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS;
202
+ getConfiguredVideoResolution(requestedResolution) {
203
+ const [defaultResolution] = WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS;
204
+ const configured = process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION;
205
+ if (configured && configured !== 'auto') {
206
+ if (WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.includes(configured)) {
207
+ this.log.debug(`Using configured MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION ${configured}`);
208
+ return configured;
209
+ }
210
+ this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION "${configured}" (supported: ${WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.join(', ')}, auto); falling back to ${defaultResolution}`);
211
+ return defaultResolution;
212
+ }
187
213
  if (requestedResolution) {
188
- if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requestedResolution)) {
189
- this.log.debug(`Using requested webcam capture resolution ${requestedResolution}`);
214
+ if (WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.includes(requestedResolution)) {
215
+ this.log.debug(`Using requested video stream resolution ${requestedResolution} (MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION=auto)`);
190
216
  return requestedResolution;
191
217
  }
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}`);
218
+ this.log.warn(`Requested video stream resolution "${requestedResolution}" is not supported (supported: ${WeriftWebRtcSession.SUPPORTED_VIDEO_RESOLUTIONS.join(', ')}); falling back to ${defaultResolution}`);
197
219
  return defaultResolution;
198
220
  }
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}`);
221
+ this.log.debug(`No requested video stream resolution available; using default ${defaultResolution} (MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION=auto)`);
204
222
  return defaultResolution;
205
223
  }
206
224
  getConfiguredVideoSource() {
@@ -209,9 +227,10 @@ export class WeriftWebRtcSession {
209
227
  case 'none':
210
228
  case 'test':
211
229
  case 'webcam':
230
+ case 'rtsp':
212
231
  return source;
213
232
  default:
214
- this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_SOURCE "${source}" (supported: test, webcam, none); falling back to none`);
233
+ this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_SOURCE "${source}" (supported: test, webcam, rtsp, none); falling back to none`);
215
234
  return 'none';
216
235
  }
217
236
  }
@@ -225,13 +244,18 @@ export class WeriftWebRtcSession {
225
244
  this.log.debug(`Test pattern params: resolution=640x480, description="${testPatternInput.description}", bitrateKbps=${testPatternInput.bitrateKbps}`);
226
245
  return testPatternInput;
227
246
  }
228
- const device = process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE;
247
+ const device = process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE;
229
248
  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');
249
+ 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
250
  return testPatternInput;
232
251
  }
233
- const resolution = process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION ?? this.getConfiguredWebcamResolution(requestedResolution);
234
- const bitrateKbps = this.getConfiguredWebcamBitrate();
252
+ const resolution = this.getConfiguredVideoResolution(requestedResolution);
253
+ const bitrateKbps = this.getConfiguredVideoBitrate();
254
+ if (videoSource === 'rtsp') {
255
+ const description = `RTSP camera (${device}, ${resolution})`;
256
+ this.log.debug(`RTSP capture params: url=${device}, resolution=${resolution}, description="${description}", bitrateKbps=${bitrateKbps}`);
257
+ return { args: ['-rtsp_transport', 'tcp', '-i', device, '-vf', `scale=${resolution.replace('x', ':')}`], description, bitrateKbps };
258
+ }
235
259
  const description = `local webcam (${device}, ${resolution})`;
236
260
  this.log.debug(`Webcam capture params: device=${device}, resolution=${resolution}, description="${description}", bitrateKbps=${bitrateKbps}`);
237
261
  switch (process.platform) {
@@ -485,6 +509,13 @@ export class WeriftWebRtcSession {
485
509
  await this.peerConnection.close();
486
510
  this.cleanupTestVideoArtifacts();
487
511
  this.cleanupTestAudioArtifacts();
512
+ WeriftWebRtcSession.activeSessions.delete(this);
488
513
  this.log.info(`RTCPeerConnection closed (connectionState=${this.peerConnection.connectionState})`);
489
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
+ }
490
521
  }
@@ -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. 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.7",
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.7",
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.7",
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",