web sdk video - Genetec/DAP GitHub Wiki

About video in the Web SDK

This guide explains the main video concepts exposed by the Web SDK and shows how to work with cameras, bookmarks, recording, PTZ, privacy protection, video protection, and video blocking.

It is organized in three layers:

  • the model, which explains the main video entities and how they relate
  • the configuration surface, which explains how to read and change settings on video units, cameras, and streams
  • the operations surface, which explains the live workflows built on top of those entities

The focus is on the camera workflows that third-party integrations most often need:

  • finding cameras
  • understanding how cameras relate to video units and archiver roles
  • reading and configuring video units and peripherals
  • understanding camera streams and stream usages
  • reading camera state and configuration
  • adding, editing, and deleting bookmarks
  • starting and stopping manual recording
  • sending PTZ commands and working with PTZ presets, patterns, and tours
  • understanding camera sequences
  • retrieving thumbnails
  • understanding privacy protection
  • protecting video
  • blocking and unblocking video
  • querying the reports that go with those operations

Model

The main video entity in the Web SDK is Camera.

A camera is also connected to two other important video entities:

  • a VideoUnit, which is the unit that hosts the camera
  • an ArchiverRole, which records the camera and provides its default recording configuration

A camera has operational state such as:

  • whether it is online
  • whether it supports PTZ
  • whether it is currently blocked
  • whether privacy protection is enabled
  • what its current recording state is

Video workflows then build on top of that camera:

  • bookmarks mark important times on a camera timeline
  • manual recording starts or stops archiving on demand
  • PTZ moves the camera or recalls a preset, pattern, or preset tour
  • video streams expose bitrate, frame rate, resolution, and connection settings
  • camera sequences rotate through multiple cameras for display
  • thumbnails let you retrieve frames from archived video
  • privacy protection masks or blurs portions of the video for supported cameras
  • video protection prevents video from being deleted
  • blocking restricts who can view the video
flowchart LR
    Camera[Camera]
    Camera --> State[Status and properties]
    Camera --> Bookmarks[Bookmarks]
    Camera --> Recording[Manual recording]
    Camera --> PTZ[PTZ and presets]
    Camera --> Streams[Video streams]
    Camera --> Sequences[Camera sequences]
    Camera --> Thumbnails[Thumbnails]
    Camera --> Privacy[Privacy protection]
    Camera --> Protection[Video protection]
    Camera --> Blocking[Video blocking]

    Bookmarks --> BookmarkReport[Bookmark report]
    Recording --> RecordingReport[RecordingEvent report]
    Streams --> StreamState[Stream configuration]
    Sequences --> SequenceReport[VideoSequence report]
    Thumbnails --> ThumbnailReport[Thumbnail report]
    Privacy --> CameraReports[CameraConfiguration and CameraEvent reports]
    Protection --> VideoFileReport[VideoFile report]
    Blocking --> BlockingReport[BlockingVideoEvent report]
    State --> CameraReports[CameraConfiguration and CameraEvent reports]

Cameras, video units, and archiver roles

Most day-to-day video integrations work directly with Camera.

VideoUnit and ArchiverRole matter because they explain where the camera lives and where its recording is handled:

  • Unit on the camera identifies the video unit that hosts it
  • RoleGuid on the camera identifies its owning archiver role
  • SourceArchivers on the camera lists the archivers currently used as archive sources
  • ArchiverRoleGuid on the video unit identifies the archiver role that controls that unit

Read the relationship from the camera:

GET /entity?q=entity={camera-guid},Name,Unit,RoleGuid,SourceArchivers

Read the video unit:

GET /entity?q=entity={video-unit-guid},Name,ArchiverRoleGuid

Read the archiver role:

GET /entity?q=entity={archiver-guid},Name,Type,RunningState

If you need to list video units, use EntityConfiguration:

GET /report/EntityConfiguration?q=EntityTypes@VideoUnit,Page=1,PageSize=10,ReturnFields@Name

Configuration

Video units and peripherals

The Web SDK exposes VideoUnit directly.

This is the entity behind the Config Tool identity, properties, peripherals, and location tabs for a camera unit.

Video unit identity

Read the main identity and relationship fields:

GET /entity?q=entity={video-unit-guid},Name,Description,Manufacturer,Model,MacAddress,FirmwareVersion,ArchiverRoleGuid,Cameras,Devices

The most useful fields are:

  • Name and Description
  • Manufacturer, Model, MacAddress, and FirmwareVersion
  • ArchiverRoleGuid, which identifies the archiver role that controls the unit
  • Cameras, which lists the cameras hosted by the unit
  • Devices, which lists the unit's child devices such as hosted camera devices, input points, output relays, and speakers

Video unit network and login settings

Read the network and login-related fields:

GET /entity?q=entity={video-unit-guid},Dhcp,IPAddress,SubnetMask,Gateway,CommandPort,SecureCommandPort,Hostname,UseDefaultLogon,Username,SecureConnection

These fields map to the Config Tool properties tab:

  • Dhcp, IPAddress, SubnetMask, and Gateway
  • CommandPort and SecureCommandPort
  • Hostname
  • UseDefaultLogon and Username

