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

package/lib/matter-media.mjs

@@ -8,6 +8,7 @@ const integer = (value, fallback, min, max) => Number.isInteger(value) && value
 const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
 const timer = (callback, ms) => { const value = setTimeout(callback, ms); value.unref(); return value; };
 const isRtp = bytes => Buffer.isBuffer(bytes) && bytes.length >= 12 && bytes.length <= 2048 && (bytes[0] >> 6) === 2;
+const exceptionTypes = new Set(['Error', 'TypeError', 'RangeError', 'OperationError', 'InvalidStateError', 'InvalidModificationError', 'InvalidAccessError', 'NotSupportedError', 'SyntaxError', 'AbortError']);
 function localUrl(value, paths) {
   try {
     const url = new URL(value);
@@ -63,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');
@@ -94,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 {}
@@ -113,26 +127,46 @@ export class MatterMedia {
       if (track.kind === 'audio') track.onReceiveRtp.subscribe(packet => this.receiveTalk(session, packet));
     });
     try {
-      if (offer !== undefined) await peer.setRemoteDescription({ type: 'offer', sdp: offer });
+      // Install source codec constraints before applying an offer. With no local
+      // source werift chooses the first H264 MIME match, which can be a different
+      // profile from the encoded RTP source in a browser's multi-profile offer.
       for (const [kind, enabled] of [['video', session.video], ['audio', session.audio]]) {
         if (!enabled) continue;
+        session.negotiationStage = `replace_${kind}_track`;
         const track = new MediaStreamTrack({ kind, codec: codecs[kind][0] }); session[`${kind}Track`] = track;
-        const existing = offer !== undefined ? peer.getTransceivers().find(t => t.kind === kind && !t.stopped) : undefined;
         const direction = kind === 'audio' && this.config.enableTalkback !== false ? 'sendrecv' : 'sendonly';
-        if (existing) { await existing.sender.replaceTrack(track); existing.direction = direction; session[`${kind}Sender`] = existing.sender; }
-        else if (offer === undefined) session[`${kind}Sender`] = peer.addTransceiver(track, { direction }).sender;
-        else throw fault('media_not_offered');
+        session[`${kind}Sender`] = peer.addTransceiver(track, { direction }).sender;
+      }
+      if (offer !== undefined) {
+        session.negotiationStage = 'remote_description'; await peer.setRemoteDescription({ type: 'offer', sdp: offer });
+        for (const kind of ['video', 'audio']) {
+          if (session[kind] && !peer.getTransceivers().some(t => t.sender === session[`${kind}Sender`] && t.mid != null && !t.stopped && !t.rejected)) throw fault('media_not_offered');
+        }
       }
-      await peer.setLocalDescription(offer !== undefined ? await peer.createAnswer() : await peer.createOffer());
+      session.negotiationStage = offer !== undefined ? 'create_answer' : 'create_offer';
+      const description = offer !== undefined ? await peer.createAnswer() : await peer.createOffer();
+      session.negotiationStage = 'local_description'; await peer.setLocalDescription(description);
       if (!this.alive(session)) throw fault('session_closed');
       return offer !== undefined ? { answer: peer.localDescription.sdp } : { offer: peer.localDescription.sdp };
-    } catch (error) { await this.closeSession(id); throw fault(error?.reason === 'media_not_offered' ? 'media_not_offered' : 'negotiation_failed'); }
+    } 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, session); throw fault(reason);
+    }
   }
