Skip to main content
Version: 1.0

Camera

Camera component.

Methods​

Camera.GetCapabilities​

Returns the supported resolutions, detection types, and zone limitations.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

Response​

Attributes in the result:

PropertyTypeDescription

resolutions

array of strings

List of supported stream resolutions and frame rates (e.g. "1920x1080@25"). The values returned here are the only ones accepted by the streams.N.resolution configuration field.

bitrate_range

array of numbers

Two numbers [min, max] representing the minimum and maximum supported stream bitrate in kbps. The streams.N.bitrate configuration field must fall within this range.

detect

array of strings

List of supported detection types (currently "motion").

max_zones

number

Maximum number of CameraZone instances that can be created.

zone_type

array of strings

List of supported zone shapes (currently "rectangle").

Camera.GetStatus​

Obtain current status (streamer state, motion, active streams and recordings).

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

Response​

See the status section.

Camera.GetConfig​

Obtain the camera configuration.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

Response​

See the configuration section.

Camera.SetConfig​

Update the camera configuration. Only the fields included in the request are modified; omitted fields are left unchanged. Setting a field to null resets it to the device default.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

config

object

Configuration to apply (see the configuration section). The streams object is keyed by stream id and may contain a subset of stream entries; setting an individual stream entry to null resets that stream to its defaults.

Response​

PropertyTypeDescription

restart_required

boolean

true if a device restart is required for the new configuration to take effect.

Camera.Set​

Arm/disarm the camera and/or turn privacy mode on or off. At least one of arm or privacy must be provided; omitted parameters are left unchanged. The new values are persisted and reflected in the status. Turning privacy on suspends the streamer: video and audio capture stop and the speaker is disabled; turning it off resumes it.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

arm

boolean

Optional. Whether the camera is armed.

privacy

boolean

Optional. Privacy mode. When enabled, the streamer is suspended: video and audio capture stop, the speaker is disabled, and no streams or recordings can be served until privacy mode is turned off.

Response​

The result from this method is null.

Camera.CaptureImage​

Capture a single still image from a stream. The image is uploaded to the cloud and, if local storage is mounted, also stored on the SD card. The returned media_id can be used to retrieve the image once it has been processed (see the media_ready notification).

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

stream

number

Optional. Stream id to capture from (default 0).

Response​

Attributes in the result:

PropertyTypeDescription

media_id

string

Unique identifier (UUID) for the captured image

Camera.StartRecording​

Start a video recording. The recording is uploaded to the cloud and, if local storage is mounted, also stored on the SD card. The returned rec_id is used to identify the recording in subsequent Camera.StopRecording calls and in the recordings field of Camera.GetStatus.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

duration

number

Optional. Recording duration in seconds (default 60). The recording stops automatically once this duration elapses, unless Camera.StopRecording is called first.

stream

number

Optional. Stream id to record from (default 0).

Response​

Attributes in the result:

PropertyTypeDescription

rec_id

string

Unique identifier (UUID) of the new recording

Camera.StopRecording​

Stop one or all active recordings.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

rec_id

string

Optional. Unique identifier of the recording to stop, as returned by Camera.StartRecording. When omitted, all currently active recordings are stopped.

Response​

The result from this method is null.

Camera.AddZone​

Create a new CameraZone. The zone definition is supplied directly as parameters of the call.

Request​

Parameters (the parameters object is the zone definition; see CameraZone configuration for full details):

PropertyTypeDescription

id

number

Id of the camera component

enable

boolean

Whether the zone is active.

type

string

Zone type. See accepted values.

coordinates

array of numbers

Polygon coordinates [x0, y0, x1, y1, ...] in the normalized 0..10000 grid (see coordinate system). At least two points (4 values) are required.

color

array of numbers

Optional. Preview color [R, G, B], each component in the range 0..255.

name

string

Optional. Human-readable zone name.

null is not accepted for enable, type, coordinates, color or name; either omit the field or provide a value of the correct type.

