Snapshot caching causes incorrect preview image age counter in Apple Home’s preview

[dougasimpson]

Describe the behavior

The Snapshot plugin can supply HomeKit with a cached image up to one hour old for an ordinary camera. In testing, when a camera went offline, Home repeatedly displayed that cached image with a counter progressing from “Now” to approximately 11 seconds. Each successful refresh returned the same old image and reset the counter. A camera that had been offline for 45 minutes therefore appeared to have a preview only 0–11 seconds old, rather than showing its actual age.

The camera console confirmed:

Snapshot failed, but recovered from cache

Cached responses can also understate preview age while a camera is online. The approximately 11-second refresh cycle was observed during testing; it is not necessarily a fixed HomeKit interval.

To reproduce

1. Enable Snapshot and HomeKit for a working camera.
2. Open the camera overview in Apple Home and obtain a preview.
3. Disconnect the camera’s power.
4. Observe several preview refresh cycles.
5. Confirm that the unchanged image’s counter repeatedly resets to “Now.”
6. Check the camera console for cached snapshot recovery.

Expected behavior

After the camera has been offline, Home should display an appropriately aged preview counter, such as “45m,” rather than continually cycling between “Now” and 11 seconds.

The counter represents time since Home’s last successful preview. When that preview was acquired immediately before disconnection, it should reflect approximately how long the camera has been offline. In our tests without the Snapshot plugin’s fallback, Home provided this behavior natively.

Home should also control whether it retains the last good preview or displays an unavailable state. Scrypted should report acquisition failure rather than successfully return a generated “Snapshot Failed” image.

Proposed fix

Add a global Require Fresh HomeKit Snapshots setting, enabled by default, that:

• Shares captures already in progress without reusing completed cached snapshots.
• Reports acquisition and image-processing failures as request errors.
• Prevents stale-image and generated-error-image fallback.
• Lets Home manage the previous preview and its age counter.
• Restores legacy behavior when disabled.

Implementation: PR #2171.

Testing completed

The proposed fix has completed our automated and physical-camera test plan:

• All 15 regression tests, SDK build, plugin type checks, and plugin builds passed.
• Controlled failures verified strict rejection, legacy fallback, and recovery.
• Physical unplug/reconnect tests on iOS and macOS confirmed retention of the last good image with a correctly aging counter and normal recovery.
• Live view worked correctly, and HomeKit pairing remained unchanged.

Environment

• Server: Mac mini, macOS; local Node installation.
• Initial plugin versions: Snapshot 0.2.68, HomeKit 1.2.69.
• Camera integration: ONVIF.
• Clients: Apple Home on iOS and macOS.
• Exact OS versions and camera model were not recorded in this report.