VIRGO sends a status message to VIRGA every couple seconds. The body of the status message lists all active feeds by feed name and it lists the current state of every feed. The purpose of this message is to keep the VIRGA server up-to-date about the current state of all active feeds. (e.g. whether the feed went offline because of an error)
Keep feed names short. A feed name is used as a simple and short handle to identify a feed in the context of the COP protocol. Feed name do not need to be globally unique; they only need to be unique with respect to a single VIRGO instance.
A feed name is NOT:
Feed names should be at most be 16 characters in length.
VIRGO posts a status message via an HTTP POST request. The body of the message looks like this:
{
"mod-date": "656756" // [required][epoch time] the modification date of the currently active virgo state
"version": "1.0.0" // [required][semantic version] the semantic version number of the currently active virgo instance
"capabilities": { // [optional] Specifies the capabilities of the client. If this is not specified then the default values are used.
"config": "true" // [optional][bool][default=true] Indicates whether configuration of this client is allowed. If not present the default value is used.
"capture": "true", // [optional][bool][default=true] Indicates whether viewing of streams from this client is allowed. If not present the default value is used.
}
// The most recent COP-HTTP error
"error": { // [optional][dictionary] only present if the previous COP configuration request had a syntax or semantic error
"code": <int: error code>
"message": <string: error message>
}
// The per-feed state.
"feeds": {
"camera_1": {
"status": "ok", // [required][string] this feed is up and running
"pid": 56757, // [optional] the PID of the feed daemon if the daemon is running; missing otherwise
"start-date": "...", // [optional][epoch time] the date & time when the feed was most recently enabled (not updated if the feed is restarted because of an error)
"p-time": 68767, // [optional][milliseconds] how much time the feed has spent on processing the video stream in terms of milliseconds
"capturing" : true, // [optional][boolean][default=false] indicates whether the stream is currently depositing frames to its capture deposit url.
"statistics": { // [optional][dictionary] only present if feed statistics is enabled (see chapter "Feed Statistics" below
...
}
},
"camera_2": {
"status": "error", // [required][string] This feed has encountered an error and virgod is retrying
"error": { // [optional][dictionary] only present if the feed status is "error" or "failed"
"code": <int: error code>,
"message": <string: error message>,
"retry-count": <int: number of retries>
}
}
}
}
A VIRGO feed is always in one of the following states:
Feed status | Has statistics | Has start date | Has p time | Has error | Description |
---|---|---|---|---|---|
prerolling | no | yes | yes | yes | The feed is in the process of starting up, connecting to the video source, and priming the video decoder. Note that the feed dictionary may contain an error dictionary if an error was encountered while prerolling. The feed automatically retries in this case. |
ok | yes | yes | yes | no | The feed is up and running without problems. VIRGO is able to receive a video stream from the feed URL, it is able to decode it, and it is able to run face detection and face recognition on it. |
error | no | yes | yes | yes | The feed has encountered an error while processing the video stream. VIRGO expects that it will be able to recover from this error without user intervention. (e.g. a temporary resource shortage or an unexpected crash of the feed daemon) The feed dictionary contains an additional error dictionary with the error code, error message, and retry count. |
failed | no | yes | yes | yes | The feed has encountered a fatal error and VIRGO is unable to recover from it without the help of the user. User intervention is required to fix the problem. E.g. the feed is a video file and the file was not found. The feed dictionary contains an additional error dictionary with the error code and error message. |
eos | yes | yes | yes | no | The feed has encountered an end-of-stream condition. For example, the feed URL might point to a video file and the whole video file has been processed. The feed will remain in the end-of-stream state until it is deactivated or until it is updated with a new feed URL and the state “active”: true. Note that the statistical information in this state represents the last know statistics. (e.g. the final statistics at the end of a video file) |
inactive | no | no | no | no | The feed is currently disabled. A disabled feed exists but does not process the incoming video stream. |
The following HTTP custom headers are included with every status message request:
Header | Description |
---|---|
X-CLIENT-ID | The client id of the virgod instance. This is immutable, factory configured, unique and descriptive vrgo instance identifier. For example: VRGO-LNX-TRPR-16-123 |
X-CLIENT-TYPE | The type of the client. This is a combination of the client name and the platform name. For example: Virgo-Linux |
A feed dictionary contains an error dictionary if the feed has encountered an error. Most errors are recoverable and virgod automatically retries the feed. A few errors are fatal and require action by the user to make the feed work again. The following table lists the available information in an error dictionary:
Proprtyy | Type | Description |
---|---|---|
code | Int | The error code. |
message | String | The error message. |
retry-count | Int? | Exists only if virgod has retried the operation. The number of retries. |
The status request may include per-feed statistics in the form of a statistics dictionary. Delivery of feed statistics is enabled by setting the “statistics.enabled” key in the feed state dictionary to “true”. The following table lists the available statistics and what information it represents:
Property | Type | Description |
---|---|---|
w | Int? | The width of a video frame in pixels. This value is sent after the resolution of the input stream has become available. |
h | Int? | The height of a video frame in pixels. This value is sent after the resolution of the input stream has become available. |
fps | Float? | The nominal frame rate of the source video. This is the frame rate at which the video should be played back, not the rate at which frames are being processed. This value is sent after the frame rate of the input stream has become available. |
cpu.usage | Float? | The amount of CPU time (user + system) that the feed is using. This is a percentage value in the range 0…1. This value is only sent while the feed is actively processing the input stream. |
gpu.usage | Float? | The amount of GPU processing power used by the feed. This is a percentage value in the range 0…1. The entry only exists if the feed is using a GPU. |
gpu.uses | String? | A string which indicates which modules in the feed are using the GPU: V → video decoder F → face detector B → badge detector O → object detector empty/non-existing string indicates that the feed is not using the GPU at all. |
gpu.id | Int? | The unique ID of the GPU used by the feed. This entry only exists if the feed is using a GPU. |
gpu.name | String? | The name of the GPU which the feed is using. This entry only exists if the feed is using a GPU. |
detector.dps | Float? | The rate at which detection operations are executed on incoming frames. This effectively represents the rate at which frames are processed. This value is only sent after object detection has started for the input stream. |
detector.latency | Milliseconds? | The time in milliseconds it takes to run a single detection operation. This value is only sent while object detection is active for an input stream. |
recognizer.latency | Milliseconds? | The time in milliseconds it takes to run a single recognition operation. This value is only sent while object recognition is active for an input stream. |
detector.trigger-count | Int | The number of detection operations that have been triggered so far. This value is initially 0. |
detector.badge-count | Int | The number of badges that have been detected. This value is initially 0. |
detector.face-count | Int | The number of faces that have been detected. This value is initially 0. |
detector.error-count | Int | The number of detection operations that have failed for some reason. This value is initially 0. |
detector.skipped-count | Int | The number of detection operations that were skipped because at the time of detection there were no available detectors. This can indicate too much load on the machine. This value is initially 0. |
recognizer.trigger-count | Int | The number of face recognition and reconfirmation operations that have been triggered so far. This value is initially 0. |
recognizer.face-count | Int | The number of faces that have been successfully recognized or reconfirmed. This value is initially 0. |
recognizer.error-count | Int | The number of faces recognition operations that have failed for some reason. This value is initially 0. |
recognizer.skipped-count | Int | The number of recognition operations that were skipped because at the time of recognition there were no available recognizers. This can indicate too much load on the machine. This value is initially 0. |
reporter.event-count | Int? | The number of events that have been reported. Only appears if reporting is turned on. This value is initially 0. |