企业官网建设流程全解析

• 音视频
• 后端
• 物联网
• 计算机视觉

本篇指南以 Scrypted 仓库内 Google Device Access 插件随附的 Gen 1 摄像头设置文档 为核心，讲解如何将 Nest / Google 云摄像头（Gen 1，即基于 RTSP 云流方案的型号）接入 Scrypted 并稳定服务于 HomeKit。你将掌握三个关键实践：安装 Rebroadcast 插件并启用预缓冲（Prebuffer）以弥补云摄像头事件前画面缺失的问题、理解 Gen 1 快照机制的局限与解决办法、以及正确开启 HomeKit Transcoding 并保持解码器/编码器参数为空以获得最稳定的流媒体体验。文中所有结论均有仓库源码与配置佐证。

一、Gen 1 与 Gen 2：先分清你的摄像头属于哪一代

Scrypted 的 Google Device Access 插件会根据设备能力自动区分两代摄像头，并分别提供不同的配置文档：

• 在 main.ts 中，deviceIsWebRtc()通过检查设备 traitsdm.devices.traits.CameraLiveStream的supportedProtocols是否包含WEB_RTC来判断是否属于 Gen 2；
• 相机类的getReadmeMarkdown()方法（main.ts）据此决定向用户展示哪份文档：WebRTC 设备显示 README-camera-v2.md，其余设备显示 README-camera-v1.md。

也就是说，Gen 1 摄像头走的是插件通过 Smart Device Management（SDM）API 生成的云端 RTSP 流，而 Gen 2 走 WebRTC。本指南聚焦 Gen 1 的配置。若你的设备是 Gen 2，其文档仅少了"快照由事件生成"这一条说明（Gen 2 完全不提供快照），其余 Rebroadcast 与预缓冲部分完全一致，可一并参考。

二、为什么云摄像头必须依赖预缓冲

原文档开篇即强调：首先安装 Rebroadcast 插件。这是由云摄像头的本质决定的——Nest 摄像头是云端取流设备，不像局域网摄像头那样有本地一直拉流的通道。

2.1 预缓冲默认关闭的后果

在 main.ts 中，getVideoStream()只有在调用方显式请求时才会通过sdm.devices.commands.CameraLiveStream.GenerateRtspStream向 Google 申请生成 RTSP 流，并在流上附加refreshAt（当前实现为 4 分钟刷新一次的令牌，见addRefreshOptions()，main.ts）。也就是说：默认情况下只有"被查看"时才有流。

这直接导致两个后果，与文档警告一致：

1. 事件前的画面可能丢失：既然平时没有持续拉流，摄像头在检测到动作、触发事件之前的画面没有任何缓冲，HomeKit 安全视频（HSV）等依赖预缓冲实现"事件前回放"的功能就无法覆盖动作发生前的时刻。
2. 快照不可用：流处于非活动状态时，HomeKit 界面会显示 "Snapshot Unavailable"。

2.2 预缓冲的原理与收益

Rebroadcast 插件（即 prebuffer-mixin）的作用是：保持与所有已连接摄像头的持续连接，并在内存中缓冲最近一小段视频（源码中prebufferDurationMs = 10000，即约 10 秒，见 main.ts）。这份"即时回放"既被 HomeKit Secure Video 用于事件回放，也能显著加速直播流的启动。

对应到 Google 云摄像头，启用预缓冲意味着插件会持续从云端拉流并缓存，因此：

• 事件发生时，HomeKit 能拿到事件发生前（预缓冲窗口内）的画面；
• 快照始终可用——插件可以直接从预缓冲流中取帧生成快照。

原文档同时也给出了一条务实的权衡建议：如果你的宽带无法承受一条持续连接不间断地下载摄像头视频流，就不要开启预缓冲。这是一个典型的"带宽换体验"取舍，请根据实际网络条件决定。

三、Gen 1 快照机制：只有"最近事件"快照

原文档明确指出：Gen 1 摄像头只提供"最近一次事件"的快照。这个行为可以从源码中得到完整印证，理解它有助于你判断快照何时可用、何时会显示 "Snapshot Unavailable"。

3.1 快照的三级取值逻辑

NestCamera.takePicture()（main.ts）的实现顺序是：

1. 优先使用预缓冲流：如果设备当前存在带prebuffer标记的媒体流选项（即 Rebroadcast 插件已启用且流已预热），则直接以refresh: false从该流取帧，此时快照必然可用；
2. 回退到最近事件快照：若设备 trait 中存在sdm.devices.traits.CameraEventImage（即deviceHasEventImages()，main.ts），且插件缓存了lastMotionEventId，则调用sdm.devices.commands.CameraEventImage.GenerateImage向 Google 请求生成事件快照；
3. 否则直接抛错'snapshot unavailable'——这就是 HomeKit 中 "Snapshot Unavailable" 的来源。

3.2 事件快照有 30 秒有效期

事件快照并非随时可取。在插件的 Pub/Sub 推送处理器onRequest()（main.ts）中，当收到sdm.devices.events.CameraMotion.Motion或sdm.devices.events.CameraPerson.Person事件时，插件会记录lastMotionEventId，并通过两个setTimeout分别将事件 ID 与motionDetected状态在30 秒后清除，代码注释也注明"事件快照在发布后 30 秒过期"。这解释了为什么：

