SNAPSHOTS.md

Persistent Snapshots

Persistent Snapshots is a way to take snapshots of the camera and store them on disk. You can then access them via HomeKit. Persistent Snapshots is not defined in the HAP but instead implemented by hkcam with custom characteristics.

Persistent Snapshots are supported by Home 3.

Why?

Taking snapshots is an essential feature of any security camera. For example you want to take a snapshot once motion is detected in room. But there are currently no IP cameras which support that via HomeKit.

hkcam implements Persistent Snapshots with custom HomeKit characteristics. This means you can use this feature in HomeKit scenes and automations.

Custom Characteristics

The following characteristics are used to handle snapshots.

• TakeSnapshot takes a snapshot.
• Assets returns an index of all snapshots as JSON.
• GetAsset returns JPEG data representing a snapshot.
• DeleteAssets deletes snapshots.

To take a snapshot, you should write true to the TakeSnapshot characteristic.

---

After that the Assets characteristic contains the snapshot in the returned JSON. The value of the Assets characteristic might look like this.

{
    "assets":[
        {
            "id": "1.jpg",
            "date": "2019-04-01T10:00:00+00:00"
        }
    ]
}

---

To get the data of the snapshot with id 1.jpg, you should send the following JSON to the GetAsset characteristic.

{
    "id": "1.jpg",
    "width": 320,
    "height": 240
}

If you omit width or height (or set it to 0), the image keeps the aspect ratio while resizing.

After a successful write, the GetAsset characteristic value contains the JPEG data.

---

If you want to delete the snapshot, you send the following JSON to the DeleteAssets characteristic.

{
    "ids": [
        "1.jpg"
    ]
}