@linanw/homebridge-mijia-remote-camera 0.2.1 → 0.3.0

package/lib/matter-device.mjs

@@ -11,12 +11,14 @@ import { CameraAvStreamManagement } from '@matter/main/clusters/camera-av-stream
 import { WebRtcTransportRequestor } from '@matter/main/clusters/web-rtc-transport-requestor';
 import { Status, StatusResponseError, StreamUsage, VendorId, EndpointNumber } from '@matter/main/types';
 import { assertRemoteActor, hasRemoteActor, NodeSession, Invoke, DeviceCommissioner } from '@matter/main/protocol';
+import { MatterPtzStepControl, MijiaPtzStepBehavior } from './matter-ptz-cluster.mjs';
 
 const LIVE = StreamUsage.LiveView;
 const NIGHT = ['off', 'on', 'auto'];
 const reject = (status, message) => { throw new StatusResponseError(message, status); };
 const bounded = (value, fallback, min, max) => Number.isFinite(Number(value))
   ? Math.min(max, Math.max(min, Math.round(Number(value)))) : fallback;
+const streamCapacity = value => Number.isInteger(value) && value >= 1 && value <= 4 ? value : 2;
 const text = (value, fallback, max = 32) => Array.from(String(value || fallback)).slice(0, max).join('');
 const samePeer = (a, b) => a.fabricIndex === b.fabricIndex && a.nodeId === b.nodeId;
 const clone = value => structuredClone(value);
