Nimble WebSocket API v1 documentation

Nimble WebSocket API v1

application/json

Nimble's WebSocket API (Application Programming Interface) enables users to subscribe to real-time streaming data and events. Behind this API is a software layer that routes data, arbitrates resources and executes Deep Learning and analytics functions to enable enriched business insights at world-class speed.

The latest online documentation can be found here.

The Key Elements of Nimble

Nimble and the WebSocket API have six key elements: Configuration, Source, Sink, Pipeline, Channel, and Stream.
A Configuration is a collection of Sources, Sinks and Pipeline Elements arranged to execute the desired analytic behavior.
A Source brings data into Nimble.
A Sink pushes data out of Nimble.
A Pipeline is made up of processing elements that perform some analytics task.
Since a Source can be shared between multiple Pipelines, a Channel is an abstraction of both a Source and a Pipeline that can be thought of as "the data brought in by this Source is operated on by this Pipeline".
A Stream is a proxied fMP4 video stream from a Source.

WebSocket topics

There are three WebSocket topic categories:

/config : allows you to subscribe to notifications about the changes in the Configuration.
/exports : allows you to subscribe to the metadata output of the Channel as well as inspect Channel properties such as its current Configuration, processing rate (FPS), and latency.
/stats : allows you to subscribe to Nimble's system-level details such as current CPU and Memory load.

Operations

CONF /v1/config/notify
Notification events for changes to the Configuration.

Specify which events to subscribe to.

Operation IDconfig-subscribe
bindingVersion
0.1.0
method
GET
object
oneOf
Adheres to:
boolean
The initial subscription state for all events.

array<string>
non-empty
An initial set of events to subscribe to.

Items:
string
uid: ConfigNotificationType
Allowed values:
"source"
"sink"
"pipeline"
Additional properties are NOT allowed.
Accepts the following message:
Configuration notification subscriptionConfigNotificationSubscription
Subscribe or unsubscribe from Configuration events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: ConfigNotificationType
Allowed values:
"source"
"sink"
"pipeline"
Additional properties are NOT allowed.
Examples
#1 Example
Enable all events.
#2 Example
Enable only Source events.
{ "source": true }

#3 Example
Disable Source and enable Pipeline events.
{ "source": false, "pipeline": true }

#4 Example
Disable all events (verbose).
{ "source": false, "pipeline": false, "sink": false }
SUB /v1/config/notify
Notification events for changes to the Configuration.

Open a WebSocket connection to receive notification events for changes in the Configuration.

Operation IDconfig-notify
Accepts the following message:
Configuration notificationConfigNotification
Global Configuration change notification.
oneOf
object
uid: ConfigSourceCreated
type
required
string
Const:"source"
action
required
string
Const:"created"
required
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Source ID

oneOf
object
Video Source

type
required
string
Const:"video"
required
oneOf
The URL to a camera or other video streaming device.

Adheres to:
string
format: uri
A simple URL string. May include username and password if they don't contain special characters.

object
An object containing a URL with extra authentication properties.

url
required
string
format: uri
URL without username and password.

user
required
string
Username for HTTP/RTSP authentication.

pass
required
string
Password for HTTP/RTSP authentication.

Additional properties are allowed.
rate
number
format: float> 0
The playback rate of the video stream. The ingestion rate is always real-time, but if the playback rate is slower than the ingestion rate then frames will be dropped. Optional, if omitted playback will occur at the video-defined speed.

decoder
string
The name of the desired video decoder library.

Default value:"gst_h264"
Allowed values:
"gst"
"gst_h264"
"ffmpeg"
Additional properties are allowed.
object
File Source

type
required
string
Const:"file"
address
required
string
A local file path, relative to the current working directory, of the video file to read. If running in a Docker container, any sample video files must be volume-mounted into the container at runtime.

rate
number
format: float> 0
The ingestion and playback rate of the video file. Optional, if omitted playback will occur at the video-defined speed.

Additional properties are allowed.
object
Nimble Source

type
required
string
Const:"nimble"
address
required
string
The hostname (and optional port, default 6344) to access a remote Nimble instance.

channel
required
integer
format: int32>= 0uid: id
Channel ID

image
required
string
The method for generating the RGB image associated with the metadata.

Valid options are:

embedded: Decode and use the embedded jpeg image. If the jpeg is missing (image-encoder omitted), then no image will be available to any pipelines that are attached to this source.

Allowed values:
"embedded"
proxy
boolean
If the Channel has an associated Stream, then setting this to true will cause Nimble to create a local Stream and proxy the remote Stream. This should be set to true for edge deployments to avoid sending MP4 data multiple times over slow/low bandwidth edge-to-cloud connection. Optional.

Default value:false
base_path
string
Provide an alternative base path to access the Nimble API. Optional.

Default value:""
Additional properties are allowed.
object
ZeroMQ Source

type
required
string
Const:"zmq"
address
required
string
format: uri
The tcp:// URL of the remote ZeroMQ publisher to connect to. The fragment portion of the URL subscribes to a specific ZeroMQ topic string.

Additional properties are allowed.
object
Infinite Source

type
required
string
Const:"inf"
rate
number
format: float> 0
The rate at which image frames are generated. Optional, if omitted generation rate will be uncapped.

Additional properties are allowed.
restricted any
oneOf
Adheres to:
integer
format: int32>= 0
Local Stream Reference (Stream ID)

object
Remote Stream Reference (Stream ID + Remote Host)

id
required
integer
format: int32>= 0uid: id
Stream ID

hostname
required
string
format: hostname
Hostname of the remote Nimble instance.

port
integer
[ 1 .. 65535 ]
Port number of the remote Nimble instance.

Default value:6344
Additional properties are NOT allowed.
Or to:
null
Additional properties are allowed.
object
uid: ConfigSourceUpdated
type
required
string
Const:"source"
action
required
string
Const:"updated"
required
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Source ID

allOf
oneOf
object
Video Source

type
required
string
Const:"video"
required
oneOf
The URL to a camera or other video streaming device.

Adheres to:
string
format: uri
A simple URL string. May include username and password if they don't contain special characters.

object
An object containing a URL with extra authentication properties.

url
required
string
format: uri
URL without username and password.

user
required
string
Username for HTTP/RTSP authentication.

pass
required
string
Password for HTTP/RTSP authentication.

Additional properties are allowed.
rate
number
format: float> 0
The playback rate of the video stream. The ingestion rate is always real-time, but if the playback rate is slower than the ingestion rate then frames will be dropped. Optional, if omitted playback will occur at the video-defined speed.

decoder
string
The name of the desired video decoder library.

Default value:"gst_h264"
Allowed values:
"gst"
"gst_h264"
"ffmpeg"
Additional properties are allowed.
object
File Source

type
required
string
Const:"file"
address
required
string
A local file path, relative to the current working directory, of the video file to read. If running in a Docker container, any sample video files must be volume-mounted into the container at runtime.

rate
number
format: float> 0
The ingestion and playback rate of the video file. Optional, if omitted playback will occur at the video-defined speed.

Additional properties are allowed.
object
Nimble Source

type
required
string
Const:"nimble"
address
required
string
The hostname (and optional port, default 6344) to access a remote Nimble instance.

channel
required
integer
format: int32>= 0uid: id
Channel ID

image
required
string
The method for generating the RGB image associated with the metadata.

Valid options are:

embedded: Decode and use the embedded jpeg image. If the jpeg is missing (image-encoder omitted), then no image will be available to any pipelines that are attached to this source.

Allowed values:
"embedded"
proxy
boolean
If the Channel has an associated Stream, then setting this to true will cause Nimble to create a local Stream and proxy the remote Stream. This should be set to true for edge deployments to avoid sending MP4 data multiple times over slow/low bandwidth edge-to-cloud connection. Optional.

