matterbridge-example-camera 0.0.6-dev-20260721-4f7106a → 0.0.6

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,9 +28,7 @@ If you like this project and find it useful, please consider giving it a star on
28
28
 
29
29
  <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
30
30
 
31
- ## [0.0.6] - Dev branch
32
-
33
- ## [0.0.6] - Dev branch
31
+ ## [0.0.6] - 2026-07-21
34
32
 
35
33
  ### Added
36
34
 
@@ -38,8 +36,14 @@ If you like this project and find it useful, please consider giving it a star on
38
36
  - [platform]: Register a Floodlight Camera example device in `onStart`, and verify it's registered in `onConfigure`.
39
37
  - [tests]: Add `vitest/devices/floodlightCamera.test.ts` covering default options, custom `lightOptions`, camera identify, power source variants, additional tagged lights, and custom stream usages; extend `vitest/module.test.ts` with the Floodlight Camera "device not registered" `onConfigure` error path.
40
38
 
39
+ ### Changed
40
+
41
+ - [webrtc]: Add the required `generator` setting (`none`, `test`, or `webcam`, default `none`), the optional `webcam` ffmpeg device setting with no default, and the required `webcamResolution` setting (`640x480`, `1280x720`, or `1920x1080`, default `640x480`). `test` selects the SMPTE bars pattern, `webcam` captures from the configured device, and `none` negotiates video without attaching a track.
42
+
41
43
  ### Fixed
42
44
 
45
+ - [webrtc]: Allocate `WebRTCSessionID` values monotonically from 0 through 65534 across both `SolicitOffer` and new-session `ProvideOffer` requests, wrapping to 0 and skipping active identifiers instead of deriving the next value from the currently active sessions.
46
+ - [platform]: Initialize missing `whiteList` and `blackList` properties for older saved configs so the frontend Home page exposes its device-selection checkboxes.
43
47
  - [webrtc]: `provideIceCandidates` unconditionally skipped every mDNS host ICE candidate (`*.local`), so a peer that only offers mDNS-obfuscated candidates (the Chromium/Edge default) left the werift peer connection with zero usable remote candidates — signaling succeeded but the stream stayed black. werift-ice already resolves `.local` candidates via a real multicast DNS query before pairing them, so candidates are no longer skipped and that resolution is allowed to run; the per-candidate apply timeout is bumped from 2000ms to 5000ms to leave headroom for the mDNS round trip. Verified against a real Edge client: the mDNS candidate resolved and applied in 98ms and video streamed correctly. See the new "Known limitation: Firefox may only offer a link-local address on a non-HTTPS page" note in the README for a related, separate client-side issue this does not fix.
44
48
  - [snapshot]: README asset docs still described the pre-#15 `camera-color-test-*.jpeg` names; `CaptureSnapshot` now reads `camera-color-{640-480,1280-720,1920-1080}.jpeg`. Also documented why all three calibration cards are kept under the ~65535-byte Matter message-size ceiling (AES-CCM's 13-byte nonce) and why it can't be worked around by tuning TCP.
45
49
 
package/README.md CHANGED
@@ -60,6 +60,7 @@ Features:
60
60
 
61
61
  - Exposes the Camera AV Stream Management cluster with the Video, Audio and ImageControl features (the Snapshot feature is not implemented in this example; see Snapshot Camera).
62
62
  - Exposes the WebRtcTransportProvider cluster and registers a WebRtcTransportRequestor client, so a bound device can solicit and receive WebRTC offers.
63
+ - Allocates WebRTC session identifiers monotonically from 0 through 65534, wrapping to 0 and skipping identifiers that still belong to active sessions, as required by Matter 1.6.
63
64
  - Automatically selects or allocates a video/audio stream when a client's `SolicitOffer`/`ProvideOffer` omits `videoStreams`/`audioStreams` (and their deprecated single-id counterparts), per the Matter specification's automatic stream selection for revision 1 clients. This is required to interoperate with clients that never allocate streams explicitly, such as Home Assistant's Matter camera integration.
64
65
  - Supports configurable stream usages and priorities, encoder limits, video sensor parameters, viewport, rate-distortion trade-off points, and microphone capabilities.
65
66
  - Optional Identify cluster support, with configurable identify time and type. Set to Identify.IdentifyType.None to omit the cluster entirely.
@@ -102,28 +103,55 @@ Features:
102
103
 
103
104
  `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.
104
105
 
105
- The video source defaults to a synthetic SMPTE bars test pattern, or can be switched to a real local webcam. Configure it with environment variables:
106
+ The platform configuration controls WebRTC video injection with these properties:
106
107
 
107
- - `MATTERBRIDGE_CAMERA_DISABLE_TEST_VIDEO=1`: disables video injection entirely (only the negotiated transceiver is created, with no track attached).
108
- - `MATTERBRIDGE_CAMERA_VIDEO_SOURCE=webcam`: capture from a local webcam via ffmpeg instead of the SMPTE bars test pattern. Requires `MATTERBRIDGE_CAMERA_WEBCAM_DEVICE`; falls back to the test pattern (with a warning) if unset.
109
- - `MATTERBRIDGE_CAMERA_WEBCAM_DEVICE=<device>`: 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).
110
- - `MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION=<width>x<height>`: default webcam capture resolution — `640x480` (default), `1280x720`, or `1920x1080`. Falls back to `640x480` (with a warning) for unsupported values. 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).
108
+ - `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.
109
+ - `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.
110
+ - `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).
111
111
 
112
- A real client's resolution/quality picker (e.g. in Home Assistant) takes precedence over `MATTERBRIDGE_CAMERA_WEBCAM_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 webcam capture resolution for the session. `MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION` is used when no matching allocated stream is found, or when the requested resolution isn't one of the three supported above.
112
+ 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.
113
113
 
114
- Requires `ffmpeg` to be installed. The resolver first tries `PATH`, then `/usr/bin/ffmpeg`, `/bin/ffmpeg`, and `/usr/local/bin/ffmpeg`. On Windows it also checks winget/Gyan installs under `%LOCALAPPDATA%\Microsoft\WinGet\Packages\Gyan.FFmpeg_*\ffmpeg-*\bin\ffmpeg.exe`, plus `%ProgramFiles%\ffmpeg\bin\ffmpeg.exe`, `%ProgramFiles%\Gyan\FFmpeg\bin\ffmpeg.exe`, `%ProgramFiles(x86)%\ffmpeg\bin\ffmpeg.exe`, and `%ProgramFiles(x86)%\Gyan\FFmpeg\bin\ffmpeg.exe`.
114
+ Requires `ffmpeg` to be installed. The resolver checks the system command and common installation directories on Linux, macOS, and Windows.
115
115
 
116
- Example, capturing from a real Linux webcam at 720p:
116
+ Use ffmpeg itself to list the available capture devices and find the right value for `webcam`:
117
117
 
