@linanw/homebridge-mijia-remote-camera 0.1.0 → 0.1.1

package/README.md

@@ -4,13 +4,13 @@
 
 登录、家庭选择、远程摄像头连接、快照和 HomeKit 视频由插件管理，无需独立的 viewer / relay 容器或另一个摄像头插件。摄像头可以位于其他网络。
 
-这是实验性接入，目前后端仅实现 CS2/vendor 4。**尚未在小米智能摄像机 3 Pro 云台版上验证实际出画面，也未完成真实 Apple 家庭配对。** npm 安装成功不代表该型号受支持。
+目前后端仅实现 CS2/vendor 4。已在一台小米智能摄像机 3 Pro 云台版上验证跨网络远程取流，以及真实 Apple“家庭”的配对、预览和直播。具体测试环境见下文“验证范围”；其他型号、地区和网络环境尚未逐一验证。
 
 要求 Linux x86_64、Node.js 22 或 24、Homebridge 1.9+ 或 2.x，以及支持自定义插件设置页的 Homebridge UI。适用 Synology DS1618+ 上以 host 网络运行的 Homebridge Docker。支持 glibc 和 musl；其他架构不支持。
 
 ## 安装和首次导入
 
-公开 npm 包仅包含插件代码，**首次需要从已有的本地运行包导入组件**。运行组件不随 npm 分发，也不会自动从网上下载；详情见 `THIRD_PARTY_NOTICES.md`。目前支持指定版本的本地包 `homebridge-mijia-remote-camera-0.1.0.tgz`，已有该包的用户可按以下步骤迁移。没有该本地包时，npm 包本身不能提供视频功能。
+公开 npm 包包含插件代码和由这些源码编译的自有 Java 适配器，**首次需要从已有的本地运行包导入组件**。运行组件不随 npm 分发，也不会自动从网上下载；详情见 `THIRD_PARTY_NOTICES.md`。目前支持指定版本的本地包 `homebridge-mijia-remote-camera-0.1.0.tgz`，已有该包的用户可按以下步骤迁移。没有该本地包时，npm 包本身不能提供视频功能。
 
 先停止此前连接这台摄像头的 `viewer` / `relay` 容器。若已经安装旧的无 scope 插件，先在 Homebridge 管理界面的终端内卸载并重启 Homebridge，释放旧进程：
 
@@ -52,10 +52,12 @@ mijia-camera-setup --from /homebridge/homebridge-mijia-remote-camera-0.1.0.tgz -
 
 已有有效插件会话时可点击“使用已有登录，读取家庭”。取消或失败的授权保留原凭据。更换已发布的摄像头需要重启 Homebridge；同一摄像头更新登录或家庭选择可以刷新连接。
 
-摄像头作为独立配件发布。在 iPhone“家庭 → 添加配件 → 更多选项”中选择它，使用现有 Homebridge 的配对 PIN 添加。
+摄像头作为独立配件发布。在 iPhone“家庭 → 添加配件 → 更多选项”中选择它，使用该摄像头启动日志中 `Please add [...] manually in Home app. Setup Code:` 后面的配对码。插件运行在子桥时，这个码可能与 Homebridge 首页的主桥配对码不同。
 
 默认最高 640×360、12 fps、700 kbps，最多一路实时视频。当前提供实时视频和快照，未接入声音、对讲、云台、运动事件、录像回放及 HomeKit Secure Video。
 
+为兼容 Apple“家庭”的媒体能力协商，插件默认公布 AAC-ELD 16 kHz 音频能力和静音 Microphone 服务；实际不采集或发送摄像头声音。家庭中可能显示麦克风控件，目前仍只提供视频。
+
 ## 数据和运行管理
 
 会话、设备选择和导入的组件保存在：
@@ -74,4 +76,20 @@ mijia-camera-setup --from /homebridge/homebridge-mijia-remote-camera-0.1.0.tgz -
 
 ## 验证范围
 
-已验证原生 HAP CameraController、合成视频快照与 SRTP 发送／独立接收解码、进程清理、授权取消与原子保存、家庭作用域、真实 Homebridge 设置页 IPC 和本地 Java 启动。实际摄像头取流和 Apple 家庭配对仍需设备端验证。
+实际设备验证使用一台小米智能摄像机 3 Pro 云台版，摄像头与 NAS 位于不同网络。Synology DS1618+ 上的 Homebridge Docker 使用 host 网络，Homebridge 2.0.2 / HAP 2.1.6；远程源为 HEVC，由 NAS 解码并转换为 HomeKit 视频。用户已确认 iOS 26.6.2 的 Apple“家庭”预览和直播正常。
+
+本地测试另覆盖 Homebridge 1／2 的原生 HAP CameraController、加密快照与 SRTP 发送／独立接收解码、进程清理、授权取消与原子保存、家庭作用域、真实 Homebridge 设置页 IPC 和本地 Java 启动。
+
+远程中继仍可能间歇断开并自动重连，重连期间预览和直播可能暂不可用。目前尚未完成长时间稳定性验证。
+
+## 连接诊断
+
+设置页可展开“连接诊断”，查看连接阶段、重试次数、上次失败原因及 HomeKit 快照／直播请求计数。“已收到摄像头视频”表示米家视频源已就绪；快照和直播计数则显示 HomeKit 是否已请求媒体。也可在 Homebridge 终端运行：
+
+```sh
+mijia-camera-diagnose --storage /var/lib/homebridge
+```
+
+`--storage` 必须是实例真实的存储目录，也可能是 `/homebridge`。输出不包含小米凭据、设备 ID 或视频地址。HomeKit 快照请求不会跳过连接重试间隔。
+
+能在插件中收到视频、但 Apple“家庭”添加失败时，请检查摄像头日志中的独立 HomeKit 端口及 Setup Code；摄像头端口与主桥／子桥端口不同。

package/THIRD_PARTY_NOTICES.md

@@ -1,9 +1,12 @@
 # Distribution and components
 
 The code distributed in this npm package is licensed under MIT. It does not
-contain the micam backend, compiled bridge, Java runtime, FFmpeg binary, or
+contain the micam backend, third-party Java runtime, FFmpeg binary, or
 ffmpeg-for-homebridge installer. The runtime manifest contains provenance and
 SHA-256 identifiers only; it does not grant rights to the identified components.
+The included `backend/bridge.jar` contains only the original MIT-licensed
+`mijia.bridge.Bridge` adapter classes built from the supplied Java source.
+No micam or Jackson implementation classes are included in that JAR.
 
 The local setup command imports runtime files already available on the user's
 machine. It does not download them or upload them to npm. Local runtime files

package/backend/Bridge.java

@@ -29,9 +29,10 @@ import java.util.Map;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.LongSupplier;
 import java.util.function.Supplier;
 