Default value:false
base_path
string
Provide an alternative base path to access the Nimble API. Optional.

Default value:""
Additional properties are allowed.
object
ZeroMQ Source

type
required
string
Const:"zmq"
address
required
string
format: uri
The tcp:// URL of the remote ZeroMQ publisher to connect to. The fragment portion of the URL subscribes to a specific ZeroMQ topic string.

Additional properties are allowed.
object
Infinite Source

type
required
string
Const:"inf"
rate
number
format: float> 0
The rate at which image frames are generated. Optional, if omitted generation rate will be uncapped.

Additional properties are allowed.
restricted any
oneOf
Adheres to:
integer
format: int32>= 0
Local Stream Reference (Stream ID)

object
Remote Stream Reference (Stream ID + Remote Host)

id
required
integer
format: int32>= 0uid: id
Stream ID

hostname
required
string
format: hostname
Hostname of the remote Nimble instance.

port
integer
[ 1 .. 65535 ]
Port number of the remote Nimble instance.

Default value:6344
Additional properties are NOT allowed.
Or to:
null
And with:
restricted any
>= 2 properties
Additional properties are allowed.
object
uid: ConfigSourceStats
type
required
string
Const:"source"
action
required
string
Const:"stats"
required
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Source ID

object
status
required
string
Status codes for programmatic use:

"starting": Source is starting up

"ready": Source has started up and is ready to ingest data

"running": Source has started up and is actively ingesting data

"stalled": Source has become unresponsive for an unknown reason

"error": An error has occurred within the Source

Allowed values:
"starting"
"ready"
"running"
"stalled"
"error"
code
string
Error code for programmatic error handling:

"access": Unable to access camera over network

"auth": Invalid camera credentials

"format": Unsupported video format

"decode": Invalid or corrupted video stream

"unknown": Unidentified error

Allowed values:
"access"
"auth"
"format"
"decode"
"unknown"
reason
string
Error reason string for debugging purposes only

fps
required
number
format: float>= 0
The ingestion frame rate of the Source (measured in frames per second)

latency
required
number
format: float>= 0
The ingestion latency of the Source (measured in milliseconds)

Additional properties are allowed.
Additional properties are allowed.
object
uid: ConfigSourceDeleted
type
required
string
Const:"source"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0uid: id
Source ID

Additional properties are NOT allowed.
Additional properties are allowed.
object
uid: ConfigSinkCreated
type
required
string
Const:"sink"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0
Sink ID

object
type
string
Allowed values:
"file"
"embedding"
"zmq"
"inf"
address
string
array<integer>
A list of sources to include. An empty list indicates no filtering is enabled.

Default value:[]
Items:
integer
format: int32>= 0uid: id
Source ID

Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ConfigSinkUpdated
type
required
string
Const:"sink"
action
required
string
Const:"updated"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Sink ID

object
type
string
Allowed values:
"file"
"embedding"
"zmq"
"inf"
address
string
array<integer>
A list of sources to include. An empty list indicates no filtering is enabled.

Default value:[]
Items:
integer
format: int32>= 0uid: id
Source ID

Additional properties are allowed.
And with:
restricted any
>= 2 properties
Additional properties are allowed.
object
uid: ConfigSinkStats
type
required
string
Const:"sink"
action
required
string
Const:"stats"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Sink ID

object
status
required
string
Status codes for programmatic use:

"starting": Sink is starting up

"ready": Sink has started up and is ready to consume data

"running": Sink has started up and is actively consuming data

"stalled": Sink has become unresponsive for an unknown reason

"error": An error has occurred within the Sink

Allowed values:
"starting"
"ready"
"running"
"stalled"
"error"
code
string
Error code for programmatic error handling:

"unknown": Unidentified error

Allowed values:
"unknown"
reason
string
Error reason string for debugging purposes only

fps
required
number
format: float>= 0
The consuming frame rate of the Sink (measured in frames per second)

latency
required
number
format: float>= 0
The consuming latency of the Source (measured in milliseconds)

Additional properties are allowed.
Additional properties are allowed.
object
uid: ConfigSinkDeleted
type
required
string
Const:"sink"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0
Sink ID

Additional properties are NOT allowed.
Additional properties are allowed.
object
uid: ConfigPipelineCreated
type
required
string
Const:"pipeline"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0
Pipeline ID

object
array<object>
non-empty
Sequence of processing elements

name
required
string
The name of the element.

object
Element initialization arguments.

The list of valid parameters are available from the params schema defined by the element. Only arguments with a corresponding defined parameter will be passed to the element.

Additional properties are allowed.
object
A mapping from Source IDs to static metadata JSON.

This enables configuring different static metadata for the Pipeline based on the Source. The static metadata is served for the Channel produced from the Source and Pipeline. The keys of this object are Source IDs and the values are arbitrary JSON objects. Multiple Source IDs may be included in each key by separating them with commas.

If this property is omitted, then an empty JSON object is used by default for unspecified sources. Using an empty string key in this mapping allows overriding the default JSON object.

oneOf
Adheres to:
restricted any
must match: ^(\d+,?)+$
Or to:
string
Allowed values:
""
object
A Pipeline element configuration used for the input source(s).

x-additionalPropertiesName
source-id
Additional properties are allowed.
usecase
string
The high-level description of the analytics performed by the pipeline.

array<integer>
IDs of input sources to the pipeline

Items:
integer
format: int32>= 0uid: id
Source ID

array<integer>
IDs of output sinks from the pipeline

Items:
integer
format: int32>= 0
Sink ID

Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ConfigPipelineUpdated
type
required
string
Const:"pipeline"
action
required
string
Const:"updated"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Pipeline ID

object
array<object>
non-empty
Sequence of processing elements

name
required
string
The name of the element.

object
Element initialization arguments.

The list of valid parameters are available from the params schema defined by the element. Only arguments with a corresponding defined parameter will be passed to the element.

Additional properties are allowed.
object
A mapping from Source IDs to static metadata JSON.

This enables configuring different static metadata for the Pipeline based on the Source. The static metadata is served for the Channel produced from the Source and Pipeline. The keys of this object are Source IDs and the values are arbitrary JSON objects. Multiple Source IDs may be included in each key by separating them with commas.

If this property is omitted, then an empty JSON object is used by default for unspecified sources. Using an empty string key in this mapping allows overriding the default JSON object.

oneOf
Adheres to:
restricted any
must match: ^(\d+,?)+$
Or to:
string
Allowed values:
""
object
A Pipeline element configuration used for the input source(s).

x-additionalPropertiesName
source-id
Additional properties are allowed.
usecase
string
The high-level description of the analytics performed by the pipeline.

array<integer>
IDs of input sources to the pipeline

Items:
integer
format: int32>= 0uid: id
Source ID

array<integer>
IDs of output sinks from the pipeline

Items:
integer
format: int32>= 0
Sink ID

Additional properties are allowed.
And with:
restricted any
>= 2 properties
Additional properties are allowed.
object
uid: ConfigPipelineStats
type
required
string
Const:"pipeline"
action
required
string
Const:"stats"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Pipeline ID

object
status
required
string
Status codes for programmatic use:

"starting": Pipeline is starting up

"ready": Pipeline has started up and is ready to process data

"running": Pipeline has started up and is actively processing data

"stalled": Pipeline has become unresponsive for an unknown reason

"error": An error has occurred within the Pipeline

Allowed values:
"starting"
"ready"
"running"
"stalled"
"error"
code
string
Error code for programmatic error handling:

"unknown": Unidentified error

Allowed values:
"unknown"
reason
string
Error reason string for debugging purposes only

fps
required
number
format: float>= 0
The processing frame rate of the Pipeline (measured in frames per second)