• 若事件刚发生不久，快照可以取到；
• 若长时间没有事件、又未启用预缓冲，快照必然不可用。

因此原文档的结论非常直接：开启预缓冲后快照将始终可用——因为走的是第一条路径（预缓冲流取帧），彻底绕开了事件快照的时效限制。

四、HomeKit Transcoding：必须开启，且参数留空

原文档给出的第二条硬性要求：Gen 1 摄像头必须启用 HomeKit Transcoding，在 HomeKit Transcoding 设置中同时开启流媒体与录像的转码（streams and recordings），并且解码器与编码器参数保持空白——官方经验表明默认参数最可靠。

4.1 该设置项在源码中的位置

HomeKit 插件的相机混入（Camera Mixin）通过getMixinSettings()暴露"Debug Mode"设置（camera-mixin.ts），其可选项包括Transcode Video与Transcode Audio，二者即对应原文档所说的"对流媒体和录像启用转码"。该选项存储于debugMode键，由 camera-debug-mode-storage.ts 解析为video/audio/recording三个布尔位。

设置界面中还有独立的rtpSender（RTP 发送器）选项（Default/Scrypted/FFmpeg），默认值即可。原文档强调的"参数留空"，对应的是编码器/解码器高级参数区域——HomeKit 插件会根据设备实际情况自动填充默认参数（例如codecCopy与transcode的自动判定、默认编码参数见 camera-streaming-ffmpeg.ts），手动填入非默认参数反而容易引入不兼容问题。

4.2 为什么 Gen 1 必须转码

从架构上理解：Gen 1 摄像头通过getSdmRtspMediaStreamOptions()暴露的是一条Cloud RTSP流（main.ts），其视频编码为 H.264、音频为 AAC，且userConfigurable: false——这条流由 Google 云端生成、走公网传输。HomeKit 对摄像头流的编码格式、时间戳、比特率等有严格要求，云端生成的流通常无法直接满足，因此需要转码使其符合 HomeKit 协议要求。这也是"参数留空、用默认值"最稳的原因：默认值针对 Scrypted 与 HomeKit 的兼容性做了长期调优。

五、完整配置步骤清单

将原文档的要点整理为可直接照做的操作序列：

5.1 安装与启用预缓冲

1. 在 Scrypted 插件市场安装Rebroadcast插件（即@scrypted/prebuffer-mixin，它已列入 Google Device Access 插件的pluginDependencies，见 package.json，随插件自动部署）；
2. 在摄像头（Google Device Access 导入的 Nest 相机）的混入设置中启用预缓冲（Prebuffer）；
3. 权衡：若你的外网带宽无法承受持续下载视频流，可关闭预缓冲，但会牺牲事件前画面与快照可用性。

5.2 确认 HomeKit 转码设置

1. 进入该摄像头的 HomeKit 混入（Mixin）设置；
2. 在HomeKit Transcoding / Debug Mode中，勾选Transcode Video与Transcode Audio（同时覆盖流媒体与录像，HomeKit Secure Video 录制同样需要转码后的流）；
3. 解码器（Decoder）与编码器（Encoder）参数保持空白，使用默认值；
4. 若想进一步排查，可尝试切换 RTP Sender（Scrypted/FFmpeg）以定位问题，但日常使用保持默认。

5.3 验证结果

• 流处于活动状态（正在观看）时，HomeKit 应能正常显示画面；
• 启用预缓冲后，即使不观看，HomeKit 中的快照也应始终可用，不再出现 "Snapshot Unavailable"；
• 录像中应包含事件发生前的约 10 秒预缓冲画面。

六、FAQ：常见疑问与源码依据

Q1：为什么我的 Nest 相机看的是 v2 文档而不是 v1？因为你的设备 traitCameraLiveStream.supportedProtocols包含WEB_RTC，被插件判定为 Gen 2（main.ts）。Gen 2 不提供任何快照，其余预缓冲配置与本文一致。

Q2：快照提示 "Snapshot Unavailable" 是不是故障？不是故障。对 Gen 1 而言，这是"未启用预缓冲 + 无近期事件"时的正常表现（takePicture()会直接抛出'snapshot unavailable'，main.ts）。启用预缓冲即可解决。

Q3：预缓冲会不会浪费带宽？会。预缓冲需要在后台持续下载摄像头流。原文档明确建议：带宽不足时不要启用。可根据自身宽带情况在"事件完整性"与"带宽占用"之间取舍。

Q4：转码参数留空后画质/性能如何？插件会自动按设备能力选择codecCopy直通或transcode转码（camera-streaming-ffmpeg.ts），配合硬件加速可用时自动启用。默认参数是官方在大量设备上验证过的最可靠组合，不建议擅自修改。

如需了解 Google Device Access 插件整体的账号创建、OAuth 与 Pub/Sub 推送订阅配置，可阅读插件主 README.md 与 Pub/Sub 中继服务实现 app.ts；Gen 2 摄像头（WebRTC）的配置差异见 README-camera-v2.md。本文所有源码引用均来自当前仓库，配置界面以你所安装的 Scrypted 版本实际显示为准。

• 音视频
• 后端
• 物联网
• 计算机视觉