Accepted values for `type`:
ValueDescription

"motion"

Motion-detection zone. Motion events inside the zone are reported via CameraZone notifications and aggregated into the camera's overall motion status.

"privacy"

Privacy zone. The area is blacked out in all video streams; no motion is reported for this zone.

Response​

Attributes in the result:

PropertyTypeDescription

zone_id

number

Id of the newly created CameraZone

Camera.DeleteZone​

Delete a previously-created CameraZone. The default zone (created automatically when the camera is initialized) cannot be deleted.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

zone_id

number

Id of the CameraZone to delete

Response​

The result from this method is null.

Camera.PlaySound​

Plays a sound through the camera's speaker. Exactly one of sound or file must be provided:

  • sound plays one of the built-in sounds by name.
  • file plays an .opus file stored on the camera's SD card.

Playing sounds requires sounds.enable to be true (see Configuration); otherwise the method returns an error. The camera must also not be in privacy mode — the streamer is suspended while privacy is on, so the speaker is disabled and the call fails. The call completes once the streamer reports the playback result, so a missing or unplayable file is reported as an error rather than a false success.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the camera component

sound

string

Name of a built-in sound to play. Mutually exclusive with file. See accepted values.

file

string

Path of an .opus file on the camera's SD card, relative to the card root (e.g. "audio/doorbell.opus"). Must not contain ... Mutually exclusive with sound.

Accepted values for `sound`:
ValueDescription

"alert"

Alert tone.

"ding-dong"

Doorbell chime.

"notification"

Notification tone.

Response​

The result from this method is null.

Configuration​

The Camera configuration controls audio, video, night-vision and per-stream parameters. Arming and privacy mode are not part of the configuration; they are reported in the status and changed with Camera.Set.

Properties:

PropertyTypeDescription

id

number

Id of the camera component

name

string

Name of the camera.

led

object

LED settings.

PropertyTypeDescription

enable

boolean

Enable the LED activity indication.

audio

object

Audio settings.

PropertyTypeDescription

input

object

Microphone settings.

PropertyTypeDescription

enable

boolean

Enable the microphone (audio capture).

output

object

Speaker settings.

PropertyTypeDescription

volume

number

Speaker volume, 0..100.

sounds

object

Event sound settings.

PropertyTypeDescription

enable

boolean

Enable playing sounds. When false, Camera.PlaySound returns an error and event sounds (e.g. camera on, privacy on/off, factory/network reset) are not played.

motion

object

Motion detection settings.

PropertyTypeDescription

sensitivity

string

Motion detection sensitivity preset: "low", "medium" or "high".

recording

object

Motion-triggered recording settings.

PropertyTypeDescription

enable

boolean

Record a clip when motion is detected.

night_vision

object

Night-vision (IR-cut filter and IR LEDs) settings.

PropertyTypeDescription

mode

string

Night-vision mode. See accepted values.

ir_leds

boolean

Enable the IR LEDs in night mode.

light_threshold

number

Ambient light level around which day and night mode switch, 0..100. Lower values switch at a darker level (night mode engages only when it gets quite dark), higher values switch at a brighter level. Used in auto mode.

sensitivity

number

Day/night switch sensitivity, 0..100 (0 = most stable / most resistant to flipping between modes, 100 = most sensitive). Used in auto mode.

rtsp

object

RTSP server settings.

PropertyTypeDescription

enable

boolean

Enable the RTSP server.

video

object

Video image settings.

PropertyTypeDescription

brightness

number

Brightness, 0..100.

contrast

number

Contrast, 0..100.

saturation

number

Saturation, 0..100.

sharpness

number

Sharpness, 0..100.

tint

number

Tint, -256..256.

temperature

number

Color temperature, -256..256.

flip

boolean

Flip the image vertically.

mirror

boolean

Mirror the image horizontally.

antiflicker

string

Anti-flicker mode, matched to the local mains frequency to avoid banding under artificial lighting. See accepted values.