IPAddress returns a plain string. SubnetMask and Gateway return IPAddress objects with fields such as Address and AddressFamily.

Some unit fields, such as Hostname, can be null or omitted in q= results when the unit does not have a value configured.

Changing network or login settings can interrupt connectivity to the unit. This guide uses read examples for those fields and only shows safe update examples elsewhere.

The Web SDK also exposes SecureConnection, but this guide does not treat it as a direct one-to-one mapping for the Config Tool labels shown on every unit.

The Web SDK does not expose the unit-level Config Tool capability labels such as Audio or Supports SSL as direct property reads.

Video unit network management

Use the validation method before you apply new network settings:

GET /entity?q=entity={video-unit-guid},IsNetworkSettingsCombinationValid({ip-address},{subnet-mask},{gateway})

The three parameters are IPv4 strings such as 10.200.78.113, 255.255.255.0, and 10.200.78.1.

Update the network settings:

POST /entity?q=entity={video-unit-guid},UpdateNetworkSettings({ip-address},{subnet-mask},{gateway})

This updates the unit's IP address, subnet mask, and gateway together and also disables DHCP by setting Dhcp to false. Validate the combination first, because a bad update can disconnect the unit from the archiver.

Video unit location

Read the location fields:

GET /entity?q=entity={video-unit-guid},TimeZone,GeographicalLocation,LinkedMaps

TimeZone maps to the Location tab.

GeographicalLocation contains the latitude and longitude used for map placement.

LinkedMaps lists the maps that already reference the unit.

Updating safe video unit fields

This guide uses Description as a safe example of a simple unit update:

POST /entity?q=entity={video-unit-guid},Description={description}

Enumerating peripherals

Use the unit's Devices collection to enumerate child devices:

GET /entity?q=entity={video-unit-guid},Devices

Then read each child device directly:

GET /entity/{device-guid}

Child devices can include:

  • hosted camera devices with DeviceType VideoEncoder
  • input points with DeviceType VideoUnitInput
  • output relays with DeviceType VideoUnitOutput
  • speakers with DeviceType AudioDecoder

The child-device response also includes:

  • PhysicalName
  • Description
  • LogicalId
  • Unit
  • State (only available on VideoUnitInput and VideoUnitOutput devices)

Child-device activation state

Read the activation state of a unit child device:

GET /entity?q=entity={video-unit-guid},GetDeviceActivationState({device-guid})

Deactivate a child device:

POST /entity?q=entity={video-unit-guid},DeactivateDevice({device-guid}),GetDeviceActivationState({device-guid})

Reactivate the same child device:

POST /entity?q=entity={video-unit-guid},ActivateDevice({device-guid}),GetDeviceActivationState({device-guid})

Use the device-guid returned by the unit's Devices collection. This workflow is useful for temporarily disabling one hosted camera, input point, output relay, or speaker without deleting the unit itself.

Input points and output relays

Video-unit input points and output relays expose DefaultState.

Read an input point:

GET /entity?q=entity={input-device-guid},Name,PhysicalName,DefaultState,State,Unit

Read an output relay:

GET /entity?q=entity={output-device-guid},Name,PhysicalName,DefaultState,State,Unit

DefaultState uses the values Open and Close.

Set the default state:

POST /entity?q=entity={input-or-output-guid},DefaultState=Open

or

POST /entity?q=entity={input-or-output-guid},DefaultState=Close

Speakers

The speaker device itself exposes Volume:

GET /entity?q=entity={speaker-guid},Name,PhysicalName,Volume,Unit

Set the speaker volume:

POST /entity?q=entity={speaker-guid},Volume={volume}

volume is an integer percentage from 0 to 100.

The Web SDK does not expose the speaker UDP port or Connection type as direct property reads.

Hosted camera child devices

The unit also has a child device with DeviceType VideoEncoder for each hosted camera input:

GET /entity?q=entity={hosted-camera-device-guid},Name,PhysicalName,Description,LogicalId,Unit

Use the main Camera entity for most camera operations. Use the hosted camera child device only when you specifically need the unit-level device entry under Devices.

The Web SDK does not expose the hosted camera child device Input number as a direct property read.

Video streams

VideoStream is the entity that exposes the camera's stream-level configuration.

This is the part of the Web SDK you use when you need to read or update settings such as:

  • bitrate
  • frame rate
  • constant bit rate
  • resolution
  • supported resolutions and supported rate ranges
  • preferred stream connection type

A camera can expose multiple streams. Streams gives you the stream GUIDs, and StreamUsages tells you what each stream is used for, such as Live, Archiving, Remote, LowQuality, or HighQuality.

Start from the camera:

GET /entity?q=entity={camera-guid},Streams,StreamUsages,SupportsLiveStreaming

Then read one stream directly:

GET /entity/{video-stream-guid}

If you want a narrower response, read only the fields you need:

GET /entity?q=entity={video-stream-guid},Name,Camera,VideoCompressionAlgorithm,ConstantBitRate,PreferredConnectionType,SupportedConnectionTypes,VideoCompressionCapabilities,VideoCompressions