118
- ```bash
119
- MATTERBRIDGE_CAMERA_VIDEO_SOURCE=webcam MATTERBRIDGE_CAMERA_WEBCAM_DEVICE=/dev/video0 MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION=1280x720 npm start
118
+ - Linux (v4l2): `v4l2-ctl --list-devices` (from `v4l-utils`), or `ls /dev/video*`.
119
+ - 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.
120
+ - Windows (dshow): `ffmpeg -f dshow -list_devices true -i dummy` — video devices are listed by name under "DirectShow video devices", e.g. `"Integrated Camera"`; use that exact name as the device value.
121
+
122
+ Example configuration for a real Linux webcam at 720p:
123
+
124
+ ```json
125
+ {
126
+ "generator": "webcam",
127
+ "webcam": "/dev/video0",
128
+ "webcamResolution": "1280x720"
129
+ }
120
130
  ```
121
131
 
122
- ### Known limitation: Firefox may only offer a link-local address on a non-HTTPS page
132
+ Example, capturing from a real Windows webcam at 720p:
133
+
134
+ ```json
135
+ {
136
+ "generator": "webcam",
137
+ "webcam": "Integrated Camera",
138
+ "webcamResolution": "1280x720"
139
+ }
140
+ ```
141
+
142
+ ### Known limitation: mDNS ICE candidates can't be resolved across a Docker Desktop host boundary
143
+
144
+ When matterbridge runs in a container (e.g. via Docker Desktop on Windows/macOS) and the WebRTC-consuming page runs in a browser on the host machine — for example the matterjs-server dashboard — `provideIceCandidates` can fail every candidate with `ICE candidate apply timeout after 5000ms`, even though matterbridge and the Matter controller container can reach each other fine.
145
+
146
+ The cause: Chromium-based browsers (Edge, Chrome) hide the page's real local IP behind a random `<uuid>.local` mDNS name in ICE host candidates by default. Resolving that name requires a real multicast DNS query/response over the LAN (see the Firefox limitation above). Docker Desktop's virtualized networking (WSL2/Hyper-V) does not forward multicast traffic between a container's network and the Windows/macOS host, so matterbridge's mDNS query for the browser's candidate name never reaches the browser, and the candidate can never resolve — no matter how the container networking is otherwise configured.
147
+
148
+ Packet captures confirm this: the query correctly leaves the matterbridge container and even reaches other containers on the same Docker network, but never reaches a browser running on the host, and no reply is ever seen.
123
149
 
124
- `MatterbridgeWebRtcTransportProviderServer.provideIceCandidates` applies every ICE candidate it receives, including mDNS-obfuscated `*.local` host candidates (the Chromium/Edge default): werift-ice resolves those via a real multicast DNS query before pairing them, so no special handling is needed here.
150
+ The fix is on the browser side, not in this plugin: disable mDNS obfuscation of local ICE candidates so the browser advertises its real LAN IP instead of a `.local` name, which skips mDNS resolution entirely.
125
151
 
126
- This relies on the client machine actually offering a usable address in the first place. Firefox has been observed advertising only a non-routable IPv6 link-local (`fe80::...`) address — instead of its real LAN IP — when the WebRTC-consuming page is loaded over plain HTTP from a non-`localhost` origin (i.e. not a secure context: not `https://`, not `http://localhost`/`127.0.0.1`), even with `media.peerconnection.ice.obfuscate_host_addresses` disabled in `about:config`. A link-local address can never be reached by a remote peer, so the connection stays black-screen no matter how the candidate is resolved. Chromium-based browsers (Edge, Chrome) were unaffected under the same conditions. If a stream stays black specifically with Firefox, check whether the page serving the WebRTC client is a secure context (`window.isSecureContext` in devtools, or `about:webrtc` for the actual candidates gathered) before assuming a bug in this plugin — serving that page over HTTPS, or via `localhost`, is the fix.
152
+ - **Edge**: go to `edge://flags/#enable-webrtc-hide-local-ips-with-mdns`, set **"Anonymize local IPs exposed by WebRTC"** to **Disabled**, then relaunch the browser.
153
+ - **Chrome**: the same flag is at `chrome://flags/#enable-webrtc-hide-local-ips-with-mdns`.
154
+ - **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`.
127
155
 
128
156
  ## Werift integration test
129
157
 
@@ -192,7 +220,7 @@ WebRTC media tracks transport encoded H.264 or Opus frames in RTP packets; they
192
220
  ## Chip tests
193
221
 
194
222
  ```bash
195
- docker rm matterbridge-chip-test-hub -f && docker pull luligu/matterbridge:chip-test && docker run -dit --network matterbridge --restart always --stop-timeout 60 --name matterbridge-chip-test-hub -p 8283:8283 -v "%USERPROFILE%/GitHub/matterbridge-example-camera/temp:/tmp/matter_testing/logs" luligu/matterbridge:chip-test
223
+ docker rm matterbridge-chip-test-hub -f && docker pull luligu/matterbridge:chip-test && docker run -dit --network matterbridge --restart always --stop-timeout 60 --name matterbridge-chip-test-hub -p 8283:8283 -v "C:/Users/your-user/GitHub/matterbridge-example-camera/temp:/tmp/matter_testing/logs" luligu/matterbridge:chip-test
196
224
  docker logs -f matterbridge-chip-test-hub --tail 1000
197
225
  docker exec -it matterbridge-chip-test-hub bash