latency
required
number
format: float>= 0
The processing latency of the Pipeline (measured in milliseconds)

Additional properties are allowed.
Additional properties are allowed.
object
uid: ConfigPipelineDeleted
type
required
string
Const:"pipeline"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0
Pipeline ID

Additional properties are NOT allowed.
Additional properties are allowed.
Examples
#1 Example
Live video Source created.
{ "type": "source", "action": "created", "value": { "id": 2, "type": "video", "address": "rtsp://localhost:554/axis-media/media.amp", "rate": 30 } }

#2 Example
Live video Source updated (address and rate).
{ "type": "source", "action": "updated", "value": { "id": 2, "type": "video", "address": "rtsp://localhost:8554/h264major", "rate": 15 } }

#3 Example
Live video Source stats updated.
{ "type": "source", "action": "stats", "value": { "id": 2, "status": "running", "fps": 15, "latency": 12.85 } }

#4 Example
Live video Source deleted.
{ "type": "source", "action": "deleted", "value": { "id": 2 } }

#5 Example
File Sink created.
{ "type": "sink", "action": "created", "value": { "id": 1, "type": "file", "address": "./output.mp4", "filter": [] } }

#6 Example
File Sink updated (address and filter).
{ "type": "sink", "action": "updated", "value": { "id": 1, "type": "file", "address": "./new_output.mp4", "filter": [ 2 ] } }

#7 Example
File Sink stats updated.
{ "type": "sink", "action": "stats", "value": { "id": 1, "status": "running", "fps": 14.8, "latency": 147.2 } }

#8 Example
File Sink deleted.
{ "type": "sink", "action": "deleted", "value": { "id": 1 } }

#9 Example
Pipeline created.
{ "type": "pipeline", "action": "created", "value": { "id": 0, "elements": [ { "name": "infer", "args": { "model": "person-detection-nano", "score_threshold": 0.3, "iou_threshold": 0.3 } }, { "name": "object-tracking-OH", "args": { "max_age": 3, "min_hits": 3, "history": 50, "region": "bottom", "ratio": 0.2, "moving_average": 3 } } ], "usecase": "my-usecase", "sources": [ 2 ], "sinks": [ 1 ] } }

#10 Example
Pipeline updated (usecase and sinks).
{ "type": "pipeline", "action": "updated", "value": { "id": 0, "elements": [ { "name": "infer", "args": { "model": "person-detection-nano", "score_threshold": 0.3, "iou_threshold": 0.3 } }, { "name": "object-tracking-OH", "args": { "max_age": 3, "min_hits": 3, "history": 50, "region": "bottom", "ratio": 0.2, "moving_average": 3 } } ], "usecase": "new-usecase", "sources": [ 2 ], "sinks": [] } }

#11 Example
Pipeline stats updated.
{ "type": "pipeline", "action": "stats", "value": { "id": 0, "status": "running", "fps": 14.9, "latency": 122.67 } }

#12 Example
Pipeline deleted.
{ "type": "pipeline", "action": "deleted", "value": { "id": 0 } }
CONF /v1/config/source/{id}/publish
Publish data directly to a Source.

Note: This endpoint is only valid for Sources that support publishing.

Operation IDconfig-source-publish
id
required
integer
format: int32>= 0uid: id
The ID of the Source to publish to.

bindingVersion
0.1.0
method
GET
object
Note: The Source defines the query parameters (i.e. publish options) that are accepted.

Additional properties are allowed.
Accepts the following message:
Source publish dataSourcePublishData
Note: The Source defines the payload format of the published data.
Payload
string
format: binary
Examples
string

This example has been generated automatically.
CONF /v1/exports/notify
Notification events for changes to the Exports.

Specify which events to subscribe to.

Operation IDexports-subscribe
bindingVersion
0.1.0
method
GET
object
oneOf
Adheres to:
boolean
The initial subscription state for all events.

array<string>
non-empty
An initial set of events to subscribe to.

Items:
string
uid: ExportsNotificationType
Allowed values:
"channel"
"stream"
Additional properties are NOT allowed.
Accepts the following message:
Exports notification subscriptionExportsNotificationSubscription
Subscribe or unsubscribe from events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: ExportsNotificationType
Allowed values:
"channel"
"stream"
Additional properties are NOT allowed.
Examples
#1 Example
Enable all events.
#2 Example
Enable only Channel events.
{ "channel": true }

#3 Example
Disable Channel and enable Stream events.
{ "channel": false, "stream": true }

#4 Example
Disable all events (verbose).
{ "channel": false, "stream": false }
SUB /v1/exports/notify
Notification events for changes to the Exports.

Open a WebSocket connection to receive notification events for changes to the Exports.

Operation IDexports-notify
Accepts the following message:
Exports notificationExportsNotification
Exports changed notification
oneOf
object
uid: ExportsChannelCreated
type
required
string
Const:"channel"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0uid: id
Channel ID

object
source
integer
format: int32>= 0uid: id
Source ID

pipeline
integer
format: int32>= 0
Pipeline ID

oneOf
Adheres to:
integer
format: int32>= 0
Local Stream Reference (Stream ID)

object
Remote Stream Reference (Stream ID + Remote Host)

id
required
integer
format: int32>= 0uid: id
Stream ID

hostname
required
string
format: hostname
Hostname of the remote Nimble instance.

port
integer
[ 1 .. 65535 ]
Port number of the remote Nimble instance.

Default value:6344
Additional properties are NOT allowed.
Or to:
null
Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ExportsChannelDeleted
type
required
string
Const:"channel"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0uid: id
Channel ID

Additional properties are allowed.
Additional properties are allowed.
object
uid: ExportsStreamCreated
type
required
string
Const:"stream"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0uid: id
Stream ID

object
array<integer>
non-empty
Items:
integer
format: int32>= 0uid: id
Source ID

Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ExportsStreamDeleted
type
required
string
Const:"stream"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0uid: id
Stream ID

Additional properties are allowed.
Additional properties are allowed.
Examples
#1 Example
Stream created.
{ "type": "stream", "action": "created", "value": { "id": 0, "sources": [ 2 ] } }

#2 Example
Channel created.
{ "type": "channel", "action": "created", "value": { "id": 1, "source": 2, "pipeline": 3, "stream": 0 } }

#3 Example
Channel deleted.
{ "type": "channel", "action": "deleted", "value": { "id": 1 } }

#4 Example
Stream deleted.
{ "type": "stream", "action": "deleted", "value": { "id": 0 } }
CONF /v1/exports/channels/metadata
Multi-Channel metadata streaming.

Specify which channels to subscribe to.

Operation IDchannels-metadata-subscribe
bindingVersion
0.1.0
method
GET
object
uid: ChannelsQuerySubscription
oneOf
Adheres to:
boolean
The initial subscription state for all channels.

array<integer>
non-empty
An initial set of channels to subscribe to.

Items:
integer
format: int32>= 0uid: id
Channel ID

Additional properties are allowed.
object
uid: ChannelMetadataQuerySubscription
format
string
Name of supported metadata formatter

Default value:"megh"
Allowed values:
"aws"
"megh"
message_format
string
Specific the message format used to encapsulate the channel metadata.

The protobuf message format is defined in this .proto file: channel_multipart.proto The ChannelMultipart and ChannelMultipartWithId message types should be used to parse received WebSocket messages.

Default value:"json"
Allowed values:
"json"
"protobuf"
metadata_format
read-only
string
The encoding format of the channel metadata. Channel metadata will always be JSON-compatible, but different encoding formats may be more efficient by default. Only applies when message_format = "protobuf".

Default value:"json"
Allowed values:
"json"
"bson"
"cbor"
"message_pack"
"amazon_ion_text"
"amazon_ion_binary"
"smile"
metadata_compression
read-only
string
Applies compression to the channel metadata to reduce bandwidth usage. Only applies when message_format = "protobuf".

