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 +11 -2
- package/README.md +28 -65
- package/dist/module.js +67 -42
- package/dist/rootNode.js +6 -5
- package/dist/timeSynchronizationServer.js +171 -0
- package/matterbridge-example-camera.config.json +3 -2
- package/matterbridge-example-camera.schema.json +20 -5
- package/npm-shrinkwrap.json +3 -534
- package/package.json +2 -3
- package/dist/behaviors/cameraAvSettingsUserLevelManagementServer.js +0 -43
- package/dist/behaviors/cameraAvStreamManagementServer.js +0 -337
- package/dist/behaviors/chimeServer.js +0 -28
- package/dist/behaviors/clients.js +0 -29
- package/dist/behaviors/ffmpeg.js +0 -103
- package/dist/behaviors/snapshot.js +0 -139
- package/dist/behaviors/webRtcTransportProviderServer.js +0 -400
- package/dist/behaviors/webRtcTransportRequestorServer.js +0 -5
- package/dist/behaviors/weriftSession.js +0 -537
- package/dist/devices/audioDoorbell.js +0 -61
- package/dist/devices/camera.js +0 -93
- package/dist/devices/chime.js +0 -44
- package/dist/devices/doorbell.js +0 -30
- package/dist/devices/floodlightCamera.js +0 -79
- package/dist/devices/intercom.js +0 -71
- package/dist/devices/snapshotCamera.js +0 -62
- package/dist/devices/videoDoorbell.js +0 -79
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.
|
|
33
|
+
## [1.0.0] - Dev branch
|
|
34
34
|
|
|
35
35
|
### Breaking changes
|
|
36
36
|
|
|
37
|
-
- [matterbridge]: Require matterbridge v.3.10.
|
|
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
|
[](https://github.com/microsoft/typescript-go)
|
|
14
14
|
[](https://nodejs.org/)
|
|
15
15
|
[](https://matterbridge.io)
|
|
16
|
-

|
|
17
16
|
|
|
18
17
|
[](https://www.npmjs.com/package/matterbridge)
|
|
19
18
|
[](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
|
-
-
|
|
37
|
-
- `src/
|
|
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.
|
|
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
|
-
|
|
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  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  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 `
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
|
390
|
-
- `camera-color-test-1280-720.jpeg`: 1280×720 extended color-rectangle snapshot
|
|
391
|
-
- `camera-color-test-640-480.jpeg`: 640×480 extended color-rectangle snapshot
|
|
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
|
|
358
|
+
#### Why snapshots stay under ~64 KB
|
|
394
359
|
|
|
395
|
-
|
|
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.
|
|
29
|
-
throw new Error(`This plugin requires Matterbridge version >= "3.10.
|
|
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.
|
|
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 ??= '
|
|
31
|
+
this.config.audioGenerator ??= 'test';
|
|
38
32
|
this.config.animationInterval ??= 60;
|
|
39
33
|
this.config.debug ??= false;
|
|
40
34
|
this.config.unregisterOnShutdown ??= false;
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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}
|
|
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 {
|
|
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(
|
|
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:
|
|
24
|
+
timeZone: [{ offset: 0, validAt: MATTER_EPOCH_US }],
|
|
24
25
|
dstOffset: [],
|
|
25
26
|
localTime: null,
|
|
26
27
|
timeZoneDatabase: TimeSynchronization.TimeZoneDatabase.None,
|
|
27
|
-
timeZoneListMaxSize:
|
|
28
|
-
dstOffsetListMaxSize:
|
|
28
|
+
timeZoneListMaxSize: 2,
|
|
29
|
+
dstOffsetListMaxSize: 2,
|
|
29
30
|
});
|
|
30
31
|
root.behaviors.require(TlsCertificateManagementServer, {
|
|
31
32
|
maxRootCertificates: 5,
|