Homebridge Snapshot Motion

A lightweight motion sensor plugin for Homebridge that detects motion based on changes in snapshot image size — perfect for cameras and intercoms that provide only static image snapshots.

🔍 Problem

Some intercoms and IP cameras (such as Loxone Intercom) do not provide a native motion detection feature or RTSP stream compatible with HomeKit Secure Video (HKSV). These devices often expose only a JPEG/MJPEG snapshot over HTTP — insufficient for full automation and HKSV features.

✅ Solution

This plugin monitors a camera's snapshot URL and detects motion by measuring changes in image file size between snapshots. If a noticeable change in size occurs (indicating motion, light changes, etc.), the plugin triggers a HomeKit Motion Sensor and optionally calls a webhook URL.

HomeKit Secure Video will still perform video analysis on its own, so a basic motion trigger is enough to enable full HKSV recording.

📸 How It Works

• Periodically checks the snapshot image using an HTTP GET request with Range: bytes=0-0 (downloads just the image header)
• Compares the Content-Length (or Content-Range) value with a historical average/median
• Adjusts for image format-specific header sizes (e.g. JPEG ~623 bytes) to improve accuracy
• Triggers motion if the percentage difference exceeds configured thresholds
• Prevents loops by clearing and restarting a cooldown timer on each detection
• Optional webhook request is sent when motion is detected

💡 Use Cases

• Add motion detection to intercoms and MJPEG-only cameras
• Trigger automation from HomeKit based on motion
• Integrate basic snapshot-based motion sensing into systems like Loxone, Scrypted, or low-end RTSP devices

---

⚙️ Configuration

Add an accessory to your Homebridge config.json:

{
  "accessories": [
    {
        "accessory": "SnapshotMotionSensor",
        "name": "Snapshot Motion Sensor",
        "snapshotUrl": "http://192.168.1.10:8888/snapshot.jpg",
        "minChangePercent": 2,
        "maxChangePercent": 80,
        "checkInterval": 555,
        "cooldownSeconds": 10,
        "historyLimit": 32,
        "webhookUrl": "http://localhost:1111/motion",
        "debug": true
    }
  ]
}

🔧 Options

Key	Type	Description
accessory	string	Must be "SnapshotMotion"
name	string	Name of the sensor in HomeKit
snapshotUrl	string	Required. URL to fetch the snapshot image
webhookUrl	string	(Optional) GET request sent on motion detection
minChangePercent	number	Minimum % change in size to trigger motion (e.g. 3 for 3%)
maxChangePercent	number	Maximum % to accept (e.g. avoid flashes, default 95)
checkInterval	number	How often to check for image size change (in ms)
motionCooldown	number	Cooldown period in seconds before another motion event is allowed
historyLimit	number	Size of history buffer for stable baseline size (default: 32)
debug	boolean	Enable verbose logging in Homebridge logs

---

🧪 Technical Notes

• Uses GET with a Range: bytes=0-0 header to avoid downloading the entire image.
• Attempts to estimate image payload size by subtracting format-specific header bytes (e.g., 623 bytes for JPEG).
• Maintains a rolling history of snapshot sizes and compares against the median of past values (for noise immunity).
• Automatically avoids double-triggering by using a single cooldownTimer, cleared and restarted on each new detection.

---

💠 Developed by

Vladimir Sobolev 🔗 https://github.com/350d 𝕏 @350d

---

📜 License

MIT © 2025