Default value:"brotli"
Allowed values:
"none"
"deflate"
"brotli"
"xz"
Additional properties are allowed.
Accepts the following message:
Channels subscriptionChannelsSubscription
Specify which Channels to subscribe to.
oneOf
Adheres to:
boolean
The subscription state for all events.

array<integer>
The Channels to subscribe to.

Items:
integer
format: int32>= 0uid: id
Channel ID

Examples
#1 Example
Enable all Channels.
#2 Example
Enable only Channels 0 and 1.
[ 0, 1 ]

#3 Example
Disable Channel 1.
[ 1 ]
SUB /v1/exports/channels/metadata
Multi-Channel metadata streaming.

Receive JSON metadata from all inferencing Channels.

Operation IDchannels-metadata
Accepts the following message:
Channel metadata with IDChannelMetadataWithID
Metadata for a frame of video extracted by the inferencing Channel.
oneOf
uid: ChannelMultipartWithID
tuple<integer, object, ...optional<string>>
[ 2 .. 3 ] items
Multi-part metadata message without timestamp.

1 item:
integer
format: int32>= 0uid: id
Channel ID

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

tuple<integer, object, number, ...optional<string>>
[ 3 .. 4 ] items
Multi-part metadata message with timestamp.
This message format is used when the stream property of the channel is non-null.

1 item:
integer
format: int32>= 0uid: id
Channel ID

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
3 item:
number
format: doubleuid: ChannelMetadataTimestamp
Media presentation timestamp (PTS)

Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

Or to:
string
format: bytemedia type: application/x-protobufencoding: binary
A binary message encoded with Protobuf v3 (proto3) according to the ChannelMultipartWithId message type: channel_multipart.proto

Examples
[ 0, {} ]

This example has been generated automatically.
CONF /v1/exports/channels/notify
Multi-Channel event notification.

Specify which channels to subscribe to.

Operation IDchannels-notify-subscribe
bindingVersion
0.1.0
method
GET
object
uid: ChannelsQuerySubscription
oneOf
Adheres to:
boolean
The initial subscription state for all channels.

array<integer>
non-empty
An initial set of channels to subscribe to.

Items:
integer
format: int32>= 0uid: id
Channel ID

Additional properties are allowed.
Accepts the following message:
Channels subscriptionChannelsSubscription
Specify which Channels to subscribe to.
oneOf
Adheres to:
boolean
The subscription state for all events.

array<integer>
The Channels to subscribe to.

Items:
integer
format: int32>= 0uid: id
Channel ID

Examples
#1 Example
Enable all Channels.
#2 Example
Enable only Channels 0 and 1.
[ 0, 1 ]

#3 Example
Disable Channel 1.
[ 1 ]
SUB /v1/exports/channels/notify
Multi-Channel event notification.

Receive notification events for updates to Channels.

Operation IDchannels-notify
Accepts the following message:
Channel notification with IDChannelNotificationWithID
Channel statistics changed notification.
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Channel ID

oneOf
uid: ChannelNotifications
object
uid: ChannelFPS
The processing frame rate of the channel

type
required
string
Const:"fps"
value
required
number
format: float>= 0
The processing frame rate of the channel (measured in frames per second)

Additional properties are allowed.
object
uid: ChannelLatency
The processing latency of the channel

type
required
string
Const:"latency"
value
required
number
format: float>= 0
The processing latency of the channel (measured in milliseconds)

Additional properties are allowed.
Examples
#1 Example
FPS changed event (for Channel 0).
{ "id": 0, "type": "fps", "value": 29.2 }

#2 Example
Latency changed event (for Channel 1).
{ "id": 1, "type": "latency", "value": 134.1 }
CONF /v1/exports/channel/{id}/metadata
Channel metadata streaming.

Configure the channel metadata stream.

Operation IDchannel-metadata-config
id
required
integer
format: int32>= 0uid: id
The ID of the Channel to connect to.
bindingVersion
0.1.0
method
GET
object
uid: ChannelMetadataQuerySubscription
format
string
Name of supported metadata formatter

Default value:"megh"
Allowed values:
"aws"
"megh"
message_format
string
Specific the message format used to encapsulate the channel metadata.

The protobuf message format is defined in this .proto file: channel_multipart.proto The ChannelMultipart and ChannelMultipartWithId message types should be used to parse received WebSocket messages.

Default value:"json"
Allowed values:
"json"
"protobuf"
metadata_format
read-only
string
The encoding format of the channel metadata. Channel metadata will always be JSON-compatible, but different encoding formats may be more efficient by default. Only applies when message_format = "protobuf".

Default value:"json"
Allowed values:
"json"
"bson"
"cbor"
"message_pack"
"amazon_ion_text"
"amazon_ion_binary"
"smile"
metadata_compression
read-only
string
Applies compression to the channel metadata to reduce bandwidth usage. Only applies when message_format = "protobuf".

Default value:"brotli"
Allowed values:
"none"
"deflate"
"brotli"
"xz"
Additional properties are allowed.
object
uid: ChannelMetadataConfig
live
boolean
Whether the metadata stream is considered "live" when the WebSocket connection is established.

If the metadata stream is considered "live", then messages will always be sent across the WebSocket. If the metadata stream is NOT considered "live", then messages will only be sent if the metadata contains inference/analytics results in the JSON, or qualifying messages were sent recently (see metadata_timeout).

The "live" status of the connection can be dynamically changed at runtime by sending specific JSON messages from the client, or by using the "live timeout" feature.

This is part of the "On-demand metadata streaming" feature.

Default value:true
live_timeout
integer
format: int32>= 0
Configures the connection to automatically set the "live" status to false after a certain amount of time (measured in milliseconds).

If the timeout value is set to zero, then the "live" status will never automatically change.

The timer associated with this timeout is reset whenever the "live" status is manually set at runtime (even if the status value is unchanged).

This is part of the "On-demand metadata streaming" feature.

Default value:0
metadata_timeout
integer
format: int32>= 0
Configures the amount of time (measured in milliseconds) to keep sending messages after a message is sent that contained inference/analytics results in the JSON.

If the timeout value is set to zero, then only messages that contain inference/analytics results in the JSON are sent.

This is part of the "On-demand metadata streaming" feature.

Default value:0
Additional properties are allowed.
Accepts the following message:
Channel metadata configurationChannelMetadataConfig
Configuration object to dynamically change connection behavior.
object
uid: ChannelMetadataConfig
live
boolean
Whether the metadata stream is considered "live" when the WebSocket connection is established.

If the metadata stream is considered "live", then messages will always be sent across the WebSocket. If the metadata stream is NOT considered "live", then messages will only be sent if the metadata contains inference/analytics results in the JSON, or qualifying messages were sent recently (see metadata_timeout).

The "live" status of the connection can be dynamically changed at runtime by sending specific JSON messages from the client, or by using the "live timeout" feature.

This is part of the "On-demand metadata streaming" feature.

Default value:true
live_timeout
integer
format: int32>= 0
Configures the connection to automatically set the "live" status to false after a certain amount of time (measured in milliseconds).

If the timeout value is set to zero, then the "live" status will never automatically change.

The timer associated with this timeout is reset whenever the "live" status is manually set at runtime (even if the status value is unchanged).

This is part of the "On-demand metadata streaming" feature.

Default value:0
metadata_timeout
integer
format: int32>= 0
Configures the amount of time (measured in milliseconds) to keep sending messages after a message is sent that contained inference/analytics results in the JSON.

If the timeout value is set to zero, then only messages that contain inference/analytics results in the JSON are sent.

This is part of the "On-demand metadata streaming" feature.