The most important parts of that response are:

  • VideoCompressionCapabilities, which gives the supported bitrate range, frame-rate range, and supported resolutions
  • VideoCompressions, which gives the current scheduled stream configuration

Each VideoCompressions entry includes the schedule GUID and the actual values in use, such as BitRate, FrameRate, ResolutionX, and ResolutionY.

StreamUsages answers a different question: which stream is used for Live, Archiving, Remote, LowQuality, and HighQuality.

The same stream can be assigned to more than one usage.

Updating stream configuration

Stream settings are schedule-specific. Use the schedule GUID from VideoCompressions.

Set the bitrate:

POST /entity?q=entity={video-stream-guid},SetBitRate({schedule-guid},{bit-rate})

Set the frame rate:

POST /entity?q=entity={video-stream-guid},SetFrameRate({schedule-guid},{frame-rate})

Enable or disable constant bit rate:

POST /entity?q=entity={video-stream-guid},SetConstantBitRate({schedule-guid},true)

Set the resolution:

POST /entity?q=entity={video-stream-guid},SetResolution({schedule-guid},StreamSupportedResolution(){Width={width},Height={height},PalWidth={pal-width},PalHeight={pal-height},OmnicastResolution={omnicast-resolution},IsImageCropped=false})

Use the schedule-guid from the VideoCompressions entry you want to change. bit-rate is the target bitrate value for that schedule, and frame-rate is the target frames-per-second value. For the resolution update, copy one complete StreamSupportedResolution(){Width={width},Height={height},PalWidth={pal-width},PalHeight={pal-height},OmnicastResolution={omnicast-resolution},IsImageCropped=false} value from the stream capabilities instead of inventing it manually.

Advanced stream settings

The Web SDK also exposes these stream-level updates:

  • SetDynamicFrameRate({schedule-guid},{enabled})
  • SetDynamicFrameRateMinimumFrameRate({schedule-guid},{minimum-frame-rate})
  • SetDynamicKeyFrameInterval({schedule-guid},{enabled})
  • SetDynamicKeyFrameIntervalMaximumLength({schedule-guid},{maximum-length})
  • SetMaximumAllowedBitRate({schedule-guid},{maximum-allowed-bit-rate})
  • SetKeyFrameInterval({schedule-guid},{key-frame-interval},{measure})
  • SetRecordingFrameInterval({schedule-guid},{recording-frame-interval})

Use them like this:

POST /entity?q=entity={video-stream-guid},SetDynamicFrameRate({schedule-guid},true)

POST /entity?q=entity={video-stream-guid},SetDynamicFrameRateMinimumFrameRate({schedule-guid},5)

POST /entity?q=entity={video-stream-guid},SetDynamicKeyFrameInterval({schedule-guid},true)

POST /entity?q=entity={video-stream-guid},SetDynamicKeyFrameIntervalMaximumLength({schedule-guid},80)

POST /entity?q=entity={video-stream-guid},SetMaximumAllowedBitRate({schedule-guid},8000)

POST /entity?q=entity={video-stream-guid},SetKeyFrameInterval({schedule-guid},80,Images)

POST /entity?q=entity={video-stream-guid},SetRecordingFrameInterval({schedule-guid},RecordAllFrames)

The parameters mean:

  • enabled turns the dynamic setting on or off.
  • minimum-frame-rate is the floor used when dynamic frame rate is enabled. It must be between 1 and the stream's current frame rate.
  • maximum-length is the maximum dynamic key-frame interval length. It must be between the current key-frame interval and 16 * frame rate.
  • maximum-allowed-bit-rate must stay within the stream capability range returned by VideoCompressionCapabilities.
  • key-frame-interval is the interval value itself. Valid range depends on the measure: 1 to 20 for Seconds, 1 to 600 for Images.
  • measure is Seconds, Images, or None. Use None to keep the stream's current measure unchanged.
  • recording-frame-interval is a RecordingFrameInterval value such as RecordAllFrames, RecordAllKeyFrames, Record15FramePer1Second, Record10FramePer1Second, Record6FramePer1Second, Record5FramePer1Second, Record2FramePer1Second, or Record1FramePer1Second.

Not every encoder supports every setting. Use the stream capabilities and current compression values to decide which updates are valid for the target camera.

Updating stream usage

Use SetStreamUsage on the camera when you want to change which stream is used for one of the camera's usage types:

POST /entity?q=entity={camera-guid},SetStreamUsage(LowQuality,{video-stream-guid})

POST /entity?q=entity={camera-guid},SetStreamUsage(Archiving,{video-stream-guid})

This is different from changing bitrate, frame rate, or resolution on the stream itself. SetStreamUsage chooses which stream the camera should use for a usage such as Live, Archiving, or LowQuality.

Here, LowQuality and Archiving are StreamingType values. Replace them with the usage you want to change. video-stream-guid must be one of the stream GUIDs returned by the camera's Streams collection.

Finding cameras

Use EntityConfiguration to search for cameras by name and return their GUIDs.

GET /report/EntityConfiguration?q=EntityTypes@Camera,Page=1,PageSize=10,ReturnFields@Name