@@ -28,8 +30,8 @@ function requireOwner(item, peer, kind) {
 
 /** Runtime resource accounting shared by all fabrics of one camera. Not persisted encoder state. */
 export class MatterCameraResources {
-  constructor(maxStreams = 1) {
-    this.maxStreams = maxStreams;
+  constructor(maxStreams = 2) {
+    this.maxStreams = streamCapacity(maxStreams);
     this.allocated = { video: new Map(), audio: new Map(), snapshot: new Map() };
     this.sessions = new Map();
     this.nextStream = 1;
@@ -186,7 +188,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
   const height = bounded(config.height, 360, 120, 720) & ~1;
   const fps = bounded(config.frameRate, 12, 1, 30);
   const bitRate = bounded(config.bitRate, 800000, 64000, 2000000);
-  const maxStreams = bounded(config.maxStreams, 1, 1, 1);
+  const maxStreams = streamCapacity(config.maxStreams);
   const audioEnabled = config.enableAudio !== false;
   const speakerEnabled = config.enableTalkback === true;
   const nightEnabled = config.nightVision === true && typeof runtime?.setNightVision === 'function';
@@ -212,6 +214,9 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
   const resources = new MatterCameraResources(maxStreams), { allocated, sessions } = resources;
   let server, endpoint, closed = false, cachedCommissioned = false,
     nextControl = 1, lastError, applyingNightMode = false;
+  const ptz = new MatterPtzStepControl({ runtime, onChange: state => {
+    if (endpoint && !closed) return endpoint.set({ mijiaPtzStep: state });
+  } });
   const features = ['Video', 'Audio', 'Snapshot', ...(speakerEnabled ? ['Speaker'] : []), ...(nightEnabled ? ['NightVision'] : [])];
   const dimensions = { width, height };
   const snapshotCapabilities = [{ resolution: dimensions, maxFrameRate: 1, imageCodec: 0,
@@ -297,6 +302,15 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
     // The library default writes the passcode, manual pairing code and QR to the process log.
     initiateCommissioning() {}
   }
+  class MijiaPtzStepServer extends MijiaPtzStepBehavior {
+    // The external shared guard rejects simultaneous actors instead of queueing movement
+    // behind the cluster's state lock. Attribute publications use separate transactions.
+    static lockOnInvoke = false;
+    async moveStep({ direction }) {
+      actor(this);
+      await ptz.move(direction);
+    }
+  }
   class MijiaAvServer extends CameraAvStreamManagementServer.with(...features) {
     async initialize() {
       // Allocations hold runtime encoder resources and do not survive a process restart.
@@ -475,14 +489,15 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
         ...(config.listeningAddressIpv6 ? { listeningAddressIpv6: config.listeningAddressIpv6 } : {}) },
       basicInformation: { vendorName: 'linanw', vendorId: VendorId(0xfff1), productName: 'Mijia Remote Camera',
         productId: 0x8001, nodeLabel: text(name, 'Mijia Camera'), serialNumber: text(serialNumber, identifier),
-        hardwareVersion: 1, softwareVersion: 201, softwareVersionString: '0.2.1' },
+        hardwareVersion: 1, softwareVersion: 300, softwareVersionString: '0.3.0' },
     });
     const audioCapabilities = { maxNumberOfChannels: 1, supportedCodecs: [0], supportedSampleRates: [48000], supportedBitDepths: [16] };
-    endpoint = new Endpoint(CameraDevice.with(MijiaAvServer, MijiaWebRtcServer, WebRtcTransportRequestorClient), {
+    endpoint = new Endpoint(CameraDevice.with(MijiaAvServer, MijiaWebRtcServer, WebRtcTransportRequestorClient, MijiaPtzStepServer), {
       id: 'camera', number: EndpointNumber(1),
+      mijiaPtzStep: ptz.state(),
       cameraAvStreamManagement: {
-        maxContentBufferSize: 1000000, maxNetworkBandwidth: 5000000, maxConcurrentEncoders: 1,
-        maxEncodedPixelRate: width * height * fps,
+        maxContentBufferSize: 1000000, maxNetworkBandwidth: 5000000 * maxStreams, maxConcurrentEncoders: maxStreams,
+        maxEncodedPixelRate: width * height * fps * maxStreams,
         supportedStreamUsages: [LIVE], streamUsagePriorities: [LIVE],
         videoSensorParams: { sensorWidth: width, sensorHeight: height, maxFps: fps },
         minViewportResolution: { width: 160, height: 120 }, currentFrameRate: fps,
@@ -508,6 +523,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
       })().catch(() => {});
     });
   } catch (error) {
+    ptz.close();
     await server?.close().catch(() => {});
     throw error;
   }
@@ -521,6 +537,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
     async start() {
       if (closed) throw new Error('matter_closed');
       await server.start();
+      await ptz.refresh();
       if (nightEnabled && typeof runtime?.getNightVision === 'function') {
         const value = await runtime.getNightVision().catch(() => undefined);
         if (value) await nightChanged(value);
@@ -556,8 +573,10 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
       await Promise.allSettled([...sessions.values()].map(item => end(item, 5, true)));
       return this.status();
     },
+    refreshPtzCapabilities(options) { return ptz.refresh(options); },
     async close() {
       if (closed) return;
+      ptz.close();
       cachedCommissioned = !!server.state.commissioning?.commissioned;
       await Promise.allSettled([...sessions.values()].map(item => end(item, 2, true)));
       closed = true;

package/lib/matter-diagnostics.mjs

@@ -19,10 +19,10 @@ export function safeMatterStatus(value = {}) {
   const source = value.media;
   if (object(source)) {
     const media = {};
-    for (const key of ['sessions', 'failures', 'videoPackets', 'audioPackets', 'talkPackets', 'talkBytes']) {
+    for (const key of ['sessions', 'failures', 'videoPackets', 'audioPackets', 'talkPackets', 'talkBytes', 'activeSessions', 'maxSessions', 'activeSources', 'videoSources', 'audioSources', 'sourceJobs', 'sourceSockets']) {
       if (count(source[key])) media[key] = source[key];
     }
-    for (const key of ['active', 'microphoneMuted', 'speakerMuted']) if (typeof source[key] === 'boolean') media[key] = source[key];
+    for (const key of ['active', 'microphoneMuted', 'speakerMuted', 'talkbackActive']) if (typeof source[key] === 'boolean') media[key] = source[key];
     for (const [key, allowed] of Object.entries({"lastFailure": ["negotiation_failed", "media_not_offered", "webrtc_timeout", "webrtc_failed", "webrtc_disconnected", "media_unavailable", "udp_error", "ffmpeg_unavailable", "ffmpeg_exit", "video_timeout"], "lastFailureStage": ["remote_description", "replace_video_track", "replace_audio_track", "create_answer", "create_offer", "local_description", "remote_answer"], "lastFailureType": ["Error", "TypeError", "RangeError", "OperationError", "InvalidStateError", "InvalidModificationError", "InvalidAccessError", "NotSupportedError", "SyntaxError", "AbortError"]})) {
       if (allowed.includes(source[key])) media[key] = source[key];
     }

package/lib/matter-media.mjs

@@ -64,22 +64,35 @@ export class MatterMedia {
     this.config = config; this.snapshotDelegate = snapshotDelegate; this.spawnProcess = spawnProcess;
     this.connectTimeoutMs = connectTimeoutMs; this.mediaTimeoutMs = mediaTimeoutMs;
     this.microphoneMuted = config.enableAudio === false; this.speakerMuted = config.enableAudio === false || config.enableTalkback === false;
-    this.microphoneVolume = 100; this.speakerVolume = 100; this.closed = false; this.session = undefined;
+    this.microphoneVolume = 100; this.speakerVolume = 100; this.closed = false;
+    this.maxStreams = integer(config.maxStreams, 2, 1, 4);
+    this.sessions = new Map(); this.sources = new Map(); this.talkOwner = undefined;
     this.counters = { sessions: 0, failures: 0, videoPackets: 0, audioPackets: 0, talkPackets: 0, talkBytes: 0, state: 'idle' };
   }
-  status() { return { ...this.counters, active: Boolean(this.session), microphoneMuted: this.microphoneMuted, speakerMuted: this.speakerMuted }; }
+  // Kept for consumers that inspect the original single-view transport.
+  get session() { return this.sessions.values().next().value; }
+  status() {
+    const sources = [...this.sources.values()];
+    return { ...this.counters, active: this.sessions.size > 0, activeSessions: this.sessions.size,
+      maxSessions: this.maxStreams, sourceJobs: sources.reduce((count, source) => count + source.jobs.size, 0),
+      sourceSockets: sources.reduce((count, source) => count + source.sockets.size, 0),
+      activeSources: sources.length, videoSources: sources.filter(source => source.kind === 'video').length,
+      audioSources: sources.filter(source => source.kind === 'audio').length, talkbackActive: Boolean(this.talkOwner),
+      microphoneMuted: this.microphoneMuted, speakerMuted: this.speakerMuted };
+  }
   emit(session, state) {
-    this.counters.state = state;
+    this.counters.state = state === 'closed' && this.sessions.size ? ([...this.sessions.values()].some(value => value.peer.connectionState === 'connected') ? 'connected' : 'connecting') : state;
     try { session.onState?.(state); } catch {}
   }
-  alive(session) { return this.session === session && !session.closed && !this.closed; }
+  alive(session) { return this.sessions.get(String(session.id)) === session && !session.closed && !this.closed; }
   fail(session, reason = 'media_unavailable') {
     if (!this.alive(session)) return;
-    this.counters.failures++; this.counters.lastFailure = reason; this.emit(session, 'failed'); void this.closeSession(session.id);
+    this.counters.failures++; this.counters.lastFailure = reason; this.emit(session, 'failed'); void this.closeSession(session.id, session);
   }
   async createSession({ id, offer, video, audio, onCandidate, onState, iceServers, iceTransportPolicy } = {}) {
     if (this.closed) throw fault('closed');
-    if (this.session) throw fault('session_busy');
+    if (this.sessions.has(String(id))) throw fault('duplicate_session');
+    if (this.sessions.size >= this.maxStreams) throw fault('session_busy');
     if (iceTransportPolicy !== undefined && iceTransportPolicy !== 'all') throw fault('relay_unavailable');
     if (iceServers !== undefined && (!Array.isArray(iceServers) || iceServers.length)) throw fault('ice_servers_unsupported');
     if ((typeof id !== 'string' && typeof id !== 'number') || !String(id).length || String(id).length > 160 || (!video && !audio)) throw fault('invalid_session');
@@ -95,9 +108,9 @@ export class MatterMedia {
         keyFrameInterval: integer(video.keyFrameInterval, 1000, 200, 4000) } : undefined,
       audio: audio && this.config.enableAudio !== false ? { channels: 1, bitRate: integer(audio.bitRate, 24000, 16000, 64000) } : undefined };
     if (!session.video && !session.audio) { await peer.close(); throw fault('audio_disabled'); }
-    this.session = session; this.counters.sessions++; this.emit(session, 'connecting');
+    this.sessions.set(String(id), session); this.counters.sessions++; this.emit(session, 'connecting');
     session.connectTimer = timer(() => this.fail(session, 'webrtc_timeout'), this.connectTimeoutMs);
-    session.lifeTimer = timer(() => this.closeSession(id), 30 * 60 * 1000);
+    session.lifeTimer = timer(() => this.closeSession(id, session), 30 * 60 * 1000);
     peer.onIceCandidate.subscribe(candidate => {
       if (!candidate || !this.alive(session) || session.candidateCount++ >= 128) return;
       try { onCandidate?.({ candidate: candidate.candidate, sdpMid: candidate.sdpMid ?? undefined, sdpMLineIndex: candidate.sdpMLineIndex ?? undefined }); } catch {}
@@ -137,8 +150,9 @@ export class MatterMedia {
       return offer !== undefined ? { answer: peer.localDescription.sdp } : { offer: peer.localDescription.sdp };
     } catch (error) {
       const reason = error?.reason === 'media_not_offered' ? 'media_not_offered' : 'negotiation_failed';
+      if (!this.alive(session)) { await this.closeSession(id, session); throw fault('session_closed'); }
       this.negotiationFailure(session, error, reason);
-      await this.closeSession(id); throw fault(reason);
+      await this.closeSession(id, session); throw fault(reason);
     }
   }
   negotiationFailure(session, error, reason = 'negotiation_failed') {
@@ -146,13 +160,13 @@ export class MatterMedia {
     this.counters.lastFailureStage = session.negotiationStage || 'create_offer';
     this.counters.lastFailureType = exceptionTypes.has(error?.name) ? error.name : 'Error';
   }
-  getSession(id) { const session = this.session; if (!session || session.id !== id || session.closed) throw fault('unknown_session'); return session; }
+  getSession(id) { const session = this.sessions.get(String(id)); if (!session || session.closed) throw fault('unknown_session'); return session; }
   async provideAnswer(id, value) {
     const session = this.getSession(id); sdp(value);
     if (session.peer.signalingState !== 'have-local-offer') throw fault('invalid_session_state');
     session.negotiationStage = 'remote_answer';
     try { await session.peer.setRemoteDescription({ type: 'answer', sdp: value }); }
-    catch (error) { this.negotiationFailure(session, error); await this.closeSession(id); throw fault('negotiation_failed'); }
+    catch (error) { if (!this.alive(session)) throw fault('session_closed'); this.negotiationFailure(session, error); await this.closeSession(id, session); throw fault('negotiation_failed'); }
   }
   async addCandidates(id, candidates) {
     const session = this.getSession(id);
@@ -165,83 +179,144 @@ export class MatterMedia {
     }
     session.remoteCandidates = (session.remoteCandidates || 0) + candidates.length;
   }
-  async socket(session) {
-    const socket = createSocket('udp4'); session.sockets.add(socket);
-    socket.on('error', () => this.fail(session, 'udp_error'));
+  ownerAlive(owner) { return owner.kind ? this.sourceAlive(owner) : this.alive(owner); }
+  ownerFail(owner, reason) { if (owner.kind) this.failSource(owner, reason); else this.fail(owner, reason); }
+  async socket(owner) {
+    const socket = createSocket('udp4'); owner.sockets.add(socket);
+    socket.on('error', () => this.ownerFail(owner, 'udp_error'));
     await new Promise((resolve, reject) => { socket.once('error', reject); socket.bind(0, '127.0.0.1', resolve); });
-    if (!this.alive(session)) { socket.close(); throw fault('session_closed'); }
+    if (!this.ownerAlive(owner)) { owner.sockets.delete(socket); try { socket.close(); } catch {} throw fault('session_closed'); }
     return socket;
   }
-  job(session, args, failure = true) {
+  job(owner, args, failure = true) {
     let child;
     try { child = this.spawnProcess(this.ffmpegPath, ['-hide_banner', '-nostdin', '-loglevel', 'error', ...args], { stdio: ['pipe', 'pipe', 'pipe'] }); }
     catch { throw fault('ffmpeg_unavailable'); }
-    session.jobs.add(child); child.stdin?.on('error', () => {}); child.stdout?.on('error', () => {});
-    child.stderr?.on('data', () => {}); child.on('error', () => { if (failure) this.fail(session, 'ffmpeg_unavailable'); });
-    child.once('close', () => { session.jobs.delete(child); if (failure && this.alive(session) && !child.intentionalStop) this.fail(session, 'ffmpeg_exit'); });
+    owner.jobs.add(child); child.stdin?.on('error', () => {}); child.stdout?.on('error', () => {});
+    child.stderr?.on('data', () => {}); child.on('error', () => { if (failure) this.ownerFail(owner, 'ffmpeg_unavailable'); });
+    child.once('close', () => { owner.jobs.delete(child); if (failure && this.ownerAlive(owner) && !child.intentionalStop) this.ownerFail(owner, 'ffmpeg_exit'); });
     return child;
   }
-  kill(session, child) {
-    if (!child) return; child.intentionalStop = true; session.jobs.delete(child);
+  kill(owner, child) {
+    if (!child) return; child.intentionalStop = true; owner.jobs.delete(child);
     try { child.kill('SIGTERM'); } catch {}
     timer(() => { if (child.exitCode === null && child.signalCode === null) { try { child.kill('SIGKILL'); } catch {} } }, 1500);
   }
+  sourceAlive(source) { return this.sources.get(source.key) === source && !source.closed && !this.closed && source.subscribers.size > 0; }
+  attachSource(session, kind) {
+    if (!this.alive(session) || (kind === 'audio' && this.microphoneMuted)) return;
+    if (session[`${kind}Source`]) return session[`${kind}Source`];
+    const profile = kind === 'video' ? session.video : { ...session.audio, volume: this.microphoneVolume };
+    const key = `${kind}:${JSON.stringify(profile)}`;
+    let source = this.sources.get(key);
+    if (!source || source.closed) {
+      source = { key, kind, profile, subscribers: new Set(), jobs: new Set(), sockets: new Set(), generation: 0 };
+      this.sources.set(key, source);
+    }
+    source.subscribers.add(session); session[`${kind}Source`] = source;
+    if (kind === 'audio') session.audioSender.replaceRTP({ sequenceNumber: 0, timestamp: 0 }, true, 960);
+    if (!source.starting && !source.started) {
+      source.started = true;
+      if (kind === 'video') source.starting = this.startVideoSource(source).catch(() => this.failSource(source, 'media_unavailable'));
+      else void this.startAudioSource(source);
+    }
+    return source;
+  }
+  detachSource(session, kind) {
+    const source = session[`${kind}Source`]; session[`${kind}Source`] = undefined;
+    if (!source) return;
+    source.subscribers.delete(session);
+    if (!source.subscribers.size) this.closeSource(source);
+  }
+  stopSourceMedia(source) {
+    source.generation++; clearTimeout(source.poll); clearTimeout(source.deadline); source.poll = undefined;
+    source.child = undefined;
+    for (const child of [...source.jobs]) this.kill(source, child);
+    for (const socket of source.sockets) { try { socket.close(); } catch {} } source.sockets.clear();
+  }
+  closeSource(source) {
+    if (source.closed) return;
+    source.closed = true;
+    if (this.sources.get(source.key) === source) this.sources.delete(source.key);
+    this.stopSourceMedia(source);
+    for (const session of source.subscribers) if (session[`${source.kind}Source`] === source) session[`${source.kind}Source`] = undefined;
+    source.subscribers.clear();
+  }
+  failSource(source, reason = 'media_unavailable') {
+    if (!this.sourceAlive(source)) return;
+    const sessions = [...source.subscribers]; this.closeSource(source);
+    for (const session of sessions) this.fail(session, reason);
+  }
+  fanout(source, bytes, payloadType) {
+    if (!this.sourceAlive(source) || !isRtp(bytes) || (bytes[1] & 0x7f) !== payloadType || (source.kind === 'audio' && this.microphoneMuted)) return;
+    clearTimeout(source.deadline);
+    for (const session of [...source.subscribers]) {
+      if (!this.alive(session) || session[`${source.kind}Source`] !== source) continue;
+      this.counters[`${source.kind}Packets`]++;
+      // Each peer has independent SSRC, sequence mapping, retransmission and SRTP.
+      // writeRtp parses/clones its input; no mutable RTP packet crosses peers.
+      try { session[`${source.kind}Track`].writeRtp(bytes); } catch { this.fail(session, 'media_unavailable'); }
+    }
+  }
   async startMedia(session) {
     if (!this.alive(session)) return;
     if ((session.video && !session.videoSender.codec) || (session.audio && !session.audioSender.codec)) throw fault('codec_unavailable');
-    if (session.video) {
-      const source = localUrl(await this.runtime.ensureReady({ timeoutMs: 5000 }), ['/cam.ts']);
-      if (!this.alive(session)) return;
-      const socket = await this.socket(session), v = session.video;
-      session.videoDeadline = timer(() => this.fail(session, 'video_timeout'), this.mediaTimeoutMs);
-      socket.on('message', bytes => { if (!this.alive(session) || !isRtp(bytes) || (bytes[1] & 0x7f) !== 96) return; clearTimeout(session.videoDeadline); this.counters.videoPackets++; session.videoTrack.writeRtp(bytes); });
-      this.job(session, ['-rw_timeout', '8000000', '-analyzeduration', '1000000', '-probesize', '2000000', '-f', 'mpegts', '-i', source,
-        '-map', '0:v:0', '-an', '-sn', '-dn', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-profile:v', 'baseline', '-level:v', '3.1',
-        '-preset', 'ultrafast', '-tune', 'zerolatency', '-threads', '2', '-vf', `scale=${v.width}:${v.height}:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,pad=${v.width}:${v.height}:(ow-iw)/2:(oh-ih)/2`,
-        '-r', String(v.frameRate), '-b:v', String(v.bitRate), '-maxrate', String(v.bitRate), '-bufsize', String(v.bitRate * 2),
-        '-g', String(Math.max(1, Math.round(v.frameRate * v.keyFrameInterval / 1000))), '-bf', '0', '-x264-params', 'repeat-headers=1',
-        '-payload_type', '96', '-f', 'rtp', `rtp://127.0.0.1:${socket.address().port}?pkt_size=1200`]);
-    }
-    if (session.audio) void this.startAudio(session);
+    if (session.video) this.attachSource(session, 'video');
+    if (session.audio) this.startAudio(session);
+  }
+  async startVideoSource(source) {
+    const url = localUrl(await this.runtime.ensureReady({ timeoutMs: 5000 }), ['/cam.ts']);
+    if (!this.sourceAlive(source)) return;
+    const socket = await this.socket(source), v = source.profile;
+    if (!this.sourceAlive(source)) return;
+    source.deadline = timer(() => this.failSource(source, 'video_timeout'), this.mediaTimeoutMs);
+    socket.on('message', bytes => this.fanout(source, bytes, 96));
+    source.child = this.job(source, ['-rw_timeout', '8000000', '-analyzeduration', '1000000', '-probesize', '2000000', '-f', 'mpegts', '-i', url,
+      '-map', '0:v:0', '-an', '-sn', '-dn', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-profile:v', 'baseline', '-level:v', '3.1',
+      '-preset', 'ultrafast', '-tune', 'zerolatency', '-threads', '2', '-vf', `scale=${v.width}:${v.height}:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,pad=${v.width}:${v.height}:(ow-iw)/2:(oh-ih)/2`,
+      '-r', String(v.frameRate), '-b:v', String(v.bitRate), '-maxrate', String(v.bitRate), '-bufsize', String(v.bitRate * 2),
+      '-g', String(Math.max(1, Math.round(v.frameRate * v.keyFrameInterval / 1000))), '-bf', '0', '-x264-params', 'repeat-headers=1',
+      '-payload_type', '96', '-f', 'rtp', `rtp://127.0.0.1:${socket.address().port}?pkt_size=1200`]);
   }
-  async startAudio(session) {
-    if (!this.alive(session) || this.microphoneMuted || session.audioChild || session.audioStarting || !session.audio) return;
-    const generation = session.audioGeneration || 0; session.audioStarting = true;
+  startAudio(session) { if (this.alive(session) && !this.microphoneMuted && session.audio) this.attachSource(session, 'audio'); }
+  async startAudioSource(source) {
+    if (!this.sourceAlive(source) || this.microphoneMuted || source.child || source.starting) return;
+    const generation = source.generation; source.starting = true;
     try {
       const value = await this.runtime.audioSource?.();
-      if (!this.alive(session) || this.microphoneMuted || generation !== (session.audioGeneration || 0)) return;
-      if (!value) { this.pollAudio(session, 2000); return; }
-      const source = audioSource(value), socket = await this.socket(session); session.audioSocket = socket;
-      if (!this.alive(session) || this.microphoneMuted || generation !== (session.audioGeneration || 0)) {
-        session.sockets.delete(socket); try { socket.close(); } catch {} return;
-      }
-      session.audioSender.replaceRTP({ sequenceNumber: 0, timestamp: 0 }, true, 960);
-      socket.on('message', bytes => { if (this.alive(session) && !this.microphoneMuted && generation === (session.audioGeneration || 0) && isRtp(bytes) && (bytes[1] & 0x7f) === 111) { this.counters.audioPackets++; session.audioTrack.writeRtp(bytes); } });
-      session.audioChild = this.job(session, ['-rw_timeout', '8000000', '-f', source.format, '-i', source.url, '-map', '0:a:0', '-vn', '-sn', '-dn',
-        '-af', `volume=${this.microphoneVolume / 100}`, '-c:a', 'libopus', '-ar', '48000', '-ac', '1', '-application', 'lowdelay', '-frame_duration', '20',
-        '-b:a', String(session.audio.bitRate), '-payload_type', '111', '-f', 'rtp', `rtp://127.0.0.1:${socket.address().port}?pkt_size=1200`], false);
-      const child = session.audioChild;
-      child.on('error', () => this.restartAudio(session)); child.once('close', () => { if (session.audioChild === child) this.restartAudio(session); });
-    } catch { if (this.alive(session)) this.pollAudio(session, 2000); }
+      if (!this.sourceAlive(source) || this.microphoneMuted || generation !== source.generation) return;
+      if (!value) { this.pollAudio(source, 2000); return; }
+      const audio = audioSource(value), socket = await this.socket(source);
+      if (!this.sourceAlive(source) || this.microphoneMuted || generation !== source.generation) { source.sockets.delete(socket); try { socket.close(); } catch {} return; }
+      for (const session of source.subscribers) session.audioSender.replaceRTP({ sequenceNumber: 0, timestamp: 0 }, true, 960);
+      socket.on('message', bytes => this.fanout(source, bytes, 111));
+      const child = this.job(source, ['-rw_timeout', '8000000', '-f', audio.format, '-i', audio.url, '-map', '0:a:0', '-vn', '-sn', '-dn',
+        '-af', `volume=${source.profile.volume / 100}`, '-c:a', 'libopus', '-ar', '48000', '-ac', '1', '-application', 'lowdelay', '-frame_duration', '20',
+        '-b:a', String(source.profile.bitRate), '-payload_type', '111', '-f', 'rtp', `rtp://127.0.0.1:${socket.address().port}?pkt_size=1200`], false);
+      source.child = child;
+      child.on('error', () => { if (source.child === child) this.restartAudioSource(source); });
+      child.once('close', () => { if (source.child === child) this.restartAudioSource(source); });
+    } catch { if (this.sourceAlive(source)) this.pollAudio(source, 2000); }
     finally {
-      session.audioStarting = false;
-      if (this.alive(session) && !this.microphoneMuted && !session.audioChild && !session.audioPoll)
-        this.pollAudio(session, 500);
+      source.starting = false;
+      if (this.sourceAlive(source) && !this.microphoneMuted && !source.child && !source.poll) this.pollAudio(source, 500);
     }
   }
-  pollAudio(session, ms) {
-    clearTimeout(session.audioPoll);
-    session.audioPoll = timer(() => { session.audioPoll = undefined; void this.startAudio(session); }, ms);
+  pollAudio(source, ms) {
+    if (!this.sourceAlive(source)) return;
+    clearTimeout(source.poll);
+    source.poll = timer(() => { source.poll = undefined; void this.startAudioSource(source); }, ms);
   }
-  stopAudio(session) {
-    session.audioGeneration = (session.audioGeneration || 0) + 1; clearTimeout(session.audioPoll); session.audioPoll = undefined;
-    this.kill(session, session.audioChild); session.audioChild = undefined;
-    if (session.audioSocket) { session.sockets.delete(session.audioSocket); try { session.audioSocket.close(); } catch {} session.audioSocket = undefined; }
+  stopAudio(session) { this.detachSource(session, 'audio'); }
+  restartAudioSource(source) {
+    this.stopSourceMedia(source);
+    if (this.sourceAlive(source) && !this.microphoneMuted) this.pollAudio(source, 500);
   }
-  restartAudio(session) { this.stopAudio(session); if (this.alive(session) && !this.microphoneMuted) this.pollAudio(session, 500); }
+  restartAudio(session) { this.stopAudio(session); if (this.alive(session) && !this.microphoneMuted && session.started) this.startAudio(session); }
   receiveTalk(session, packet) {
     if (!this.alive(session) || this.speakerMuted || !session.audio || this.config.enableTalkback === false) return;
-    this.counters.talkPackets++;
+    if (this.talkOwner && this.talkOwner !== session) return;
+    this.talkOwner = session; this.counters.talkPackets++;
     if (!session.talk) { session.talk = { queue: [], size: 0, closed: false }; void this.startTalk(session, session.talk); }
     const talk = session.talk; clearTimeout(talk.idleTimer); talk.idleTimer = timer(() => this.stopTalk(session), 2500);
     const copy = packet.clone(); copy.header.extensions = []; copy.header.payloadType = 111;
@@ -284,14 +359,15 @@ export class MatterMedia {
   }
   stopTalk(session, expected) {
     const talk = session.talk; if (!talk || (expected && expected !== talk)) return; session.talk = undefined; talk.closed = true;
+    if (this.talkOwner === session) this.talkOwner = undefined;
     clearTimeout(talk.idleTimer); clearTimeout(talk.readyTimer); talk.queue.length = 0; talk.size = 0;
     this.kill(session, talk.child); talk.post?.end(); timer(() => talk.post?.destroy(), 300);
     if (talk.socket) { session.sockets.delete(talk.socket); try { talk.socket.close(); } catch {} }
   }
-  setMicrophoneMuted(value) { this.microphoneMuted = value === true || this.config.enableAudio === false; if (this.session) { this.stopAudio(this.session); if (!this.microphoneMuted && this.session.started) void this.startAudio(this.session); } }
-  setSpeakerMuted(value) { this.speakerMuted = value === true || this.config.enableAudio === false || this.config.enableTalkback === false; if (this.session) this.stopTalk(this.session); }
-  setMicrophoneVolume(value) { this.microphoneVolume = clamp(integer(value, 100, 0, 100), 0, 100); if (this.session) this.restartAudio(this.session); }
-  setSpeakerVolume(value) { this.speakerVolume = clamp(integer(value, 100, 0, 100), 0, 100); if (this.session) this.stopTalk(this.session); }
+  setMicrophoneMuted(value) { this.microphoneMuted = value === true || this.config.enableAudio === false; for (const session of this.sessions.values()) this.stopAudio(session); if (!this.microphoneMuted) for (const session of this.sessions.values()) if (session.started) this.startAudio(session); }
+  setSpeakerMuted(value) { this.speakerMuted = value === true || this.config.enableAudio === false || this.config.enableTalkback === false; for (const session of this.sessions.values()) this.stopTalk(session); }
+  setMicrophoneVolume(value) { this.microphoneVolume = clamp(integer(value, 100, 0, 100), 0, 100); for (const session of this.sessions.values()) this.stopAudio(session); if (!this.microphoneMuted) for (const session of this.sessions.values()) if (session.started) this.startAudio(session); }
+  setSpeakerVolume(value) { this.speakerVolume = clamp(integer(value, 100, 0, 100), 0, 100); for (const session of this.sessions.values()) this.stopTalk(session); }
   async snapshot({ width = 320, height = 180 } = {}) {
     if (this.closed) throw fault('closed');
     width = integer(width, 320, 2, 1280); height = integer(height, 180, 2, 720);
@@ -300,9 +376,10 @@ export class MatterMedia {
     if (!Buffer.isBuffer(data) || data.length > 8 * 1024 * 1024) throw fault('snapshot_invalid');
     return { data, ...jpegSize(data) };
   }
-  async closeSession(id) {
-    const session = this.session; if (!session || session.id !== id || session.closed) return;
-    session.closed = true; this.session = undefined;
+  async closeSession(id, expected) {
+    const session = this.sessions.get(String(id)); if (!session || session.closed || (expected && session !== expected)) return;
+    session.closed = true; this.sessions.delete(String(id));
+    this.detachSource(session, 'video');
     for (const name of ['connectTimer', 'disconnectTimer', 'lifeTimer', 'videoDeadline']) clearTimeout(session[name]);
     this.stopAudio(session); this.stopTalk(session);
     for (const child of [...session.jobs]) this.kill(session, child);
@@ -311,6 +388,6 @@ export class MatterMedia {
     try { await session.peer.close(); } catch {}
     this.emit(session, 'closed');
   }
-  async close() { this.closed = true; if (this.session) await this.closeSession(this.session.id); }
+  async close() { this.closed = true; await Promise.all([...this.sessions.keys()].map(id => this.closeSession(id))); for (const source of [...this.sources.values()]) this.closeSource(source); }
 }
 export const createMatterMedia = options => new MatterMedia(options);

package/lib/matter-ptz-cluster.mjs

@@ -0,0 +1,100 @@
+import { ClusterBehavior } from '@matter/main';
+import { ClusterModel } from '@matter/main/model';
+import { ClusterId, ClusterType, Status, StatusResponseError } from '@matter/main/types';
+
+// Test VID matches this development Matter camera. This is a directional step extension,
+// not the standard MechanicalPan/Tilt cluster and never describes angles or zoom.
+export const MIJIA_PTZ_STEP_CLUSTER_ID = ClusterId(0xfff1fc01);
+export const PTZ_STEP_DIRECTIONS = Object.freeze(['up', 'down', 'left', 'right']);
+const fail = (status, message) => { throw new StatusResponseError(message, status); };
+const field = (name, id, type, extra = {}) => ({ tag: 'field', name, id, type, conformance: 'M', ...extra });
+const attribute = (name, id, type, value) => ({ tag: 'attribute', name, id, type,
+  access: 'R V', conformance: 'M', default: value });
+
+export const MijiaPtzStep = ClusterType(new ClusterModel({
+  name: 'MijiaPtzStep', id: MIJIA_PTZ_STEP_CLUSTER_ID, classification: 'application', children: [
+    { tag: 'attribute', name: 'ClusterRevision', id: 0xfffd, type: 'ClusterRevision', default: 1 },
+    attribute('Supported', 0, 'bool', false),
+    attribute('Available', 1, 'bool', false),
+    attribute('Mode', 2, 'ModeEnum', 0),
+    attribute('Directions', 3, 'DirectionBitmap', 0),
+    { tag: 'datatype', name: 'ModeEnum', type: 'enum8', children: [field('Step', 0)] },
+    { tag: 'datatype', name: 'DirectionEnum', type: 'enum8', children: PTZ_STEP_DIRECTIONS.map((name, id) =>
+      field(name[0].toUpperCase() + name.slice(1), id)) },
+    { tag: 'datatype', name: 'DirectionBitmap', type: 'map8', children: PTZ_STEP_DIRECTIONS.map((name, id) =>
+      ({ tag: 'field', name: name[0].toUpperCase() + name.slice(1), constraint: String(id), conformance: 'M' })) },
+    { tag: 'command', name: 'MoveStep', id: 0, access: 'O', conformance: 'M', direction: 'request', response: 'status',
+      children: [field('Direction', 0, 'DirectionEnum', { constraint: '0 to 3' })] },
+  ],
+}));
+
+export const MijiaPtzStepBehavior = ClusterBehavior.for(MijiaPtzStep);
+
+export function normalizeMatterPtzCapabilities(value) {
+  const supported = value?.supported === true && value?.relativeStep === true;
+  const directions = supported && Array.isArray(value.directions)
+    ? PTZ_STEP_DIRECTIONS.filter(direction => value.directions.includes(direction)) : [];
+  return { supported: supported && directions.length > 0, available: supported && directions.length > 0 && value.available === true,
+    mode: 0, directions: Object.fromEntries(PTZ_STEP_DIRECTIONS.map(direction => [direction, directions.includes(direction)])) };
+}
+
+/** Shared across Matter actors so simultaneous fabrics cannot queue camera movements. */
+export class MatterPtzStepControl {
+  constructor({ runtime, onChange } = {}) {
+    this.runtime = runtime; this.onChange = onChange; this.closed = false; this.busy = false;
+    this.revision = 0; this.selectionRevision = 0; this.capabilities = normalizeMatterPtzCapabilities();
+    this.publication = Promise.resolve();
+  }
+  state() { return { ...this.capabilities, directions: { ...this.capabilities.directions },
+    available: !this.closed && !this.busy && this.capabilities.available }; }
+  publish() {
+    // endpoint.set() transactions can acquire their locks out of invocation order. Serialize
+    // publications and read the latest state when each runs so a stale busy update cannot
+    // leave controllers permanently unavailable after the command has completed.
+    this.publication = this.publication.then(() => this.onChange?.(this.state())).catch(() => {});
+    return this.publication;
+  }
+  async refresh({ invalidate = false } = {}) {
+    const revision = ++this.revision;
+    if (invalidate) { this.selectionRevision++; this.capabilities = normalizeMatterPtzCapabilities(); this.publish(); }
+    if (this.closed) return this.state();
+    let value;
+    try { value = await this.runtime?.getPtzCapabilities?.(); } catch {}
+    if (!this.closed && revision === this.revision) {
+      this.capabilities = normalizeMatterPtzCapabilities(value); await this.publish();
+    }
+    return this.state();
+  }
+  async move(direction) {
+    if (!Number.isInteger(direction) || !PTZ_STEP_DIRECTIONS[direction]) fail(Status.ConstraintError, 'Invalid step direction');
+    if (this.closed) fail(Status.InvalidInState, 'Direction control is closed');
+    if (this.busy) fail(Status.Busy, 'Direction control is busy');
+    // Set the guard before any await, including an asynchronous capability lookup.
+    this.busy = true; this.publish();
+    const selectionRevision = this.selectionRevision;
+    try {
+      await this.refresh();
+      if (this.closed || selectionRevision !== this.selectionRevision) fail(Status.InvalidInState, 'Camera selection changed');
+      const state = this.capabilities;
+      if (!state.supported || !state.available || !state.directions[PTZ_STEP_DIRECTIONS[direction]]
+        || typeof this.runtime?.movePtz !== 'function') fail(Status.InvalidInState, 'Direction step is unavailable');
+      let reply;
+      try { reply = await this.runtime.movePtz(PTZ_STEP_DIRECTIONS[direction]); }
+      catch (error) {
+        if (error?.reason === 'ptz_busy' || error?.reason === 'control_busy') fail(Status.Busy, 'Direction control is busy');
+        if (['ptz_unsupported', 'ptz_unavailable', 'auth_in_progress', 'query_cancelled'].includes(error?.reason))
+          fail(Status.InvalidInState, 'Direction step is unavailable');
+        fail(Status.Failure, 'Direction step was not accepted');
+      }
+      if (this.closed || selectionRevision !== this.selectionRevision) fail(Status.InvalidInState, 'Camera selection changed');
+      if (reply?.accepted !== true) fail(Status.Failure, 'Direction step was not accepted');
+    } finally {
+      this.busy = false;
+      if (!this.closed) await this.refresh();
+    }
+  }
+  close() {
+    this.closed = true; this.revision++; this.selectionRevision++;
+    this.capabilities = normalizeMatterPtzCapabilities(); this.publish();
+  }
+}

package/lib/matter-service.mjs

@@ -43,10 +43,11 @@ export class MatterService {
       if (!Number.isInteger(port) || port < 1024 || port > 65535 || typeof networkInterface !== 'string'
         || !/^[A-Za-z0-9_.:-]{1,40}$/.test(networkInterface) || typeof this.storagePath !== 'string')
         throw failure('matter_configuration_invalid');
+      const maxStreams = bounded(this.config.matterMaxStreams, 2, 1, 4);
       const createMedia = this.mediaFactory ?? (await import('./matter-media.mjs')).createMatterMedia;
       if (this.closed) throw failure('matter_closed');
       this.media = await createMedia({ runtime: this.runtime, ffmpegPath: this.runtime.ffmpegPath,
-        config: this.config, snapshotDelegate: this.delegate });
+        config: { ...this.config, maxStreams }, snapshotDelegate: this.delegate });
       const createDevice = this.deviceFactory ?? (await import('./matter-device.mjs')).createMatterDevice;
       if (this.closed) throw failure('matter_closed');
       const selected = this.runtime.selected?.();
@@ -57,7 +58,7 @@ export class MatterService {
           height: bounded(this.config.maxHeight, 360, 120, 720) & ~1,
           frameRate: bounded(this.config.maxFPS, 12, 1, 25),
           bitRate: bounded(this.config.maxBitrate, 700, 100, 2000) * 1000,
-          maxStreams: 1, enableAudio: this.config.enableAudio !== false,
+          maxStreams, enableAudio: this.config.enableAudio !== false,
           enableTalkback: this.config.enableAudio !== false && this.config.enableTalkback !== false,
           nightVision: this.config.enableNightVision !== false
             && ['chuangmi.camera.061a01', 'chuangmi.camera.061a03'].includes(selected?.model) } });
@@ -67,8 +68,17 @@ export class MatterService {
       this.state = 'ready';
       this.statusListener = value => {
         if (value?.ready !== true) void Promise.resolve().then(() => this.device?.closeSessions?.()).catch(() => {});
+        void Promise.resolve().then(() => this.device?.refreshPtzCapabilities?.()).catch(() => {});
+      };
+      this.selectionListener = () => {
+        try { void Promise.resolve(this.device?.refreshPtzCapabilities?.({ invalidate: true })).catch(() => {}); } catch {}
+      };
+      this.ptzListener = () => {
+        void Promise.resolve().then(() => this.device?.refreshPtzCapabilities?.()).catch(() => {});
       };
       this.runtime.on?.('status', this.statusListener);
+      this.runtime.on?.('selection', this.selectionListener);
+      this.runtime.on?.('ptz-capabilities', this.ptzListener);
       return this.status();
     } catch (error) {
       await this._release();
@@ -102,7 +112,9 @@ export class MatterService {
   }
   async _release() {
     if (this.statusListener) this.runtime.off?.('status', this.statusListener);
-    this.statusListener = undefined;
+    if (this.selectionListener) this.runtime.off?.('selection', this.selectionListener);
+    if (this.ptzListener) this.runtime.off?.('ptz-capabilities', this.ptzListener);
+    this.statusListener = this.selectionListener = this.ptzListener = undefined;
     for (const value of [this.device, this.media]) { try { await value?.close?.(); } catch {} }
   }
   close() {