streams

object

Per-stream configuration. The object is keyed by stream id (e.g. "0", "1").

PropertyTypeDescription

resolution

string

Stream resolution and frame rate (e.g. "1920x1080@25"). Must be one of the values reported by Camera.GetCapabilities in resolutions.

bitrate

number

Stream bitrate in kbps. Must fall within the range reported by Camera.GetCapabilities in bitrate_range.

Accepted values for `night_vision.mode`:
ValueDescription

"auto"

Switch between day and night mode automatically based on the configured thresholds.

"day"

Force day mode.

"night"

Force night mode.

Accepted values for `video.antiflicker`:
ValueDescription

"50Hz"

Anti-flicker tuned for 50 Hz mains (Europe, Asia, Africa, Australia).

"60Hz"

Anti-flicker tuned for 60 Hz mains (North America, parts of South America).

Status​

The status of the Camera component reports the arm and privacy state, the streamer state, current motion state, the number of active live streams, and any ongoing recordings. Use Camera.Set to change arm and privacy.

Properties:

PropertyTypeDescription

id

number

Id of the camera component

arm

boolean

Whether the camera is armed.

privacy

boolean

Privacy mode. When enabled, the streamer is suspended: video and audio capture stop, the speaker is disabled, and no streams or recordings can be served until privacy mode is turned off.

streamer

string

Current state of the streamer. See accepted values.

streamer_version

string

Optional. Version string reported by the streamer; absent if the streamer has not reported one yet.

motion

boolean

true if motion is currently detected in any CameraZone.

streams

number

Number of currently active live streams.

recording_encryption

object

Recording encryption state.

PropertyTypeDescription

configured

boolean

true if end-to-end encryption of cloud recordings has been set up on this device.

recordings

object

Active recordings. Present only when at least one recording is in progress. The object is keyed by recording id (UUID).

PropertyTypeDescription

ts

number

Unix timestamp when the recording started.

stream

number

Stream id being recorded.

duration

number

Optional. Requested recording duration in seconds; absent for recordings without a fixed duration.

trigger

object

Optional. The event that triggered the recording. Present only for motion-triggered recordings; absent for recordings started via Camera.StartRecording. Carries the source component (component, id), the event name (always "motion_detected") and the timestamp (ts).

errors

array of strings

Optional. Currently active error conditions. Absent when there are no errors. See accepted values.

Accepted values for `streamer`:
ValueDescription

"stopped"

The streamer is not running.

"starting"

The streamer is starting up.

"running"

The streamer is running and ready to serve streams, snapshots and recordings.

"stopping"

The streamer is shutting down (e.g. after entering privacy mode or before a reboot).

"unknown"

The streamer state could not be determined.

Accepted values for entries in `errors`:
ValueDescription

"streamer_fs_bad"

The streamer's filesystem version does not match the expected version and may need to be reflashed.

HTTP endpoints​

In addition to the JSON-RPC methods, the Camera component exposes the following HTTP endpoint:

GET /camera/<id>/snapshot​

Returns a single live JPEG snapshot from the camera. The camera must be enabled, not in privacy mode, and have its streamer status equal to "running" (see Status).

The endpoint is protected by the device's standard HTTP digest authentication; the same credentials used for JSON-RPC apply.

  • Methods: GET, HEAD
  • Path parameter: id — id of the camera component (e.g. 0).
  • Response: 200 OK with Content-Type: image/jpeg and the JPEG bytes in the body. 502 Bad Gateway is returned if a snapshot cannot be produced.

Example:

curl --digest -u "admin:<password>" \
  -o snapshot.jpg \
  http://<device>/camera/0/snapshot

WHEP (WebRTC-HTTP Egress Protocol)​

The Camera component also exposes a WHEP endpoint for establishing a WebRTC session over plain HTTP. This is a standards-based alternative to the Streamer.* JSON-RPC signaling and is directly compatible with WHEP-capable clients (e.g. browsers, go2rtc).