-  getSession(id) { const session = this.session; if (!session || session.id !== id || session.closed) throw fault('unknown_session'); return session; }
+  negotiationFailure(session, error, reason = 'negotiation_failed') {
+    this.counters.failures++; this.counters.lastFailure = reason;
+    this.counters.lastFailureStage = session.negotiationStage || 'create_offer';
+    this.counters.lastFailureType = exceptionTypes.has(error?.name) ? error.name : 'Error';
+  }
+  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');
-    try { await session.peer.setRemoteDescription({ type: 'answer', sdp: value }); } catch { this.fail(session, 'negotiation_failed'); throw fault('negotiation_failed'); }
+    session.negotiationStage = 'remote_answer';
+    try { await session.peer.setRemoteDescription({ type: 'answer', sdp: value }); }
+    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);
@@ -145,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 startAudio(session) {
-    if (!this.alive(session) || this.microphoneMuted || session.audioChild || session.audioStarting || !session.audio) return;
-    const generation = session.audioGeneration || 0; session.audioStarting = true;
+  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`]);
+  }
+  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;
@@ -264,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);
@@ -280,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);
@@ -291,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() {

package/lib/platform.mjs

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { MijiaCameraDelegate } from './camera.mjs';
 import { configureNightVision } from './night-vision.mjs';
+import { configurePtz } from './ptz.mjs';
 import { MatterService } from './matter-service.mjs';
 
 export const PLUGIN_NAME = '@linanw/homebridge-mijia-remote-camera';
@@ -69,6 +70,7 @@ export class MijiaRemoteCameraPlatform {
     if (!selected || !numeric(selected.deviceId) || !numeric(selected.homeId) || !numeric(selected.homeOwner)) {
       this.delegate?.shutdown();
       this.nightVision?.shutdown?.();
+      this.ptz?.shutdown?.();
       await this.matter?.close?.();
       this.log.info('请打开插件设置，登录米家并选择家庭和摄像头。');
       return;
@@ -76,6 +78,7 @@ export class MijiaRemoteCameraPlatform {
     if (this.deviceId && this.deviceId !== selected.deviceId) {
       this.delegate?.shutdown();
       this.nightVision?.shutdown?.();
+      this.ptz?.shutdown?.();
       await this.matter?.close?.();
       this.log.info('已保存新的摄像头选择，请重启 Homebridge 使配件变更生效。');
       return;
@@ -95,7 +98,7 @@ export class MijiaRemoteCameraPlatform {
       ?.setCharacteristic(this.api.hap.Characteristic.Manufacturer, 'Xiaomi')
       .setCharacteristic(this.api.hap.Characteristic.Model, label(selected.model || '米家远程摄像头'))
       .setCharacteristic(this.api.hap.Characteristic.SerialNumber, `MiCam-${opaqueId}`)
-      .setCharacteristic(this.api.hap.Characteristic.FirmwareRevision, '0.2.0');
+      .setCharacteristic(this.api.hap.Characteristic.FirmwareRevision, '0.3.0');
     this.delegate = this.delegateFactory({ api: this.api, log: this.log, runtime: this.runtime,
       config: this.config, ffmpegPath: this.runtime.ffmpegPath });
     accessory.configureController(this.delegate.controller);
@@ -103,6 +106,9 @@ export class MijiaRemoteCameraPlatform {
     if (this.delegate.talkbackEnabled) this.delegate.controller.setSpeakerMuted(false);
     if (this.config.enableNightVision !== false) this.nightVision = configureNightVision({ api: this.api,
       accessory, runtime: this.runtime, model: selected.model, name: '夜视', log: this.log });
+    if (this.config.enablePtzSwitches === true) this.ptz = await configurePtz({ api: this.api,
+      accessory, runtime: this.runtime, selection: selected, log: this.log });
+    if (this.stopping) { this.ptz?.shutdown?.(); this.nightVision?.shutdown?.(); this.delegate?.shutdown(); return; }
     this.api.publishExternalAccessories(PLUGIN_NAME, [accessory]);
     this.accessory = accessory;
     this.deviceId = selected.deviceId;
@@ -120,6 +126,7 @@ export class MijiaRemoteCameraPlatform {
     this.stopping = true;
     this.delegate?.shutdown();
     this.nightVision?.shutdown?.();
+    this.ptz?.shutdown?.();
     this.runtime?.off?.('selection', this.selectionListener);
     await Promise.allSettled([this.matter?.close?.(), this.runtime?.stop?.()]);
     await this.runtime?.close?.();