Once you know the camera GUID, read the camera directly:

GET /entity?q=entity={camera-guid},Name,IsOnline,CameraSubType

For the general search patterns behind this, see Referencing entities.

Camera identity and state

The camera properties most useful to Web SDK developers are:

Meaning Web SDK member Read Update
Camera name Name Yes Name={value}
Online state IsOnline Yes No
Camera subtype CameraSubType Yes Not covered in this guide
PTZ support IsPtz Yes No
Current PTZ address PtzAddress Yes Not covered in this guide
Privacy protection state IsPrivacyProtected Yes Use SetPrivacyProtection or RemovePrivacyProtection()
Blocked state IsBlocked Yes Use Block or Unblock
Current recording state RecordingState Yes Use recording methods
Owning archiver role RoleGuid Yes No
Archive sources SourceArchivers Yes No
Hosting video unit Unit Yes No
Metadata streams MetadataStreams Yes No

Common reads:

GET /entity?q=entity={camera-guid},Name,IsOnline,IsPtz,IsBlocked,IsPrivacyProtected,RecordingState,RoleGuid,Unit

GET /entity?q=entity={camera-guid},MetadataStreams

If you need broader camera configuration data such as manufacturer, model, stream usage, recording mode, retention period, or network settings, use the CameraConfiguration report:

GET /report/CameraConfiguration?q=Cameras@{camera-guid},MaximumResultCount=1

Camera recording configuration

The camera entity exposes the main recording-tab settings through RecordingConfiguration.

Read the main recording configuration values:

GET /entity?q=entity={camera-guid},RecordingConfiguration.UseCustomRecordingSettings,RecordingConfiguration.AutomaticCleanup,RecordingConfiguration.RetentionPeriod,RecordingConfiguration.AudioRecording,RecordingConfiguration.RedundantArchiving,RecordingConfiguration.PreEventRecordingTime,RecordingConfiguration.PostEventRecordingTime,RecordingConfiguration.DefaultManualRecordingTime,RecordingConfiguration.EncryptionType

These values map to the Recording tab:

  • UseCustomRecordingSettings tells you whether the camera uses inherited or custom recording settings
  • AutomaticCleanup and RetentionPeriod map to automatic cleanup and retention
  • AudioRecording and RedundantArchiving map to the corresponding recording options
  • PreEventRecordingTime and PostEventRecordingTime map to the pre-event and post-event durations
  • DefaultManualRecordingTime maps to the default manual recording length
  • EncryptionType maps to the recording encryption mode

For the configured recording modes, read the full RecordingConfiguration object:

GET /entity?q=entity={camera-guid},RecordingConfiguration

That response includes ScheduledRecordingModes, which hold the recording mode and the schedule GUID for each configured entry.

If you need the deeper nested recording values, read them explicitly:

GET /entity?q=entity={camera-guid},RecordingConfiguration.Recording.MetadataRecording,RecordingConfiguration.Recording.ScheduledArchivingModes

Those nested values let you answer two additional Recording-tab questions:

  • MetadataRecording tells you whether metadata recording is enabled
  • ScheduledArchivingModes gives the configured archiving mode and schedule entries in the nested recording object

Camera video settings

The camera entity and its streams share the Video tab.

Read the camera-level values:

GET /entity?q=entity={camera-guid},Streams,StreamUsages,IsBoostQualityOnManualRecordingEnabled,IsBoostQualityOnEventRecordingEnabled

Use the camera to answer these questions:

  • which stream GUIDs exist on the camera
  • which stream is used for Live, Archiving, Remote, LowQuality, and HighQuality
  • whether boost quality is enabled for manual recording or event recording

Use the VideoStream entity to read or change the actual stream configuration, including bitrate, frame rate, resolution, multicast settings, and the boost-quality profiles.

Read the stream-level network and boost-quality values:

GET /entity?q=entity={video-stream-guid},PreferredConnectionType,SupportedConnectionTypes,MulticastAddress,MulticastAddressIPv6,BoostQualityOnManualRecording,BoostQualityOnEventRecording

These values map to the lower part of the Video tab:

  • PreferredConnectionType and SupportedConnectionTypes map to the connection-type controls
  • MulticastAddress and MulticastAddressIPv6 map to the multicast network settings
  • BoostQualityOnManualRecording and BoostQualityOnEventRecording contain the full boosted compression profile used when those options are enabled

MulticastAddress and MulticastAddressIPv6 serialize as endpoint objects with nested address information and a Port, not as plain strings.

Camera motion detection

Read the camera's motion-detection support and current configurations:

GET /entity?q=entity={camera-guid},MotionDetectionCapabilities,MotionDetectionConfigurations

MotionDetectionCapabilities tells you which motion-detection features the camera supports, such as software detection, hardware detection, multiple zones, irregular zones, or motion search.

MotionDetectionConfigurations returns the configured motion-detection entries on the camera. Each configuration can include:

  • the detection type
  • the schedule GUID
  • sensitivity
  • one or more zones

Use this read to understand whether the camera already has motion detection configured and whether the configuration is schedule-based.

Camera color and signal settings

Read the color and signal values:

GET /entity?q=entity={camera-guid},ScheduledVideoAttributes,VideoSignalRate

ScheduledVideoAttributes contains the schedule-specific color settings currently exposed by the Web SDK:

  • Brightness
  • Contrast
  • Hue
  • Saturation
  • Schedule

VideoSignalRate maps to the analog-format choice shown in Config Tool.

The Web SDK does not expose Sharpness as a camera property.

Camera hardware settings

Read the camera hardware values:

GET /entity?q=entity={camera-guid},IsPtz,PtzProtocol,PtzAddress,PtzIdleDelay,PtzLockDelay,LockState,VideoEncoderDevice,HierarchicalChildren

These values map to the Hardware tab:

  • IsPtz tells you whether PTZ is enabled
  • PtzProtocol and PtzAddress map to the PTZ protocol and address
  • PtzIdleDelay and PtzLockDelay expose PTZ timing values
  • LockState shows the current PTZ lock state
  • VideoEncoderDevice identifies the hosted encoder child device
  • HierarchicalChildren lists child entities such as the associated speaker and microphone devices

Read a child audio device directly when you need its device-level settings:

GET /entity/{child-device-guid}

HierarchicalChildren can contain:

  • an AudioEncoder child for the microphone
  • an AudioDecoder child for the speaker

The microphone child device exposed values such as:

  • SupportedAudioDataFormats
  • Bitrate
  • Channel
  • DataFormat
  • SampleBits
  • SamplingRate

The speaker child device exposed Volume, which is documented in the Video units and peripherals section.

If you need zoom-range details, read the PTZ capability values:

GET /entity?q=entity={camera-guid},PtzCapabilities.IsZoomFactorSupported,PtzCapabilities.ZoomFactorMinimum,PtzCapabilities.ZoomFactorMaximum

Those values are only useful when IsZoomFactorSupported is true.

PTZ idle behavior

Read the current PTZ idle behavior:

GET /entity?q=entity={camera-guid},PtzIdleCommand,PtzIdleActionNumber

Set the camera so it has no PTZ idle action:

POST /entity?q=entity={camera-guid},PtzIdleCommand=None,PtzIdleActionNumber=0,PtzIdleCommand,PtzIdleActionNumber

PtzIdleCommand is the action the camera performs after it has been idle long enough. The useful command families are:

  • None
  • Preset
  • Pattern
  • PresetTour
  • GoHome

PtzIdleActionNumber is the preset, pattern, or tour number when the selected idle command needs one. Use 0 when the idle command is None or another command that does not use a numbered target. Valid values are 0 through 9999.

The Web SDK does not expose the speaker selector, microphone selector, streaming-status output, tampering settings, enhanced PTZ, or image rotation as direct camera property reads.

Operations

Bookmarks

Bookmarks mark a point in time on a camera timeline and attach a short description to it.

The Web SDK supports bookmark operations in two ways:

  • as camera methods on /entity
  • as live commands on /action

Use UTC timestamps in bookmark requests.

Camera method form

Add a bookmark:

POST /entity?q=entity={camera-guid},AddBookmark({timestamp-utc},{description})

Edit a bookmark:

POST /entity?q=entity={camera-guid},EditCameraBookmark({timestamp-utc},{description})

Delete a bookmark:

POST /entity?q=entity={camera-guid},DeleteCameraBookmark({timestamp-utc})

timestamp-utc is the bookmark time in UTC. description is the text shown for that bookmark in Security Center clients.

Action form

Add a bookmark:

POST /action?q=AddCameraBookmark({camera-guid},{timestamp-utc},{description})

Edit a bookmark:

POST /action?q=EditCameraBookmark({camera-guid},{timestamp-utc},{description})

Delete a bookmark:

POST /action?q=DeleteCameraBookmark({camera-guid},{timestamp-utc})

Finding bookmarks

Use the Bookmark report:

GET /report/Bookmark?q=Cameras@{camera-guid},TimeRange.SetTimeRange({start-utc},{end-utc})

Filter by description:

GET /report/Bookmark?q=Cameras@{camera-guid},TimeRange.SetTimeRange({start-utc},{end-utc}),DescriptionFilter={text}

Manual recording

The Web SDK lets you start and stop manual recording in both action-style and camera-method form.

Use /action when you want a direct operator command.

Use /entity when you want to work through the camera entity itself.

Action form

Start recording:

POST /action?q=StartRecording({camera-guid},{length})

Start recording and lock it:

POST /action?q=StartRecording({camera-guid},{length},{locked})

Start recording on a specific archiver role:

POST /action?q=StartRecording({camera-guid},{length},{locked},{targeted-role-guid})

Stop recording:

POST /action?q=StopRecording({camera-guid})

Stop recording on a specific archiver role:

POST /action?q=StopRecording({camera-guid},{targeted-role-guid})

length is a TimeSpan such as 00:10:00. locked controls whether the recording is protected from normal deletion. targeted-role-guid is the GUID of the ArchiverRole or AuxiliaryArchiverRole that should receive the command.

If you need the camera's normal archiver, start by reading RoleGuid or SourceArchivers from the camera.