The signaling operates in non-trickle mode: all ICE candidates are embedded in the SDP. Trickle ICE (PATCH) is not supported.

caution

Token-based authentication is not currently supported for the WHEP endpoint, so it is not usable when the device is password-protected.

The WHEP URL to use in an NVR or other WHEP client is /camera/<id>/whep/<stream>, where id is the camera component id and stream is the stream id to receive (the available stream ids are reported by Camera.GetConfig). For example:

  • http://<device>/camera/0/whep/0 — high-resolution stream.
  • http://<device>/camera/0/whep/1 — lower-resolution stream.

Webhook Events​

Available events from Camera component that can trigger webhooks:

  • camera.motion - produced when the global motion status changes to true (motion detected in any active zone).
  • camera.motion_end - produced when the global motion status changes to false (motion is no longer detected in any active zone).
  • camera.armed - produced when the camera becomes armed (the arm status changes to true).
  • camera.disarmed - produced when the camera becomes disarmed (the arm status changes to false).
  • camera.privacy_on - produced when privacy mode is turned on (the privacy status changes to true); video and audio capture stop and the speaker is disabled.
  • camera.privacy_off - produced when privacy mode is turned off (the privacy status changes to false); capture resumes.

Notifications​

This section describes notifications for events specific to the Camera component. For general information please see this page.

Instances of the Camera component can send notifications for the following events:

PropertyTypeDescription

media_ready

event

Emitted when a media file (image or video) has been finalized on the device and is ready to be retrieved or uploaded.

PropertyTypeDescription

rec_id

string

Recording id (UUID). For images captured via Camera.CaptureImage, this is generated alongside media_id.

media_id

string

Media id (UUID) of the finalized file.

mime_type

string

MIME type of the media file. Currently "image/jpeg" for snapshots and thumbnails, "video/mp4" for video recordings.

ts

number

Unix timestamp at which the media was created.

upload_complete

event

Emitted when a media file has been successfully uploaded to the cloud.

PropertyTypeDescription

rec_id

string

Recording id (UUID).

media_id

string

Media id (UUID) of the uploaded file.

rec_key_enc

string

Internal, used for end-to-end encryption of the uploaded media. Present only when recording encryption is configured (see recording_encryption in the status section).

ts

number

Unix timestamp at which the upload completed.

upload_failed

event

Emitted when uploading a media file to the cloud fails.

PropertyTypeDescription

rec_id

string

Recording id (UUID).

media_id

string

Media id (UUID) of the file that failed to upload.

ts

number

Unix timestamp at which the upload failed.

Examples​

Camera.GetCapabilities example​

http://192.168.33.1/rpc/Camera.GetCapabilities?id=0

Response

{
  "resolutions": [
    "1920x1080@25",
    "1280x720@25"
  ],
  "bitrate_range": [
    512,
    2048
  ],
  "detect": [
    "motion"
  ],
  "max_zones": 10,
  "zone_type": [
    "rectangle"
  ]
}

Camera.GetStatus example​

http://192.168.33.1/rpc/Camera.GetStatus?id=0

Response

{
  "id": 0,
  "arm": true,
  "privacy": false,
  "streamer": "running",
  "streamer_version": "1.2.3",
  "motion": true,
  "streams": 1,
  "recording_encryption": {
    "configured": false
  },
  "recordings": {
    "019abff8-1550-7b01-9384-39ef40145209": {
      "ts": 1722887500,
      "stream": 0,
      "duration": 30,
      "trigger": {
        "component": "camerazone:200",
        "event": "motion_detected",
        "ts": 1722887500
      }
    }
  }
}

Camera.GetConfig example​

http://192.168.33.1/rpc/Camera.GetConfig?id=0

Response

