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 ensureTestAudioTrack(codec) {
364
+ async generateAudioTrack(codec) {
360
365
  if (this.testAudioAttached)
361
366
  return;
362
- if (process.env.MATTERBRIDGE_CAMERA_DISABLE_TEST_AUDIO === '1') {
363
- this.log.debug('Test audio injection disabled by MATTERBRIDGE_CAMERA_DISABLE_TEST_AUDIO=1');
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.ensureTestAudioTrack(preferredAudioCodec);
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();
@@ -6,6 +6,7 @@
6
6
  "videoGenerator": "none",
7
7
  "videoResolution": "auto",
8
8
  "videoBitrate": 1000,
9
+ "audioGenerator": "none",
9
10
  "animationInterval": 60,
10
11
  "debug": false,
11
12
  "unregisterOnShutdown": false
@@ -2,7 +2,7 @@
2
2
  "title": "Matterbridge example camera plugin",
3
3
  "description": "matterbridge-example-camera v. 1.0.0 by https://github.com/Luligu",
4
4
  "type": "object",
5
- "required": ["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)",
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.8-dev-20260726-dffb00d",
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-dffb00d",
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "matterbridge-example-camera",
3
- "version": "0.0.8-dev-20260726-dffb00d",
3
+ "version": "0.0.8-dev-20260726-02502e0",
4
4
  "description": "Matterbridge camera example plugin",
5
5
  "author": "https://github.com/Luligu",
6
6
  "license": "Apache-2.0",