matterbridge-example-camera 0.0.8-dev-20260726-dffb00d → 0.0.8-dev-20260726-02502e0
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
|
@@ -40,6 +40,9 @@ If you like this project and find it useful, please consider giving it a star on
|
|
|
40
40
|
- [tests]: Add `rtsp` video source and `videoResolution` precedence (`auto` vs. fixed, webcam and rtsp) coverage in `vitest/webrtc/weriftSession.test.ts`; extend `vitest/module.test.ts` with the `videoGenerator` normalization test and a test for the `videoResolution` default of `auto`.
|
|
41
41
|
- [webrtc]: Add `WeriftWebRtcSession.closeAll()`, a static helper that closes every active session (peer connection plus any injected ffmpeg generators). `onShutdown` now calls it so a graceful platform shutdown cleans up leftover WebRTC sessions itself instead of relying solely on the `process.on('exit', ...)` fallback.
|
|
42
42
|
- [tests]: Add `closeAll` coverage in `vitest/webrtc/weriftSession.test.ts`, covering closing all active sessions and the no-active-sessions case.
|
|
43
|
+
- [platform]: Add an `audioGenerator` config property (`none`/`test`, defaulting to `none`) replacing the undocumented `MATTERBRIDGE_CAMERA_DISABLE_TEST_AUDIO=1` env var toggle, mirroring `videoGenerator`'s pattern via the new `MATTERBRIDGE_CAMERA_AUDIO_SOURCE` env var. Test-voice audio injection is now opt-in instead of on by default.
|
|
44
|
+
- [docs]: Document `audioGenerator` in the README and schema.
|
|
45
|
+
- [tests]: Extend `vitest/module.test.ts` with `audioGenerator` normalization/apply coverage; update `vitest/webrtc/weriftSession.test.ts` for the new `MATTERBRIDGE_CAMERA_AUDIO_SOURCE` gate.
|
|
43
46
|
|
|
44
47
|
### Fixed
|
|
45
48
|
|
package/README.md
CHANGED
|
@@ -186,9 +186,9 @@ So, to let either Intercom 1 or Intercom 2 start a call, on the fabric they shar
|
|
|
186
186
|
|
|
187
187
|
With both directions in place, either Intercom can call the other; a call initiated the other way only needs its own binding/ACL pair, already covered above since both were set up symmetrically.
|
|
188
188
|
|
|
189
|
-
## WebRTC video injection
|
|
189
|
+
## WebRTC video and audio injection
|
|
190
190
|
|
|
191
|
-
`WeriftWebRtcSession` (see `src/webrtc/weriftSession.ts`) wraps a real werift `RTCPeerConnection` for each WebRtcTransportProvider session (see `MatterbridgeWebRtcTransportProviderServer` in `src/behaviors/webRtcTransportProviderServer.ts`), so the session's SDP offer/answer and ICE candidates are handled by a real WebRTC peer connection instead of being just recorded. It can also inject a real ffmpeg-generated video track into the negotiated connection, so the end-to-end media path can be validated without a real camera capture pipeline.
|
|
191
|
+
`WeriftWebRtcSession` (see `src/webrtc/weriftSession.ts`) wraps a real werift `RTCPeerConnection` for each WebRtcTransportProvider session (see `MatterbridgeWebRtcTransportProviderServer` in `src/behaviors/webRtcTransportProviderServer.ts`), so the session's SDP offer/answer and ICE candidates are handled by a real WebRTC peer connection instead of being just recorded. It can also inject a real ffmpeg-generated video 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.
|
|
192
192
|
|
|
193
193
|
The platform configuration controls WebRTC video injection with these properties:
|
|
194
194
|
|
|
@@ -200,6 +200,10 @@ The platform configuration controls WebRTC video injection with these properties
|
|
|
200
200
|
|
|
201
201
|
- `videoBitrate` is required and accepts a number (the target encoder bitrate in kbps). It defaults to `1000`. It applies to the `webcam` and `rtsp` sources only; the `test` pattern is always encoded at a fixed 1000 kbps regardless of this setting. Since the encoder always uses `-preset ultrafast -tune zerolatency` for low-latency live view (lower compression efficiency than slower presets), suggested values are higher than typical streaming guides: ~800 for `640x480`, ~2000 for `1280x720`, ~2500 for `1920x1080`.
|
|
202
202
|
|
|
203
|
+
The platform configuration controls WebRTC audio injection with this property:
|
|
204
|
+
|
|
205
|
+
- `audioGenerator` is required and accepts `none` or `test`. 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.
|
|
206
|
+
|
|
203
207
|
With `videoResolution: "auto"`, a real client's resolution/quality picker (e.g. in Home Assistant) drives the capture/output resolution: it allocates a video stream with `CameraAvStreamManagement.VideoStreamAllocate` before soliciting or providing a WebRTC offer, and `MatterbridgeWebRtcTransportProviderServer` looks up that stream's `maxResolution` to select the resolution for the session. For `webcam` this is the capture resolution passed to ffmpeg; for `rtsp` the camera keeps streaming at its own native resolution and ffmpeg scales it to match.
|
|
204
208
|
|
|
205
209
|
Requires `ffmpeg` to be installed. The resolver checks the system command and common installation directories on Linux, macOS, and Windows.
|
package/dist/module.js
CHANGED
|
@@ -35,6 +35,7 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
|
|
|
35
35
|
this.config.videoGenerator ??= 'none';
|
|
36
36
|
this.config.videoResolution ??= 'auto';
|
|
37
37
|
this.config.videoBitrate ??= 1000;
|
|
38
|
+
this.config.audioGenerator ??= 'none';
|
|
38
39
|
this.config.animationInterval ??= 60;
|
|
39
40
|
this.config.debug ??= false;
|
|
40
41
|
this.config.unregisterOnShutdown ??= false;
|
|
@@ -45,12 +46,14 @@ export class ExampleMatterbridgeCameraPlatform extends MatterbridgeDynamicPlatfo
|
|
|
45
46
|
process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE = this.config.videoSource;
|
|
46
47
|
process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION = this.config.videoResolution;
|
|
47
48
|
process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE = String(this.config.videoBitrate);
|
|
49
|
+
process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE = this.config.audioGenerator;
|
|
48
50
|
this.log.debug(`Platform ${this.config.name} config:\n${RESET}${inspect(this.config, { depth: 10, colors: true })}`);
|
|
49
51
|
this.log.debug(`Platform ${this.config.name} environment variables:\n${RESET}${inspect({
|
|
50
52
|
MATTERBRIDGE_CAMERA_VIDEO_SOURCE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE,
|
|
51
53
|
MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE: process.env.MATTERBRIDGE_CAMERA_VIDEO_SOURCE_DEVICE,
|
|
52
54
|
MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION: process.env.MATTERBRIDGE_CAMERA_VIDEO_RESOLUTION,
|
|
53
55
|
MATTERBRIDGE_CAMERA_VIDEO_BITRATE: process.env.MATTERBRIDGE_CAMERA_VIDEO_BITRATE,
|
|
56
|
+
MATTERBRIDGE_CAMERA_AUDIO_SOURCE: process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE,
|
|
54
57
|
}, { depth: 10, colors: true })}`);
|
|
55
58
|
this.log.info(`Platform ${this.config.name} initialized successfully`);
|
|
56
59
|
}
|
|
@@ -19,6 +19,10 @@ export class WeriftWebRtcSession {
|
|
|
19
19
|
testAudioGenerator;
|
|
20
20
|
testAudioUdpDisposer;
|
|
21
21
|
testAudioAttached = false;
|
|
22
|
+
diagnosticsInterval;
|
|
23
|
+
static DIAGNOSTICS_INTERVAL_MS = 10_000;
|
|
24
|
+
lastDiagnosticsCounters;
|
|
25
|
+
dtlsTransportsWithStateLogging = new Set();
|
|
22
26
|
constructor(webRtcSessionId) {
|
|
23
27
|
this.webRtcSessionId = webRtcSessionId;
|
|
24
28
|
this.peerConnection = new RTCPeerConnection({ codecs: { audio: [useOPUS(), usePCMU()], video: [useH264(), useVP8()] } });
|
|
@@ -47,6 +51,7 @@ export class WeriftWebRtcSession {
|
|
|
47
51
|
this.log.info(`Peer connection state: ${state}`);
|
|
48
52
|
});
|
|
49
53
|
this.log.debug(`Created RTCPeerConnection with codecs: audio=[OPUS, PCMU], video=[H264, VP8] for session ${webRtcSessionId}`);
|
|
54
|
+
this.diagnosticsInterval = setInterval(() => void this.logDiagnosticsSnapshot(), WeriftWebRtcSession.DIAGNOSTICS_INTERVAL_MS);
|
|
50
55
|
WeriftWebRtcSession.activeSessions.add(this);
|
|
51
56
|
if (!WeriftWebRtcSession.exitHandlerRegistered) {
|
|
52
57
|
WeriftWebRtcSession.exitHandlerRegistered = true;
|
|
@@ -356,11 +361,11 @@ export class WeriftWebRtcSession {
|
|
|
356
361
|
}
|
|
357
362
|
}
|
|
358
363
|
static TEST_VOICE_PATH = fileURLToPath(new URL('../../assets/test-voice.opus', import.meta.url));
|
|
359
|
-
async
|
|
364
|
+
async generateAudioTrack(codec) {
|
|
360
365
|
if (this.testAudioAttached)
|
|
361
366
|
return;
|
|
362
|
-
if (process.env.
|
|
363
|
-
this.log.debug(
|
|
367
|
+
if (process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE !== 'test') {
|
|
368
|
+
this.log.debug(`Test audio injection skipped (MATTERBRIDGE_CAMERA_AUDIO_SOURCE=${process.env.MATTERBRIDGE_CAMERA_AUDIO_SOURCE ?? 'none'})`);
|
|
364
369
|
return;
|
|
365
370
|
}
|
|
366
371
|
const ffmpegCommand = await this.resolveCommand('ffmpeg');
|
|
@@ -457,6 +462,7 @@ export class WeriftWebRtcSession {
|
|
|
457
462
|
await this.peerConnection.setLocalDescription(offer);
|
|
458
463
|
const sdp = this.peerConnection.localDescription.sdp;
|
|
459
464
|
this.log.info(`Created local SDP offer (${this.summarizeSdp(sdp)})`);
|
|
465
|
+
this.logDtlsTransportStateChanges();
|
|
460
466
|
return sdp;
|
|
461
467
|
}
|
|
462
468
|
async createAnswer(offerSdp, videoResolution) {
|
|
@@ -480,7 +486,7 @@ export class WeriftWebRtcSession {
|
|
|
480
486
|
const preferredAudioCodec = this.getPreferredInjectableAudioCodec();
|
|
481
487
|
if (preferredAudioCodec) {
|
|
482
488
|
this.preferAudioCodecOnTransceivers(preferredAudioCodec.mimeType.toLowerCase());
|
|
483
|
-
await this.
|
|
489
|
+
await this.generateAudioTrack(preferredAudioCodec);
|
|
484
490
|
}
|
|
485
491
|
else {
|
|
486
492
|
this.log.warn('No injectable audio codec available on negotiated transceivers (supported: Opus)');
|
|
@@ -493,19 +499,61 @@ export class WeriftWebRtcSession {
|
|
|
493
499
|
await this.peerConnection.setLocalDescription(answer);
|
|
494
500
|
const sdp = this.peerConnection.localDescription.sdp;
|
|
495
501
|
this.log.info(`Created local SDP answer (${this.summarizeSdp(sdp)})`);
|
|
502
|
+
this.logDtlsTransportStateChanges();
|
|
496
503
|
return sdp;
|
|
497
504
|
}
|
|
498
505
|
async applyAnswer(answerSdp) {
|
|
499
506
|
this.log.debug(`ApplyAnswer requested (${this.summarizeSdp(answerSdp)})`);
|
|
500
507
|
await this.peerConnection.setRemoteDescription({ type: 'answer', sdp: answerSdp });
|
|
501
508
|
this.log.info(`Remote SDP answer applied (signalingState=${this.peerConnection.signalingState})`);
|
|
509
|
+
this.logDtlsTransportStateChanges();
|
|
502
510
|
}
|
|
503
511
|
async addIceCandidate(candidate, sdpMid, sdpMLineIndex) {
|
|
504
512
|
this.log.debug(`Applying ICE candidate (mid=${sdpMid ?? 'null'}, mLine=${sdpMLineIndex ?? 'null'}, endOfCandidates=${candidate.trim() === ''})`);
|
|
505
513
|
await this.peerConnection.addIceCandidate({ candidate, sdpMid: sdpMid ?? undefined, sdpMLineIndex: sdpMLineIndex ?? undefined });
|
|
506
514
|
}
|
|
515
|
+
logDtlsTransportStateChanges() {
|
|
516
|
+
for (const transport of this.peerConnection.dtlsTransports) {
|
|
517
|
+
if (this.dtlsTransportsWithStateLogging.has(transport))
|
|
518
|
+
continue;
|
|
519
|
+
this.dtlsTransportsWithStateLogging.add(transport);
|
|
520
|
+
transport.onStateChange.subscribe((state) => {
|
|
521
|
+
this.log.info(`DTLS transport state: ${state}`);
|
|
522
|
+
});
|
|
523
|
+
}
|
|
524
|
+
}
|
|
525
|
+
async logDiagnosticsSnapshot() {
|
|
526
|
+
const iceStates = this.peerConnection.iceTransports.map((transport) => transport.state).join(',') || 'none';
|
|
527
|
+
const dtlsStates = this.peerConnection.dtlsTransports.map((transport) => transport.state).join(',') || 'none';
|
|
528
|
+
const stats = [...(await this.peerConnection.getStats()).values()];
|
|
529
|
+
const nominatedPair = stats
|
|
530
|
+
.filter((stat) => stat.type === 'candidate-pair')
|
|
531
|
+
.map((stat) => stat)
|
|
532
|
+
.find((pair) => pair.nominated === true);
|
|
533
|
+
const outboundRtp = stats.filter((stat) => stat.type === 'outbound-rtp').map((stat) => stat);
|
|
534
|
+
const candidatePairPacketsSent = nominatedPair?.packetsSent ?? 0;
|
|
535
|
+
const candidatePairPacketsReceived = nominatedPair?.packetsReceived ?? 0;
|
|
536
|
+
const outboundRtpPacketsSent = outboundRtp.reduce((sum, stat) => sum + (stat.packetsSent ?? 0), 0);
|
|
537
|
+
const previous = this.lastDiagnosticsCounters;
|
|
538
|
+
this.lastDiagnosticsCounters = { candidatePairPacketsSent, candidatePairPacketsReceived, outboundRtpPacketsSent };
|
|
539
|
+
const delta = (current, previousValue) => previousValue === undefined ? 'n/a' : `${current - previousValue >= 0 ? '+' : ''}${current - previousValue}`;
|
|
540
|
+
const outboundRtpSummary = outboundRtp.map((stat) => `${stat.kind ?? 'unknown'}:packetsSent=${stat.packetsSent ?? 0}`).join(', ') || 'none';
|
|
541
|
+
this.log.debug([
|
|
542
|
+
'Diagnostics:',
|
|
543
|
+
`- connectionState=${this.peerConnection.connectionState}`,
|
|
544
|
+
`- iceConnectionState=${this.peerConnection.iceConnectionState}`,
|
|
545
|
+
`- iceGatheringState=${this.peerConnection.iceGatheringState}`,
|
|
546
|
+
`- signalingState=${this.peerConnection.signalingState}`,
|
|
547
|
+
`- iceTransportStates=[${iceStates}]`,
|
|
548
|
+
`- dtlsTransportStates=[${dtlsStates}]`,
|
|
549
|
+
`- nominatedPair(packetsSent=${candidatePairPacketsSent} Δ${delta(candidatePairPacketsSent, previous?.candidatePairPacketsSent)}, packetsReceived=${candidatePairPacketsReceived} Δ${delta(candidatePairPacketsReceived, previous?.candidatePairPacketsReceived)})`,
|
|
550
|
+
`- outboundRtp[${outboundRtpSummary}] (totalPacketsSent Δ${delta(outboundRtpPacketsSent, previous?.outboundRtpPacketsSent)})`,
|
|
551
|
+
].join('\n'));
|
|
552
|
+
}
|
|
507
553
|
async close() {
|
|
508
554
|
this.log.debug('Closing RTCPeerConnection');
|
|
555
|
+
clearInterval(this.diagnosticsInterval);
|
|
556
|
+
this.diagnosticsInterval = undefined;
|
|
509
557
|
await this.peerConnection.close();
|
|
510
558
|
this.cleanupTestVideoArtifacts();
|
|
511
559
|
this.cleanupTestAudioArtifacts();
|
|
@@ -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": ["videoGenerator", "videoResolution"],
|
|
5
|
+
"required": ["videoGenerator", "videoResolution", "audioGenerator"],
|
|
6
6
|
"properties": {
|
|
7
7
|
"name": {
|
|
8
8
|
"description": "Plugin Name",
|
|
@@ -67,6 +67,13 @@
|
|
|
67
67
|
"type": "number",
|
|
68
68
|
"default": 1000
|
|
69
69
|
},
|
|
70
|
+
"audioGenerator": {
|
|
71
|
+
"title": "Audio Generator",
|
|
72
|
+
"description": "Select the WebRTC audio generator: none disables track injection (only the audio transceiver is negotiated), and test injects a recorded test-voice clip, looped, e.g. for an Intercom's Listen live view.",
|
|
73
|
+
"type": "string",
|
|
74
|
+
"enum": ["none", "test"],
|
|
75
|
+
"default": "none"
|
|
76
|
+
},
|
|
70
77
|
"debug": {
|
|
71
78
|
"title": "Enable Debug",
|
|
72
79
|
"description": "Enable the debug for the plugin (development only)",
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "matterbridge-example-camera",
|
|
3
|
-
"version": "0.0.8-dev-20260726-
|
|
3
|
+
"version": "0.0.8-dev-20260726-02502e0",
|
|
4
4
|
"lockfileVersion": 3,
|
|
5
5
|
"requires": true,
|
|
6
6
|
"packages": {
|
|
7
7
|
"": {
|
|
8
8
|
"name": "matterbridge-example-camera",
|
|
9
|
-
"version": "0.0.8-dev-20260726-
|
|
9
|
+
"version": "0.0.8-dev-20260726-02502e0",
|
|
10
10
|
"license": "Apache-2.0",
|
|
11
11
|
"dependencies": {
|
|
12
12
|
"node-ansi-logger": "3.3.0",
|
package/package.json
CHANGED