{
  "id": 0,
  "name": "Front door",
  "led": {
    "enable": true
  },
  "audio": {
    "input": {
      "enable": true
    },
    "output": {
      "volume": 100
    }
  },
  "sounds": {
    "enable": true
  },
  "motion": {
    "sensitivity": "medium",
    "recording": {
      "enable": true
    }
  },
  "night_vision": {
    "mode": "auto",
    "ir_leds": true,
    "light_threshold": 50,
    "sensitivity": 50
  },
  "rtsp": {
    "enable": true
  },
  "video": {
    "brightness": 50,
    "contrast": 50,
    "flip": false,
    "mirror": false,
    "saturation": 50,
    "sharpness": 50,
    "tint": 0,
    "temperature": 0,
    "antiflicker": "50Hz"
  },
  "streams": {
    "0": {
      "resolution": "1920x1080@25",
      "bitrate": 2048
    },
    "1": {
      "resolution": "1280x720@25",
      "bitrate": 1024
    }
  }
}

Camera.SetConfig example​

http://192.168.33.1/rpc/Camera.SetConfig?id=0&config={"video":{"brightness":60,"mirror":true},"streams":{"1":{"bitrate":1500}}}

Response

{
  "restart_required": false
}

Camera.Set example​

http://192.168.33.1/rpc/Camera.Set?id=0&arm=true&privacy=false

Response

null

Camera.CaptureImage example​

http://192.168.33.1/rpc/Camera.CaptureImage?id=0&stream=0

Response

{
  "media_id": "019abff8-3bfa-7475-af43-89b0a792d705"
}

Camera.StartRecording example​

http://192.168.33.1/rpc/Camera.StartRecording?id=0&duration=30&stream=0

Response

{
  "rec_id": "019abff8-1550-7b01-9384-39ef40145209"
}

Camera.StopRecording example​

http://192.168.33.1/rpc/Camera.StopRecording?id=0&rec_id="019abff8-1550-7b01-9384-39ef40145209"

Response

null

Camera.AddZone example​

http://192.168.33.1/rpc/Camera.AddZone?id=0&enable=true&type="motion"&coordinates=[1000,2000,5000,2000,5000,8000,1000,8000]&color=[255,0,0]&name="Entrance"

Response

{
  "zone_id": 200
}

Camera.DeleteZone example​

http://192.168.33.1/rpc/Camera.DeleteZone?id=0&zone_id=201

Response

null

Camera.PlaySound example (built-in sound)​

http://192.168.33.1/rpc/Camera.PlaySound?id=0&sound="ding-dong"

Response

null

Camera.PlaySound example (uploaded file)​

http://192.168.33.1/rpc/Camera.PlaySound?id=0&file="audio/doorbell.opus"

Response

null

Notifications example​

  • Media ready
A new media file (image or video) is now ready
{
   "src": "shellycamera-068df8bc340f",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1764157298,
      "events": [
         {
            "component": "camera:0",
            "event": "media_ready",
            "ts": 1764157298,
            "rec_id": "019abff8-1550-7b01-9384-39ef40145209",
            "media_id": "019abff8-3bfa-7475-af43-89b0a792d705",
            "mime_type": "video/mp4"
         }
      ]
   }
}
  • Upload complete
A media file has been uploaded to the cloud
{
   "src": "shellycamera-068df8bc340f",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1764157305,
      "events": [
         {
            "component": "camera:0",
            "event": "upload_complete",
            "ts": 1764157305,
            "rec_id": "019abff8-1550-7b01-9384-39ef40145209",
            "media_id": "019abff8-3bfa-7475-af43-89b0a792d705",
            "rec_key_enc": "base64-encoded-encrypted-key"
         }
      ]
   }
}
  • Upload failed
Uploading a media file to the cloud has failed
{
   "src": "shellycamera-068df8bc340f",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1764157310,
      "events": [
         {
            "component": "camera:0",
            "event": "upload_failed",
            "ts": 1764157310,
            "rec_id": "019abff8-1550-7b01-9384-39ef40145209",
            "media_id": "019abff8-3bfa-7475-af43-89b0a792d705"
         }
      ]
   }
}