A legacy overload also accepts a RecordingInitiator value:

POST /action?q=StartRecording({camera-guid},{length},Alarm)

This compatibility overload still works, but the guide prefers the locked and targeted-role-guid forms for new integrations.

Camera method form

Start recording:

POST /entity?q=entity={camera-guid},StartRecording({length})

Start recording with lock:

POST /entity?q=entity={camera-guid},StartRecording({length},{locked})

When locked is true, the recording state becomes OnLocked instead of On. Locked recordings cannot be stopped by other users or automatic rules.

Start recording with lock and role:

POST /entity?q=entity={camera-guid},StartRecording({length},{locked},{role-guid})

Stop recording:

POST /entity?q=entity={camera-guid},StopRecording()

In the camera-method overloads, length is the requested recording duration. role-guid is the targeted archiver role GUID.

Stop recording on a specific archiver role:

POST /entity?q=entity={camera-guid},StopRecording({role-guid})

Reading recording state

Read the current recording state:

GET /entity?q=entity={camera-guid},RecordingState

The main RecordingState values are:

  • Off
  • On
  • OnLocked
  • OffLocked
  • OnAboutToStop
  • Problem

Read the recording state for one specific role:

POST /entity?q=entity={camera-guid},GetRecordingStateForRole({role-guid})

Finding recording history

Use the RecordingEvent report:

GET /report/RecordingEvent?q=Cameras@{camera-guid},TimeRange.SetTimeRange({start-utc},{end-utc})

PTZ, presets, patterns, and tours

PTZ applies only to cameras that support it.

Check that first:

GET /entity?q=entity={camera-guid},IsPtz

You can also check whether a specific PTZ command is supported:

GET /entity?q=entity={camera-guid},PtzCapabilities.IsSupportedCommand({ptz-command-type})

Read the preset, pattern, and tour ranges exposed by the camera:

GET /entity?q=entity={camera-guid},PtzCapabilities.NumberOfPresets,PtzCapabilities.NumberOfPatterns,PtzCapabilities.NumberOfPresetTours,PtzCapabilities.PresetBase,PtzCapabilities.PatternBase,PtzCapabilities.PresetTourBase

PTZ command families and arguments

SendPtzCommand({camera-guid},{command-type},{parameter1},{parameter2}) does not use one generic argument model. The two numeric arguments depend on the PTZ command family.

Family Common commands parameter1 parameter2
Pan and tilt StartPanTilt, StopPanTilt Horizontal speed for StartPanTilt Vertical speed for StartPanTilt
Zoom StartZoom, StopZoom 0 = zoom in, 1 = zoom out for StartZoom Zoom speed
Focus StartFocus, StopFocus 0 = near, 1 = far for StartFocus Focus speed
Iris StartIris, StopIris 0 = open, 1 = close for StartIris Iris speed
Presets GoToPreset, SetPreset, ClearPreset Preset ID 0
Preset tours StartPresetTour, StopPresetTour Tour ID for StartPresetTour 0
Patterns StartPattern, StopPattern, RunPattern, ClearPattern Pattern ID 0
Auxiliary SetAuxiliary, ClearAuxiliary Auxiliary ID 0
Single-shot and menu commands Home, Flip, Enter, menu commands Usually 0 Usually 0

For the speed-based commands, the public SDK documents speeds from 1 to 100.

The public PtzCommandType enum also contains advanced and vendor-specific commands such as SpecificCommand, Vcr, RunTour, RunSequence, Sequence, Lock, OverrideLock, GoToNormalizedPosition, and GoToImagePosition.

Presets, patterns, and preset tours

These three concepts are different:

  • a preset is one saved PTZ position
  • a pattern is a recorded PTZ movement path
  • a preset tour moves through a tour defined on the camera

Read the names:

POST /entity?q=entity={camera-guid},GetPtzPresetName({preset-id})

POST /entity?q=entity={camera-guid},GetPtzPatternName({pattern-id})

POST /entity?q=entity={camera-guid},GetPtzPresetTourName({tour-id})

preset-id, pattern-id, and tour-id are the camera's PTZ numbering values. Use the camera's PTZ capability fields such as PresetBase, PatternBase, PresetTourBase, and the corresponding counts to determine the valid IDs for that camera.

Enable or disable PTZ:

POST /entity?q=entity={camera-guid},EnablePtz(true)

Set the PTZ preset name:

POST /entity?q=entity={camera-guid},SetPtzPresetName({preset-id},{name})

Set the PTZ pattern name:

POST /entity?q=entity={camera-guid},SetPtzPatternName({pattern-id},{name})

Sending PTZ commands

Use /action for live PTZ movement commands:

POST /action?q=SendPtzCommand({camera-guid},{command-type},{parameter1},{parameter2})

Common examples:

POST /action?q=SendPtzCommand({camera-guid},Home,0,0)

POST /action?q=SendPtzCommand({camera-guid},GoToPreset,{preset-id},0)

POST /action?q=SendPtzCommand({camera-guid},RunPattern,{pattern-id},0)

POST /action?q=SendPtzCommand({camera-guid},StartPresetTour,{tour-id},0)