Default value:0
Additional properties are allowed.
Examples
#1 Example
Set 'live' status to expire after 10 seconds.
{ "live_timeout": 10000 }

#2 Example
Send 'live' message from client to maintain 'live' status before timeout is reached.
{ "live": true }

#3 Example
Set 'live' status to never expire.
{ "live_timeout": 0 }

#4 Example
Set metadata timeout so frames continue to be sent for 5 seconds after the last detection.
{ "metadata_timeout": 5000 }

#5 Example
Only send metadata frames that contain inference/analytics results in the JSON, regardless of previous frames.
{ "metadata_timeout": 0 }
SUB /v1/exports/channel/{id}/metadata
Channel metadata streaming.

Receive JSON metadata from an inferencing Channel.

Operation IDchannel-metadata
id
required
integer
format: int32>= 0uid: id
The ID of the Channel to connect to.
Accepts the following message:
Channel metadataChannelMetadata
Metadata for a frame of video extracted by the inferencing Channel.
oneOf
uid: ChannelMultipart
tuple<object, ...optional<string>>
[ 1 .. 2 ] items
Multi-part metadata message without timestamp.

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

tuple<object, number, ...optional<string>>
[ 2 .. 3 ] items
Multi-part metadata message with timestamp.
This message format is used when the stream property of the channel is non-null.

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
2 item:
number
format: doubleuid: ChannelMetadataTimestamp
Media presentation timestamp (PTS)

Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

Or to:
string
format: bytemedia type: application/x-protobufencoding: binary
A binary message encoded with Protobuf v3 (proto3) according to the ChannelMultipart message type: channel_multipart.proto

Examples
[ {} ]

This example has been generated automatically.
CONF /v1/exports/channel/{id}/notify
Channel event notification.

Specify which events to subscribe to.

Operation IDchannel-notify-subscribe
id
required
integer
format: int32>= 0uid: id
The ID of the Channel to connect to.
bindingVersion
0.1.0
method
GET
object
oneOf
Adheres to:
boolean
The initial subscription state for all events.

array<string>
non-empty
An initial set of events to subscribe to.

Items:
string
uid: ChannelNotificationType
Allowed values:
"fps"
"latency"
Additional properties are NOT allowed.
Accepts the following message:
Channel notification subscriptionChannelNotificationSubscription
Subscribe or unsubscribe from Channel events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: ChannelNotificationType
Allowed values:
"fps"
"latency"
Additional properties are NOT allowed.
Examples
#1 Example
Enable all events.
#2 Example
Enable FPS events.
{ "fps": true }

#3 Example
Disable FPS and enable latency events.
{ "fps": false, "latency": true }

#4 Example
Disable all events (verbose).
{ "fps": false, "latency": false }
SUB /v1/exports/channel/{id}/notify
Channel event notification.

Receive notification events for updates to specific Channel.

Operation IDchannel-notify
id
required
integer
format: int32>= 0uid: id
The ID of the Channel to connect to.
Accepts the following message:
Channel notificationChannelNotification
Channel statistic changed notification.
oneOf
uid: ChannelNotifications
object
uid: ChannelFPS
The processing frame rate of the channel

type
required
string
Const:"fps"
value
required
number
format: float>= 0
The processing frame rate of the channel (measured in frames per second)

Additional properties are allowed.
object
uid: ChannelLatency
The processing latency of the channel

type
required
string
Const:"latency"
value
required
number
format: float>= 0
The processing latency of the channel (measured in milliseconds)

Additional properties are allowed.
Examples
#1 Example
FPS changed event.
{ "type": "fps", "value": 29.2 }

#2 Example
Latency changed event.
{ "type": "latency", "value": 134.1 }
SUB /v1/exports/stream/{id}
Video streaming.

Receive a binary stream of fragmented MP4 video.
- External Docs
Operation IDmp4-video-stream
id
required
integer
format: int32>= 0uid: id
The ID of the Stream to connect to.

bindingVersion
0.1.0
method
GET
Accepts one of the following messages:
- #0Stream statusStreamStatus
  Stream status indication.
  text/plain
  oneOf
  Adheres to:
  string
  uid: StreamReset
  Indicates the video has reached end-of-stream and is restarting.
  
  Const:"reset"
  Examples
  #1 Example
  Reset status.
  reset
- #1Stream dataStreamData
  Fragmented MP4 video Stream data.
  video/mp4
  Payload
  string
  format: binary
  Examples
  string
  
  This example has been generated automatically.
CONF /v1/stats/notify
Notification events for updates to the Statistics.

Specify which events to subscribe to.

Operation IDstats-subscribe
bindingVersion
0.1.0
method
GET
object
oneOf
Adheres to:
boolean
The initial subscription state for all events.

array<string>
non-empty
An initial set of events to subscribe to.

Items:
string
uid: StatsType
Allowed values:
"uptime"
"cpu"
"memory"
"network"
"activated"
Additional properties are NOT allowed.
Accepts the following message:
Global statistics notification subscriptionStatsNotificationSubscription
Subscribe or unsubscribe from events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: StatsType
Allowed values:
"uptime"
"cpu"
"memory"
"network"
"activated"
Additional properties are NOT allowed.
Examples
#1 Example
Enable all events.
#2 Example
Enable only CPU Load events.
{ "cpu": true }

#3 Example
Disable CPU Load and enable Memory events.
{ "cpu": false, "memory": true }

#4 Example
Disable all events (verbose).
{ "cpu": false, "memory": false }
SUB /v1/stats/notify
Notification events for updates to the Statistics.

Receive notification events for updates to Statistics.

Operation IDstats-notify
Accepts the following message:
Global stats notificationStatsNotification
Global statistics changed notification.
oneOf
object
uid: StatUptime
The uptime (in seconds) since Nimble started

type
required
string
Const:"uptime"
value
required
number
format: float>= 0
The uptime (in seconds) since Nimble started

Additional properties are allowed.
object
uid: StatCPU
The CPU load (measured in CPU threads utilized)

type
required
string
Const:"cpu"
value
required
number
format: float>= 0
CPU utilization (measured in CPU threads)

Additional properties are allowed.
object
uid: StatMemory
The amount of memory used (measured in bytes)

type
required
string
Const:"memory"
required
object
Amount of virtual and physical memory used (measured in bytes)

virtual
required
integer
format: int64>= 0
Amount of virtual memory used (measured in bytes)

physical
required
integer
format: int64>= 0
Amount of resident physical memory used (measured in bytes)

total
required
integer
format: int64>= 0
Amount of total physical memory (measured in bytes)

available
required
integer
format: int64>= 0
Amount of available physical memory (measured in bytes)

Additional properties are allowed.
Additional properties are allowed.
object
uid: StatNetwork
The amount of network used (measured in bytes/sec)

type
required
string
Const:"network"
required
object
The amount of network used (measured in bytes/sec)

send
required
integer
format: int64>= 0
Amount of tx network used (measured in bytes/sec)

receive
required
integer
format: int64>= 0
Amount of rx network used (measured in bytes/sec)

congestion
required
boolean
Whether tx network is congested

Additional properties are allowed.
Additional properties are allowed.
object
uid: StatActivated
The activation status

type
required
string
Const:"activated"
value
required
boolean
Whether Nimble is activated or not.

Additional properties are allowed.
Examples
#1 Example
Uptime (in seconds).
{ "type": "uptime", "value": 29.763 }

#2 Example
One CPU thread utilized.
{ "type": "cpu", "value": 1 }

#3 Example
Half of a CPU thread utilized.
{ "type": "cpu", "value": 0.5 }

#4 Example
2.5GiB virtual memory and 800MiB physical RAM used. 4GB physical memory on the system with 1GB available.
{ "type": "memory", "value": { "virtual": 2684354560, "physical": 838860800, "total": 4294967296, "available": 1073741824 } }

