matterbridge-example-camera 0.2.2-dev-20261010-1ee5e62 → 1.0.0-dev-20261018-bf79d0b

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
@@ -30,14 +30,19 @@ If you like this project and find it useful, please consider giving it a star on
30
30
 
31
31
  <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
32
32
 
33
- ## [0.2.2] - Dev branch
33
+ ## [1.0.0] - Dev branch
34
34
 
35
35
  ### Breaking changes
36
36
 
37
- - [matterbridge]: Require matterbridge v.3.10.10 with matter v.1.6.0.
37
+ - [matterbridge]: Require matterbridge v.3.10.15 with matter v.1.6.0.
38
+ - [camera]: Use the matterbridge camera stack (`matterbridge/devices/camera`) and remove the local copy in `src/behaviors` and `src/devices` with its tests.
39
+ - [config]: Pass the media options to the devices as `weriftOfferOptions` instead of the `MATTERBRIDGE_CAMERA_*` environment variables. The test audio is now a generated tone, and a `webcam`/`rtsp`/`microphone` generator without a source injects no track instead of falling back to the test source.
40
+ - [config]: Default `videoGenerator` and `audioGenerator` to `test`, so live view and snapshots work out of the box (requires ffmpeg).
38
41
 
39
42
  ### Added
40
43
 
44
+ - [ffmpeg]: Add the `autoInstallFfmpeg` option (Docker only, enabled by default) and the `installFfmpeg` button, as in matterbridge-camera and matterbridge-webcam.
45
+ - [timeSync]: Add `MatterbridgeTimeSynchronizationServer`, a Time Synchronization server backed by the host clock, and use it in `addRootNodeCamera`.
41
46
  - [devcontainer]: Add [`Dev Container`](.devcontainer/README.md) v.2.2.0 with dual Node and Bun runtime support.
42
47
  - [agents]: Add a [`shared setup`](.agents/README.md) for all agents: OpenAI Codex, Claude Code, GitHub Copilot and Google Gemini / Antigravity.
43
48
  - [agents]: Add [`commit message instructions`](.github/commit-message-instructions.md) v.1.0.0 for the VS Code Copilot "Generate Commit Message" button (Conventional Commits).
@@ -46,6 +51,10 @@ If you like this project and find it useful, please consider giving it a star on
46
51
  ### Changed
47
52
 
48
53
  - [test]: Migrate tests from `matterbridge/vitest-utils` to the unified `matterbridge/test-utils`.
54
+ - [workflows]: Build and test against the matterbridge `dev` branch (`automator.workflow`).
55
+ - [webrtc]: Close the WebRTC sessions of the plugin devices on shutdown with `closeWebRtcSessions`.
56
+ - [rootNode]: Set the first TimeZone entry with a ValidAt of 0 (the Matter epoch) as required, and allow 2 TimeZone and DSTOffset entries.
57
+ - [chip]: Keep only the generic composition, conformance and default warnings tests in `chipTests.json`: the camera clusters are tested in matterbridge.
49
58
  - [styleguide]: Update [`STYLEGUIDE.md`](STYLEGUIDE.md) to v.1.1.0: align it with the lint and format config and add the Commit Messages and Changelog sections.
50
59
  - [vscode]: Update `.vscode/settings.json` to v.1.0.15: configure commit message instructions, exclude templates from Vitest discovery and refine terminal command approvals.
51
60
  - [agents]: Update `.antigravity/settings.json` to v.1.0.5: allow read-only Git commands.