POST /action?q=SendPtzCommand({camera-guid},StopPresetTour,0,0)

The PTZ examples require a PTZ-capable camera. Preset, pattern, and tour commands also require IDs that exist on the target camera.

Camera sequences

A camera sequence is not the same thing as a PTZ pattern.

  • a PTZ pattern is movement recorded on one PTZ camera
  • a camera sequence is an entity that rotates through multiple cameras

Camera sequences are exposed as entity type Sequence.

Query camera sequences:

GET /report/EntityConfiguration?q=EntityTypes@Sequence,Page=1,PageSize=10,ReturnFields@Name

Read one camera sequence:

GET /entity/{sequence-guid}

The sequence contains CameraSequenceItem values with:

  • the camera GUID
  • the dwell time
  • an optional PTZ preset or pattern command
  • an optional auxiliary command

Do not confuse the Sequence entity type with the VideoSequence report. A camera sequence is a display/layout concept. The VideoSequence report is a video-history report.

Thumbnails

There are two different thumbnail concepts in the Web SDK.

Camera thumbnail

The camera entity itself has a Thumbnail property.

When you read the full camera entity, that property appears in the serialized response:

GET /entity/{camera-guid}

Camera thumbnails are not supported through the Web SDK.

Do not use the Web SDK to read or update Camera.Thumbnail.

Video thumbnails from archived video

Use the Thumbnail report when you want thumbnail frames from archived video.

In AddTimestampRange({camera-guid},{start-utc},{end-utc},{count},{width}), count is how many thumbnails you want back and width is the requested thumbnail width in pixels. In AddTimestamp({camera-guid},{timestamp-utc},{width}), the last argument is the width for that one thumbnail.

Request one thumbnail from one camera and time range:

GET /report/Thumbnail?q=AddTimestampRange({camera-guid},{start-utc},{end-utc},1,{width})

Request multiple thumbnails from one camera:

GET /report/Thumbnail?q=AddTimestampRange({camera-guid},{start-utc},{end-utc},{count},{width})

Request one thumbnail from multiple cameras:

GET /report/Thumbnail?q=AddTimestamp({camera-guid-1},{timestamp-utc-1},{width-1}),AddTimestamp({camera-guid-2},{timestamp-utc-2},{width-2})

The thumbnail report returns rows that include:

  • Camera - The camera GUID
  • Timestamp - The UTC timestamp of the thumbnail frame
  • Thumbnail - Base64-encoded JPEG image data. Decode the Base64 string to get the raw JPEG bytes.
  • Context - The context GUID
  • LatestFrame - The UTC timestamp of the most recent available frame

If the requested range does not contain a usable frame, the report returns metadata with an empty Thumbnail value.

Privacy protection

Privacy protection is different from both video protection and blocking.

  • privacy protection masks or blurs portions of the video
  • video protection prevents archived video from being deleted
  • blocking restricts who can view the video

Read the current state:

GET /entity?q=entity={camera-guid},IsPrivacyProtected

If your camera already has a privacy-protection stream configured and you know that stream GUID, you can apply privacy protection:

POST /entity?q=entity={camera-guid},SetPrivacyProtection({privacy-protection-stream-guid})

Remove privacy protection:

POST /entity?q=entity={camera-guid},RemovePrivacyProtection()

These methods are only for managed archiver cameras that use privacy-protection streams. On other cameras, the methods fail.

privacy-protection-stream-guid is the GUID of a privacy-protection stream already configured for that managed-archiver camera.

This guide does not cover creating or discovering privacy-protection streams.

Video protection

The Web SDK exposes two related but different protection workflows.

Protect video as it is archived

Use StartVideoProtection when you want newly archived video to be protected for a period of time.

span is how much upcoming video to protect as it is archived. duration is how long that protection remains in effect, and it must be at least one day. This method does not trigger recording. The camera must already be recording for any video to be protected. This method is not supported by Omnicast federated cameras.

Start live protection:

POST /entity?q=entity={camera-guid},StartVideoProtection({span},{duration})

Stop live protection:

POST /entity?q=entity={camera-guid},StopVideoProtection({delay})

delay is how long to wait before stopping live protection. Use 00:00:00 to stop immediately.

Protect an existing archived time range

Use AddVideoProtection and RemoveVideoProtection when you want to protect or unprotect a specific archived time range that already exists.

Here, duration is how long the archived time range should remain protected. It must be more than one day.

Add protection to an archived range. The end-utc time cannot be in the future:

POST /entity?q=entity={camera-guid},AddVideoProtection({start-utc},{end-utc},{duration})

Remove protection from an archived range. As a security measure, the video remains protected for 24 hours before protection is dropped:

POST /entity?q=entity={camera-guid},RemoveVideoProtection({start-utc},{end-utc})

These archived-range operations depend on matching video files already existing for that camera and time period.

Finding protected video

Use the VideoFile report:

GET /report/VideoFile?q=Cameras@{camera-guid},TimeRange.SetTimeRange({start-utc},{end-utc})

Filter by protection state:

GET /report/VideoFile?q=Cameras@{camera-guid},VideoProtectionStates@Protected

Blocking and unblocking video