#5 Example
4Mbps send/receive bandwith used (in bytes per second).
{ "type": "network", "value": { "send": 524288, "receive": 524288, "congestion": false } }

#6 Example
Nimble is activated.
{ "type": "activated", "value": true }

Messages

#1Configuration notification subscriptionConfigNotificationSubscription
Subscribe or unsubscribe from Configuration events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: ConfigNotificationType
Allowed values:
"source"
"sink"
"pipeline"
Additional properties are NOT allowed.
#2Configuration notificationConfigNotification
Global Configuration change notification.
oneOf
object
uid: ConfigSourceCreated
type
required
string
Const:"source"
action
required
string
Const:"created"
required
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Source ID

oneOf
object
Video Source

type
required
string
Const:"video"
required
oneOf
The URL to a camera or other video streaming device.

Adheres to:
string
format: uri
A simple URL string. May include username and password if they don't contain special characters.

object
An object containing a URL with extra authentication properties.

url
required
string
format: uri
URL without username and password.

user
required
string
Username for HTTP/RTSP authentication.

pass
required
string
Password for HTTP/RTSP authentication.

Additional properties are allowed.
rate
number
format: float> 0
The playback rate of the video stream. The ingestion rate is always real-time, but if the playback rate is slower than the ingestion rate then frames will be dropped. Optional, if omitted playback will occur at the video-defined speed.

decoder
string
The name of the desired video decoder library.

Default value:"gst_h264"
Allowed values:
"gst"
"gst_h264"
"ffmpeg"
Additional properties are allowed.
object
File Source

type
required
string
Const:"file"
address
required
string
A local file path, relative to the current working directory, of the video file to read. If running in a Docker container, any sample video files must be volume-mounted into the container at runtime.

rate
number
format: float> 0
The ingestion and playback rate of the video file. Optional, if omitted playback will occur at the video-defined speed.

Additional properties are allowed.
object
Nimble Source

type
required
string
Const:"nimble"
address
required
string
The hostname (and optional port, default 6344) to access a remote Nimble instance.

channel
required
integer
format: int32>= 0uid: id
Channel ID

image
required
string
The method for generating the RGB image associated with the metadata.

Valid options are:

embedded: Decode and use the embedded jpeg image. If the jpeg is missing (image-encoder omitted), then no image will be available to any pipelines that are attached to this source.

Allowed values:
"embedded"
proxy
boolean
If the Channel has an associated Stream, then setting this to true will cause Nimble to create a local Stream and proxy the remote Stream. This should be set to true for edge deployments to avoid sending MP4 data multiple times over slow/low bandwidth edge-to-cloud connection. Optional.

Default value:false
base_path
string
Provide an alternative base path to access the Nimble API. Optional.

Default value:""
Additional properties are allowed.
object
ZeroMQ Source

type
required
string
Const:"zmq"
address
required
string
format: uri
The tcp:// URL of the remote ZeroMQ publisher to connect to. The fragment portion of the URL subscribes to a specific ZeroMQ topic string.

Additional properties are allowed.
object
Infinite Source

type
required
string
Const:"inf"
rate
number
format: float> 0
The rate at which image frames are generated. Optional, if omitted generation rate will be uncapped.

Additional properties are allowed.
restricted any
oneOf
Adheres to:
integer
format: int32>= 0
Local Stream Reference (Stream ID)

object
Remote Stream Reference (Stream ID + Remote Host)

id
required
integer
format: int32>= 0uid: id
Stream ID

hostname
required
string
format: hostname
Hostname of the remote Nimble instance.

port
integer
[ 1 .. 65535 ]
Port number of the remote Nimble instance.

Default value:6344
Additional properties are NOT allowed.
Or to:
null
Additional properties are allowed.
object
uid: ConfigSourceUpdated
type
required
string
Const:"source"
action
required
string
Const:"updated"
required
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Source ID

allOf
oneOf
object
Video Source

type
required
string
Const:"video"
required
oneOf
The URL to a camera or other video streaming device.

Adheres to:
string
format: uri
A simple URL string. May include username and password if they don't contain special characters.

object
An object containing a URL with extra authentication properties.

url
required
string
format: uri
URL without username and password.

user
required
string
Username for HTTP/RTSP authentication.

pass
required
string
Password for HTTP/RTSP authentication.

Additional properties are allowed.
rate
number
format: float> 0
The playback rate of the video stream. The ingestion rate is always real-time, but if the playback rate is slower than the ingestion rate then frames will be dropped. Optional, if omitted playback will occur at the video-defined speed.

decoder
string
The name of the desired video decoder library.

Default value:"gst_h264"
Allowed values:
"gst"
"gst_h264"
"ffmpeg"
Additional properties are allowed.
object
File Source

type
required
string
Const:"file"
address
required
string
A local file path, relative to the current working directory, of the video file to read. If running in a Docker container, any sample video files must be volume-mounted into the container at runtime.

rate
number
format: float> 0
The ingestion and playback rate of the video file. Optional, if omitted playback will occur at the video-defined speed.

Additional properties are allowed.
object
Nimble Source

type
required
string
Const:"nimble"
address
required
string
The hostname (and optional port, default 6344) to access a remote Nimble instance.

channel
required
integer
format: int32>= 0uid: id
Channel ID

image
required
string
The method for generating the RGB image associated with the metadata.

Valid options are:

embedded: Decode and use the embedded jpeg image. If the jpeg is missing (image-encoder omitted), then no image will be available to any pipelines that are attached to this source.

Allowed values:
"embedded"
proxy
boolean
If the Channel has an associated Stream, then setting this to true will cause Nimble to create a local Stream and proxy the remote Stream. This should be set to true for edge deployments to avoid sending MP4 data multiple times over slow/low bandwidth edge-to-cloud connection. Optional.

Default value:false
base_path
string
Provide an alternative base path to access the Nimble API. Optional.

Default value:""
Additional properties are allowed.
object
ZeroMQ Source

type
required
string
Const:"zmq"
address
required
string
format: uri
The tcp:// URL of the remote ZeroMQ publisher to connect to. The fragment portion of the URL subscribes to a specific ZeroMQ topic string.

Additional properties are allowed.
object
Infinite Source

type
required
string
Const:"inf"
rate
number
format: float> 0
The rate at which image frames are generated. Optional, if omitted generation rate will be uncapped.

Additional properties are allowed.
restricted any
oneOf
Adheres to:
integer
format: int32>= 0
Local Stream Reference (Stream ID)

object
Remote Stream Reference (Stream ID + Remote Host)

id
required
integer
format: int32>= 0uid: id
Stream ID

hostname
required
string
format: hostname
Hostname of the remote Nimble instance.

port
integer
[ 1 .. 65535 ]
Port number of the remote Nimble instance.

Default value:6344
Additional properties are NOT allowed.
Or to:
null
And with:
restricted any
>= 2 properties
Additional properties are allowed.
object
uid: ConfigSourceStats
type
required
string
Const:"source"
action
required
string
Const:"stats"
required
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Source ID

object
status
required
string
Status codes for programmatic use:

"starting": Source is starting up

"ready": Source has started up and is ready to ingest data

"running": Source has started up and is actively ingesting data

"stalled": Source has become unresponsive for an unknown reason

"error": An error has occurred within the Source

Allowed values:
"starting"
"ready"
"running"
"stalled"
"error"
code
string
Error code for programmatic error handling:

"access": Unable to access camera over network

"auth": Invalid camera credentials

"format": Unsupported video format

"decode": Invalid or corrupted video stream

"unknown": Unidentified error

Allowed values:
"access"
"auth"
"format"
"decode"
"unknown"
reason
string
Error reason string for debugging purposes only

fps
required
number
format: float>= 0
The ingestion frame rate of the Source (measured in frames per second)