-/** Private machine interface for Homebridge. No terminal prompts or raw upstream logs. */
+/** Machine interface for Homebridge. No terminal prompts or raw upstream logs. */
 public final class Bridge {
     private static final ObjectMapper JSON = new ObjectMapper();
     private static final PrintStream OUTPUT = System.out;
@@ -44,7 +45,43 @@ public final class Bridge {
     private static final class Failure extends RuntimeException {
         final int exit;
         final String reason;
-        Failure(int exit, String reason) { this.exit = exit; this.reason = reason; }
+        Failure(int exit, String reason) { super(reason); this.exit = exit; this.reason = reason; }
+    }
+
+    enum Stage {
+        DEVICE_LOOKUP("device_lookup"), PROVISIONING("provisioning"), RELAY_CONNECT("relay_connect"),
+        AUTHENTICATION("authentication"), WAITING_VIDEO("waiting_video");
+        final String value;
+        Stage(String value) { this.value = value; }
+    }
+
+    /** The first keyframe deadline is independent of subsequent non-keyframe traffic. */
+    static final class VideoWatchdog {
+        private final LongSupplier clock;
+        private final long started;
+        private final long packetTimeout;
+        private final long keyframeTimeout;
+        private long lastVideo;
+        private boolean receivedKeyframe;
+
+        VideoWatchdog(LongSupplier clock, Duration packetTimeout, Duration keyframeTimeout) {
+            this.clock = clock;
+            this.packetTimeout = packetTimeout.toNanos();
+            this.keyframeTimeout = keyframeTimeout.toNanos();
+            this.started = clock.getAsLong();
+            this.lastVideo = started;
+        }
+
+        void observe(boolean video, boolean keyframe) {
+            long now = clock.getAsLong();
+            if (now - lastVideo >= packetTimeout || (!receivedKeyframe && now - started >= keyframeTimeout)) {
+                throw new Failure(5, "no_video");
+            }
+            if (video) {
+                lastVideo = now;
+                if (keyframe) receivedKeyframe = true;
+            }
+        }
     }
 
     public static void main(String[] args) {
@@ -85,6 +122,7 @@ public final class Bridge {
         }
         if (args.length < 4) throw new Failure(7, "invalid_request");
         Home home = new Home(identifier(args[2]), identifier(args[3]), "", false);
+        if (action.equals("stream")) progress(Stage.DEVICE_LOOKUP);
         List<Device> cameras = request(() -> cloud.deviceList(home)).stream().filter(Device::isCamera).toList();
         if (action.equals("devices") && args.length == 4) {
             emit(Map.of("success", true, "devices", cameras.stream().map(device -> Map.<String, Object>of(
@@ -99,6 +137,7 @@ public final class Bridge {
         Device device = cameras.stream().filter(camera -> did.equals(camera.did())).findFirst()
                 .orElseThrow(() -> new Failure(7, "camera_not_in_home"));
         if (!device.online()) throw new Failure(4, "camera_offline");
+        progress(Stage.PROVISIONING);
         Provisioning provision = request(() -> cloud.missGetVendor(did));
         if (!provision.isCs2()) {
             emit(Map.of("success", false, "reason", "unsupported_transport", "vendor", provision.vendorId()));
@@ -141,22 +180,24 @@ public final class Bridge {
         Thread hook = new Thread(() -> { running.set(false); resources.close(); }, "mijia-bridge-stop");
         Runtime.getRuntime().addShutdownHook(hook);
         try {
+            progress(Stage.RELAY_CONNECT, provision.vendorId());
             resources.relay = new RelaySession(Uid.parse(provision.p2pId()), provision.servers(), null);
             RelaySession.Established established = resources.relay.connect(Duration.ofSeconds(90));
             resources.connection = new PpppConnection(resources.relay.socket(), established.relay(), null);
             resources.connection.start();
             resources.camera = new MissClient(resources.connection);
+            progress(Stage.AUTHENTICATION, provision.vendorId());
             resources.camera.authenticate(provision.clientPublic(), provision.sign(), Duration.ofSeconds(15));
             resources.camera.useSessionKey(MissCrypto.sessionKey(provision.clientPrivate(), provision.devicePublic()));
+            progress(Stage.WAITING_VIDEO, provision.vendorId());
             resources.camera.startVideo(quality, false);
-            long lastVideo = System.nanoTime();
+            VideoWatchdog watchdog = new VideoWatchdog(System::nanoTime, Duration.ofSeconds(10), Duration.ofSeconds(15));
             while (running.get()) {
                 MediaPacket frame = resources.camera.nextMedia(Duration.ofSeconds(1));
+                watchdog.observe(frame != null && frame.isVideo(), frame != null && frame.isVideo() && frame.isKeyframe());
                 if (frame == null || !frame.isVideo()) {
-                    if (System.nanoTime() - lastVideo > Duration.ofSeconds(10).toNanos()) throw new Failure(5, "no_video");
                     continue;
                 }
-                lastVideo = System.nanoTime();
                 if (resources.server == null) {
                     if (!frame.isKeyframe()) continue;
                     resources.server = new HttpStreamServer(port, "/cam.ts", null);
@@ -209,6 +250,12 @@ public final class Bridge {
                 "invalid_device_response", "device_pagination_incomplete", "home_request_failed", "home_request_rejected")
                 .contains(value) ? value : "discovery_failed";
     }
+    static void progress(Stage stage) {
+        emit(Map.of("success", true, "event", "progress", "stage", stage.value));
+    }
+    static void progress(Stage stage, int vendor) {
+        emit(Map.of("success", true, "event", "progress", "stage", stage.value, "vendor", vendor));
+    }
     private static synchronized void emit(Object value) {
         try { OUTPUT.println(JSON.writeValueAsString(value)); OUTPUT.flush(); }
         catch (Exception ignored) { }

package/bin/diagnose.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { createRpcClient } from '../lib/rpc.mjs';
+import { safeDiagnostics } from '../lib/diagnostics.mjs';
+
+const args = process.argv.slice(2);
+if (args.length && (args.length !== 2 || args[0] !== '--storage' || !args[1] || args[1].startsWith('--'))) {
+  console.error('用法: mijia-camera-diagnose --storage <Homebridge 数据目录>');
+  process.exitCode = 2;
+} else {
+  const storage = resolve(args[1] || process.env.HOMEBRIDGE_STORAGE_PATH || process.env.UIX_STORAGE_PATH || join(homedir(), '.homebridge'));
+  try {
+    const metadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const state = await createRpcClient(join(storage, 'mijia-remote-camera')).request('status', {});
+    console.log(JSON.stringify({ pluginVersion: metadata.version, ...safeDiagnostics(state) }, null, 2));
+  } catch {
+    console.error('无法读取运行状态。请确认 Homebridge 已启动，且 --storage 指向其实际数据目录。');
+    process.exitCode = 1;
+  }
+}

package/homebridge-ui/public/index.html

@@ -12,7 +12,8 @@
   <div class="eyebrow">MIJIA · HOMEBRIDGE</div>
   <h1>米家远程摄像头</h1>
   <p class="intro">登录你的小米账号，选择家庭和摄像头。视频由此插件连接米家远程中继，再接入 Apple 家庭。</p>
-  <div id="runtimeStatus" class="status"><span class="dot"></span><span id="runtimeText">正在检查插件状态…</span></div>
+  <div id="runtimeStatus" class="status"><span class="dot"></span><div><span id="runtimeText">正在检查插件状态…</span><div id="connectionDetail" class="small"></div><div id="mediaDetail" class="small"></div></div></div>
+  <details style="margin:-8px 0 20px"><summary style="cursor:pointer;color:var(--muted)">连接诊断</summary><p class="small" style="margin-top:10px">以下报告只包含连接阶段和状态，可复制用于排查。</p><pre id="diagnosticsReport" style="white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;padding:12px;background:var(--panel);border-radius:8px">尚未读取到连接状态。</pre><button id="copyDiagnostics" class="secondary" disabled>复制脱敏诊断</button><p id="diagnosticsHint" class="small" aria-live="polite" style="margin-top:8px"></p></details>
   <section id="components" class="hide"><div class="step">首次设置 · 本地组件</div><h2>导入已有的运行包</h2><p class="small">公开 npm 包仅包含插件代码。先将已有的 <code>homebridge-mijia-remote-camera-0.1.0.tgz</code> 放入 Homebridge 容器的 <code>/homebridge</code>，在管理界面的终端执行：</p><pre style="white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px">mijia-camera-setup --from /homebridge/homebridge-mijia-remote-camera-0.1.0.tgz --storage /homebridge</pre><p class="small">完成后重启 Homebridge。使用其他存储位置时请调整路径。导入程序仅读取本地运行文件，不读取旧包的账号信息。</p></section>
   <section id="bootstrap" class="hide"><div class="step">首次设置</div><h2>先启用插件</h2><p class="small">保存基本配置后，在 Homebridge 首页重新启动。然后回到这里登录小米账号。</p><button id="enable">启用并保存配置</button><div class="row"><button id="check" class="secondary">已重新启动，检查连接</button></div><p id="bootstrapText" class="small" style="margin-top:12px"></p></section>
   <section><div class="step">01 · 小米账号</div><h2>通过官方页面登录</h2>
@@ -26,13 +27,13 @@
     <div class="row"><button id="save" disabled>使用这台摄像头</button></div><p id="selectionState" class="small" style="margin-top:12px"></p>
   </section>
   <div id="error" class="error" role="alert"></div>
-  <div class="footer small"><p>首次连接可能需要一两分钟。当前只提供实时视频和快照。</p><p>配件发布后，在“Apple 家庭 → 添加配件 → 更多选项”中选择摄像头，使用 Homebridge 配对 PIN 添加。</p><p>登录数据只保存在 Homebridge 的私有插件目录，不写入插件配置。</p></div>
+  <div class="footer small"><p>首次连接可能需要一两分钟。当前只提供实时视频和快照。</p><p>配件发布后，在“Apple 家庭 → 添加配件 → 更多选项”中选择摄像头，使用摄像头启动日志中的 Setup Code 添加；子桥配对码可能与主桥不同。</p><p>登录数据只保存在 Homebridge 的私有插件目录，不写入插件配置。</p></div>
 </main>
 <script>
 (() => {
   const $ = id => document.getElementById(id);
   const regions = ['cn','sg','de','us','ru','i2'];
-  let homes=[], devices=[], loginId, pollTimer, statusTimer, configs=[], connected=false, authBusy=false, regionTouched=false, regionNeedsLogin=false, runtimeRegion='cn';
+  let homes=[], devices=[], loginId, pollTimer, statusTimer, clockTimer, configs=[], connected=false, authBusy=false, regionTouched=false, regionNeedsLogin=false, runtimeRegion='cn', diagnosticValue={}, statusReceivedAt=0;
   const messages = { plugin_not_running:'插件尚未启动。请先保存配置并重新启动 Homebridge。', auth_required:'需要完成小米登录。',
     unauthenticated:'需要完成小米登录。', network_error:'连接小米服务失败，请稍后重试。', request_timeout:'请求超时，请稍后重试。',
     login_expired:'登录链接已过期，请重新生成。', login_not_approved:'小米授权未完成，请重新尝试。', login_cancelled:'本次登录已取消。',
@@ -40,7 +41,111 @@
     credentials_write_failed:'无法保存登录数据，请检查 Homebridge 插件目录权限。', home_request_rejected:'家庭列表请求被拒绝，请检查账号权限与地区。',
     home_request_failed:'无法读取家庭或设备列表，请检查网络与登录状态。', session_expired:'小米会话已过期，请重新登录。',
     unsupported_protocol:'当前摄像头的远程传输协议尚不支持。', offline:'米家报告摄像头离线。', selection_missing:'请选择家庭和摄像头。',
-    backend_unavailable:'插件后端暂不可用，请查看 Homebridge 状态。', runtime_unavailable:'插件连接暂不可用，请重新启动 Homebridge。', authentication_required:'小米登录需要重新授权，请生成官方登录链接。', camera_offline:'米家报告摄像头离线。', camera_not_in_home:'所选家庭中未找到此摄像头，请重新选择。', unsupported_transport:'当前摄像头的远程协议尚不支持。', no_video:'摄像头尚未返回视频，请检查电源与网络。', connect_timeout:'连接摄像头超时，正在等待重连。', backend_failed:'取流后端未能启动，请查看插件状态。', storage_failed:'无法访问插件私有目录，请检查权限。', runtime_in_use:'另一个插件进程正在使用此目录。', query_timeout:'读取家庭或设备超时，请重试。', not_selected:'请登录并选择摄像头。', auth_in_progress:'正在进行小米授权，请完成或取消后继续。' };
+    backend_unavailable:'插件后端暂不可用，请查看 Homebridge 状态。', runtime_unavailable:'插件连接暂不可用，请重新启动 Homebridge。', authentication_required:'小米登录需要重新授权，请生成官方登录链接。', camera_offline:'米家报告摄像头离线。', camera_not_in_home:'所选家庭中未找到此摄像头，请重新选择。', unsupported_transport:'当前摄像头的远程协议尚不支持。', no_video:'摄像头尚未返回视频，请检查电源与网络。', connect_timeout:'连接摄像头超时，正在等待重连。', connection_failed:'远程连接未能建立，请检查摄像头与 Homebridge 的网络。', backend_failed:'取流后端未能启动，请查看插件状态。', storage_failed:'无法访问插件私有目录，请检查权限。', runtime_in_use:'另一个插件进程正在使用此目录。', query_timeout:'读取家庭或设备超时，请重试。', not_selected:'请登录并选择摄像头。', auth_in_progress:'正在进行小米授权，请完成或取消后继续。' };
+  const diagnosticStates=new Set(['idle','starting','ready','retrying','blocked','stopped','paused']);
+  const diagnosticStages=new Set(['device_lookup','provisioning','relay_connect','authentication','waiting_video']);
+  const diagnosticReasons=new Set(['not_selected','starting','ready','stopped','retrying','connect_timeout','authentication_required','session_expired','camera_offline','camera_not_in_home','unsupported_transport','invalid_request','invalid_home_selection','invalid_home_response','missing_home_owner','invalid_device_response','device_pagination_incomplete','home_request_failed','home_request_rejected','discovery_failed','backend_failed','connection_failed','no_video','port_in_use','runtime_in_use','runtime_closed','runtime_unavailable','query_timeout','query_cancelled','invalid_backend_response','storage_failed','auth_in_progress']);
+  const mediaReasons = new Set(['media_unavailable', 'closed', 'source_not_ready', 'source_timeout', 'source_invalid',
+    'snapshot_busy', 'snapshot_timeout', 'snapshot_too_large', 'snapshot_invalid', 'ffmpeg_missing', 'ffmpeg_permission',
+    'ffmpeg_spawn', 'ffmpeg_exit', 'ffmpeg_cpu_unsupported', 'input_timeout', 'input_unavailable', 'input_invalid',
+    'decode_failed', 'encoder_unavailable', 'encode_failed', 'udp_unreachable', 'udp_in_use', 'udp_error',
+    'invalid_prepare', 'invalid_stream', 'start_timeout', 'prepare_timeout', 'receiver_timeout', 'stream_stopped', 'stream_reset']);
+  const mediaEvents = new Set(['snapshot_requested', 'snapshot_success', 'snapshot_failure', 'stream_prepared',
+    'stream_start', 'stream_first_frame', 'stream_failure', 'stream_stop', 'stream_rtcp_first']);
+  const mediaSignals = new Set(['SIGTERM', 'SIGKILL', 'SIGILL', 'SIGABRT', 'SIGSEGV', 'SIGBUS', 'SIGFPE']);
+  const mediaStreamStates = new Set(['idle', 'prepared', 'starting', 'active', 'stopped']);
+  const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+  const count = value => Number.isSafeInteger(value) && value >= 0;
+  const timestamp = value => value === null || (typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value));
+
+  function safeMediaDiagnostics(value) {
+    const result = {};
+    for (const key of ['activeStreams', 'activeJobs']) if (count(value[key])) result[key] = value[key];
+    for (const [kind, counters, timestamps] of [
+      ['snapshot', ['requests', 'successes', 'failures', 'lastBytes'], ['lastRequestedAt', 'lastCompletedAt', 'lastFailureAt']],
+      ['stream', ['prepared', 'starts', 'firstFrames', 'failures', 'stops', 'rtcpPackets'],
+        ['lastPreparedAt', 'lastStartedAt', 'lastFirstFrameAt', 'lastStoppedAt', 'lastRtcpAt', 'lastFailureAt']],
+    ]) {
+      const source = value[kind];
+      if (!record(source)) continue;
+      const section = {};
+      for (const key of counters) if (count(source[key])) section[key] = source[key];
+      for (const key of timestamps) if (timestamp(source[key])) section[key] = source[key];
+      if (source.lastFailure === null || mediaReasons.has(source.lastFailure)) section.lastFailure = source.lastFailure;
+      if (kind === 'snapshot' && (source.lastElapsedMs === null || count(source.lastElapsedMs))) section.lastElapsedMs = source.lastElapsedMs;
+      if (kind === 'stream' && mediaStreamStates.has(source.state)) section.state = source.state;
+      if (Object.keys(section).length) result[kind] = section;
+    }
+    if (value.lastEvent === null) result.lastEvent = null;
+    else if (record(value.lastEvent) && mediaEvents.has(value.lastEvent.type)
+      && typeof value.lastEvent.at === 'string' && timestamp(value.lastEvent.at)) {
+      const source = value.lastEvent, event = { type: source.type, at: source.at };
+      for (const key of ['width', 'height', 'bytes', 'elapsedMs', 'rtcpPackets']) if (count(source[key])) event[key] = source[key];
+      if (mediaReasons.has(source.reason)) event.reason = source.reason;
+      if (count(source.exitCode) && source.exitCode <= 65535) event.exitCode = source.exitCode;
+      if (mediaSignals.has(source.signal)) event.signal = source.signal;
+      if (typeof source.cached === 'boolean') event.cached = source.cached;
+      result.lastEvent = event;
+    }
+    return result;
+  }
+
+  // Keep the shareable report in step with lib/diagnostics.mjs; never serialize the raw RPC response.
+  function safeDiagnostics(value = {}) {
+    const result = {};
+    if (!record(value)) return result;
+    if (diagnosticStates.has(value.state)) result.state = value.state;
+    if (diagnosticReasons.has(value.reason)) result.reason = value.reason;
+    if (diagnosticStages.has(value.stage)) result.stage = value.stage;
+    for (const key of ['ready', 'videoReceived', 'paused', 'selected', 'authenticated']) {
+      if (typeof value[key] === 'boolean') result[key] = value[key];
+    }
+    if (['cn', 'sg', 'de', 'us', 'ru', 'i2'].includes(value.region)) result.region = value.region;
+    for (const key of ['attempt', 'connectingElapsedSeconds', 'retryInSeconds', 'vendor']) {
+      if (Number.isSafeInteger(value[key]) && value[key] >= 0 && value[key] <= (key === 'vendor' ? 100 : 1000000000)) result[key] = value[key];
+    }
+    if (value.lastFailure === null || diagnosticReasons.has(value.lastFailure)) result.lastFailure = value.lastFailure;
+    for (const key of ['connectingSince', 'retryAt', 'lastFailureAt']) {
+      if (timestamp(value[key])) result[key] = value[key];
+    }
+    if (value.media === null) result.media = null;
+    else if (record(value.media)) {
+      const media = safeMediaDiagnostics(value.media);
+      if (Object.keys(media).length) result.media = media;
+    }
+    return result;
+  }
+  const stageLabels={device_lookup:'正在核对摄像头',provisioning:'正在获取远程连接信息',relay_connect:'正在连接远程中继',authentication:'正在验证摄像头会话',waiting_video:'正在等待摄像头首个关键帧'};
+  function renderRuntime(){
+    const value=diagnosticValue, since=Math.max(0,Math.floor((Date.now()-statusReceivedAt)/1000));
+    const live=value.ready===true&&value.videoReceived===true;
+    $('runtimeStatus').dataset.live=String(live);
+    const detail=[];
+    if(value.state==='starting'){
+      $('runtimeText').textContent=stageLabels[value.stage]||'正在连接摄像头…';
+      if(value.attempt>0)detail.push(`正在尝试第 ${value.attempt} 次`);
+      if(Number.isSafeInteger(value.connectingElapsedSeconds))detail.push(`已等待 ${value.connectingElapsedSeconds+since} 秒`);
+    }else if(value.state==='retrying'){
+      const remaining=Number.isSafeInteger(value.retryInSeconds)?Math.max(0,value.retryInSeconds-since):0;
+      $('runtimeText').textContent=remaining>0?`连接中断，将在 ${remaining} 秒后重试。`:'连接中断，即将重试。';
+      if(value.attempt>0)detail.push(`第 ${value.attempt} 次尝试未完成`);
+    }else if(live){
+      $('runtimeText').textContent='已收到摄像头视频。';
+      if(value.attempt>0)detail.push(`第 ${value.attempt} 次尝试已连接`);
+    }else if(value.ready===true||value.state==='ready'){
+      $('runtimeText').textContent='等待摄像头首帧。';
+    }else{
+      const states={idle:'请登录并选择摄像头。',stopped:'连接已停止。',paused:'连接已暂停，请选择摄像头启动。',blocked:'连接需要处理。'};
+      $('runtimeText').textContent=messages[value.reason]||states[value.state]||'插件已运行，可以登录并选择摄像头。';
+      if(value.attempt>0)detail.push(`已尝试 ${value.attempt} 次`);
+    }
+    if(value.lastFailure)detail.push(`上次连接：${messages[value.lastFailure]||'未能完成，请查看连接诊断。'}`);
+    $('connectionDetail').textContent=detail.join(' · ');
+    const media=[];
+    if(Number.isSafeInteger(value.media?.snapshot?.requests))media.push(`快照 ${value.media.snapshot.requests} 次`);
+    if(Number.isSafeInteger(value.media?.stream?.starts))media.push(`直播 ${value.media.stream.starts} 次`);
+    $('mediaDetail').textContent=media.length?'HomeKit 媒体请求：'+media.join(' · '):'';
+  }
   function reason(error){return error?.error?.reason || error?.requestError?.reason || error?.reason || error?.message;}
   function showError(error){const key=reason(error); $('error').textContent=messages[key] || '操作未完成，请检查插件状态后重试。'; if(key==='plugin_not_running')$('bootstrap').classList.remove('hide');}
   function clearError(){$('error').textContent='';}
@@ -50,7 +155,8 @@
   function chosenDevice(){return devices[Number($('devices').value)];}
   function setLoginBusy(busy){authBusy=busy;$('login').disabled=busy||!connected; $('load').disabled=busy||!connected||regionNeedsLogin; $('region').disabled=busy; $('cancel').classList.toggle('hide',!busy);}
   function hideLoginLink(){$('loginLink').classList.add('hide');$('officialLogin').removeAttribute('href');}
-  async function status(){try{const value=await request('/status');connected=true;$('components').classList.add('hide');$('bootstrap').classList.add('hide');if(regions.includes(value.region)){runtimeRegion=value.region;if(!regionTouched&&!authBusy)$('region').value=runtimeRegion;}regionNeedsLogin=$('region').value!==runtimeRegion;setLoginBusy(authBusy);const ready=value.ready===true||value.state==='ready';$('runtimeStatus').dataset.live=String(ready);const states={idle:'请登录并选择摄像头。',unconfigured:'请登录并选择摄像头。',connecting:'正在连接摄像头…',starting:'正在连接摄像头…',ready:value.videoReceived?'已收到摄像头视频。':'转播端口已就绪，等待摄像头首帧。',retrying:'连接中断，正在等待重连。',paused:'连接已暂停，请选择摄像头启动。',blocked:'连接需要处理。'};$('runtimeText').textContent=messages[value.reason]||states[value.state]||'插件已运行，可以登录并选择摄像头。';}catch(error){connected=false;$('login').disabled=true;$('load').disabled=true;$('runtimeText').textContent='等待插件启动';showError(error);}}
+  async function status(){try{const value=await request('/status');connected=true;$('components').classList.add('hide');$('bootstrap').classList.add('hide');if(regions.includes(value.region)){runtimeRegion=value.region;if(!regionTouched&&!authBusy)$('region').value=runtimeRegion;}regionNeedsLogin=$('region').value!==runtimeRegion;setLoginBusy(authBusy);diagnosticValue=safeDiagnostics(value);statusReceivedAt=Date.now();$('diagnosticsReport').textContent=JSON.stringify(diagnosticValue,null,2);$('copyDiagnostics').disabled=false;renderRuntime();}catch(error){connected=false;$('login').disabled=true;$('load').disabled=true;$('runtimeStatus').dataset.live='false';$('runtimeText').textContent='等待插件启动';$('connectionDetail').textContent='';$('mediaDetail').textContent='';showError(error);}}
+  $('copyDiagnostics').onclick=async()=>{try{if(typeof navigator==='undefined'||typeof navigator.clipboard?.writeText!=='function')throw Error('clipboard_unavailable');await navigator.clipboard.writeText($('diagnosticsReport').textContent);$('diagnosticsHint').textContent='已复制脱敏诊断。';}catch{$('diagnosticsHint').textContent='浏览器无法自动复制，请手动选中上方诊断报告并复制。';}};
   async function loadHomes(){clearError();$('selectionState').textContent='正在读取家庭…';try{const response=await request('/homes');homes=Array.isArray(response)?response:(response.homes||[]);options($('homes'),homes,home=>(home.name||'未命名家庭')+(home.shared?' · 共享家庭':''),'当前地区没有可访问的家庭');$('selectionState').textContent=homes.length?'请选择目标家庭。':'请检查地区及账号的家庭访问权限。';devices=[];options($('devices'),[],()=>'', '先选择家庭');$('save').disabled=true;$('cameraName').disabled=true;if(homes.length)await loadDevices();}catch(error){$('selectionState').textContent='';showError(error);}}
   async function loadDevices(){const home=chosenHome();if(!home)return;clearError();$('selectionState').textContent='正在读取此家庭的摄像头…';$('save').disabled=true;try{const response=await request('/devices',{homeId:String(home.id),homeOwner:String(home.ownerId)});devices=Array.isArray(response)?response:(response.devices||[]);options($('devices'),devices,device=>(device.name||device.model||'摄像头')+(device.online===false?' · 离线':''),'此家庭没有摄像头');$('selectionState').textContent='';deviceChanged();}catch(error){devices=[];options($('devices'),[],()=>'', '读取设备失败');$('selectionState').textContent='';showError(error);}}
   function deviceChanged(){const device=chosenDevice();$('cameraName').disabled=!device;$('save').disabled=!device;$('cameraName').value=device?(device.name||'米家摄像头'):'';}
@@ -58,11 +164,11 @@
   $('login').onclick=async()=>{clearError();hideLoginLink();clearTimeout(pollTimer);setLoginBusy(true);$('authState').textContent='正在生成官方登录链接…';try{const value=await request('/auth/start',{region:$('region').value});const url=new URL(value.loginUrl);if(url.protocol!=='https:'||!(url.hostname==='mi.com'||url.hostname.endsWith('.mi.com')||url.hostname==='xiaomi.com'||url.hostname.endsWith('.xiaomi.com')))throw Error('unsafe_url');loginId=value.loginId;$('officialLogin').href=url.href;$('loginLink').classList.remove('hide');$('authState').textContent='请打开链接完成授权。';pollTimer=setTimeout(pollAuth,1000);}catch(error){setLoginBusy(false);showError(error);$('authState').textContent='';}};
   $('cancel').onclick=async()=>{clearTimeout(pollTimer);try{await request('/auth/cancel',{loginId});}catch(error){showError(error);}hideLoginLink();setLoginBusy(false);$('authState').textContent='已取消。已有登录数据保留。';};
   $('region').onchange=()=>{regionTouched=true;regionNeedsLogin=$('region').value!==runtimeRegion;setLoginBusy(authBusy);$('authState').textContent=regionNeedsLogin?'已切换地区，请生成新登录链接后读取家庭。':'';}; $('load').onclick=loadHomes; $('homes').onchange=loadDevices; $('devices').onchange=deviceChanged;
-  $('save').onclick=async()=>{const home=chosenHome(),device=chosenDevice();if(!home||!device)return;clearError();$('save').disabled=true;try{const result=await request('/select',{homeId:String(home.id),homeOwner:String(home.ownerId),deviceId:String(device.deviceId||device.did),name:$('cameraName').value.trim()||device.name,model:device.model,region:$('region').value});$('selectionState').textContent=result.restartRequired?'已保存新的摄像头。请重启 Homebridge 使配件变更生效。':'选择已保存，正在连接摄像头。配对时请使用 Homebridge PIN。';await status();}catch(error){showError(error);}finally{$('save').disabled=false;}};
+  $('save').onclick=async()=>{const home=chosenHome(),device=chosenDevice();if(!home||!device)return;clearError();$('save').disabled=true;try{const result=await request('/select',{homeId:String(home.id),homeOwner:String(home.ownerId),deviceId:String(device.deviceId||device.did),name:$('cameraName').value.trim()||device.name,model:device.model,region:$('region').value});$('selectionState').textContent=result.restartRequired?'已保存新的摄像头。请重启 Homebridge 使配件变更生效。':'选择已保存，正在连接摄像头。配对码见摄像头启动日志中的 Setup Code。';await status();}catch(error){showError(error);}finally{$('save').disabled=false;}};
   $('enable').onclick=async()=>{clearError();try{if(!configs.length){configs=[{platform:'MijiaRemoteCamera',name:'米家远程摄像头',region:$('region').value}];await homebridge.updatePluginConfig(configs);}await homebridge.savePluginConfig();$('bootstrapText').textContent='已保存。请在 Homebridge 首页重新启动，再回到这里检查连接。';}catch(error){showError(error);}};
   $('check').onclick=status;
-  async function init(){try{homebridge.hideSchemaForm();try{const components=await request('/components');if(components.ready===false)$('components').classList.remove('hide');}catch{}configs=await homebridge.getPluginConfig();if(!Array.isArray(configs))configs=[];const region=configs[0]?.region;if(regions.includes(region))$('region').value=region;if(!configs.length)$('bootstrap').classList.remove('hide');await status();try{const pending=await request('/auth/status');if(pending.state==='waiting'){loginId=pending.loginId;setLoginBusy(true);$('authState').textContent='先前的授权仍在等待确认。也可取消后生成新链接。';pollTimer=setTimeout(pollAuth,1000);}}catch{}statusTimer=setInterval(status,5000);}catch(error){showError(error);}}
-  window.addEventListener('beforeunload',()=>{clearInterval(statusTimer);clearTimeout(pollTimer);});
+  async function init(){try{homebridge.hideSchemaForm();try{const components=await request('/components');if(components.ready===false)$('components').classList.remove('hide');}catch{}configs=await homebridge.getPluginConfig();if(!Array.isArray(configs))configs=[];const region=configs[0]?.region;if(regions.includes(region))$('region').value=region;if(!configs.length)$('bootstrap').classList.remove('hide');await status();try{const pending=await request('/auth/status');if(pending.state==='waiting'){loginId=pending.loginId;setLoginBusy(true);$('authState').textContent='先前的授权仍在等待确认。也可取消后生成新链接。';pollTimer=setTimeout(pollAuth,1000);}}catch{}statusTimer=setInterval(status,5000);clockTimer=setInterval(()=>{if(connected)renderRuntime();},1000);}catch(error){showError(error);}}
+  window.addEventListener('beforeunload',()=>{clearInterval(statusTimer);clearInterval(clockTimer);clearTimeout(pollTimer);});
   init();
 })();
 </script></body></html>

package/lib/camera.mjs

@@ -2,7 +2,47 @@ import { spawn } from 'node:child_process';
 import { createSocket } from 'node:dgram';
 import { isIP } from 'node:net';
 
-const error = () => new Error('摄像头暂不可用，请在插件设置中检查米家连接。');
+const MEDIA_REASONS = new Set(['media_unavailable', 'closed', 'source_not_ready', 'source_timeout', 'source_invalid',
+  'snapshot_busy', 'snapshot_timeout', 'snapshot_too_large', 'snapshot_invalid', 'ffmpeg_missing', 'ffmpeg_permission',
+  'ffmpeg_spawn', 'ffmpeg_exit', 'ffmpeg_cpu_unsupported', 'input_timeout', 'input_unavailable', 'input_invalid',
+  'decode_failed', 'encoder_unavailable', 'encode_failed', 'udp_unreachable', 'udp_in_use', 'udp_error',
+  'invalid_prepare', 'invalid_stream', 'start_timeout', 'prepare_timeout', 'receiver_timeout', 'stream_stopped', 'stream_reset']);
+const SIGNALS = new Set(['SIGTERM', 'SIGKILL', 'SIGILL', 'SIGABRT', 'SIGSEGV', 'SIGBUS', 'SIGFPE']);
+const EVENTS = new Set(['snapshot_requested', 'snapshot_success', 'snapshot_failure', 'stream_prepared',
+  'stream_start', 'stream_first_frame', 'stream_failure', 'stream_stop', 'stream_rtcp_first']);
+const safeReason = (value, fallback = 'media_unavailable') => MEDIA_REASONS.has(value) ? value : fallback;
+const safeExit = value => Number.isInteger(value) && value >= 0 && value <= 65535 ? value : null;
+const safeSignal = value => SIGNALS.has(value) ? value : null;
+const error = (reason, code, signal) => Object.assign(new Error('摄像头暂不可用，请在插件设置中检查米家连接。'),
+  { reason: safeReason(reason), exitCode: safeExit(code), signal: safeSignal(signal) });
+const elapsed = started => Math.max(0, Math.floor(performance.now() - started));
+function spawnReason(failure) {
+  return ({ ENOENT: 'ffmpeg_missing', EACCES: 'ffmpeg_permission', EPERM: 'ffmpeg_permission' })[failure?.code] || 'ffmpeg_spawn';
+}
+function stderrClassifier() {
+  let tail = Buffer.alloc(0), reason;
+  const patterns = [
+    [/Unknown encoder|Encoder .*not found/i, 'encoder_unavailable'],
+    [/Permission denied/i, 'ffmpeg_permission'],
+    [/Connection timed out|Operation timed out/i, 'input_timeout'],
+    [/Connection refused|Server returned [45]\d\d|HTTP error [45]\d\d/i, 'input_unavailable'],
+    [/Error while decoding|Invalid NAL|Error parsing NAL/i, 'decode_failed'],
+    [/Invalid data found|Could not find codec parameters|could not find.*codec/i, 'input_invalid'],
+    [/Error while opening encoder|Error initializing.*encoder|Error setting.*profile/i, 'encode_failed'],
+    [/Network is unreachable|No route to host/i, 'udp_unreachable'],
+    [/Address already in use/i, 'udp_in_use'],
+  ];
+  return {
+    consume(chunk) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk.subarray(-8192) : Buffer.from(String(chunk).slice(-8192)).subarray(-8192);
+      tail = Buffer.concat([tail, bytes]).subarray(-8192);
+      const value = tail.toString('utf8');
+      for (const [pattern, category] of patterns) if (pattern.test(value)) { reason = category; break; }
+    },
+    failure(code, signal) { return signal === 'SIGILL' ? 'ffmpeg_cpu_unsupported' : reason || 'ffmpeg_exit'; },
+    clear() { tail = Buffer.alloc(0); },
+  };
+}
 const once = callback => {
   let called = false;
   return (...args) => { if (!called) { called = true; callback(...args); } };
@@ -15,9 +55,9 @@ function safeSource(value) {
     const url = new URL(value);
     if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname)
       || url.username || url.password || url.search || url.hash || url.pathname !== '/cam.ts'
-      || !/^\d+$/.test(url.port) || +url.port < 1024 || +url.port > 65535) throw error();
+      || !/^\d+$/.test(url.port) || +url.port < 1024 || +url.port > 65535) throw error('source_invalid');
     return url.href;
-  } catch { throw error(); }
+  } catch { throw error('source_invalid'); }
 }
 function sourceArgs(source) {
   return ['-hide_banner', '-nostdin', '-loglevel', 'error', '-rw_timeout', '8000000',
@@ -29,12 +69,25 @@ function resize(width, height) {
 
 /** Native Homebridge/HAP streaming delegate. All transport keys remain in memory. */
 export class MijiaCameraDelegate {
-  constructor({ api, log, runtime, config = {}, ffmpegPath, spawnProcess = spawn }) {
+  constructor({ api, log, runtime, config = {}, ffmpegPath, spawnProcess = spawn, onMediaEvent,
+    startDeadlineMs = 7500, snapshotTimeoutMs = 10000, audioCompatibility = true }) {
     this.api = api;
+    this.audioCompatibility = audioCompatibility === true;
     this.log = log;
     this.runtime = runtime;
     this.ffmpegPath = ffmpegPath || config.ffmpegPath || 'ffmpeg';
     this.spawnProcess = spawnProcess;
+    this.onMediaEvent = typeof onMediaEvent === 'function' ? onMediaEvent : undefined;
+    this.startDeadlineMs = number(startDeadlineMs, 7500, 1, 7500);
+    this.snapshotTimeoutMs = number(snapshotTimeoutMs, 10000, 1, 10000);
+    this.media = {
+      snapshot: { requests: 0, successes: 0, failures: 0, lastRequestedAt: null, lastCompletedAt: null,
+        lastElapsedMs: null, lastBytes: 0, lastFailure: null, lastFailureAt: null },
+      stream: { prepared: 0, starts: 0, firstFrames: 0, failures: 0, stops: 0, rtcpPackets: 0,
+        lastPreparedAt: null, lastStartedAt: null, lastFirstFrameAt: null, lastStoppedAt: null,
+        lastRtcpAt: null, lastFailure: null, lastFailureAt: null },
+      lastEvent: null,
+    };
     this.limits = {
       width: number(config.maxWidth, 640, 160, 1920),
       height: number(config.maxHeight, 360, 120, 1080),
@@ -45,11 +98,13 @@ export class MijiaCameraDelegate {
     this.jobs = new Set();
     this.snapshots = new Map();
     this.closed = false;
+    // Negotiate one-way AAC-ELD for Home compatibility; camera audio remains disabled.
     this.controller = new api.hap.CameraController({
       cameraStreamCount: 1,
       delegate: this,
       streamingOptions: {
         supportedCryptoSuites: [0],
+        ...(this.audioCompatibility ? { audio: { twoWayAudio: false, codecs: [{ type: 'AAC-eld', samplerate: 16 }] } } : {}),
         video: {
           codec: { profiles: [0, 1, 2], levels: [0, 1, 2] },
           resolutions: [[320, 180, 30], [320, 240, 15], [320, 240, 30],
@@ -59,34 +114,76 @@ export class MijiaCameraDelegate {
     });
   }
 
+  mediaEvent(type, details = {}) {
+    if (!EVENTS.has(type)) return;
+    const value = { type, at: new Date().toISOString() };
+    for (const key of ['width', 'height', 'bytes', 'elapsedMs', 'rtcpPackets']) {
+      if (Number.isSafeInteger(details[key]) && details[key] >= 0) value[key] = details[key];
+    }
+    if (MEDIA_REASONS.has(details.reason)) value.reason = details.reason;
+    if (safeExit(details.exitCode) !== null) value.exitCode = details.exitCode;
+    if (safeSignal(details.signal)) value.signal = details.signal;
+    if (typeof details.cached === 'boolean') value.cached = details.cached;
+    const snapshot = this.media.snapshot, stream = this.media.stream;
+    const increment = (object, key) => { object[key] = Math.min(Number.MAX_SAFE_INTEGER, object[key] + 1); };
+    if (type === 'snapshot_requested') { increment(snapshot, 'requests'); snapshot.lastRequestedAt = value.at; }
+    if (type === 'snapshot_success' || type === 'snapshot_failure') {
+      increment(snapshot, type === 'snapshot_success' ? 'successes' : 'failures');
+      snapshot.lastCompletedAt = value.at; snapshot.lastElapsedMs = value.elapsedMs ?? null;
+      snapshot.lastBytes = type === 'snapshot_success' ? value.bytes ?? 0 : 0;
+      if (type === 'snapshot_failure') { snapshot.lastFailure = value.reason ?? 'media_unavailable'; snapshot.lastFailureAt = value.at; }
+    }
+    const transitions = { stream_prepared: ['prepared', 'lastPreparedAt'], stream_start: ['starts', 'lastStartedAt'],
+      stream_first_frame: ['firstFrames', 'lastFirstFrameAt'], stream_stop: ['stops', 'lastStoppedAt'] };
+    if (transitions[type]) { const [count, timestamp] = transitions[type]; increment(stream, count); stream[timestamp] = value.at; }
+    if (type === 'stream_failure') { increment(stream, 'failures'); stream.lastFailure = value.reason ?? 'media_unavailable'; stream.lastFailureAt = value.at; }
+    this.media.lastEvent = Object.freeze(value);
+    try { Promise.resolve(this.onMediaEvent?.({ ...value })).catch(() => {}); } catch {}
+  }
+
+  getMediaDiagnostics() {
+    const session = this.sessions.values().next().value;
+    return { snapshot: { ...this.media.snapshot }, stream: { ...this.media.stream, state: session?.state || 'idle' },
+      activeStreams: this.sessions.size, activeJobs: this.jobs.size,
+      lastEvent: this.media.lastEvent ? { ...this.media.lastEvent } : null };
+  }
+
   async source() {
-    if (this.closed) throw error();
+    if (this.closed) throw error('closed');
     let timer;
     try {
       const source = await Promise.race([
         this.runtime.ensureReady({ timeoutMs: 3000 }),
-        new Promise((_, reject) => { timer = setTimeout(() => reject(error()), 3200); timer.unref(); }),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(error('source_timeout')), 3200); timer.unref(); }),
       ]);
-      if (this.closed) throw error();
+      if (this.closed) throw error('closed');
       return safeSource(source);
+    } catch (failure) {
+      throw error(safeReason(failure?.reason, 'source_not_ready'));
     } finally { clearTimeout(timer); }
   }
 
   handleSnapshotRequest(request, callback) {
-    const done = once(callback);
     const width = Math.min(number(request.width, 320, 2, 4096), this.limits.width);
     const height = Math.min(number(request.height, 180, 2, 4096), this.limits.height);
+    const started = performance.now();
+    this.mediaEvent('snapshot_requested', { width, height });
+    const done = once((failure, buffer, cached = false) => {
+      this.mediaEvent(failure ? 'snapshot_failure' : 'snapshot_success', { width, height, elapsedMs: elapsed(started), cached,
+        ...(failure ? { reason: safeReason(failure?.reason), exitCode: failure?.exitCode, signal: failure?.signal } : { bytes: buffer.length }) });
+      callback(failure ? error(failure?.reason) : undefined, buffer);
+    });
     const key = `${width}x${height}`;
     const existing = this.snapshots.get(key);
     if (existing && existing.expires > Date.now()) {
-      existing.promise.then(buffer => done(undefined, buffer), () => done(error()));
+      existing.promise.then(buffer => done(undefined, buffer, existing.expires !== Infinity), failure => done(failure));
       return;
     }
     for (const [cachedKey, entry] of this.snapshots) {
       if (entry.expires <= Date.now()) { clearTimeout(entry.timer); this.snapshots.delete(cachedKey); }
     }
     if ([...this.snapshots.values()].filter(entry => entry.expires === Infinity).length >= 2) {
-      done(error()); return;
+      done(error('snapshot_busy')); return;
     }
     if (this.snapshots.size >= 4) {
       const staleKey = [...this.snapshots].find(([, entry]) => entry.expires !== Infinity)?.[0];
@@ -105,7 +202,7 @@ export class MijiaCameraDelegate {
       }, 3000);
       entry.timer.unref();
     }, () => { if (this.snapshots.get(key) === entry) this.snapshots.delete(key); });
-    promise.then(buffer => done(undefined, buffer), () => done(error()));
+    promise.then(buffer => done(undefined, buffer), failure => done(failure));
   }
 
   async snapshot(width, height) {
@@ -114,69 +211,101 @@ export class MijiaCameraDelegate {
       let process;
       let output = Buffer.alloc(0);
       let timer;
+      const diagnostic = stderrClassifier();
       const finish = once((failure, buffer) => {
         clearTimeout(timer);
+        diagnostic.clear();
         if (process) this.jobs.delete(process);
-        failure ? reject(error()) : resolve(buffer);
+        failure ? reject(failure) : resolve(buffer);
       });
       try {
         process = this.spawnProcess(this.ffmpegPath, [
           ...sourceArgs(source), '-map', '0:v:0', '-an', '-sn', '-dn',
           '-vf', resize(width, height), '-frames:v', '1', '-threads', '1',
           '-f', 'image2pipe', '-vcodec', 'mjpeg', 'pipe:1',
-        ], { stdio: ['ignore', 'pipe', 'ignore'] });
+        ], { stdio: ['ignore', 'pipe', 'pipe'] });
         this.jobs.add(process);
+        process.stderr?.on('data', data => diagnostic.consume(data));
         process.stdout.on('data', data => {
           if (output.length + data.length > 8 * 1024 * 1024) {
+            finish(error('snapshot_too_large'));
             this.kill(process);
-            finish(error());
           } else output = Buffer.concat([output, data]);
         });
-        process.once('error', () => finish(error()));
-        process.once('close', code => {
+        process.once('error', failure => finish(error(spawnReason(failure))));
+        process.once('close', (code, signal) => {
           const jpeg = code === 0 && output.length > 4 && output[0] === 0xff && output[1] === 0xd8;
-          finish(jpeg ? undefined : error(), output);
+          finish(jpeg ? undefined : error(code === 0 ? 'snapshot_invalid' : diagnostic.failure(code, signal), code, signal), output);
         });
-        timer = setTimeout(() => { this.kill(process); finish(error()); }, 10000);
+        timer = setTimeout(() => { finish(error('snapshot_timeout')); this.kill(process); }, this.snapshotTimeoutMs);
         timer.unref();
-      } catch { finish(error()); }
+      } catch (failure) { finish(error(spawnReason(failure))); }
     });
   }
 
   prepareStream(request, callback) {
     const done = once(callback);
-    const source = request.video;
+    const source = request.video, audio = request.audio;
+    const validAudio = !this.audioCompatibility || (audio && Number.isInteger(audio.port) && audio.port >= 1 && audio.port <= 65535
+      && audio.srtpCryptoSuite === 0 && Buffer.isBuffer(audio.srtp_key) && audio.srtp_key.length === 16
+      && Buffer.isBuffer(audio.srtp_salt) && audio.srtp_salt.length === 14);
     if (this.closed || typeof request.sessionID !== 'string' || request.sessionID.length > 128
       || this.sessions.size >= 1 || this.sessions.has(request.sessionID)
       || ![4, 6].includes(isIP(request.targetAddress))
       || (request.addressVersion === 'ipv6') !== (isIP(request.targetAddress) === 6)
-      || !source || !Number.isInteger(source.port) || source.port < 1 || source.port > 65535
+      || !validAudio || !source || !Number.isInteger(source.port) || source.port < 1 || source.port > 65535
       || source.srtpCryptoSuite !== 0 || !Buffer.isBuffer(source.srtp_key) || source.srtp_key.length !== 16
       || !Buffer.isBuffer(source.srtp_salt) || source.srtp_salt.length !== 14) {
-      done(error());
+      this.mediaEvent('stream_failure', { reason: 'invalid_prepare' });
+      done(error('invalid_prepare'));
       return;
     }
-    const socket = createSocket(request.addressVersion === 'ipv6' ? 'udp6' : 'udp4');
+    let socket, audioSocket;
+    try {
+      const family = request.addressVersion === 'ipv6' ? 'udp6' : 'udp4';
+      socket = createSocket(family);
+      if (this.audioCompatibility) audioSocket = createSocket(family);
+    } catch {
+      try { socket?.close(); } catch {}
+      this.mediaEvent('stream_failure', { reason: 'udp_error' }); done(error('udp_error')); return;
+    }
     const session = {
-      id: request.sessionID, socket, address: request.targetAddress, port: source.port,
+      id: request.sessionID, socket, audioSocket, finishPrepare: done, address: request.targetAddress, port: source.port,
       crypto: Buffer.concat([source.srtp_key, source.srtp_salt]),
       key: Buffer.from(source.srtp_key), salt: Buffer.from(source.srtp_salt),
       ssrc: this.api.hap.CameraController.generateSynchronisationSource(), state: 'prepared',
+      rtcpPackets: 0,
+      ...(audioSocket ? { audioKey: Buffer.from(audio.srtp_key), audioSalt: Buffer.from(audio.srtp_salt),
+        audioSsrc: this.api.hap.CameraController.generateSynchronisationSource() } : {}),
     };
     this.sessions.set(session.id, session);
-    socket.on('error', () => { this.stopStream(session.id); done(error()); });
+    const socketError = () => { this.failStream(session, 'udp_error'); done(error('udp_error')); };
+    socket.on('error', socketError);
+    audioSocket?.on('error', socketError);
     socket.on('message', (_buffer, remote) => {
-      if (session.state === 'active' && remote.address === session.address) this.keepAlive(session);
+      if (session.state === 'active' && remote.address === session.address) {
+        session.rtcpPackets = Math.min(Number.MAX_SAFE_INTEGER, session.rtcpPackets + 1);
+        this.media.stream.rtcpPackets = Math.min(Number.MAX_SAFE_INTEGER, this.media.stream.rtcpPackets + 1);
+        this.media.stream.lastRtcpAt = new Date().toISOString();
+        if (session.rtcpPackets === 1) this.mediaEvent('stream_rtcp_first', { rtcpPackets: 1 });
+        this.keepAlive(session);
+      }
     });
-    socket.bind(0, () => {
+    let bindings = audioSocket ? 2 : 1;
+    const bound = () => {
+      if (--bindings > 0) return;
       if (!this.sessions.has(session.id) || this.closed) { this.stopStream(session.id); done(error()); return; }
       session.timer = setTimeout(() => this.expire(session.id), 15000);
       session.timer.unref();
+      this.mediaEvent('stream_prepared');
       done(undefined, { video: {
         port: socket.address().port, ssrc: session.ssrc,
         srtp_key: Buffer.from(session.key), srtp_salt: Buffer.from(session.salt),
-      } });
-    });
+      }, ...(audioSocket ? { audio: { port: audioSocket.address().port, ssrc: session.audioSsrc,
+        srtp_key: Buffer.from(session.audioKey), srtp_salt: Buffer.from(session.audioSalt) } } : {}) });
+    };
+    try { socket.bind(0, bound); audioSocket?.bind(0, bound); }
+    catch { socketError(); }
   }
 
   handleStreamRequest(request, callback) {
@@ -186,19 +315,43 @@ export class MijiaCameraDelegate {
       this.sessions.has(request.sessionID) ? done() : done(error());
       return;
     }
-    if (request.type !== 'start') { done(error()); return; }
-    this.startStream(request, done).catch(() => done(error()));
+    if (request.type !== 'start') { this.mediaEvent('stream_failure', { reason: 'invalid_stream' }); done(error('invalid_stream')); return; }
+    this.startStream(request, done).catch(() => {
+      const session = this.sessions.get(request.sessionID);
+      if (session) this.failStream(session, 'media_unavailable');
+      done(error());
+    });
+  }
+
+  failStream(session, reason, details = {}) {
+    if (this.sessions.get(session.id) !== session) return;
+    const safe = safeReason(reason);
+    this.mediaEvent('stream_failure', { ...details, reason: safe,
+      ...(session.started === undefined ? {} : { elapsedMs: elapsed(session.started) }) });
+    this.stopStream(session.id, safe);
+    session.finishStart?.(error(safe));
+    try { this.controller.forceStopStreamingSession(session.id); } catch {}
   }
 
   async startStream(request, callback) {
     const session = this.sessions.get(request.sessionID);
-    if (!session || session.state !== 'prepared') { callback(error()); return; }
+    const done = once(callback);
+    if (!session || session.state !== 'prepared') {
+      this.mediaEvent('stream_failure', { reason: 'invalid_stream' }); done(error('invalid_stream')); return;
+    }
     session.state = 'starting';
+    session.started = performance.now();
+    session.deadline = session.started + this.startDeadlineMs;
+    session.finishStart = done;
+    clearTimeout(session.timer);
+    session.timer = setTimeout(() => this.failStream(session, 'start_timeout'), this.startDeadlineMs);
+    session.timer.unref();
+    this.mediaEvent('stream_start');
     let source;
     try { source = await this.source(); }
-    catch { this.stopStream(session.id); callback(error()); return; }
-    if (this.sessions.get(session.id) !== session || this.closed) { callback(error()); return; }
-    clearTimeout(session.timer);
+    catch (failure) { this.failStream(session, safeReason(failure?.reason, 'source_not_ready')); return; }
+    if (this.sessions.get(session.id) !== session || this.closed) { done(error('stream_stopped')); return; }
+    if (performance.now() >= session.deadline) { this.failStream(session, 'start_timeout'); return; }
     const video = request.video || {};
     const width = Math.min(number(video.width, 640, 2, 4096), this.limits.width);
     const height = Math.min(number(video.height, 360, 2, 4096), this.limits.height);
@@ -217,31 +370,40 @@ export class MijiaCameraDelegate {
       '-srtp_out_suite', 'AES_CM_128_HMAC_SHA1_80', '-srtp_out_params', session.crypto.toString('base64'),
       '-progress', 'pipe:1', '-nostats', target];
     let process;
+    const diagnostic = stderrClassifier();
+    let progress = '';
     try {
-      process = this.spawnProcess(this.ffmpegPath, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+      process = this.spawnProcess(this.ffmpegPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
       session.process = process;
       this.jobs.add(process);
-      session.timer = setTimeout(() => {
-        this.stopStream(session.id); callback(error());
-      }, 10000);
-      session.timer.unref();
+      process.stderr?.on('data', data => diagnostic.consume(data));
       process.stdout.on('data', data => {
-        if (session.state === 'starting' && /frame=\s*[1-9]\d*/.test(data.toString())) {
-          session.state = 'active';
-          this.keepAlive(session);
-          callback();
+        if (this.sessions.get(session.id) !== session || session.state !== 'starting') return;
+        if (performance.now() >= session.deadline) { this.failStream(session, 'start_timeout'); return; }
+        const bytes = Buffer.isBuffer(data) ? data.subarray(-8192) : Buffer.from(String(data).slice(-8192)).subarray(-8192);
+        progress += bytes.toString('utf8');
+        if (progress.length > 16384) { this.failStream(session, 'media_unavailable'); return; }
+        let newline;
+        while ((newline = progress.indexOf('\n')) >= 0) {
+          const line = progress.slice(0, newline).trim(); progress = progress.slice(newline + 1);
+          if (/^frame=\s*[1-9]\d*$/.test(line)) {
+            session.state = 'active'; progress = '';
+            this.mediaEvent('stream_first_frame', { elapsedMs: elapsed(session.started) });
+            this.keepAlive(session);
+            done();
+            break;
+          }
         }
       });
-      process.once('error', () => { this.stopStream(session.id); callback(error()); });
-      process.once('close', () => {
+      process.once('error', failure => this.failStream(session, spawnReason(failure)));
+      process.once('close', (code, signal) => {
         this.jobs.delete(process);
         if (this.sessions.get(session.id) === session) {
-          this.stopStream(session.id);
-          callback(error());
-          try { this.controller.forceStopStreamingSession(session.id); } catch {}
+          this.failStream(session, diagnostic.failure(code, signal), { exitCode: code, signal });
         }
+        diagnostic.clear();
       });
-    } catch { this.stopStream(session.id); callback(error()); }
+    } catch (failure) { this.failStream(session, spawnReason(failure)); }
   }
 
   keepAlive(session) {
@@ -251,8 +413,8 @@ export class MijiaCameraDelegate {
   }
 
   expire(id) {
-    this.stopStream(id);
-    try { this.controller.forceStopStreamingSession(id); } catch {}
+    const session = this.sessions.get(id);
+    if (session) this.failStream(session, session.state === 'prepared' ? 'prepare_timeout' : 'receiver_timeout');
   }
 
   kill(process) {
@@ -263,19 +425,26 @@ export class MijiaCameraDelegate {
     process.once('close', () => clearTimeout(timer));
   }
 
-  stopStream(id) {
+  stopStream(id, reason = 'stream_stopped') {
     const session = this.sessions.get(id);
     if (!session) return;
     this.sessions.delete(id);
+    const starting = session.state === 'starting';
+    session.state = 'stopped';
     clearTimeout(session.timer);
     try { session.socket.close(); } catch {}
+    try { session.audioSocket?.close(); } catch {}
     this.kill(session.process);
     if (session.process) this.jobs.delete(session.process);
     session.crypto.fill(0); session.key.fill(0); session.salt.fill(0);
+    session.audioKey?.fill(0); session.audioSalt?.fill(0);
+    this.mediaEvent('stream_stop', { reason: safeReason(reason), rtcpPackets: session.rtcpPackets });
+    session.finishPrepare?.(error(reason));
+    if (starting) session.finishStart?.(error(reason));
   }
 
   reset() {
-    for (const id of [...this.sessions.keys()]) this.stopStream(id);
+    for (const id of [...this.sessions.keys()]) this.stopStream(id, 'stream_reset');
     for (const process of this.jobs) this.kill(process);
     this.jobs.clear();
     for (const entry of this.snapshots.values()) clearTimeout(entry.timer);

package/lib/diagnostics.mjs

@@ -0,0 +1,78 @@
+const states = new Set(['idle', 'starting', 'ready', 'retrying', 'blocked', 'stopped', 'paused']);
+const stages = new Set(['device_lookup', 'provisioning', 'relay_connect', 'authentication', 'waiting_video']);
+const reasons = new Set(['not_selected', 'starting', 'ready', 'stopped', 'retrying', 'connect_timeout',
+  'authentication_required', 'session_expired', 'camera_offline', 'camera_not_in_home', 'unsupported_transport',
+  'invalid_request', 'invalid_home_selection', 'invalid_home_response', 'missing_home_owner', 'invalid_device_response',
+  'device_pagination_incomplete', 'home_request_failed', 'home_request_rejected', 'discovery_failed',
+  'backend_failed', 'connection_failed', 'no_video', 'port_in_use', 'runtime_in_use', 'runtime_closed',
+  'runtime_unavailable', 'query_timeout', 'query_cancelled', 'invalid_backend_response', 'storage_failed', 'auth_in_progress']);
+const mediaReasons = new Set(['media_unavailable', 'closed', 'source_not_ready', 'source_timeout', 'source_invalid',
+  'snapshot_busy', 'snapshot_timeout', 'snapshot_too_large', 'snapshot_invalid', 'ffmpeg_missing', 'ffmpeg_permission',
+  'ffmpeg_spawn', 'ffmpeg_exit', 'ffmpeg_cpu_unsupported', 'input_timeout', 'input_unavailable', 'input_invalid',
+  'decode_failed', 'encoder_unavailable', 'encode_failed', 'udp_unreachable', 'udp_in_use', 'udp_error',
+  'invalid_prepare', 'invalid_stream', 'start_timeout', 'prepare_timeout', 'receiver_timeout', 'stream_stopped', 'stream_reset']);
+const mediaEvents = new Set(['snapshot_requested', 'snapshot_success', 'snapshot_failure', 'stream_prepared',
+  'stream_start', 'stream_first_frame', 'stream_failure', 'stream_stop', 'stream_rtcp_first']);
+const mediaSignals = new Set(['SIGTERM', 'SIGKILL', 'SIGILL', 'SIGABRT', 'SIGSEGV', 'SIGBUS', 'SIGFPE']);
+const mediaStreamStates = new Set(['idle', 'prepared', 'starting', 'active', 'stopped']);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const count = value => Number.isSafeInteger(value) && value >= 0;
+const timestamp = value => value === null || (typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value));
+
+function safeMediaDiagnostics(value) {
+  const result = {};
+  for (const key of ['activeStreams', 'activeJobs']) if (count(value[key])) result[key] = value[key];
+  for (const [kind, counters, timestamps] of [
+    ['snapshot', ['requests', 'successes', 'failures', 'lastBytes'], ['lastRequestedAt', 'lastCompletedAt', 'lastFailureAt']],
+    ['stream', ['prepared', 'starts', 'firstFrames', 'failures', 'stops', 'rtcpPackets'],
+      ['lastPreparedAt', 'lastStartedAt', 'lastFirstFrameAt', 'lastStoppedAt', 'lastRtcpAt', 'lastFailureAt']],
+  ]) {
+    const source = value[kind];
+    if (!record(source)) continue;
+    const section = {};
+    for (const key of counters) if (count(source[key])) section[key] = source[key];
+    for (const key of timestamps) if (timestamp(source[key])) section[key] = source[key];
+    if (source.lastFailure === null || mediaReasons.has(source.lastFailure)) section.lastFailure = source.lastFailure;
+    if (kind === 'snapshot' && (source.lastElapsedMs === null || count(source.lastElapsedMs))) section.lastElapsedMs = source.lastElapsedMs;
+    if (kind === 'stream' && mediaStreamStates.has(source.state)) section.state = source.state;
+    if (Object.keys(section).length) result[kind] = section;
+  }
+  if (value.lastEvent === null) result.lastEvent = null;
+  else if (record(value.lastEvent) && mediaEvents.has(value.lastEvent.type)
+    && typeof value.lastEvent.at === 'string' && timestamp(value.lastEvent.at)) {
+    const source = value.lastEvent, event = { type: source.type, at: source.at };
+    for (const key of ['width', 'height', 'bytes', 'elapsedMs', 'rtcpPackets']) if (count(source[key])) event[key] = source[key];
+    if (mediaReasons.has(source.reason)) event.reason = source.reason;
+    if (count(source.exitCode) && source.exitCode <= 65535) event.exitCode = source.exitCode;
+    if (mediaSignals.has(source.signal)) event.signal = source.signal;
+    if (typeof source.cached === 'boolean') event.cached = source.cached;
+    result.lastEvent = event;
+  }
+  return result;
+}
+
+/** A deliberately small report suitable for sharing during connection troubleshooting. */
+export function safeDiagnostics(value = {}) {
+  const result = {};
+  if (!record(value)) return result;
+  if (states.has(value.state)) result.state = value.state;
+  if (reasons.has(value.reason)) result.reason = value.reason;
+  if (stages.has(value.stage)) result.stage = value.stage;
+  for (const key of ['ready', 'videoReceived', 'paused', 'selected', 'authenticated']) {
+    if (typeof value[key] === 'boolean') result[key] = value[key];
+  }
+  if (['cn', 'sg', 'de', 'us', 'ru', 'i2'].includes(value.region)) result.region = value.region;
+  for (const key of ['attempt', 'connectingElapsedSeconds', 'retryInSeconds', 'vendor']) {
+    if (Number.isSafeInteger(value[key]) && value[key] >= 0 && value[key] <= (key === 'vendor' ? 100 : 1000000000)) result[key] = value[key];
+  }
+  if (value.lastFailure === null || reasons.has(value.lastFailure)) result.lastFailure = value.lastFailure;
+  for (const key of ['connectingSince', 'retryAt', 'lastFailureAt']) {
+    if (timestamp(value[key])) result[key] = value[key];
+  }
+  if (value.media === null) result.media = null;
+  else if (record(value.media)) {
+    const media = safeMediaDiagnostics(value.media);
+    if (Object.keys(media).length) result.media = media;
+  }
+  return result;
+}

package/lib/platform.mjs

@@ -39,6 +39,7 @@ export class MijiaRemoteCameraPlatform {
       storagePath: path.join(this.api.user.storagePath(), 'mijia-remote-camera'),
       config: this.config, log: this.log,
     });
+    this.runtime.mediaDiagnostics = () => this.delegate?.getMediaDiagnostics?.();
     if (this.stopping) { await this.runtime.stop(); await this.runtime.close?.(); return; }
     this.selectionListener = () => {
       this.refreshQueue = this.refreshQueue.then(() => this.refresh()).catch(() => {
@@ -77,10 +78,11 @@ 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.1.0');
+      .setCharacteristic(this.api.hap.Characteristic.FirmwareRevision, '0.1.1');
     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);
+    if (this.delegate.audioCompatibility) this.delegate.controller.setMicrophoneMuted(true);
     this.api.publishExternalAccessories(PLUGIN_NAME, [accessory]);
     this.accessory = accessory;
     this.deviceId = selected.deviceId;

package/lib/runtime-factory.mjs

@@ -1,3 +1,4 @@
+import { fileURLToPath } from 'node:url';
 import { RuntimeManager } from './runtime.mjs';
 import { BrowserLoginManager } from './auth.mjs';
 import { startRpcServer } from './rpc.mjs';
@@ -12,7 +13,7 @@ export async function createRuntime({ storagePath, config = {}, log }) {
   const runtime = new RuntimeManager({
     storagePath, config, log, region: config.region || 'cn',
     quality: config.quality ?? 1,
-    javaPath: assets.javaPath, jarPath: assets.jarPath, bridgePath: assets.bridgePath,
+    javaPath: assets.javaPath, jarPath: assets.jarPath, bridgePath: fileURLToPath(new URL('../backend/bridge.jar', import.meta.url)),
   });
   runtime.ffmpegPath = assets.ffmpegPath;
   await runtime.open();
@@ -44,7 +45,11 @@ export async function attachServices(runtime, auth, storagePath) {
   let rpc;
   try {
     rpc = await startRpcServer(storagePath, async (method, payload) => {
-      if (method === 'status') return runtime.status();
+      if (method === 'status') {
+        const status = runtime.status();
+        const media = runtime.mediaDiagnostics?.();
+        return media ? { ...status, media } : status;
+      }
       if (authorizing && ['homes', 'devices', 'select', 'resume'].includes(method)) throw failure('auth_in_progress');
       if (method === 'homes') return runtime.discoverHomes();
       if (method === 'devices') return runtime.discoverDevices(payload.homeId, payload.homeOwner);

package/lib/runtime.mjs

@@ -16,6 +16,7 @@ const REASONS = new Set(['not_selected', 'starting', 'ready', 'stopped', 'retryi
   'runtime_unavailable', 'query_timeout', 'query_cancelled', 'invalid_backend_response', 'storage_failed']);
 REASONS.add('auth_in_progress');
 const TRANSIENT_CODES = new Set([0, 3, 4, 5, 6]);
+const STAGES = ['device_lookup', 'provisioning', 'relay_connect', 'authentication', 'waiting_video'];
 
 export class RuntimeError extends Error {
   constructor(reason, code) {
@@ -101,6 +102,8 @@ export class RuntimeManager extends EventEmitter {
     this.children = new Set();
     this.wantRunning = false; this.closed = false; this.paused = false; this.token = null; this.opening = null;
     this.attempt = 0; this.generation = 0; this.starting = null; this.port = null;
+    this.connectionAttempt = 0; this.connectingSince = null; this.retryAt = null;
+    this.lastFailure = null; this.lastFailureAt = null; this.stage = null; this.stageIndex = -1;
     this.queryChain = Promise.resolve();
     this.exitHandler = () => {
       for (const child of this.children) {
@@ -141,17 +144,35 @@ export class RuntimeManager extends EventEmitter {
   }
   status() {
     const credentials = readJson(this.credentialsFile);
+    const now = Date.now();
     const report = { state: this.state, reason: this.reason, ready: this.ready, videoReceived: this.videoReceived,
       region: this.region, paused: this.paused, selected: Boolean(this.selected()), authenticated: ['ssecurity', 'serviceToken', 'userId']
-        .every(key => typeof credentials?.[key] === 'string' && credentials[key].trim()) };
+        .every(key => typeof credentials?.[key] === 'string' && credentials[key].trim()),
+      attempt: this.connectionAttempt, stage: this.stage,
+      connectingSince: this.connectingSince === null ? null : new Date(this.connectingSince).toISOString(),
+      connectingElapsedSeconds: this.connectingSince === null ? 0 : Math.max(0, Math.floor((now - this.connectingSince) / 1000)),
+      retryAt: this.retryAt === null ? null : new Date(this.retryAt).toISOString(),
+      retryInSeconds: this.retryAt === null ? 0 : Math.max(0, Math.ceil((this.retryAt - now) / 1000)),
+      lastFailure: this.lastFailure,
+      lastFailureAt: this.lastFailureAt === null ? null : new Date(this.lastFailureAt).toISOString() };
     if (this.ready && this.port) report.sourceUrl = `http://127.0.0.1:${this.port}/cam.ts`;
     if (Number.isInteger(this.vendor)) report.vendor = this.vendor;
     return report;
   }
   _state(state, reason, extra = {}) {
     this.state = state; this.reason = REASONS.has(reason) ? reason : 'backend_failed';
+    if (state !== 'starting') { this.connectingSince = null; this.stage = null; this.stageIndex = -1; }
+    if (state !== 'retrying') this.retryAt = null;
+    if (state === 'retrying' || state === 'blocked') {
+      this.lastFailure = this.reason; this.lastFailureAt = Date.now();
+    }
     Object.assign(this, extra); this.emit('status', this.status());
   }
+  _resetConnectionDiagnostics() {
+    this.attempt = 0; this.connectionAttempt = 0; this.connectingSince = null; this.retryAt = null;
+    this.lastFailure = null; this.lastFailureAt = null; this.stage = null; this.stageIndex = -1;
+    this.vendor = undefined;
+  }
   async setRegion(region) {
     if (!REGIONS.has(region)) throw new RuntimeError('invalid_request');
     await this.open(); await this.stop(); this.region = region;
@@ -249,6 +270,7 @@ export class RuntimeManager extends EventEmitter {
     this.wantRunning = true;
     clearTimeout(this.retryTimer); this.retryTimer = null;
     const generation = ++this.generation;
+    this.connectionAttempt++; this.connectingSince = Date.now(); this.stage = null; this.stageIndex = -1;
     this._state('starting', 'starting', { ready: false, videoReceived: false, vendor: undefined });
     const promise = this._start(selection, generation);
     this.starting = promise;
@@ -282,6 +304,13 @@ export class RuntimeManager extends EventEmitter {
           if (value?.success === false) {
             eventFailure = REASONS.has(value.reason) ? value.reason : 'backend_failed';
             if (Number.isInteger(value.vendor) && value.vendor >= 0 && value.vendor <= 100) this.vendor = value.vendor;
+          } else if (value?.event === 'progress' && value.success === true && this.state === 'starting') {
+            const index = STAGES.indexOf(value.stage);
+            if (index >= 0 && index >= this.stageIndex) {
+              this.stage = value.stage; this.stageIndex = index;
+              if (Number.isInteger(value.vendor) && value.vendor >= 0 && value.vendor <= 100) this.vendor = value.vendor;
+              this.emit('status', this.status());
+            }
           } else if (value?.event === 'ready' && value.success === true && value.videoReceived === true
             && value.port === this.port && ['H264', 'H265'].includes(value.codec)) {
             clearTimeout(bootTimer); if (this.bootTimer === bootTimer) this.bootTimer = null;
@@ -304,9 +333,10 @@ export class RuntimeManager extends EventEmitter {
         this.ready = false; fail(reason);
         if (timedOut || TRANSIENT_CODES.has(code)) {
           if (readyAt !== null && Date.now() - readyAt >= 60000) this.attempt = 0;
-          this._state('retrying', reason, { ready: false });
           const delay = this.retryDelays[Math.min(this.attempt++, this.retryDelays.length - 1)];
-          this.retryTimer = setTimeout(() => { this.retryTimer = null; if (this.wantRunning && !this.closed) void this.start().catch(() => {}); }, delay);
+          this.retryAt = Date.now() + delay;
+          this.retryTimer = setTimeout(() => { this.retryTimer = null; this.retryAt = null; if (this.wantRunning && !this.closed) void this.start().catch(() => {}); }, delay);
+          this._state('retrying', reason, { ready: false });
         } else this._state('blocked', reason, { ready: false });
       });
     });
@@ -315,11 +345,25 @@ export class RuntimeManager extends EventEmitter {
     if (this.paused) throw new RuntimeError('auth_in_progress');
     if (this.ready && this.child) return `http://127.0.0.1:${this.port}/cam.ts`;
     if (this.state === 'blocked') throw new RuntimeError(this.reason);
-    const ready = this.start();
+    let ready, cleanup = () => {};
+    if (this.state === 'retrying' && this.retryTimer) {
+      // HomeKit requests may wait for the existing retry, but cannot shorten its backoff.
+      const generation = this.generation;
+      ready = new Promise((resolve, reject) => {
+        const status = () => {
+          if (this.paused) reject(new RuntimeError('auth_in_progress'));
+          else if (this.ready && this.child) resolve(`http://127.0.0.1:${this.port}/cam.ts`);
+          else if (this.state === 'blocked' || (this.state === 'retrying' && generation !== this.generation)) reject(new RuntimeError(this.reason));
+          else if (!this.wantRunning || this.closed) reject(new RuntimeError('stopped'));
+        };
+        this.on('status', status);
+        cleanup = () => this.off('status', status);
+      });
+    } else ready = this.start();
     let timer;
     try {
       return await Promise.race([ready, new Promise((_, reject) => { timer = setTimeout(() => reject(new RuntimeError('starting')), Math.min(Math.max(timeoutMs, 1), this.connectTimeoutMs)); })]);
-    } finally { clearTimeout(timer); }
+    } finally { clearTimeout(timer); cleanup(); }
   }
   async stop() {
     this.wantRunning = false; this.generation++;
@@ -328,6 +372,7 @@ export class RuntimeManager extends EventEmitter {
     const helpers = [...this.helpers];
     await Promise.all([this.terminateProcess(child), ...helpers.map(helper => this.terminateProcess(helper))]);
     this.starting = null;
+    this._resetConnectionDiagnostics();
     this._state('stopped', 'stopped', { ready: false, videoReceived: false });
   }
   async pause() {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@linanw/homebridge-mijia-remote-camera",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@linanw/homebridge-mijia-remote-camera",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "cpu": [
         "x64"
       ],
@@ -20,7 +20,8 @@
         "tough-cookie": "6.0.0"
       },
       "bin": {
-        "mijia-camera-setup": "bin/setup.mjs"
+        "mijia-camera-setup": "bin/setup.mjs",
+        "mijia-camera-diagnose": "bin/diagnose.mjs"
       },
       "devDependencies": {
         "homebridge": "1.11.0"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linanw/homebridge-mijia-remote-camera",
   "displayName": "米家远程摄像头",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone Xiaomi remote camera plugin with browser login and home selection",
   "license": "MIT",
   "author": "linanw",
@@ -38,10 +38,12 @@
     "README.md",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE",
-    "npm-shrinkwrap.json"
+    "npm-shrinkwrap.json",
+    "backend/bridge.jar"
   ],
   "bin": {
-    "mijia-camera-setup": "bin/setup.mjs"
+    "mijia-camera-setup": "bin/setup.mjs",
+    "mijia-camera-diagnose": "bin/diagnose.mjs"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"