198
226
  ```
@@ -5,9 +5,9 @@ import { CameraAvStreamManagement } from 'matterbridge/matter/clusters';
5
5
  import { Status, StatusResponseError } from 'matterbridge/matter/types';
6
6
  const DEFAULT_CAMERA_COLOR_TEST_RESOLUTION = '640x480';
7
7
  const cameraColorTestJpegs = {
8
- '640x480': { data: readFileSync(new URL('../../assets/camera-color-640-480.jpeg', import.meta.url)), resolution: { width: 640, height: 480 } },
9
- '1280x720': { data: readFileSync(new URL('../../assets/camera-color-1280-720.jpeg', import.meta.url)), resolution: { width: 1280, height: 720 } },
10
- '1920x1080': { data: readFileSync(new URL('../../assets/camera-color-1920-1080.jpeg', import.meta.url)), resolution: { width: 1920, height: 1080 } },
8
+ '640x480': { data: readFileSync(new URL('../../assets/camera-color-test-640-480.jpeg', import.meta.url)), resolution: { width: 640, height: 480 } },
9
+ '1280x720': { data: readFileSync(new URL('../../assets/camera-color-test-1280-720.jpeg', import.meta.url)), resolution: { width: 1280, height: 720 } },
10
+ '1920x1080': { data: readFileSync(new URL('../../assets/camera-color-test-1920-1080.jpeg', import.meta.url)), resolution: { width: 1920, height: 1080 } },
11
11
  };
12
12
  export function cameraColorTestJpegForResolution(requestedResolution) {
13
13
  return cameraColorTestJpegs[`${requestedResolution.width}x${requestedResolution.height}`] ?? cameraColorTestJpegs[DEFAULT_CAMERA_COLOR_TEST_RESOLUTION];
@@ -6,6 +6,18 @@ import { WeriftWebRtcSession } from '../webrtc/weriftSession.js';
6
6
  import { MatterbridgeCameraAvStreamManagementServer } from './cameraAvStreamManagementServer.js';
7
7
  const DEFERRED_INVOKE_DELAY_MS = 250;
8
8
  const ICE_CANDIDATE_APPLY_TIMEOUT_MS = 5000;
9
+ const MAX_WEB_RTC_SESSION_ID = 0xfffe;
10
+ export function allocateWebRtcSessionId(nextCandidate, activeSessionIds) {
11
+ const firstCandidate = nextCandidate;
12
+ let candidate = firstCandidate;
13
+ do {
14
+ const followingCandidate = candidate === MAX_WEB_RTC_SESSION_ID ? 0 : candidate + 1;
15
+ if (!activeSessionIds.has(candidate))
16
+ return { webRtcSessionId: candidate, nextCandidate: followingCandidate };
17
+ candidate = followingCandidate;
18
+ } while (candidate !== firstCandidate);
19
+ throw new StatusResponseError('No WebRTC session identifier is available', Status.ResourceExhausted);
20
+ }
9
21
  export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportProviderServer {
10
22
  #invokeDeferred(action, description) {
11
23
  const device = this.endpoint.stateOf(MatterbridgeServer);
@@ -37,6 +49,12 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
37
49
  fabricIndex: session?.fabric?.fabricIndex ?? FabricIndex(1),
38
50
  };
39
51
  }
52
+ #allocateWebRtcSessionId() {
53
+ const activeSessionIds = new Set(this.state.currentSessions.map((session) => session.id));
54
+ const allocation = allocateWebRtcSessionId(this.internal.nextWebRtcSessionId, activeSessionIds);
55
+ this.internal.nextWebRtcSessionId = allocation.nextCandidate;
56
+ return allocation.webRtcSessionId;
57
+ }
40
58
  #resolveStreamLists(request) {
41
59
  return {
42
60
  videoStreams: request.videoStreams ?? (request.videoStreamId !== undefined && request.videoStreamId !== null ? [request.videoStreamId] : undefined),
@@ -105,13 +123,10 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
105
123
  ({ videoStreams, audioStreams } = await this.#autoAssignStreams(request.streamUsage));
106
124
  }
107
125
  if (!videoStreams?.length && !audioStreams?.length) {
108
- throw new StatusResponseError('solicitOffer requires at least one of videoStreams or audioStreams; the camera has no video or audio stream to assign automatically', Status.ConstraintError);
126
+ throw new StatusResponseError('MatterbridgeWebRtcTransportProviderServer.solicitOffer requires at least one of videoStreams or audioStreams; the camera has no video or audio stream to assign automatically', Status.ConstraintError);
109
127
  }
110
128
  const device = this.endpoint.stateOf(MatterbridgeServer);
111
- let webRtcSessionId = 0;
112
- for (const session of this.state.currentSessions) {
113
- webRtcSessionId = Math.max(webRtcSessionId, session.id + 1);
114
- }
129
+ const webRtcSessionId = this.#allocateWebRtcSessionId();
115
130
  const { peerNodeId, fabricIndex } = this.#getPeerInfo();
116
131
  this.state.currentSessions = [
117
132
  ...this.state.currentSessions,
@@ -126,17 +141,17 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
126
141
  fabricIndex,
127
142
  },
128
143
  ];
129
- device.log.info(`Solicited a WebRTC offer for session ${webRtcSessionId} (stream usage ${request.streamUsage}) (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
130
- const webRtcPeer = new WeriftWebRtcSession((level, message) => device.log[level](message), `WebRTC session ${webRtcSessionId}`);
144
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.solicitOffer: solicited a WebRTC offer for session ${webRtcSessionId} (stream usage ${request.streamUsage}) (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
145
+ const webRtcPeer = new WeriftWebRtcSession(webRtcSessionId);
131
146
  this.internal.sessions.set(webRtcSessionId, webRtcPeer);
132
147
  const sdp = await webRtcPeer.createOffer({ video: !!videoStreams?.length, audio: !!audioStreams?.length, videoResolution: this.#resolveVideoResolution(videoStreams) });
133
148
  const requestorEndpoint = await this.#resolvePeerRequestorEndpoint(peerNodeId, fabricIndex, request.originatingEndpointId);
134
149
  if (requestorEndpoint) {
135
150
  this.#invokeDeferred(async () => requestorEndpoint.commandsOf(WebRtcTransportRequestorClient).offer({ webRtcSessionId, sdp }), `Offer for session ${webRtcSessionId}`);
136
- device.log.info(`Invoking Offer on the peer's WebRtcTransportRequestor for session ${webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
151
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.solicitOffer: invoking Offer on the peer's WebRtcTransportRequestor for session ${webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
137
152
  }
138
153
  else {
139
- device.log.info(`Could not reach the peer's WebRtcTransportRequestor; the Offer for session ${webRtcSessionId} was not sent (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
154
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.solicitOffer: could not reach the peer's WebRtcTransportRequestor; the Offer for session ${webRtcSessionId} was not sent (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
140
155
  }
141
156
  return { webRtcSessionId, deferredOffer: true, ...this.#echoDeprecatedStreamIds(request, videoStreams, audioStreams) };
142
157
  }
@@ -149,12 +164,9 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
149
164
  ({ videoStreams, audioStreams } = await this.#autoAssignStreams(request.streamUsage ?? StreamUsage.LiveView));
150
165
  }
151
166
  if (!videoStreams?.length && !audioStreams?.length) {
152
- throw new StatusResponseError('provideOffer requires at least one of videoStreams or audioStreams; the camera has no video or audio stream to assign automatically', Status.ConstraintError);
153
- }
154
- webRtcSessionId = 0;
155
- for (const session of this.state.currentSessions) {
156
- webRtcSessionId = Math.max(webRtcSessionId, session.id + 1);
167
+ throw new StatusResponseError('MatterbridgeWebRtcTransportProviderServer.provideOffer requires at least one of videoStreams or audioStreams; the camera has no video or audio stream to assign automatically', Status.ConstraintError);
157
168
  }
169
+ webRtcSessionId = this.#allocateWebRtcSessionId();
158
170
  const { peerNodeId, fabricIndex } = this.#getPeerInfo();
159
171
  this.state.currentSessions = [
160
172
  ...this.state.currentSessions,
@@ -173,29 +185,29 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
173
185
  else if (!this.state.currentSessions.some((session) => session.id === webRtcSessionId)) {
174
186
  throw new StatusResponseError(`WebRTC session ${webRtcSessionId} is not present in currentSessions`, Status.NotFound);
175
187
  }
176
- device.log.info(`Received an SDP offer for session ${webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
177
- device.log.debug(`MatterbridgeWebRtcTransportProviderServer: received SDP offer for session ${webRtcSessionId}: ${request.sdp}`);
188
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideOffer: received an SDP offer for session ${webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
189
+ device.log.debug(`MatterbridgeWebRtcTransportProviderServer.provideOffer: received an SDP offer for session ${webRtcSessionId}:\n${request.sdp}`);
178
190
  const session = this.state.currentSessions.find((s) => s.id === webRtcSessionId);
179
- const webRtcPeer = this.internal.sessions.get(webRtcSessionId) ?? new WeriftWebRtcSession((level, message) => device.log[level](message), `WebRTC session ${webRtcSessionId}`);
191
+ const webRtcPeer = this.internal.sessions.get(webRtcSessionId) ?? new WeriftWebRtcSession(webRtcSessionId);
180
192
  this.internal.sessions.set(webRtcSessionId, webRtcPeer);
181
193
  const sdp = await webRtcPeer.createAnswer(request.sdp, this.#resolveVideoResolution(session.videoStreams));
182
194
  const requestorEndpoint = await this.#resolvePeerRequestorEndpoint(session.peerNodeId, session.fabricIndex, session.peerEndpointId);
183
195
  if (requestorEndpoint) {
184
196
  this.#invokeDeferred(async () => requestorEndpoint.commandsOf(WebRtcTransportRequestorClient).answer({ webRtcSessionId, sdp }), `Answer for session ${webRtcSessionId}`);
185
- device.log.info(`Invoking Answer on the peer's WebRtcTransportRequestor for session ${webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
197
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideOffer: invoking Answer on the peer's WebRtcTransportRequestor for session ${webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
186
198
  }
187
199
  else {
188
- device.log.info(`Could not reach the peer's WebRtcTransportRequestor; the Answer for session ${webRtcSessionId} was not sent (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
200
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideOffer: could not reach the peer's WebRtcTransportRequestor; the Answer for session ${webRtcSessionId} was not sent (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
189
201
  }
190
202
  return { webRtcSessionId, ...this.#echoDeprecatedStreamIds(request, session.videoStreams && [...session.videoStreams], session.audioStreams && [...session.audioStreams]) };
191
203
  }
192
204
  async provideAnswer(request) {
193
205
  const device = this.endpoint.stateOf(MatterbridgeServer);
194
206
  if (!this.state.currentSessions.some((session) => session.id === request.webRtcSessionId)) {
195
- throw new StatusResponseError(`WebRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
207
+ throw new StatusResponseError(`MatterbridgeWebRtcTransportProviderServer.provideAnswer: webRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
196
208
  }
197
- device.log.info(`Received an SDP answer for session ${request.webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
198
- device.log.debug(`MatterbridgeWebRtcTransportProviderServer: received SDP answer for session ${request.webRtcSessionId}: ${request.sdp}`);
209
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideAnswer: received an SDP answer for session ${request.webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
210
+ device.log.debug(`MatterbridgeWebRtcTransportProviderServer.provideAnswer: received SDP answer for session ${request.webRtcSessionId}:\n${request.sdp}`);
199
211
  const webRtcPeer = this.internal.sessions.get(request.webRtcSessionId);
200
212
  if (webRtcPeer) {
201
213
  await webRtcPeer.applyAnswer(request.sdp);
@@ -204,26 +216,26 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
204
216
  async provideIceCandidates(request) {
205
217
  const device = this.endpoint.stateOf(MatterbridgeServer);
206
218
  if (!this.state.currentSessions.some((session) => session.id === request.webRtcSessionId)) {
207
- throw new StatusResponseError(`WebRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
219
+ throw new StatusResponseError(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: webRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
208
220
  }
209
- device.log.info(`Received ${request.iceCandidates.length} ICE candidate(s) for session ${request.webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
221
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: received ${request.iceCandidates.length} ICE candidate(s) for session ${request.webRtcSessionId} (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
210
222
  const webRtcPeer = this.internal.sessions.get(request.webRtcSessionId);
211
223
  if (webRtcPeer) {
212
224
  for (const [index, candidate] of request.iceCandidates.entries()) {
213
225
  const startedAt = Date.now();
214
- device.log.debug(`Applying ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
226
+ device.log.debug(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: applying ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
215
227
  `(mid=${candidate.sdpMid ?? 'null'}, mLine=${candidate.sdpmLineIndex ?? 'null'}, endOfCandidates=${candidate.candidate.trim() === ''}) ` +
216
228
  `(endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
217
229
  try {
218
230
  await Promise.race([
219
231
  webRtcPeer.addIceCandidate(candidate.candidate, candidate.sdpMid, candidate.sdpmLineIndex),
220
- new Promise((_resolve, reject) => setTimeout(() => reject(new Error(`ICE candidate apply timeout after ${ICE_CANDIDATE_APPLY_TIMEOUT_MS}ms`)), ICE_CANDIDATE_APPLY_TIMEOUT_MS)),
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)),
221
233
  ]);
222
- device.log.debug(`Applied ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
234
+ device.log.debug(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: applied ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} ` +
223
235
  `in ${Date.now() - startedAt}ms (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
224
236
  }
225
237
  catch (error) {
226
- device.log.warn(`Failed ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} after ${Date.now() - startedAt}ms ` +
238
+ device.log.warn(`MatterbridgeWebRtcTransportProviderServer.provideIceCandidates: failed ICE candidate ${index + 1}/${request.iceCandidates.length} for session ${request.webRtcSessionId} after ${Date.now() - startedAt}ms ` +
227
239
  `(endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}): ${String(error)}`);
228
240
  }
229
241
  }
@@ -232,7 +244,7 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
232
244
  async endSession(request) {
233
245
  const device = this.endpoint.stateOf(MatterbridgeServer);
234
246
  if (!this.state.currentSessions.some((session) => session.id === request.webRtcSessionId)) {
235
- throw new StatusResponseError(`WebRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
247
+ throw new StatusResponseError(`MatterbridgeWebRtcTransportProviderServer.endSession: webRTC session ${request.webRtcSessionId} is not present in currentSessions`, Status.NotFound);
236
248
  }
237
249
  this.state.currentSessions = this.state.currentSessions.filter((session) => session.id !== request.webRtcSessionId);
238
250
  const webRtcPeer = this.internal.sessions.get(request.webRtcSessionId);
@@ -240,11 +252,12 @@ export class MatterbridgeWebRtcTransportProviderServer extends WebRtcTransportPr
240
252
  this.internal.sessions.delete(request.webRtcSessionId);
241
253
  await webRtcPeer.close();
242
254
  }
243
- device.log.info(`Ended WebRTC session ${request.webRtcSessionId} (reason ${request.reason}) (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
255
+ device.log.info(`MatterbridgeWebRtcTransportProviderServer.endSession: ended webRTC session ${request.webRtcSessionId} (reason ${request.reason}) (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})`);
244
256
  }
245
257
  }
246
258
  (function (MatterbridgeWebRtcTransportProviderServer) {
247
259
  class Internal {
260
+ nextWebRtcSessionId = 0;
248
261
  sessions = new Map();
249
262
  }
250
263
  MatterbridgeWebRtcTransportProviderServer.Internal = Internal;
package/dist/module.js CHANGED
@@ -21,10 +21,27 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
21
21
  throw new Error(`This plugin requires Matterbridge version >= "3.10.0". Please update Matterbridge to the latest version in the frontend.`);
22
22
  }
23
23
  this.log.info(`Initializing platform ${this.config.name}...`);
24
+ this.config.whiteList ??= [];
25
+ this.config.blackList ??= [];
26
+ this.config.generator ??= 'none';
27
+ this.config.webcamResolution ??= '640x480';
28
+ this.config.webcamBitrate ??= 1000;
29
+ this.config.animationInterval ??= 60;
30
+ this.config.debug ??= false;
31
+ this.config.unregisterOnShutdown ??= false;
32
+ process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE = this.config.generator;
33
+ if (this.config.webcam === undefined)
34
+ delete process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE;
35
+ else
36
+ process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE = this.config.webcam;
37
+ process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION = this.config.webcamResolution;
38
+ process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE = String(this.config.webcamBitrate);
24
39
  this.log.info(`Platform ${this.config.name} initialized successfully`);
25
40
  }
26
41
  async onStart(reason) {
27
42
  this.log.info(`Starting platform ${this.config.name} with reason: ${reason ?? 'No reason provided'}...`);
43
+ await this.ready;
44
+ await this.clearSelect();
28
45
  const exampleChime = new Chime('Chime', 'CHIME-001', {
29
46
  identifyTime: 5,
30
47
  identifyType: Identify.IdentifyType.AudibleBeep,
@@ -37,68 +54,58 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
37
54
  selectedChime: 0,
38
55
  enabled: true,
39
56
  });
40
- await this.registerDevice(exampleChime);
57
+ await this.addDevice(exampleChime);
41
58
  const exampleDoorbell = new Doorbell('Doorbell', 'DOORBELL-001', {
42
59
  identifyTime: 5,
43
60
  identifyType: Identify.IdentifyType.VisibleIndicator,
44
61
  powerSourceType: 'Replaceable',
45
62
  });
46
- await this.registerDevice(exampleDoorbell);
63
+ await this.addDevice(exampleDoorbell);
47
64
  const exampleAudioDoorbell = new AudioDoorbell('Audio Doorbell', 'AUDIODOORBELL-001', {
48
65
  identifyTime: 5,
49
66
  identifyType: Identify.IdentifyType.VisibleIndicator,
50
67
  powerSourceType: 'Replaceable',
51
68
  });
52
- await this.registerDevice(exampleAudioDoorbell);
69
+ await this.addDevice(exampleAudioDoorbell);
53
70
  const exampleSnapshotCamera = new SnapshotCamera('Snapshot Camera', 'SNAPSHOTCAMERA-001', {
54
71
  identifyTime: 5,
55
72
  identifyType: Identify.IdentifyType.VisibleIndicator,
56
73
  powerSourceType: 'Wired',
57
74
  });
58
- await this.registerDevice(exampleSnapshotCamera);
75
+ await this.addDevice(exampleSnapshotCamera);
59
76
  const exampleCamera = new Camera('Camera', 'CAMERA-001');
60
- await this.registerDevice(exampleCamera);
77
+ await this.addDevice(exampleCamera);
61
78
  const exampleFloodlightCamera = new FloodlightCamera('Floodlight Camera', 'FLOODLIGHTCAMERA-001', {
62
79
  powerSourceType: 'Wired',
63
80
  cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator },
64
81
  lightOptions: { name: 'Floodlight' },
65
82
  });
66
- await this.registerDevice(exampleFloodlightCamera);
83
+ await this.addDevice(exampleFloodlightCamera);
67
84
  const serverChime = new Chime('Server Chime', 'SERVER-CHIME-001', { mode: 'server' });
68
- await this.registerDevice(serverChime);
85
+ await this.addDevice(serverChime);
69
86
  const serverDoorbell = new Doorbell('Server Doorbell', 'SERVER-DOORBELL-001', { mode: 'server' });
70
- await this.registerDevice(serverDoorbell);
87
+ await this.addDevice(serverDoorbell);
71
88
  this.log.info(`Platform ${this.config.name} started successfully`);
72
89
  }
73
90
  async onConfigure() {
74
91
  await super.onConfigure();
75
92
  this.log.info(`Configuring platform ${this.config.name}...`);
76
93
  const exampleChime = this.getDeviceById('Chime-CHIME-001');
77
- if (!exampleChime)
78
- throw new Error(`Chime device not found. Please ensure the device is registered before configuration.`);
79
- await exampleChime.setCluster(PowerSource, { batChargeLevel: PowerSource.BatChargeLevel.Ok, batPercentRemaining: 150, batQuantity: 2, batReplacementDescription: 'AA' }, exampleChime.log);
80
- await exampleChime.setAttribute(ChimeCluster, 'enabled', true, exampleChime.log);
81
- const exampleDoorbell = this.getDeviceById('Doorbell-DOORBELL-001');
82
- if (!exampleDoorbell)
83
- throw new Error(`Doorbell device not found. Please ensure the device is registered before configuration.`);
84
- const exampleAudioDoorbell = this.getDeviceById('AudioDoorbell-AUDIODOORBELL-001');
85
- if (!exampleAudioDoorbell)
86
- throw new Error(`Audio doorbell device not found. Please ensure the device is registered before configuration.`);
87
- const exampleSnapshotCamera = this.getDeviceById('SnapshotCamera-SNAPSHOTCAMERA-001');
88
- if (!exampleSnapshotCamera)
89
- throw new Error(`Snapshot camera device not found. Please ensure the device is registered before configuration.`);
90
- const exampleCamera = this.getDeviceById('Camera-CAMERA-001');
91
- if (!exampleCamera)
92
- throw new Error(`Camera device not found. Please ensure the device is registered before configuration.`);
93
- const exampleFloodlightCamera = this.getDeviceById('FloodlightCamera-FLOODLIGHTCAMERA-001');
94
- if (!exampleFloodlightCamera)
95
- throw new Error(`Floodlight camera device not found. Please ensure the device is registered before configuration.`);
94
+ await exampleChime?.setCluster(PowerSource, { batChargeLevel: PowerSource.BatChargeLevel.Ok, batPercentRemaining: 150, batQuantity: 2, batReplacementDescription: 'AA' }, exampleChime.log);
95
+ await exampleChime?.setAttribute(ChimeCluster, 'enabled', true, exampleChime.log);
96
96
  if (this.config.animationInterval > 0) {
97
97
  clearInterval(this.animationInterval);
98
98
  this.animationInterval = setInterval(() => void this.animationHandler(), this.config.animationInterval * 1000);
99
99
  }
100
100
  this.log.info(`Platform ${this.config.name} configured successfully`);
101
101
  }
102
+ async addDevice(device) {
103
+ if (device.serialNumber && device.deviceName) {
104
+ this.setSelectDevice(device.serialNumber, device.deviceName);
105
+ if (this.validateDevice([device.deviceName, device.serialNumber]))
106
+ await this.registerDevice(device);
107
+ }
108
+ }
102
109
  async animationHandler() {
103
110
  this.animationPhase = this.animationPhase + 1;
104
111
  this.animationPhase = this.animationPhase > 10 ? 0 : this.animationPhase;
@@ -3,23 +3,42 @@ import { createSocket } from 'node:dgram';
3
3
  import { constants } from 'node:fs';
4
4
  import { access, readdir } from 'node:fs/promises';
5
5
  import path from 'node:path';
6
+ import { AnsiLogger, MAGENTA } from 'matterbridge/logger';
6
7
  import { RTCPeerConnection, RTCRtpCodecParameters, useH264, useOPUS, usePCMU, useVP8 } from 'werift';
7
8
  import { navigator } from 'werift/nonstandard';
8
9
  export class WeriftWebRtcSession {
9
10
  peerConnection;
10
- logger;
11
- label;
11
+ log;
12
12
  testVideoGenerator;
13
13
  testVideoUdpDisposer;
14
14
  testVideoAttached = false;
15
- constructor(logger, label = 'WebRTC session') {
16
- this.peerConnection = new RTCPeerConnection({ codecs: { audio: [useOPUS(), usePCMU()], video: [useVP8(), useH264()] } });
17
- this.logger = logger;
18
- this.label = label;
19
- this.log('debug', 'Created RTCPeerConnection');
20
- }
21
- log(level, message) {
22
- this.logger?.(level, `${this.label}: ${message}`);
15
+ constructor(webRtcSessionId) {
16
+ this.peerConnection = new RTCPeerConnection({ codecs: { audio: [useOPUS(), usePCMU()], video: [useH264(), useVP8()] } });
17
+ this.log = new AnsiLogger({ logName: `WebRTC session ${webRtcSessionId}`, logLevel: "debug", logNameColor: MAGENTA, logTimestampFormat: 4 });
18
+ this.peerConnection.iceGatheringStateChange.subscribe((state) => {
19
+ this.log.info(`ICE gathering state: ${state}`);
20
+ });
21
+ this.peerConnection.onIceCandidate.subscribe((candidate) => {
22
+ this.log.debug(candidate ? `Gathered local ICE candidate: ${candidate.candidate}` : 'ICE candidate gathering completed');
23
+ });
24
+ this.peerConnection.iceConnectionStateChange.subscribe((state) => {
25
+ this.log.info(`ICE connection state: ${state}`);
26
+ if (state === 'connected' || state === 'completed') {
27
+ for (const transport of this.peerConnection.iceTransports) {
28
+ const pair = transport.connection.nominated;
29
+ if (!pair)
30
+ continue;
31
+ const local = pair.localCandidate;
32
+ const remote = pair.remoteCandidate;
33
+ this.log.info(`Selected ICE candidate pair: local=${local.host}:${local.port} (${local.type}/${local.transport}) ` +
34
+ `remote=${remote.host}:${remote.port} (${remote.type}/${remote.transport})`);
35
+ }
36
+ }
37
+ });
38
+ this.peerConnection.connectionStateChange.subscribe((state) => {
39
+ this.log.info(`Peer connection state: ${state}`);
40
+ });
41
+ this.log.debug(`Created RTCPeerConnection with codecs: audio=[OPUS, PCMU], video=[H264, VP8] for session ${webRtcSessionId}`);
23
42
  }
24
43
  summarizeSdp(sdp) {
25
44
  const mediaKinds = sdp
@@ -99,8 +118,10 @@ export class WeriftWebRtcSession {
99
118
  continue;
100
119
  }
101
120
  }
102
- if (await this.hasCommand(candidate))
121
+ if (await this.hasCommand(candidate)) {
122
+ this.log.debug(`Found ${command} in ${candidate}`);
103
123
  return candidate;
124
+ }
104
125
  }
105
126
  return undefined;
106
127
  }
@@ -109,13 +130,8 @@ export class WeriftWebRtcSession {
109
130
  const socket = createSocket('udp4');
110
131
  socket.once('error', reject);
111
132
  socket.bind(0, '127.0.0.1', () => {
112
- const address = socket.address();
113
- if (typeof address === 'string') {
114
- socket.close();
115
- reject(new Error('Failed to allocate UDP port'));
116
- return;
117
- }
118
- const port = address.port;
133
+ const port = socket.address().port;
134
+ this.log.debug(`Allocated free UDP port ${port}`);
119
135
  socket.close(() => resolve(port));
120
136
  });
121
137
  });
@@ -128,72 +144,104 @@ export class WeriftWebRtcSession {
128
144
  const mimeType = codec.mimeType.toLowerCase();
129
145
  return mimeType === 'video/vp8' || mimeType === 'video/h264';
130
146
  });
131
- if (preferredCodec)
147
+ if (preferredCodec) {
148
+ this.log.debug(`Preferred injectable video codec: ${preferredCodec.mimeType}`);
132
149
  return preferredCodec;
150
+ }
133
151
  }
152
+ this.log.debug('No preferred injectable video codec (VP8/H264) negotiated on any video transceiver');
134
153
  return undefined;
135
154
  }
136
155
  static SUPPORTED_WEBCAM_RESOLUTIONS = ['640x480', '1280x720', '1920x1080'];
137
- static BITRATE_KBPS_BY_RESOLUTION = {
138
- '640x480': 1000,
139
- '1280x720': 2500,
140
- '1920x1080': 2000,
141
- };
156
+ static DEFAULT_BITRATE_KBPS = 1000;
157
+ getConfiguredWebcamBitrate() {
158
+ const configured = process.env.MATTERBRIDGE_CAMERA_WEBCAM_BITRATE;
159
+ if (!configured)
160
+ return WeriftWebRtcSession.DEFAULT_BITRATE_KBPS;
161
+ const bitrateKbps = Number(configured);
162
+ if (!Number.isFinite(bitrateKbps) || bitrateKbps <= 0) {
163
+ this.log.warn(`Invalid MATTERBRIDGE_CAMERA_WEBCAM_BITRATE "${configured}"; falling back to ${WeriftWebRtcSession.DEFAULT_BITRATE_KBPS}kbps`);
164
+ return WeriftWebRtcSession.DEFAULT_BITRATE_KBPS;
165
+ }
166
+ return bitrateKbps;
167
+ }
142
168
  getConfiguredWebcamResolution(requestedResolution) {
143
169
  const [defaultResolution] = WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS;
144
170
  if (requestedResolution) {
145
- if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requestedResolution))
171
+ if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requestedResolution)) {
172
+ this.log.debug(`Using requested webcam capture resolution ${requestedResolution}`);
146
173
  return requestedResolution;
147
- 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`);
174
+ }
175
+ 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`);
148
176
  }
149
177
  const requested = process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION;
150
- if (!requested)
178
+ if (!requested) {
179
+ this.log.debug(`Using default webcam capture resolution ${defaultResolution}`);
151
180
  return defaultResolution;
152
- if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requested))
181
+ }
182
+ if (WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.includes(requested)) {
183
+ this.log.debug(`Using MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION ${requested}`);
153
184
  return requested;
154
- this.log('warn', `Unsupported MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION "${requested}" (supported: ${WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.join(', ')}); falling back to ${defaultResolution}`);
185
+ }
186
+ this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION "${requested}" (supported: ${WeriftWebRtcSession.SUPPORTED_WEBCAM_RESOLUTIONS.join(', ')}); falling back to ${defaultResolution}`);
155
187
  return defaultResolution;
156
188
  }
157
- buildFfmpegVideoInputArgs(requestedResolution) {
189
+ getConfiguredVideoSource() {
190
+ const source = process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE?.trim().toLowerCase() ?? 'none';
191
+ switch (source) {
192
+ case 'none':
193
+ case 'test':
194
+ case 'webcam':
195
+ return source;
196
+ default:
197
+ this.log.warn(`Unsupported MATTERBRIDGE_CAMERA_VIDEO_SOURCE "${source}" (supported: test, webcam, none); falling back to none`);
198
+ return 'none';
199
+ }
200
+ }
201
+ buildFfmpegVideoInputArgs(videoSource, requestedResolution) {
158
202
  const testPatternInput = {
159
- args: ['-re', '-stream_loop', '-1', '-f', 'lavfi', '-i', 'smptebars=size=640x480:rate=10'],
160
- description: 'synthetic SMPTE bars test',
161
- bitrateKbps: WeriftWebRtcSession.BITRATE_KBPS_BY_RESOLUTION['640x480'],
203
+ args: ['-re', '-f', 'lavfi', '-i', 'testsrc=size=640x480:rate=10'],
204
+ description: 'synthetic moving test pattern',
205
+ bitrateKbps: WeriftWebRtcSession.DEFAULT_BITRATE_KBPS,
162
206
  };
163
- if (process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE?.toLowerCase() !== 'webcam')
207
+ if (videoSource === 'test') {
208
+ this.log.debug(`Test pattern params: resolution=640x480, description="${testPatternInput.description}", bitrateKbps=${testPatternInput.bitrateKbps}`);
164
209
  return testPatternInput;
210
+ }
165
211
  const device = process.env.MATTERBRIDGE_CAMERA_WEBCAM_DEVICE;
166
212
  if (!device) {
167
- this.log('warn', 'MATTERBRIDGE_CAMERA_VIDEO_SOURCE=webcam requires MATTERBRIDGE_CAMERA_WEBCAM_DEVICE to be set; falling back to the synthetic test video');
213
+ this.log.warn('MATTERBRIDGE_CAMERA_VIDEO_SOURCE=webcam requires MATTERBRIDGE_CAMERA_WEBCAM_DEVICE to be set; falling back to the synthetic test video');
168
214
  return testPatternInput;
169
215
  }
170
- const resolution = this.getConfiguredWebcamResolution(requestedResolution);
171
- const bitrateKbps = WeriftWebRtcSession.BITRATE_KBPS_BY_RESOLUTION[resolution];
216
+ const resolution = process.env.MATTERBRIDGE_CAMERA_WEBCAM_RESOLUTION ?? this.getConfiguredWebcamResolution(requestedResolution);
217
+ const bitrateKbps = this.getConfiguredWebcamBitrate();
172
218
  const description = `local webcam (${device}, ${resolution})`;
219
+ this.log.debug(`Webcam capture params: device=${device}, resolution=${resolution}, description="${description}", bitrateKbps=${bitrateKbps}`);
173
220
  switch (process.platform) {
174
221
  case 'linux':
175
- return { args: ['-f', 'v4l2', '-input_format', 'yuyv422', '-video_size', resolution, '-framerate', '30', '-i', device], description, bitrateKbps };
222
+ return { args: ['-f', 'v4l2', '-video_size', resolution, '-framerate', '30', '-i', device], description, bitrateKbps };
176
223
  case 'darwin':
177
224
  return { args: ['-f', 'avfoundation', '-video_size', resolution, '-framerate', '30', '-i', device], description, bitrateKbps };
178
225
  case 'win32':
179
226
  return { args: ['-f', 'dshow', '-video_size', resolution, '-framerate', '30', '-i', `video=${device}`], description, bitrateKbps };
180
227
  default:
181
- this.log('warn', `Webcam capture via ffmpeg is not supported on platform "${process.platform}"; falling back to the synthetic test video`);
228
+ this.log.warn(`Webcam capture via ffmpeg is not supported on platform "${process.platform}"; falling back to the synthetic test video`);
182
229
  return testPatternInput;
183
230
  }
184
231
  }
185
- async ensureTestVideoTrack(codec, videoResolution) {
232
+ async generateVideoTrack(codec, videoResolution) {
186
233
  if (this.testVideoAttached)
187
234
  return;
188
- if (process.env.MATTERBRIDGE_CAMERA_DISABLE_TEST_VIDEO === '1') {
189
- this.log('info', 'Test video injection disabled by MATTERBRIDGE_CAMERA_DISABLE_TEST_VIDEO=1');
235
+ const videoSource = this.getConfiguredVideoSource();
236
+ if (videoSource === 'none') {
237
+ this.log.debug('Video injection disabled by MATTERBRIDGE_CAMERA_VIDEO_SOURCE=none');
190
238
  return;
191
239
  }
192
- const videoInput = this.buildFfmpegVideoInputArgs(videoResolution);
193
- this.log('debug', `Attempting to attach ${videoInput.description} video track`);
240
+ const videoInput = this.buildFfmpegVideoInputArgs(videoSource, videoResolution);
241
+ this.log.debug(`Attempting to attach ${videoInput.description} video track at ${videoInput.bitrateKbps}kbps`);
194
242
  const ffmpegCommand = await this.resolveCommand('ffmpeg');
195
243
  if (!ffmpegCommand) {
196
- this.log('warn', 'Cannot inject video stream: missing dependency ffmpeg');
244
+ this.log.warn('Cannot inject video stream: missing dependency ffmpeg');
197
245
  return;
198
246
  }
199
247
  const selectedMimeType = (codec?.mimeType ?? 'video/vp8').toLowerCase();
@@ -209,7 +257,7 @@ export class WeriftWebRtcSession {
209
257
  const encoderArgs = selectedMimeType === 'video/h264'
210
258
  ? ['-c:v', 'libx264', '-preset', 'ultrafast', '-tune', 'zerolatency', '-pix_fmt', 'yuv420p', '-g', '20', '-b:v', bitrate, '-maxrate', bitrate, '-bufsize', bitrate]
211
259
  : ['-c:v', 'libvpx', '-deadline', 'realtime', '-cpu-used', '4', '-pix_fmt', 'yuv420p', '-g', '20', '-b:v', bitrate, '-maxrate', bitrate, '-bufsize', bitrate];
212
- const generator = spawn(ffmpegCommand, [
260
+ const ffmpegArgs = [
213
261
  '-hide_banner',
214
262
  '-loglevel',
215
263
  'error',
@@ -221,17 +269,19 @@ export class WeriftWebRtcSession {
221
269
  '-payload_type',
222
270
  String(selectedPayloadType),
223
271
  `rtp://127.0.0.1:${udpPort}`,
224
- ]);
272
+ ];
273
+ this.log.debug(`Spawning ffmpeg: ${ffmpegCommand} ${ffmpegArgs.join(' ')}`);
274
+ const generator = spawn(ffmpegCommand, ffmpegArgs);
225
275
  generator.once('error', (error) => {
226
- this.log('warn', `Video generator failed: ${error instanceof Error ? error.message : String(error)}`);
276
+ this.log.warn(`Video generator failed: ${error instanceof Error ? error.message : String(error)}`);
227
277
  });
228
278
  this.testVideoUdpDisposer = disposer;
229
279
  this.testVideoGenerator = generator;
230
280
  this.testVideoAttached = true;
231
- this.log('info', `Attached ${videoInput.description} video track (ffmpeg=${ffmpegCommand}, codec=${selectedMimeType}, payloadType=${selectedPayloadType}, sourcePort=${udpPort})`);
281
+ this.log.info(`Attached ${videoInput.description} video track (ffmpeg=${ffmpegCommand}, codec=${selectedMimeType}, payloadType=${selectedPayloadType}, sourcePort=${udpPort})`);
232
282
  }
233
283
  catch (error) {
234
- this.log('warn', `Failed to attach ${videoInput.description} video track: ${error instanceof Error ? error.message : String(error)}`);
284
+ this.log.warn(`Failed to attach ${videoInput.description} video track: ${error instanceof Error ? error.message : String(error)}`);
235
285
  }
236
286
  }
237
287
  preferVideoCodecOnTransceivers(mimeType) {
@@ -246,7 +296,7 @@ export class WeriftWebRtcSession {
246
296
  adjustedTransceivers += 1;
247
297
  }
248
298
  if (adjustedTransceivers > 0) {
249
- this.log('info', `Preferred ${mimeType.toUpperCase()} codecs on ${adjustedTransceivers} video transceiver(s)`);
299
+ this.log.debug(`Preferred ${mimeType.toUpperCase()} codecs on ${adjustedTransceivers} video transceiver(s)`);
250
300
  }
251
301
  }
252
302
  cleanupTestVideoArtifacts() {
@@ -259,16 +309,16 @@ export class WeriftWebRtcSession {
259
309
  this.testVideoAttached = false;
260
310
  }
261
311
  async createOffer(options) {
262
- this.log('debug', `createOffer requested (video=${options.video}, audio=${options.audio})`);
312
+ this.log.debug(`CreateOffer requested (video=${options.video}, audio=${options.audio}, videoResolution=${options.videoResolution ?? 'undefined'})`);
263
313
  if (options.video) {
264
314
  const preferredCodec = this.getPreferredInjectableVideoCodec();
265
315
  if (preferredCodec) {
266
316
  this.preferVideoCodecOnTransceivers(preferredCodec.mimeType.toLowerCase());
267
317
  }
268
318
  else {
269
- this.log('warn', 'No injectable video codec available on negotiated transceivers (supported: VP8, H264)');
319
+ this.log.warn('No injectable video codec available on negotiated transceivers (supported: VP8, H264)');
270
320
  }
271
- await this.ensureTestVideoTrack(preferredCodec, options.videoResolution);
321
+ await this.generateVideoTrack(preferredCodec, options.videoResolution);
272
322
  if (!this.testVideoAttached)
273
323
  this.peerConnection.addTransceiver('video', { direction: 'sendonly' });
274
324
  }
@@ -277,23 +327,23 @@ export class WeriftWebRtcSession {
277
327
  const offer = await this.peerConnection.createOffer();
278
328
  await this.peerConnection.setLocalDescription(offer);
279
329
  const sdp = this.peerConnection.localDescription.sdp;
280
- this.log('info', `Created local SDP offer (${this.summarizeSdp(sdp)})`);
330
+ this.log.info(`Created local SDP offer (${this.summarizeSdp(sdp)})`);
281
331
  return sdp;
282
332
  }
283
333
  async createAnswer(offerSdp, videoResolution) {
284
- this.log('debug', `createAnswer requested for remote offer (${this.summarizeSdp(offerSdp)})`);
334
+ this.log.debug(`CreateAnswer requested for remote offer (${this.summarizeSdp(offerSdp)}, videoResolution=${videoResolution ?? 'undefined'})`);
285
335
  await this.peerConnection.setRemoteDescription({ type: 'offer', sdp: offerSdp });
286
336
  const hasVideoTransceiver = this.peerConnection.getTransceivers().some((transceiver) => transceiver.kind === 'video');
287
- this.log('debug', `Remote offer created video transceiver: ${hasVideoTransceiver}`);
337
+ this.log.debug(`Remote offer created video transceiver: ${hasVideoTransceiver}`);
288
338
  if (hasVideoTransceiver) {
289
339
  const preferredCodec = this.getPreferredInjectableVideoCodec();
290
340
  if (preferredCodec) {
291
341
  this.preferVideoCodecOnTransceivers(preferredCodec.mimeType.toLowerCase());
292
342
  }
293
343
  else {
294
- this.log('warn', 'No injectable video codec available on negotiated transceivers (supported: VP8, H264)');
344
+ this.log.warn('No injectable video codec available on negotiated transceivers (supported: VP8, H264)');
295
345
  }
296
- await this.ensureTestVideoTrack(preferredCodec, videoResolution);
346
+ await this.generateVideoTrack(preferredCodec, videoResolution);
297
347
  }
298
348
  for (const transceiver of this.peerConnection.getTransceivers()) {
299
349
  transceiver.setDirection('sendonly');
@@ -301,22 +351,22 @@ export class WeriftWebRtcSession {
301
351
  const answer = await this.peerConnection.createAnswer();
302
352
  await this.peerConnection.setLocalDescription(answer);
303
353
  const sdp = this.peerConnection.localDescription.sdp;
304
- this.log('info', `Created local SDP answer (${this.summarizeSdp(sdp)})`);
354
+ this.log.info(`Created local SDP answer (${this.summarizeSdp(sdp)})`);
305
355
  return sdp;
306
356
  }
307
357
  async applyAnswer(answerSdp) {
308
- this.log('debug', `applyAnswer requested (${this.summarizeSdp(answerSdp)})`);
358
+ this.log.debug(`ApplyAnswer requested (${this.summarizeSdp(answerSdp)})`);
309
359
  await this.peerConnection.setRemoteDescription({ type: 'answer', sdp: answerSdp });
310
- this.log('info', `Remote SDP answer applied (signalingState=${this.peerConnection.signalingState})`);
360
+ this.log.info(`Remote SDP answer applied (signalingState=${this.peerConnection.signalingState})`);
311
361
  }
312
362
  async addIceCandidate(candidate, sdpMid, sdpMLineIndex) {
313
- this.log('debug', `Applying ICE candidate (mid=${sdpMid ?? 'null'}, mLine=${sdpMLineIndex ?? 'null'}, endOfCandidates=${candidate.trim() === ''})`);
363
+ this.log.debug(`Applying ICE candidate (mid=${sdpMid ?? 'null'}, mLine=${sdpMLineIndex ?? 'null'}, endOfCandidates=${candidate.trim() === ''})`);
314
364
  await this.peerConnection.addIceCandidate({ candidate, sdpMid: sdpMid ?? undefined, sdpMLineIndex: sdpMLineIndex ?? undefined });
315
365
  }
316
366
  async close() {
317
- this.log('debug', 'Closing RTCPeerConnection');
367
+ this.log.debug('Closing RTCPeerConnection');
318
368
  await this.peerConnection.close();
319
369
  this.cleanupTestVideoArtifacts();
320
- this.log('info', `RTCPeerConnection closed (connectionState=${this.peerConnection.connectionState})`);
370
+ this.log.info(`RTCPeerConnection closed (connectionState=${this.peerConnection.connectionState})`);
321
371
  }
322
372
  }
@@ -3,6 +3,9 @@
3
3
  "type": "DynamicPlatform",
4
4
  "whiteList": [],
5
5
  "blackList": [],
6
+ "generator": "none",
7
+ "webcamResolution": "640x480",
8
+ "webcamBitrate": 1000,
6
9
  "animationInterval": 60,
7
10
  "debug": false,
8
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": [],
5
+ "required": ["generator", "webcamResolution"],
6
6
  "properties": {
7
7
  "name": {
8
8
  "description": "Plugin Name",
@@ -42,6 +42,31 @@
42
42
  "type": "number",
43
43
  "default": 60
44
44
  },
45
+ "generator": {
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.",
48
+ "type": "string",
49
+ "enum": ["none", "test", "webcam"],
50
+ "default": "none"
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.",
55
+ "type": "string"
56
+ },
57
+ "webcamResolution": {
58
+ "title": "Webcam Resolution",
59
+ "description": "Resolution used when capturing from the configured webcam.",
60
+ "type": "string",
61
+ "enum": ["640x480", "1280x720", "1920x1080"],
62
+ "default": "640x480"
63
+ },
64
+ "webcamBitrate": {
65
+ "title": "Webcam Bitrate",
66
+ "description": "Target encoder bitrate (kbps) used when capturing from the configured webcam, regardless of resolution.",
67
+ "type": "number",
68
+ "default": 1000
69
+ },
45
70
  "debug": {
46
71
  "title": "Enable Debug",
47
72
  "description": "Enable the debug for the plugin (development only)",
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.6-dev-20260721-4f7106a",
3
+ "version": "0.0.6",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "matterbridge-example-camera",
9
- "version": "0.0.6-dev-20260721-4f7106a",
9
+ "version": "0.0.6",
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.6-dev-20260721-4f7106a",
3
+ "version": "0.0.6",
4
4
  "description": "Matterbridge camera example plugin",
5
5
  "author": "https://github.com/Luligu",
6
6
  "license": "Apache-2.0",
Binary file