latency
required
number
format: float>= 0
The ingestion latency of the Source (measured in milliseconds)

Additional properties are allowed.
Additional properties are allowed.
object
uid: ConfigSourceDeleted
type
required
string
Const:"source"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0uid: id
Source ID

Additional properties are NOT allowed.
Additional properties are allowed.
object
uid: ConfigSinkCreated
type
required
string
Const:"sink"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0
Sink ID

object
type
string
Allowed values:
"file"
"embedding"
"zmq"
"inf"
address
string
array<integer>
A list of sources to include. An empty list indicates no filtering is enabled.

Default value:[]
Items:
integer
format: int32>= 0uid: id
Source ID

Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ConfigSinkUpdated
type
required
string
Const:"sink"
action
required
string
Const:"updated"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Sink ID

object
type
string
Allowed values:
"file"
"embedding"
"zmq"
"inf"
address
string
array<integer>
A list of sources to include. An empty list indicates no filtering is enabled.

Default value:[]
Items:
integer
format: int32>= 0uid: id
Source ID

Additional properties are allowed.
And with:
restricted any
>= 2 properties
Additional properties are allowed.
object
uid: ConfigSinkStats
type
required
string
Const:"sink"
action
required
string
Const:"stats"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Sink ID

object
status
required
string
Status codes for programmatic use:

"starting": Sink is starting up

"ready": Sink has started up and is ready to consume data

"running": Sink has started up and is actively consuming data

"stalled": Sink has become unresponsive for an unknown reason

"error": An error has occurred within the Sink

Allowed values:
"starting"
"ready"
"running"
"stalled"
"error"
code
string
Error code for programmatic error handling:

"unknown": Unidentified error

Allowed values:
"unknown"
reason
string
Error reason string for debugging purposes only

fps
required
number
format: float>= 0
The consuming frame rate of the Sink (measured in frames per second)

latency
required
number
format: float>= 0
The consuming latency of the Source (measured in milliseconds)

Additional properties are allowed.
Additional properties are allowed.
object
uid: ConfigSinkDeleted
type
required
string
Const:"sink"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0
Sink ID

Additional properties are NOT allowed.
Additional properties are allowed.
object
uid: ConfigPipelineCreated
type
required
string
Const:"pipeline"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0
Pipeline ID

object
array<object>
non-empty
Sequence of processing elements

name
required
string
The name of the element.

object
Element initialization arguments.

The list of valid parameters are available from the params schema defined by the element. Only arguments with a corresponding defined parameter will be passed to the element.

Additional properties are allowed.
object
A mapping from Source IDs to static metadata JSON.

This enables configuring different static metadata for the Pipeline based on the Source. The static metadata is served for the Channel produced from the Source and Pipeline. The keys of this object are Source IDs and the values are arbitrary JSON objects. Multiple Source IDs may be included in each key by separating them with commas.

If this property is omitted, then an empty JSON object is used by default for unspecified sources. Using an empty string key in this mapping allows overriding the default JSON object.

oneOf
Adheres to:
restricted any
must match: ^(\d+,?)+$
Or to:
string
Allowed values:
""
object
A Pipeline element configuration used for the input source(s).

x-additionalPropertiesName
source-id
Additional properties are allowed.
usecase
string
The high-level description of the analytics performed by the pipeline.

array<integer>
IDs of input sources to the pipeline

Items:
integer
format: int32>= 0uid: id
Source ID

array<integer>
IDs of output sinks from the pipeline

Items:
integer
format: int32>= 0
Sink ID

Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ConfigPipelineUpdated
type
required
string
Const:"pipeline"
action
required
string
Const:"updated"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Pipeline ID

object
array<object>
non-empty
Sequence of processing elements

name
required
string
The name of the element.

object
Element initialization arguments.

The list of valid parameters are available from the params schema defined by the element. Only arguments with a corresponding defined parameter will be passed to the element.

Additional properties are allowed.
object
A mapping from Source IDs to static metadata JSON.

This enables configuring different static metadata for the Pipeline based on the Source. The static metadata is served for the Channel produced from the Source and Pipeline. The keys of this object are Source IDs and the values are arbitrary JSON objects. Multiple Source IDs may be included in each key by separating them with commas.

If this property is omitted, then an empty JSON object is used by default for unspecified sources. Using an empty string key in this mapping allows overriding the default JSON object.

oneOf
Adheres to:
restricted any
must match: ^(\d+,?)+$
Or to:
string
Allowed values:
""
object
A Pipeline element configuration used for the input source(s).

x-additionalPropertiesName
source-id
Additional properties are allowed.
usecase
string
The high-level description of the analytics performed by the pipeline.

array<integer>
IDs of input sources to the pipeline

Items:
integer
format: int32>= 0uid: id
Source ID

array<integer>
IDs of output sinks from the pipeline

Items:
integer
format: int32>= 0
Sink ID

Additional properties are allowed.
And with:
restricted any
>= 2 properties
Additional properties are allowed.
object
uid: ConfigPipelineStats
type
required
string
Const:"pipeline"
action
required
string
Const:"stats"
required
allOf
restricted any
id
required
integer
format: int32>= 0
Pipeline ID

object
status
required
string
Status codes for programmatic use:

"starting": Pipeline is starting up

"ready": Pipeline has started up and is ready to process data

"running": Pipeline has started up and is actively processing data

"stalled": Pipeline has become unresponsive for an unknown reason

"error": An error has occurred within the Pipeline

Allowed values:
"starting"
"ready"
"running"
"stalled"
"error"
code
string
Error code for programmatic error handling:

"unknown": Unidentified error

Allowed values:
"unknown"
reason
string
Error reason string for debugging purposes only

fps
required
number
format: float>= 0
The processing frame rate of the Pipeline (measured in frames per second)

latency
required
number
format: float>= 0
The processing latency of the Pipeline (measured in milliseconds)

Additional properties are allowed.
Additional properties are allowed.
object
uid: ConfigPipelineDeleted
type
required
string
Const:"pipeline"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0
Pipeline ID

Additional properties are NOT allowed.
Additional properties are allowed.
#3Exports notification subscriptionExportsNotificationSubscription
Subscribe or unsubscribe from events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: ExportsNotificationType
Allowed values:
"channel"
"stream"
Additional properties are NOT allowed.
#4Exports notificationExportsNotification
Exports changed notification
oneOf
object
uid: ExportsChannelCreated
type
required
string
Const:"channel"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0uid: id
Channel ID

object
source
integer
format: int32>= 0uid: id
Source ID

pipeline
integer
format: int32>= 0
Pipeline ID

oneOf
Adheres to:
integer
format: int32>= 0
Local Stream Reference (Stream ID)

object
Remote Stream Reference (Stream ID + Remote Host)

id
required
integer
format: int32>= 0uid: id
Stream ID

hostname
required
string
format: hostname
Hostname of the remote Nimble instance.

port
integer
[ 1 .. 65535 ]
Port number of the remote Nimble instance.

Default value:6344
Additional properties are NOT allowed.
Or to:
null
Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ExportsChannelDeleted
type
required
string
Const:"channel"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0uid: id
Channel ID

Additional properties are allowed.
Additional properties are allowed.
object
uid: ExportsStreamCreated
type
required
string
Const:"stream"
action
required
string
Const:"created"
required
allOf
restricted any
id
integer
format: int32>= 0uid: id
Stream ID

object
array<integer>
non-empty
Items:
integer
format: int32>= 0uid: id
Source ID

Additional properties are allowed.
And with:
restricted any
Additional properties are allowed.
object
uid: ExportsStreamDeleted
type
required
string
Const:"stream"
action
required
string
Const:"deleted"
required
object
id
required
integer
format: int32>= 0uid: id
Stream ID