package/README.md CHANGED
@@ -13,7 +13,6 @@
13
13
  [![TypeScript Native](https://img.shields.io/badge/TypeScript_Native-3178C6?logo=typescript&logoColor=white)](https://github.com/microsoft/typescript-go)
14
14
  [![ESM](https://img.shields.io/badge/ESM-Node.js-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
15
15
  [![matterbridge.io](https://img.shields.io/badge/matterbridge.io-online-brightgreen)](https://matterbridge.io)
16
- ![under development](https://img.shields.io/badge/status-under%20development-orange)
17
16
 
18
17
  [![powered by](https://img.shields.io/badge/powered%20by-matterbridge-blue)](https://www.npmjs.com/package/matterbridge)
19
18
  [![powered by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
@@ -33,16 +32,21 @@ Thanks to [Ludovic BOUÉ](https://github.com/lboue) for his contributions to thi
33
32
  ## Setup
34
33
 
35
34
  - `src/module.ts` will create all device types for easy testing;
36
- - `src/devices/` contains all single class device types (it will be moved directly in matterbridge core package).
37
- - `src/behaviors/` contains all required behaviors (it will be moved directly in matterbridge core package).
35
+ - the device types and the WebRTC stack come from matterbridge (`matterbridge/devices/camera`), see the [Matterbridge cameras](https://matterbridge.io/Camera.html) guide;
36
+ - `src/rootNode.ts` adds the Root Node clusters a Camera requires (Power Source, Time Synchronization, TLS Certificate Management and TLS Client Management) to a `mode: 'server'` Camera;
37
+ - `src/timeSynchronizationServer.ts` is the Time Synchronization server used there, with the TimeSyncClient, NtpClient and TimeZone features. It reports the host clock (MillisecondsGranularity) and implements SetTrustedTimeSource, SetDefaultNTP, SetTimeZone and SetDSTOffset with their validation and events; SetUTCTime is refused with TimeNotAccepted since the host clock is kept. The TLS clusters are still the empty matter.js servers.
38
38
 
39
39
  ## Requirements
40
40
 
41
- Requires Matterbridge `3.10.3` or later.
41
+ Requires Matterbridge `3.10.15` or later.
42
42
 
43
43
  Requires [`ffmpeg`](https://ffmpeg.org/) to be installed on the host or in the container. The resolver checks the system command and common installation directories on Linux, macOS, and Windows.
44
44
 
45
- Install it with the platform's package manager:
45
+ In Docker, enable the `autoInstallFfmpeg` option (enabled by default) and the plugin installs ffmpeg at start with `apk` or `apt-get` if it is not found. If you use more than one ffmpeg plugin (example camera, camera, webcam), enable it on only one of them: concurrent installs fail on the package manager lock.
46
+
47
+ The **Install ffmpeg (Linux only)** button installs ffmpeg on demand, including outside Docker. Matterbridge must run as root (or with passwordless sudo) on Linux with `apk` (Alpine) or `apt-get` (Debian/Ubuntu). The frontend reports the result; if ffmpeg is already installed, no installation is performed. On macOS and Windows, install ffmpeg manually.
48
+
49
+ Otherwise install it with the platform's package manager:
46
50
 
47
51
  ### Linux (Debian/Ubuntu)
48
52
 
@@ -181,7 +185,7 @@ Bind Server Doorbell to Server Chime with ![Matter Server Dashboard](screenshots
181
185
 
182
186
  `src/module.ts` registers exactly this pair for testing: `Server Intercom 1` (`mode: 'server'`, its own Matter node) and `Server Intercom 2` (`mode: 'server'`, its own Matter node) — commission both and follow the steps below to bind them together.
183
187
 
184
- Unlike a Doorbell/Chime pair, where only the Doorbell invokes commands on the Chime, an Intercom both hosts (server) and invokes (client) WebRtcTransportProvider and WebRtcTransportRequestor (see `#resolvePeerRequestorEndpoint` in `src/behaviors/webRtcTransportProviderServer.ts`). Once a peer invokes SolicitOffer/ProvideOffer on an Intercom's WebRtcTransportProvider, that Intercom resolves the caller's WebRtcTransportRequestor endpoint directly from the invoking peer's node id/fabric index carried by the command's CASE session — not via the Binding cluster — so the Offer/Answer "return leg" needs no binding of its own. Only the initiating invoke needs one.
188
+ Unlike a Doorbell/Chime pair, where only the Doorbell invokes commands on the Chime, an Intercom both hosts (server) and invokes (client) WebRtcTransportProvider and WebRtcTransportRequestor (see `#resolvePeerRequestorEndpoint` in matterbridge's `packages/core/src/behaviors/webRtcTransportProviderServer.ts`). Once a peer invokes SolicitOffer/ProvideOffer on an Intercom's WebRtcTransportProvider, that Intercom resolves the caller's WebRtcTransportRequestor endpoint directly from the invoking peer's node id/fabric index carried by the command's CASE session — not via the Binding cluster — so the Offer/Answer "return leg" needs no binding of its own. Only the initiating invoke needs one.
185
189
 
186
190
  So, to let either Server Intercom 1 or Server Intercom 2 start a call, on the fabric they share.
187
191
 
@@ -195,23 +199,23 @@ Bind Server Intercom 2 to Server Intercom 1 with ![Matter Server Dashboard](scre
195
199
 
196
200
  ## WebRTC video and audio injection
197
201
 
198
- `WeriftWebRtcSession` (see `src/behaviors/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 and/or audio track into the negotiated connection, so the end-to-end media path can be validated without a real camera/microphone capture pipeline.
202
+ The WebRtcTransportProvider cluster of each camera device comes from matterbridge: it wraps a real werift `RTCPeerConnection` for each session and injects an ffmpeg-generated video and/or audio track into it. The plugin builds the device `weriftOfferOptions` from the properties below and closes the WebRTC sessions of its devices on shutdown with `closeWebRtcSessions`. See the [Matterbridge cameras](https://matterbridge.io/Camera.html) guide for how a session is established and what the network needs.
199
203
 
200
204
  The platform configuration controls WebRTC video injection with these properties:
201
205
 
202
- - `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`.
206
+ - `videoGenerator` is required and accepts `none`, `test`, `webcam`, or `rtsp`. It defaults to `test`, which injects a synthetic moving test pattern. `none` negotiates the video transceiver without attaching a track, `webcam` captures from the configured local webcam, and `rtsp` pulls from the RTSP url configured in `videoSource`.
203
207
 
204
- - `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.
208
+ - `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 is a configuration error: no video track is injected and snapshots fail.
205
209
 
206
- - `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).
210
+ - `videoResolution` is required and accepts `auto`, `640x480`, `1280x720`, or `1920x1080`. It defaults to `auto`, which follows the resolution of the video stream allocated by the controller for the session (see below), falling back to `640x480` when there is none or it is not supported. 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).
207
211
 
208
- - `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`.
212
+ - `videoBitrate` is required and accepts a number (the target encoder bitrate in kbps). It defaults to `1000`. It applies to every video source, including the `test` pattern. 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`.
209
213
 
210
214
  The platform configuration controls WebRTC audio injection with these properties:
211
215
 
212
- - `audioGenerator` is required and accepts `none`, `test`, `microphone`, or `rtsp`. It defaults to `none`, which negotiates the audio transceiver (e.g. for an Intercom's "Listen" live view) without attaching a track. `test` injects a recorded test-voice clip, looped, so the end-to-end audio path can be validated without a real microphone capture pipeline. `microphone` captures from the configured local microphone, and `rtsp` pulls just the audio from the RTSP url configured in `audioSource` (any video in the stream is dropped).
216
+ - `audioGenerator` is required and accepts `none`, `test`, `microphone`, or `rtsp`. It defaults to `test`, which injects a generated 440 Hz tone that beeps once per second, so the end-to-end audio path can be validated without a real microphone capture pipeline. `none` negotiates the audio transceiver (e.g. for an Intercom's "Listen" live view) without attaching a track. `microphone` captures from the configured local microphone, and `rtsp` pulls just the audio from the RTSP url configured in `audioSource` (any video in the stream is dropped).
213
217
 
214
- - `audioSource` is optional and has no default. For the `microphone` generator it contains the OS-specific ffmpeg device identifier — e.g. an ALSA device such as `hw:0,0` on Linux, an avfoundation audio index such as `0` on macOS, or a device name such as `Microphone Array` on Windows (dshow). For the `rtsp` generator it instead holds the RTSP url, e.g. `rtsp://user:password@host:554/path` (it can be a different camera/url than `videoSource`). Selecting the `microphone` or `rtsp` generator without this property falls back to the test-voice clip with a warning.
218
+ - `audioSource` is optional and has no default. For the `microphone` generator it contains the OS-specific ffmpeg device identifier — e.g. an ALSA device such as `hw:0,0` on Linux, an avfoundation audio index such as `0` on macOS, or a device name such as `Microphone Array` on Windows (dshow). For the `rtsp` generator it instead holds the RTSP url, e.g. `rtsp://user:password@host:554/path` (it can be a different camera/url than `videoSource`). Selecting the `microphone` or `rtsp` generator without this property is a configuration error: no audio track is injected.
215
219
 
216
220
  Use ffmpeg itself to list the [available capture devices](https://trac.ffmpeg.org/wiki/Capture/Webcam) and find the right value for `audioSource`:
217
221
 
@@ -239,7 +243,9 @@ Example, pulling the audio from the same RTSP camera used for `videoSource`:
239
243
  }
240
244
  ```
241
245
 
242
- 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.
246
+ Snapshots (`CameraAvStreamManagement.CaptureSnapshot`) are captured with ffmpeg from the same video source: the cameras use their WebRTC video source and the Snapshot Camera, which has no video stream, uses `videoGenerator` and `videoSource` directly. With `videoGenerator: "none"` there is no source, so `CaptureSnapshot` fails.
247
+
248
+ 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 matterbridge 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.
243
249
 
244
250
  Use ffmpeg itself to list the [available capture devices](https://trac.ffmpeg.org/wiki/Capture/Webcam) and find the right value for `videoSource`:
245
251
 
@@ -331,68 +337,27 @@ The fix is on the browser side, not in this plugin: disable mDNS obfuscation of
331
337
 
332
338
  ### Known limitation: a client with an unreachable network interface can slow down ICE negotiation logging
333
339
 
334
- A browser gathers one host ICE candidate per local network interface it sees, mDNS-obfuscated or not. When one of those interfaces has no multicast route to the machine running Matterbridge — a disconnected VPN adapter, a Hyper-V/WSL virtual switch, a second NIC on an unrelated subnet — werift-ice's mDNS resolution for that candidate's `*.local` name can never succeed, and takes the full per-candidate apply timeout (5s, see `ICE_CANDIDATE_APPLY_TIMEOUT_MS` in `src/behaviors/webRtcTransportProviderServer.ts`) to give up on it.
340
+ A browser gathers one host ICE candidate per local network interface it sees, mDNS-obfuscated or not. When one of those interfaces has no multicast route to the machine running Matterbridge — a disconnected VPN adapter, a Hyper-V/WSL virtual switch, a second NIC on an unrelated subnet — werift-ice's mDNS resolution for that candidate's `*.local` name can never succeed, and takes the full per-candidate apply timeout (5s, see `ICE_CANDIDATE_APPLY_TIMEOUT_MS` in matterbridge's `packages/core/src/behaviors/webRtcTransportProviderServer.ts`) to give up on it.
335
341
 
336
342
  Candidates are applied concurrently, not one after another, so this doesn't compound: a candidate on a reachable interface succeeds in a few milliseconds without waiting behind a sibling candidate that's doomed to time out. `provideIceCandidates` also responds to the peer as soon as the candidates are recorded, rather than waiting for their application to finish — the same reason `SolicitOffer`/`ProvideOffer` already invoke Offer/Answer on the peer without blocking their own response — so an unreachable interface no longer delays the Matter command itself, only the background log entry for that specific candidate. If a stream is slow to start or intermittently fails specifically on a machine with multiple network interfaces/VPNs, this is the mechanism to check first (grep the Matterbridge log for `ICE candidate apply timeout`).
337
343
 
338
- ## Werift integration test
339
-
340
- The `vitest/werift.test.ts` integration test creates local client and server peers and verifies SDP offer/answer negotiation, ICE candidate exchange, a bidirectional data-channel transfer, and connection teardown with `werift`.
341
-
342
- The test uses the client as the Matter controller and the server as the camera device. Its signaling flow is:
343
-
344
- ```text
345
- Controller/client Camera/server
346
- | |
347
- |---------- SDP offer ----------------->|
348
- |------ client ICE candidates --------->|
349
- |<--------- SDP answer -----------------|
350
- |<------ server ICE candidates ---------|
351
- | |
352
- |<======= ICE + DTLS connected =========>|
353
- |<======= SCTP data channel =============>|
354
- | |
355
- |---------- start-live-view ------------>|
356
- |<--------- live-view-started -----------|
357
- | |
358
- |<=========== close peers ===============>|
359
- ```
360
-
361
- Legend:
362
-
363
- - **SDP — Session Description Protocol:** describes the media session, including codecs, formats, transport parameters, and how each peer expects to communicate. The controller sends an SDP offer and the camera returns an SDP answer.
364
- - **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.
365
- - **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.
366
- - **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.
367
- - **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.
368
-
369
- `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.
370
-
371
- In the camera implementation, Matter's WebRTC Transport Provider and Requestor clusters are responsible for carrying the SDP and ICE signaling between devices. The resulting WebRTC connection carries the media or data directly; Matter does not carry the WebRTC payload itself. This test validates werift independently and does not yet connect it to `MatterbridgeWebRtcTransportProviderServer`.
372
-
373
- Run it with:
374
-
375
- ```bash
376
- npm run test -- vitest/werift.test.ts
377
- ```
378
-
379
344
  ### Media test assets
380
345
 
381
- The `assets` directory contains deterministic three-second media fixtures for extending the werift test to real media tracks:
346
+ The `assets` directory contains deterministic three-second media fixtures. The plugin does not use them: matterbridge generates its test video, audio and snapshots with ffmpeg.
382
347
 
383
348
  - `test-video.h264`: raw H.264 Constrained Baseline video, 640×360 at 15 FPS, with a moving test pattern. Use this elementary stream when implementing H.264 NAL-unit parsing and RTP packetization.
384
349
  - `test-audio.opus`: Ogg container with mono Opus audio at 48 kHz and 64 kbit/s, containing a recorded voice track. Use the Opus packets for an audio RTP track; the Ogg container itself is not sent over WebRTC.
385
- - `test-camera.mp4`: playable reference containing the same 640×360 H.264 test pattern and a mono 1 kHz AAC track. The werift test transfers the complete file over its SCTP data channel and verifies its integrity. This exercises binary file transport, not a WebRTC video RTP track.
350
+ - `test-camera.mp4`: playable reference containing the same 640×360 H.264 test pattern and a mono 1 kHz AAC track.
386
351
  - `camera-color-1920-1080.jpeg`: 1920×1080 simplified ffmpeg-generated color-rectangle snapshot.
387
352
  - `camera-color-1280-720.jpeg`: 1280×720 simplified ffmpeg-generated color-rectangle snapshot.
388
353
  - `camera-color-640-480.jpeg`: 640×480 simplified ffmpeg-generated color-rectangle snapshot.
389
- - `camera-color-test-1920-1080.jpeg`: 1920×1080 extended color-rectangle snapshot returned by the example's `CaptureSnapshot` command.
390
- - `camera-color-test-1280-720.jpeg`: 1280×720 extended color-rectangle snapshot returned by the example's `CaptureSnapshot` command.
391
- - `camera-color-test-640-480.jpeg`: 640×480 extended color-rectangle snapshot returned by the example's `CaptureSnapshot` command.
354
+ - `camera-color-test-1920-1080.jpeg`: 1920×1080 extended color-rectangle snapshot.
355
+ - `camera-color-test-1280-720.jpeg`: 1280×720 extended color-rectangle snapshot.
356
+ - `camera-color-test-640-480.jpeg`: 640×480 extended color-rectangle snapshot.
392
357
 
393
- #### Why the snapshot calibration cards stay under ~64 KB
358
+ #### Why snapshots stay under ~64 KB
394
359
 
395
- All three calibration cards above are kept well under the Matter message size ceiling, which caps at **65535 bytes** for a single message and cannot be worked around by tuning TCP:
360
+ Snapshots, like the calibration cards above, are kept well under the Matter message size ceiling, which caps at **65535 bytes** for a single message and cannot be worked around by tuning TCP:
396
361
 
397
362
  - Every Matter message is encrypted with AES-128-CCM, using a 13-byte nonce built from the security flags, message counter, and node ID (`Session.generateNonce`, part of the Matter message-security spec, not a matter.js choice).
398
363
  - AES-CCM (RFC 3610 / NIST SP 800-38C) requires the nonce length `N` and the length-field size `L` to satisfy `N + L = 15` bytes for a 128-bit block cipher. With `N = 13`, that leaves `L = 2`.
@@ -400,8 +365,6 @@ All three calibration cards above are kept well under the Matter message size ce
400
365
 
401
366
  A `CaptureSnapshot` response whose `data` field doesn't fit fails to send: the client gets a generic invoke failure instead of an image, since the encoder cannot represent the required plaintext length in the message header. `CameraAvStreamManagement.CaptureSnapshot` returns its image as a single field of a single command response, so it inherits this ceiling directly. Matter has a dedicated mechanism for transferring larger payloads — BDX (Bulk Data Exchange), used for OTA updates and diagnostic logs — which splits big content across a sequence of acknowledged messages instead of one oversized one, but `CaptureSnapshot` doesn't use it.
402
367
 
403
- WebRTC media tracks transport encoded H.264 or Opus frames in RTP packets; they do not send an MP4, Ogg, or MPEG container directly. The current MP4 transfer deliberately uses the separate data-channel path. A future video-track test should parse the relevant elementary frames, packetize them as RTP, call werift's media track `writeRtp()`, and verify reception through `onTrack` and `onReceiveRtp`.
404
-
405
368
  ## Style guide
406
369
 
407
370
  See also the [Style Guide](./STYLEGUIDE.md) for JSDoc, naming, and logging conventions used in this repository.
package/dist/module.js CHANGED
@@ -1,20 +1,12 @@
1
1
  import { inspect } from 'node:util';
2
2
  import { MatterbridgeDynamicPlatform } from 'matterbridge';
3
- import { MatterbridgeBindingServer } from 'matterbridge/behaviors';
3
+ import { hasFfmpeg, installFfmpeg, MatterbridgeBindingServer } from 'matterbridge/behaviors';
4
+ import { AudioDoorbell, Camera, Chime, closeWebRtcSessions, Doorbell, FloodlightCamera, Intercom, SnapshotCamera, VideoDoorbell, } from 'matterbridge/devices/camera';
4
5
  import { RESET } from 'matterbridge/logger';
5
6
  import { UINT16_MAX, UINT32_MAX } from 'matterbridge/matter';
6
7
  import { ChimeClient } from 'matterbridge/matter/behaviors';
7
8
  import { Identify, Chime as ChimeCluster, PowerSource } from 'matterbridge/matter/clusters';
8
- import { isValidNumber, parseVersionString } from 'matterbridge/utils';
9
- import { WeriftWebRtcSession } from './behaviors/weriftSession.js';
10
- import { AudioDoorbell } from './devices/audioDoorbell.js';
11
- import { Camera } from './devices/camera.js';
12
- import { Chime } from './devices/chime.js';
13
- import { Doorbell } from './devices/doorbell.js';
14
- import { FloodlightCamera } from './devices/floodlightCamera.js';
15
- import { Intercom } from './devices/intercom.js';
16
- import { SnapshotCamera } from './devices/snapshotCamera.js';
17
- import { VideoDoorbell } from './devices/videoDoorbell.js';
9
+ import { isDocker, isValidNumber, parseVersionString } from 'matterbridge/utils';
18
10
  export default function initializePlugin(matterbridge, log, config) {
19
11
  return new ExampleMatterbridgeCameraPlatform(matterbridge, log, config);
20
12
  }
@@ -22,47 +14,54 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
22
14
  config;
23
15
  animationPhase = 0;
24
16
  animationInterval;
17
+ weriftOfferOptions;
25
18
  constructor(matterbridge, log, config) {
26
19
  super(matterbridge, log, config);
27
20
  this.config = config;
28
- if (typeof this.verifyMatterbridgeVersion !== 'function' || !this.verifyMatterbridgeVersion('3.10.10')) {
29
- throw new Error(`This plugin requires Matterbridge version >= "3.10.10". Please update Matterbridge to the latest version in the frontend.`);
21
+ if (typeof this.verifyMatterbridgeVersion !== 'function' || !this.verifyMatterbridgeVersion('3.10.15')) {
22
+ throw new Error(`This plugin requires Matterbridge version >= "3.10.15". Please update Matterbridge to the latest version in the frontend.`);
30
23
  }
31
24
  this.log.info(`Initializing platform ${this.config.name}...`);
32
25
  this.config.whiteList ??= [];
33
26
  this.config.blackList ??= [];
34
- this.config.videoGenerator ??= 'none';
27
+ this.config.autoInstallFfmpeg ??= true;
28
+ this.config.videoGenerator ??= 'test';
35
29
  this.config.videoResolution ??= 'auto';
36
30
  this.config.videoBitrate ??= 1000;
37
- this.config.audioGenerator ??= 'none';
31
+ this.config.audioGenerator ??= 'test';
38
32
  this.config.animationInterval ??= 60;
39
33
  this.config.debug ??= false;
40
34
  this.config.unregisterOnShutdown ??= false;
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;
44
- else
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);
48
- process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE = this.config.audioGenerator;
49
- if (this.config.audioSource === undefined)
50
- delete process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE_DEVICE;
51
- else
52
- process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE_DEVICE = this.config.audioSource;
35
+ this.weriftOfferOptions = {
36
+ offerVideo: true,
37
+ offerAudio: true,
38
+ videoSource: this.config.videoGenerator,
39
+ videoSourceDevice: this.config.videoSource,
40
+ videoResolution: this.config.videoResolution === 'auto' ? undefined : this.config.videoResolution,
41
+ videoBitrate: this.config.videoBitrate,
42
+ audioSource: this.config.audioGenerator,
43
+ audioSourceDevice: this.config.audioSource,
44
+ };
53
45
  this.log.debug(`Platform ${this.config.name} config:\n${RESET}${inspect(this.config, { depth: 10, colors: true })}`);
54
- this.log.debug(`Platform ${this.config.name} environment variables:\n${RESET}${inspect({
55
- MATTERBRIDGE_CAMERA_VIDEO_SOURCE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE,
56
- MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE,
57
- MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION: process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION,
58
- MATTERBRIDGE_CAMERA_VIDEO_BITRATE: process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE,
59
- MATTERBRIDGE_CAMERA_AUDIO_SOURCE: process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE,
60
- MATTERBRIDGE_CAMERA_AUDIO_SOURCE_DEVICE: process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE_DEVICE,
61
- }, { depth: 10, colors: true })}`);
46
+ this.log.debug(`Platform ${this.config.name} WebRTC options:\n${RESET}${inspect(this.weriftOfferOptions, { depth: 10, colors: true })}`);
62
47
  this.log.info(`Platform ${this.config.name} initialized successfully`);
63
48
  }
64
49
  async onStart(reason) {
65
50
  this.log.info(`Starting platform ${this.config.name} with reason: ${reason ?? 'no reason provided'}...`);
51
+ if ((this.matterbridge.restartMode === 'docker' || isDocker()) && this.config.autoInstallFfmpeg && !hasFfmpeg()) {
52
+ this.log.info('Installing ffmpeg...');
53
+ this.wssSendSnackbarMessage('Installing ffmpeg...', 10, 'info');
54
+ if (await installFfmpeg()) {
55
+ const message = 'ffmpeg installed successfully';
56
+ this.log.info(message);
57
+ this.wssSendSnackbarMessage(message, 10, 'success');
58
+ }
59
+ else {
60
+ const message = 'Failed to install ffmpeg: install it manually in the container';
61
+ this.log.error(message);
62
+ this.wssSendSnackbarMessage(message, 0, 'error');
63
+ }
64
+ }
66
65
  await this.ready;
67
66
  await this.clearSelect();
68
67
  const exampleChime = new Chime('Chime', 'CHIME-001', {
@@ -88,26 +87,30 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
88
87
  identifyTime: 5,
89
88
  identifyType: Identify.IdentifyType.VisibleIndicator,
90
89
  powerSourceType: 'Replaceable',
90
+ weriftOfferOptions: { ...this.weriftOfferOptions },
91
91
  });
92
92
  await this.addDevice(exampleAudioDoorbell);
93
93
  const exampleSnapshotCamera = new SnapshotCamera('Snapshot Camera', 'SNAPSHOTCAMERA-001', {
94
94
  identifyTime: 5,
95
95
  identifyType: Identify.IdentifyType.VisibleIndicator,
96
96
  powerSourceType: 'Wired',
97
+ snapshotSource: this.config.videoGenerator === 'none' ? undefined : this.config.videoGenerator,
98
+ snapshotSourceDevice: this.config.videoSource,
97
99
  });
98
100
  await this.addDevice(exampleSnapshotCamera);
99
- const exampleCamera = new Camera('Camera', 'CAMERA-001');
101
+ const exampleCamera = new Camera('Camera', 'CAMERA-001', { weriftOfferOptions: { ...this.weriftOfferOptions } });
100
102
  await this.addDevice(exampleCamera);
101
103
  const examplePtzCamera = new Camera('PTZ Camera', 'PTZCAMERA-001', {
102
104
  identifyTime: 5,
103
105
  identifyType: Identify.IdentifyType.VisibleIndicator,
104
106
  powerSourceType: 'Wired',
105
107
  ptz: true,
108
+ weriftOfferOptions: { ...this.weriftOfferOptions },
106
109
  });
107
110
  await this.addDevice(examplePtzCamera);
108
111
  const exampleFloodlightCamera = new FloodlightCamera('Floodlight Camera', 'FLOODLIGHTCAMERA-001', {
109
112
  powerSourceType: 'Battery',
110
- cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator },
113
+ cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator, weriftOfferOptions: { ...this.weriftOfferOptions } },
111
114
  lightOptions: { name: 'Floodlight' },
112
115
  });
113
116
  await this.addDevice(exampleFloodlightCamera);
@@ -115,11 +118,12 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
115
118
  identifyTime: 5,
116
119
  identifyType: Identify.IdentifyType.VisibleIndicator,
117
120
  powerSourceType: 'Replaceable',
121
+ weriftOfferOptions: { ...this.weriftOfferOptions },
118
122
  });
119
123
  await this.addDevice(exampleIntercom);
120
124
  const exampleVideoDoorbell = new VideoDoorbell('Video Doorbell', 'VIDEODOORBELL-001', {
121
125
  powerSourceType: 'Wired',
122
- cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator },
126
+ cameraOptions: { identifyTime: 5, identifyType: Identify.IdentifyType.VisibleIndicator, weriftOfferOptions: { ...this.weriftOfferOptions } },
123
127
  });
124
128
  await this.addDevice(exampleVideoDoorbell);
125
129
  const serverChime = new Chime('Server Chime', 'SERVER-CHIME-001', {
@@ -141,9 +145,9 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
141
145
  });
142
146
  const serverDoorbell = new Doorbell('Server Doorbell', 'SERVER-DOORBELL-001', { mode: 'server' });
143
147
  await this.addDevice(serverDoorbell);
144
- const serverIntercom1 = new Intercom('Server Intercom 1', 'SERVER-INTERCOM1-001', { mode: 'server' });
148
+ const serverIntercom1 = new Intercom('Server Intercom 1', 'SERVER-INTERCOM1-001', { mode: 'server', weriftOfferOptions: { ...this.weriftOfferOptions } });
145
149
  await this.addDevice(serverIntercom1);
146
- const serverIntercom2 = new Intercom('Server Intercom 2', 'SERVER-INTERCOM2-001', { mode: 'server' });
150
+ const serverIntercom2 = new Intercom('Server Intercom 2', 'SERVER-INTERCOM2-001', { mode: 'server', weriftOfferOptions: { ...this.weriftOfferOptions } });
147
151
  await this.addDevice(serverIntercom2);
148
152
  this.log.info(`Platform ${this.config.name} started successfully`);
149
153
  }
@@ -228,13 +232,34 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
228
232
  }
229
233
  }
230
234
  }
235
+ async onAction(action, value, id) {
236
+ this.log.info(`Received action ${action}${value ? ' with ' + value : ''}${id ? ' for schema ' + id : ''}`);
237
+ if (action === 'installFfmpeg') {
238
+ if (hasFfmpeg()) {
239
+ this.wssSendSnackbarMessage('ffmpeg is already installed', 10, 'info');
240
+ return;
241
+ }
242
+ this.log.info('Installing ffmpeg...');
243
+ this.wssSendSnackbarMessage('Installing ffmpeg...', 10, 'info');
244
+ if (await installFfmpeg()) {
245
+ const message = 'ffmpeg installed successfully';
246
+ this.log.info(message);
247
+ this.wssSendSnackbarMessage(message, 10, 'success');
248
+ }
249
+ else {
250
+ const message = 'Failed to install ffmpeg: requires Linux, root privileges or passwordless sudo, and apk or apt-get. See the logs for details.';
251
+ this.log.error(message);
252
+ this.wssSendSnackbarMessage(message, 0, 'error');
253
+ }
254
+ }
255
+ }
231
256
  async onShutdown(reason) {
257
+ for (const device of this.getDevices())
258
+ await closeWebRtcSessions(device);
232
259
  await super.onShutdown(reason);
233
260
  this.log.info(`Shutting down platform ${this.config.name} with reason: ${reason ?? 'no reason provided'}...`);
234
261
  clearInterval(this.animationInterval);
235
262
  this.animationInterval = undefined;
236
- this.log.info('Shutdown: closing WebRTC sessions...');
237
- await WeriftWebRtcSession.closeAll();
238
263
  if (this.config.unregisterOnShutdown)
239
264
  await this.unregisterAllDevices();
240
265
  this.log.info(`Platform ${this.config.name} shut down successfully`);
package/dist/rootNode.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { MatterbridgePowerSourceServer } from 'matterbridge/behaviors';
2
- import { TimeSynchronizationServer, TlsCertificateManagementServer, TlsClientManagementServer } from 'matterbridge/matter/behaviors';
2
+ import { TlsCertificateManagementServer, TlsClientManagementServer } from 'matterbridge/matter/behaviors';
3
3
  import { PowerSource, TimeSynchronization } from 'matterbridge/matter/clusters';
4
+ import { MATTER_EPOCH_US, MatterbridgeTimeSynchronizationServer } from './timeSynchronizationServer.js';
4
5
  export async function addRootNodeCamera(device) {
5
6
  if (!device.serverNode) {
6
7
  throw new Error(`addRootNodeCamera requires device.serverNode to be set: register the device with mode: 'server' before calling this helper.`);
@@ -13,19 +14,19 @@ export async function addRootNodeCamera(device) {
13
14
  endpointList: [],
14
15
  wiredCurrentType: PowerSource.WiredCurrentType.Ac,
15
16
  });
16
- root.behaviors.require(TimeSynchronizationServer.with(TimeSynchronization.Feature.TimeSyncClient, TimeSynchronization.Feature.NtpClient, TimeSynchronization.Feature.TimeZone), {
17
+ root.behaviors.require(MatterbridgeTimeSynchronizationServer, {
17
18
  utcTime: null,
18
19
  granularity: TimeSynchronization.Granularity.NoTimeGranularity,
19
20
  timeSource: TimeSynchronization.TimeSource.None,
20
21
  trustedTimeSource: null,
21
22
  defaultNtp: null,
22
23
  supportsDnsResolve: false,
23
- timeZone: [{ offset: 0, validAt: Date.now() * 1000 }],
24
+ timeZone: [{ offset: 0, validAt: MATTER_EPOCH_US }],
24
25
  dstOffset: [],
25
26
  localTime: null,
26
27
  timeZoneDatabase: TimeSynchronization.TimeZoneDatabase.None,
27
- timeZoneListMaxSize: 1,
28
- dstOffsetListMaxSize: 1,
28
+ timeZoneListMaxSize: 2,
29
+ dstOffsetListMaxSize: 2,
29
30
  });
30
31
  root.behaviors.require(TlsCertificateManagementServer, {
31
32
  maxRootCertificates: 5,