Blocking video is different from video protection.

  • video protection prevents archived video from being deleted
  • blocking restricts who can view the video

The camera methods are:

  • Block({start-utc},{end-utc},{blocking-level})
  • Block({start-utc},{duration},{blocking-level})
  • Unblock({start-utc},{end-utc})

Examples:

POST /entity?q=entity={camera-guid},Block({start-utc},{end-utc},{blocking-level})

POST /entity?q=entity={camera-guid},Block({start-utc},{duration},{blocking-level})

POST /entity?q=entity={camera-guid},Unblock({start-utc},{end-utc})

blocking-level is an integer from 1 to 253. A user with a user level number equal to or lower than the blocking level can view the blocked video. Level 1 is the highest security level. The requesting user can only block at or below their own security level. Overlapping blocks overwrite the previous blocking only where they overlap. If the user only has sufficient permissions to modify part of the requested time range, only that part is modified.

Read the current blocked state:

GET /entity?q=entity={camera-guid},IsBlocked

One practical rule matters here: the block start time cannot be in the future. Use a current or past UTC start time when calling Block.

Finding blocking history

Use the BlockingVideoEvent report:

GET /report/BlockingVideoEvent?q=Cameras@{camera-guid},TimeRange.SetTimeRange({start-utc},{end-utc})

Reports that go with video workflows

These are the video reports most useful alongside camera operations:

Report Use it for
Bookmark Searching bookmark events
RecordingEvent Finding recording start and stop history
Thumbnail Retrieving thumbnail frames from archived video
VideoFile Finding archived video and protection state
VideoSequence Finding archived video sequences for cameras and time ranges
BlockingVideoEvent Finding block and unblock history
CameraConfiguration Reading stream, recording, and retention configuration
CameraEvent Reading camera state-change events

Examples:

GET /report/CameraEvent?q=Cameras@{camera-guid},TimeRange.SetTimeRange({start-utc},{end-utc})

GET /report/CameraConfiguration?q=Cameras@{camera-guid}

GET /report/Thumbnail?q=AddTimestampRange({camera-guid},{start-utc},{end-utc},1,{width})

Common video operations

Find cameras:

GET /report/EntityConfiguration?q=EntityTypes@Camera,Page=1,PageSize=10,ReturnFields@Name

Read basic camera state:

GET /entity?q=entity={camera-guid},Name,IsOnline,IsPtz,IsBlocked,IsPrivacyProtected,RecordingState

Add a bookmark:

POST /entity?q=entity={camera-guid},AddBookmark({timestamp-utc},{description})

Add a bookmark through the action endpoint:

POST /action?q=AddCameraBookmark({camera-guid},{timestamp-utc},{description})

Delete a bookmark:

POST /entity?q=entity={camera-guid},DeleteCameraBookmark({timestamp-utc})

Start manual recording:

POST /action?q=StartRecording({camera-guid},{length})

Stop manual recording:

POST /action?q=StopRecording({camera-guid})

Check whether PTZ preset recall is supported:

GET /entity?q=entity={camera-guid},PtzCapabilities.IsSupportedCommand(GoToPreset)

Read PTZ capacity information:

GET /entity?q=entity={camera-guid},PtzCapabilities.NumberOfPresets,PtzCapabilities.NumberOfPatterns,PtzCapabilities.NumberOfPresetTours

Read camera streams and usages:

GET /entity?q=entity={camera-guid},Streams,StreamUsages

Change the stream used for one usage:

POST /entity?q=entity={camera-guid},SetStreamUsage(LowQuality,{video-stream-guid})

Read a PTZ preset name:

POST /entity?q=entity={camera-guid},GetPtzPresetName({preset-id})

Read a PTZ pattern name:

POST /entity?q=entity={camera-guid},GetPtzPatternName({pattern-id})

Send the camera to its home position:

POST /action?q=SendPtzCommand({camera-guid},Home,0,0)

Run a PTZ pattern:

POST /action?q=SendPtzCommand({camera-guid},RunPattern,{pattern-id},0)

Start a preset tour:

POST /action?q=SendPtzCommand({camera-guid},StartPresetTour,{tour-id},0)

Query camera sequences:

GET /report/EntityConfiguration?q=EntityTypes@Sequence,Page=1,PageSize=10,ReturnFields@Name

Retrieve archived video thumbnails:

GET /report/Thumbnail?q=AddTimestampRange({camera-guid},{start-utc},{end-utc},1,{width})

Read the privacy-protection state:

GET /entity?q=entity={camera-guid},IsPrivacyProtected

Start protecting new video as it is archived:

POST /entity?q=entity={camera-guid},StartVideoProtection({span},{duration})

Stop protecting new video:

POST /entity?q=entity={camera-guid},StopVideoProtection({delay})

Protect an existing archived range:

POST /entity?q=entity={camera-guid},AddVideoProtection({start-utc},{end-utc},{duration})

Block video:

POST /entity?q=entity={camera-guid},Block({start-utc},{end-utc},{blocking-level})

Unblock video:

POST /entity?q=entity={camera-guid},Unblock({start-utc},{end-utc})

See also