Additional properties are allowed.
Additional properties are allowed.
#5Channels subscriptionChannelsSubscription
Specify which Channels to subscribe to.
oneOf
Adheres to:
boolean
The subscription state for all events.

array<integer>
The Channels to subscribe to.

Items:
integer
format: int32>= 0uid: id
Channel ID
#6Channel notification subscriptionChannelNotificationSubscription
Subscribe or unsubscribe from Channel events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: ChannelNotificationType
Allowed values:
"fps"
"latency"
Additional properties are NOT allowed.
#7Channel notificationChannelNotification
Channel statistic changed notification.
oneOf
uid: ChannelNotifications
object
uid: ChannelFPS
The processing frame rate of the channel

type
required
string
Const:"fps"
value
required
number
format: float>= 0
The processing frame rate of the channel (measured in frames per second)

Additional properties are allowed.
object
uid: ChannelLatency
The processing latency of the channel

type
required
string
Const:"latency"
value
required
number
format: float>= 0
The processing latency of the channel (measured in milliseconds)

Additional properties are allowed.
#8Channel notification with IDChannelNotificationWithID
Channel statistics changed notification.
allOf
restricted any
id
required
integer
format: int32>= 0uid: id
Channel ID

oneOf
uid: ChannelNotifications
object
uid: ChannelFPS
The processing frame rate of the channel

type
required
string
Const:"fps"
value
required
number
format: float>= 0
The processing frame rate of the channel (measured in frames per second)

Additional properties are allowed.
object
uid: ChannelLatency
The processing latency of the channel

type
required
string
Const:"latency"
value
required
number
format: float>= 0
The processing latency of the channel (measured in milliseconds)

Additional properties are allowed.
#9Channel metadataChannelMetadata
Metadata for a frame of video extracted by the inferencing Channel.
oneOf
uid: ChannelMultipart
tuple<object, ...optional<string>>
[ 1 .. 2 ] items
Multi-part metadata message without timestamp.

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

tuple<object, number, ...optional<string>>
[ 2 .. 3 ] items
Multi-part metadata message with timestamp.
This message format is used when the stream property of the channel is non-null.

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
2 item:
number
format: doubleuid: ChannelMetadataTimestamp
Media presentation timestamp (PTS)

Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

Or to:
string
format: bytemedia type: application/x-protobufencoding: binary
A binary message encoded with Protobuf v3 (proto3) according to the ChannelMultipart message type: channel_multipart.proto
#10Channel metadata with IDChannelMetadataWithID
Metadata for a frame of video extracted by the inferencing Channel.
oneOf
uid: ChannelMultipartWithID
tuple<integer, object, ...optional<string>>
[ 2 .. 3 ] items
Multi-part metadata message without timestamp.

1 item:
integer
format: int32>= 0uid: id
Channel ID

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

tuple<integer, object, number, ...optional<string>>
[ 3 .. 4 ] items
Multi-part metadata message with timestamp.
This message format is used when the stream property of the channel is non-null.

1 item:
integer
format: int32>= 0uid: id
Channel ID

object
JSON per-frame metadata (based on configured use-case).

Important: Any position or size in the metadata is normalized from 0 to 1 relative to the dimensions of the video frame. 0,0 indicates top-left. For example, if the video dimensions are 1920x1080 pixels, then 0.5,0.2 encodes the position 960,216 in pixels. This allows the video to be transformed without requiring the metadata to be parsed and transformed too.

Additional properties are allowed.
3 item:
number
format: doubleuid: ChannelMetadataTimestamp
Media presentation timestamp (PTS)

Additional items:
string
format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg
Optional Jpeg image

Or to:
string
format: bytemedia type: application/x-protobufencoding: binary
A binary message encoded with Protobuf v3 (proto3) according to the ChannelMultipartWithId message type: channel_multipart.proto
#11Stream statusStreamStatus
Stream status indication.
- text/plain
oneOf
Adheres to:
string
uid: StreamReset
Indicates the video has reached end-of-stream and is restarting.

Const:"reset"
#12Stream dataStreamData
Fragmented MP4 video Stream data.
- video/mp4
Payload
string
format: binary
#13Global statistics notification subscriptionStatsNotificationSubscription
Subscribe or unsubscribe from events.
oneOf
Adheres to:
boolean
The subscription state for all events.

object
non-empty
A subscription change request.

(pattern property)
boolean
Property names must adhere to:
string
uid: StatsType
Allowed values:
"uptime"
"cpu"
"memory"
"network"
"activated"
Additional properties are NOT allowed.
#14Global stats notificationStatsNotification
Global statistics changed notification.
oneOf
object
uid: StatUptime
The uptime (in seconds) since Nimble started

type
required
string
Const:"uptime"
value
required
number
format: float>= 0
The uptime (in seconds) since Nimble started

Additional properties are allowed.
object
uid: StatCPU
The CPU load (measured in CPU threads utilized)

type
required
string
Const:"cpu"
value
required
number
format: float>= 0
CPU utilization (measured in CPU threads)

Additional properties are allowed.
object
uid: StatMemory
The amount of memory used (measured in bytes)

type
required
string
Const:"memory"
required
object
Amount of virtual and physical memory used (measured in bytes)

virtual
required
integer
format: int64>= 0
Amount of virtual memory used (measured in bytes)

physical
required
integer
format: int64>= 0
Amount of resident physical memory used (measured in bytes)

total
required
integer
format: int64>= 0
Amount of total physical memory (measured in bytes)

available
required
integer
format: int64>= 0
Amount of available physical memory (measured in bytes)

Additional properties are allowed.
Additional properties are allowed.
object
uid: StatNetwork
The amount of network used (measured in bytes/sec)

type
required
string
Const:"network"
required
object
The amount of network used (measured in bytes/sec)

send
required
integer
format: int64>= 0
Amount of tx network used (measured in bytes/sec)

receive
required
integer
format: int64>= 0
Amount of rx network used (measured in bytes/sec)

congestion
required
boolean
Whether tx network is congested

Additional properties are allowed.
Additional properties are allowed.
object
uid: StatActivated
The activation status

type
required
string
Const:"activated"
value
required
boolean
Whether Nimble is activated or not.

Additional properties are allowed.

The Key Elements of Nimble

WebSocket topics

Operations

CONF /v1/config/notify

Examples

#1 Example

#2 Example

#3 Example

#4 Example

SUB /v1/config/notify

Examples

#1 Example

#2 Example

#3 Example

#4 Example

#5 Example

#6 Example

#7 Example

#8 Example

#9 Example

#10 Example

#11 Example

#12 Example

CONF /v1/config/source/{id}/publish

Examples

This example has been generated automatically.

CONF /v1/exports/notify

Examples

#1 Example

#2 Example

#3 Example

#4 Example

SUB /v1/exports/notify

Examples

#1 Example

#2 Example

#3 Example

#4 Example

CONF /v1/exports/channels/metadata

Examples

#1 Example

#2 Example

#3 Example

SUB /v1/exports/channels/metadata

Examples

This example has been generated automatically.

CONF /v1/exports/channels/notify

Examples

#1 Example

#2 Example

#3 Example

SUB /v1/exports/channels/notify

Examples

#1 Example

#2 Example

CONF /v1/exports/channel/{id}/metadata

Examples

#1 Example

#2 Example

#3 Example

#4 Example

#5 Example

SUB /v1/exports/channel/{id}/metadata

Examples

This example has been generated automatically.

CONF /v1/exports/channel/{id}/notify

Examples

#1 Example

#2 Example

#3 Example

#4 Example

SUB /v1/exports/channel/{id}/notify

Examples

#1 Example

#2 Example

SUB /v1/exports/stream/{id}

Examples

#1 Example

Examples

This example has been generated automatically.