NAV
javascript python

Introduction

Example connection that subscribes to the tracking/state topic:

const WebSocket = require('ws');

const connection = new WebSocket('ws://127.0.0.1:49152');

connection.on('open', () => {
  connection.send(JSON.stringify({
    op: 'subscribe',
    topic: '/api/v1/tracking/state'
  }));
});

connection.on('message', (data) => {
  const message = JSON.parse(data);
  const isTracking = message.msg.is_tracking;
  console.log(`The system is ${isTracking ? '' : 'not '}tracking`);
});
import asyncio
import websockets
import json


async def subscribe_to_tracking():
    uri = "ws://127.0.0.1:49152"
    async with websockets.connect(uri) as websocket:
        await websocket.send(json.dumps({
            "op": "subscribe",
            "topic": "/api/v1/tracking/state"
        }))
        while True:
            message = json.loads(await websocket.recv())
            is_tracking = message['msg']['is_tracking']
            print(f'The system is {"" if is_tracking else "not "}tracking')


asyncio.get_event_loop().run_until_complete(subscribe_to_tracking())

Welcome to the documentation of the Seervision Production API. This documentation gives an overview of the communication mechanism between the client and the Seervision Suite (server).

Communication between the client and the server is performed through websockets. The server accepts requests on port 49152.

The transport mechanism

Example message:

{
  "op": "Example"
}

A message sent through the websocket is, in the base case, a JSON object with a string field called "op".

The op field indicates the type of message that this is. Messages with different values for op may be handled differently.

Optionally, a message can also provide an arbitrary string ID.

Example message with an ID:

{
  "op": "Example",
  "id": "example_id"
}

If an ID is provided with a message to the server, then related response messages will typically contain that ID as well. Log messages caused by this operation will also contain the ID.

Semantically, the ID is not an identifier of the specific message that it is in, but instead is an identifier for an interaction which may consist of a number of operations in back-and-forth messages. Thus, the ID may be used by multiple messages referring to the same transaction.

Authentication

Authentication mechanism is not provided for now, but might be added in the future.

Communication protocol

There are two concepts that allow the client communicate with the server, get updates and request changes.

Services and service calls

Example service call:

{
  "op": "call_service",
  "id": "ross_head/take_control:1",
  "service": "/api/v1/ross_head/take_control"
}

Example of a successful service response:

{
  "op": "service_response",
  "id": "ross_head/take_control:1",
  "service": "/api/v1/ross_head/take_control",
  "values": {
    "success": true
  }
}

Example of a failed service response:

{
  "op": "service_response",
  "id": "ross_head/demand_control:1",
  "service": "/api/v1/ross_head/demand_control",
  "values": "Service /api/v1/ross_head/demand_control does not exist"
}

A service provides a request/reply interface, which the client can utilize to request a one-time information or a simple "one-shot" action. To initiate the request, the client needs to send a message with a "call_service" op field. The server will then respond with a message containing a "service_response" op field, and additional information, specific to the service.

call_service fields are:

Field Required Description
op yes Must be the string "call_service".
service yes A string defining the name of the service. See below for specific services provided by the API.
id no A string identifying the request.
args no An object with arguments for the request. This format of the object depends on the service.

service_response fields are:

Field Required Description
op yes Will be the string "service_response".
service yes The name of the service that was called.
result yes true if server managed to process request successfully, false otherwise.
id no A string identifying the request.
values no If result is true, this field will contain an object with the result of the call, with the structure defined separately for every service. If result is false, values will be a string containing a detailed error message.

Topics and topic subscriptions

Example "subscribe" message:

{
  "op": "subscribe",
  "topic": "/api/v1/tracking/state"
}

Example "unsubscribe" message:

{
  "op": "unsubscribe",
  "topic": "/api/v1/tracking/state"
}

Example topic message:

{
  "op": "publish",
  "topic": "/api/v1/tracking/state",
  "msg": {
    "data": false
  }
}

A topic allows the client to subscribe to a stream of data from the server. This is especially useful when the client wants, for example, to get notified about the system status, e.g. tracking status. All messages in the topic are guaranteed to have the same format which you can find in the documents below.

The client can send a message with op equals to "subscribe" to subscribe to a specific topic and a message with op equal to "unsubscribe" to cancel the subscription. After subscription is initiated, the server will start sending messages of a type specific for this particular topic with "publish" in the op field.

subscribe and unsubscribe fields are:

Field Required Description
op yes Must be either "subscribe" or "unsubscribe" string.
topic yes A string defining the name of the topic. See below for specific services provided by the API.
id no A string identifying the subscription. If it is not provided in the unsubscribe request, all subscriptions will be cancelled. If it is provided, only subscription with the given id will be cancelled.

publish fields are:

Field Required Description
op yes Must be the string "publish".
topic yes A string defining the name of the topic.
msg yes An object with message payload. The structure of this field is specific to topics.

Versioning

API version is defined by the v<major_version>.<minor_version> string, where both major_version and minor_version are numbers. All topics and services are versioned, and have a /api/v<major_version>/ prefix.

It is guaranteed that:

  1. The transport mechanism and communication protocols will not be changed in minor version updates.
  2. The general structure of messages described above will not change in minor version updates.
  3. The messages defined for every topic and every service will not have fields removed in minor version updates. Some fields may, however, be added.

Current version

The current version of the API is v1.6.

Changelog

Date Version Description
Aug 26, 2021 v1.6 Presets are containers
Jul 20, 2021 v1.5 Added tally status.
Jun 30, 2021 v1.4 Added container status topic.
Apr 30, 2021 v1.3 Added container groups.
Apr 20, 2021 v1.2 Added containers, and added deprecation note to presets and shot presets.
Mar 8, 2021 v1.1 Removed tracking and framing presets.
Jun 23, 2020 v1.0 First public API release.

Client libraries

If you would like to implement your own client application, here're a few links to get you started:

Container groups

In the UI of the Seervision Suite Containers can be collected into groups for easier management when there are many containers in the interface. This API provides the means to query these groups.

Service: get container groups

Request message:

This service will return the list of container groups in the order they appear in the UI.

Request to get container groups:

{
  "op": "call_service",
  "service": "/api/v1/container_groups/get_all"
}

This service call doesn't expect any arguments.

Response message:

Response to the "get container groups" request:

{
  "op": "service_response",
  "service": "/api/v1/container_groups/get_all",
  "result": true,
  "values": {
    "container_groups": [{
      "group_id": "6f0c84",
      "group_name": "Group 1",
      "color": "flamingo",
      "container_ids": ["52ac65", "c6fd11"]
    }, {
      "group_id": "7c0849",
      "group_name": "Group 2",
      "color": "roquefort",
      "container_ids": []
    }, {
      "group_id": "",
      "group_name": "",
      "color": "",
      "container_ids": ["995d22"]
    }]
  }
}

The values returned will have the following fields:

Field Required Description
container_groups yes An array of ContainerGroups. It is guaranteed that the groups appear in the same order as they are displayed in the UI. It is guaranteed that a default group will always be there, and that it will be the last in the list.

Topic: get container groups

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/container_groups/updates"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/container_groups/updates"
}

The /api/v1/container_groups/updates topic can be used to subscribe to the changes to the container groups. It will publish a new message whenever a container group is added or deleted, or when the order of containers in one of the groups is updated. Upon subscription, the client will receive one immediate message with the current container groups.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/container_groups/updates",
  "msg": {
    "container_groups": [{
      "group_id": "6f0c84",
      "group_name": "Group 1",
      "color": "flamingo",
      "container_ids": ["52ac65", "c6fd11"]
    }, {
      "group_id": "7c0849",
      "group_name": "Group 2",
      "color": "roquefort",
      "container_ids": []
    }, {
      "group_id": "",
      "group_name": "",
      "color": "",
      "container_ids": ["995d22"]
    }]
  }
}

The fields of the messages in this topic are:

Field Required Description
container_groups yes An array of ContainerGroups. It is guaranteed that the groups appear in the same order as they are displayed in the UI. It is guaranteed that a default group will always be there, and that it will be the last in the list.

Containers

The system is controllable through user defined containers. Each container consists of versatile components, that define the behavior of the container once it is recalled. Among other things, containers allow the user to request the camera move to a specific "pre-set" (pan/tilt/zoom/focus) position, as well as define and recall "pre-sets" of framing shots. This effectively makes containers a replacement for Presets and Shot presets.

This section defines services for creating, deleting, and recalling containers, as well as a topic publishing updates to the containers. Refer to the Seervision user manual for more details about containers and their configurations.

Service: create a container

Request message:

This service will create a container using the current system state as specified by the provided configuration type.

Request to create a Position container:

{
  "op": "call_service",
  "service": "/api/v1/containers/create",
  "args": {
    "name": "New container",
    "configuration_type": "position"
  }
}

Request to create a Shot container:

{
  "op": "call_service",
  "service": "/api/v1/containers/create",
  "args": {
    "name": "",
    "configuration_type": "shot"
  }
}

Request to create an Empty container:

{
  "op": "call_service",
  "service": "/api/v1/containers/create",
  "args": {
    "name": "",
    "configuration_type": "empty"
  }
}

The args field passed with the request must have the following fields:

Field Required Description
name no A string, the name of the container. If not provided or empty, will be generated automatically.
configuration_type yes Container configuration. The following configuration are supported:
  • empty: creates an empty container without any components.
  • position: creates Position container with Preview, Position, Transition and Tracking components. An equivalent of a Preset.
  • shot: creates Shot container with Preview, Position, Transition, Framing and Tracking components. An equivalent of a Shot Preset.

Response message:

Response to the "create a container" request:

{
  "op": "service_response",
  "service": "/api/v1/containers/create",
  "result": true,
  "values": {
    "new_container": {
      "id": "6f0c84",
      "name": "Container 1"
    }
  }
}

The values returned will have the following fields:

Field Required Description
new_container yes A Container object defining the newly created container.

Service: delete a container

This service will delete a container of the given ID. It will not throw if the container with the given ID is missing.

Request message:

Request to delete a container:

{
  "op": "call_service",
  "service": "/api/v1/containers/delete",
  "args": {
    "container_id": "6f0c84"
  }
}

The args passed with this call should have the following structure:

Field Required Description
container_id yes A string identifying the container to be deleted.

Response message:

Response to the "delete a container" request:

{
  "op": "service_response",
  "service": "/api/v1/containers/delete",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Service: get all containers

This service will return all saved containers.

Request message:

Request to get all containers:

{
  "op": "call_service",
  "service": "/api/v1/containers/get_all"
}

This service call doesn't expect any arguments.

Response message:

Response to the "get all containers" request:

{
  "op": "service_response",
  "service": "/api/v1/containers/get_all",
  "result": true,
  "values": {
    "containers": [{
      "id": "f0c846",
      "name": "Container 1"
    }, {
      "id": "a87c21",
      "name": "Main stage"
     }]
  }
}

The values returned will have the following fields:

Field Required Description
containers yes An array of Container elements.

Service: recall a container

This service sends a request to the SV-Suite to recall specific container by its ID.

Request message:

Request to recall a container:

{
  "op": "call_service",
  "service": "/api/v1/containers/recall",
  "args": {
    "container_id": "756064"
  }
}

The service expects the following args structure:

Field Required Description
container_id yes A string identifying the container.

Response message:

Response to the "recall a container" request when container doesn't exist

{
  "op": "service_response",
  "service": "/api/v1/containers/recall",
  "result": false,
  "values": "Container with id \"756064\" does not exist"
}

Response to the successful "recall a container" request:

{
  "op": "service_response",
  "service": "/api/v1/containers/recall",
  "result": true,
  "values": {}
}

The server will return an error message if container does not exist, and an empty message otherwise.

Topic: get containers

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/containers/updates"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/containers/updates"
}

The /api/v1/containers/updates topic can be used to subscribe to changes to the containers. It will publish a new message whenever a container is added, deleted, or updated. Upon subscription, the client will receive one immediate message with the current containers.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/containers/updates",
  "msg": {
    "containers": [{
      "id": "f0c846",
      "name": "Container 1"
    }, {
      "id": "a87c21",
      "name": "Main stage"
    }]
  }
}

The fields of the messages in this topic are:

Field Required Description
containers yes An array of Container elements.

Topic: get container status

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/containers/status"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/containers/status"
}

The /api/v1/containers/status topic can be used to subscribe to notifications about the recall status of containers. Since only one container at a time can be recalled, the message sent through this topic contains information only about the last recalled container.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/containers/status",
  "msg": {
    "container_id": "f0c846",
    "status": "running"
  }
}

The fields of the messages in this topic are:

Field Required Description
container_id yes A string representing the unique container ID.
status yes A string representing the container status. There are four statuses that get reported by this topic:
  • "running": gets triggered when container execution gets started.
  • "completed": gets triggered once a container has successfully been executed.
  • "interrupted": gets triggered if container execution is interrupted by a manual camera movement.
  • "abandoned": gets triggered if container execution is interrupted by an automatic camera action, like another container or a "start tracking" action.

The system guarantees that every running status update is always followed by an abandoned, completed or interrupted status update for the same container.

Endpoints

This section describes the services that allow the user to check availability of other services and topics, provided by the API.

Service: is service available

Request message:

This service accepts service string in a request, and returns true if the service exists, and false otherwise.

Request to check service availability

{
  "op": "call_service",
  "service": "/api/v1/endpoints/is_service_available",
  "args": {
    "service": "/api/v1/tracking/start"
  }
}

The args field passed with the request must have the following fields:

Field Required Description
service yes A string, the service path to check.

Response message:

Response to the "check service availability" request if service exists:

{
  "op": "service_response",
  "service": "/api/v1/endpoints/is_service_available",
  "result": true,
  "values": {
    "is_available": true
  }
}

Response to the "check service availability" request if service does not exist:

{
  "op": "service_response",
  "service": "/api/v1/endpoints/is_service_available",
  "result": true,
  "values": {
    "is_available": false
  }
}

The values returned will have the following fields:

Field Required Description
is_available yes A boolean, true if the service exists, false otherwise.

Service: is topic available

Request message:

This service accepts topic string in a request, and returns true if the topic exists, and false otherwise.

Request to check topic availability

{
  "op": "call_service",
  "service": "/api/v1/endpoints/is_topic_available",
  "args": {
    "topic": "/api/v1/tracking/state"
  }
}

The args field passed with the request must have the following fields:

Field Required Description
topic yes A string, the topic path to check.

Response message:

Response to the "check topic availability" request if topic exists:

{
  "op": "service_response",
  "service": "/api/v1/endpoints/is_topic_available",
  "result": true,
  "values": {
    "is_available": true
  }
}

Response to the "check topic availability" request if topic does not exist:

{
  "op": "service_response",
  "service": "/api/v1/endpoints/is_topic_available",
  "result": true,
  "values": {
    "is_available": false
  }
}

The values returned will have the following fields:

Field Required Description
is_available yes A boolean, true if the topic exists, false otherwise.

Events

The Events API can be used by the consumers to tie specific events when the Seervision Suite detects a specific event. The events currently available through the Production API are tied to the Trigger Zones, but there are more to come in the future versions of the API.

Topic: get events fired by trigger zones

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/events/trigger_zones"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/events/trigger_zones"
}

The /api/v1/events/trigger_zones can be used to get updates from the Seervision Suite when a specific event is fired by a trigger zone. As soon as a trigger zone detects an event, a message will be sent down this topic with event information.

When using the API, keep in mind that: * The events only get sent for enabled trigger zones. * The events get triggered with a delay specified in the zone through the UI. * If an event is superseded by event triggered by another trigger zone with a higher priority, it will not be fired.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/events/trigger_zones",
  "msg": {
    "type": "person_entered",
    "zone_id": "756064a6f0c84610b2e63fea54a87c21"
  }
}

The msg object will have the TriggerZoneEvent type.

Presets

Presets allow the user to request the camera move to a specific "pre-set" (pan/tilt/zoom/focus) position.

This section defines services for creating, deleting, and recalling presets, as well as a topic publishing updates to the presets.

Service: create a preset

Request message:

This service will create a preset at the current camera position of a specified type and transition type.

Request to create a preset:

{
  "op": "call_service",
  "service": "/api/v1/presets/create",
  "args": {
    "name": "New preset",
    "type": "static",
    "transition_type": {
      "type": "speed",
      "speed": 4
    }
  }
}

The args field passed with the request must have the following fields:

Field Required Description
name yes A string, the name of the preset.
type yes Preset type. See Preset object definition for details.
transition_type yes An object of PresetTransitionType

Response message:

Response to the "create a preset" request:

{
  "op": "service_response",
  "service": "/api/v1/presets/create",
  "result": true,
  "values": {
    "new_preset": {
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "New preset",
      "type": "static",
      "transitionType": {
        "type": "speed",
        "speed": 4,
        "time": 0
      }
    }
  }
}

The values returned will have the following fields:

Field Required Description
new_preset yes A Preset object defining the newly created preset.

Service: delete a preset

This service will delete a preset of the given ID. It will not throw if the preset with the given ID is missing.

Request message:

Request to delete a preset:

{
  "op": "call_service",
  "service": "/api/v1/presets/delete",
  "args": {
    "preset_id": "756064a6f0c84610b2e63fea54a87c21"
  }
}

The args passed with this call should have the following structure:

Field Required Description
preset_id yes A string identifying the preset to be deleted.

Response message:

Response to the "delete a preset" request:

{
  "op": "service_response",
  "service": "/api/v1/presets/delete",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Service: get all presets

This service will return all saved presets.

Request message:

Request to get all presets:

{
  "op": "call_service",
  "service": "/api/v1/presets/get_all"
}

This service call doesn't expect any arguments.

Response message:

Response to the "get all presets" request:

{
  "op": "service_response",
  "service": "/api/v1/presets/get_all",
  "result": true,
  "values": {
    "presets": [{
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "New preset",
      "type": "static",
      "transitionType": {
        "type": "speed",
        "speed": 4,
        "time": 0
      }
    }, {
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "Main stage",
      "type": "static",
       "transitionType": {
         "type": "time",
         "speed": 0,
         "time": 5
       }
     }]
  }
}

The values returned will have the following fields:

Field Required Description
presets yes An array of Preset elements.

Service: recall a preset

This service sends a request to the SV-Suite to recall specific preset by its ID.

Request message:

Request to recall a preset:

{
  "op": "call_service",
  "service": "/api/v1/presets/recall",
  "args": {
    "preset_id": "756064a6f0c84610b2e63fea54a87c21"
  }
}

The service expects the following args structure:

Field Required Description
preset_id yes A string identifying the preset.

Response message:

Response to the "recall a preset" request when preset doesn't exist

{
  "op": "service_response",
  "service": "/api/v1/presets/recall",
  "result": false,
  "values": "Preset not found"
}

Response to the successful "recall a preset" request:

{
  "op": "service_response",
  "service": "/api/v1/presets/recall",
  "result": true,
  "values": {}
}

The server will return an error message if preset does not exist, and an empty message otherwise.

Topic: get presets

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/presets/updates"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/presets/updates"
}

The /api/v1/presets/updates topic can be used to subscribe to changes to the presets. It will publish a new message whenever a preset is added, deleted, or renamed. Upon subscription, the client will receive one immediate message with the current presets.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/presets/updates",
  "msg": {
    "presets": [{
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "New preset",
      "type": "static",
      "transitionType": {
        "type": "speed",
        "speed": 4,
        "time": 0
      }
    }, {
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "Main stage",
      "type": "static",
       "transitionType": {
         "type": "time",
         "speed": 0,
         "time": 5
       }
     }]
  }
}

The fields of the messages in this topic are:

Field Required Description
presets yes An array of Preset elements.

PTU control

Some heads (e.g. ROSS) have their own control system for the PTU. Seervision API provides a set of services that allow the client take control from the head and give it back, as well as a topic publishing messages that help the client figure out if Seervision Suite is currently in control.

Service: take control

Request message:

Request to take control:

{
  "op": "call_service",
  "service": "/api/v1/ptu_driver/take_control"
}

This service call doesn't expect any arguments.

Response message:

Response to the "take control" request:

{
  "op": "service_response",
  "service": "/api/v1/ptu_driver/take_control",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Service: release control

Request to release control

{
  "op": "call_service",
  "service": "/api/v1/ptu_driver/release_control"
}

This service call doesn't expect any arguments.

Response message:

Response to the "release control" request:

{
  "op": "service_response",
  "service": "/api/v1/ptu_driver/release_control",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Topic: PTU driver control status

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/ptu_driver/in_control"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/ptu_driver/in_control"
}

A client can subscribe to changes to the control status from the /api/v1/ptu_driver/in_control topic. Upon subscription, the client will receive one immediate message with the current status.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/ptu_driver/in_control",
  "msg": {
    "in_control": false
  }
}

The messages sent through this topic will have the following fields:

Field Required Description
in_control yes true means that Seervision Suite is in control, and false stands for the opposite.

Shot presets

It is possible to create presets of framing shots, which can later be recalled with a single service call. Refer to the Seervision user manual for more details.

This section defines services for creating, deleting, and recalling shot presets, as well as a topic publishing updates.

Service: create a shot preset

This service will create a shot preset using the current zoom level.

Request message:

Request to create a shot preset with shot position in the middle of the frame:

{
  "op": "call_service",
  "service": "/api/v1/shot_presets/create",
  "args": {
    "name": "New shot preset",
    "position": {
      "x": 0.5,
      "y": 0.5
    }
  }
}

args fields of the call are:

Field Required Description
name yes A string to be used as shot name. Its length must be between 0 and 50 characters, inclusive.
position yes A Point2d identifying shot position. For detailed description about this field check ShotPreset object description.

In case name is an empty string, it will be automatically generated instead. This name will be the lowest numeric value that is not used as a name of another shot preset.

Response message:

Response to the "create a shot preset" request:

{
  "op": "service_response",
  "service": "/api/v1/shot_presets/create",
  "result": true,
  "values": {
    "new_preset": {
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "New shot preset",
      "position": {
        "x": 0.5,
        "y": 0.5
      },
      "zoom_level": 4.8
    }
  }
}

The values returned will have the following fields:

Field Required Description
new_preset yes The newly created ShotPreset.

Service: delete a shot preset

This service will delete a shot preset of the given ID.

Request message:

Request to delete a shot preset:

{
  "op": "call_service",
  "service": "/api/v1/shot_presets/delete",
  "args": {
    "preset_id": "756064a6f0c84610b2e63fea54a87c21"
  }
}

args fields of the call are:

Field Required Description
preset_id yes A string identifying the shot to be deleted.

Response message:

Response to the "delete a shot preset" request:

{
  "op": "service_response",
  "service": "/api/v1/shot_presets/delete",
  "result": true,
  "values": {}
}

The server will return an empty message in response if the preset was successfully deleted, or if it wasn't there in the first place.

Service: get all shot presets

This service will return all saved shot presets.

Request message:

Request to get all shot presets:

{
  "op": "call_service",
  "service": "/api/v1/shot_presets/get_all"
}

This service call doesn't expect any arguments.

Response message:

Response to the "get all shot presets" request:

{
  "op": "service_response",
  "service": "/api/v1/shot_presets/get_all",
  "result": true,
  "values": {
    "presets": [{
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "New shot preset",
      "position": {
        "x": 0.5,
        "y": 0.5
      },
      "zoom_level": 4.8
    }, {
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "Full body shot",
      "position": {
        "x": 0.3,
        "y": 0.6
      },
      "zoom_level": 1.7
    }]
  }
}

The values returned will have the following fields:

Field Required Description
presets yes An array of ShotPreset elements.

Service: recall a shot preset

Request message:

Request to recall a shot preset:

{
  "op": "call_service",
  "service": "/api/v1/shot_presets/recall",
  "args": {
    "preset_id": "756064a6f0c84610b2e63fea54a87c21"
  }
}

args fields of the call are:

Field Required Description
preset_id yes A string identifying the shot preset to be recalled.

Response message:

Response to the "recall a preset" request when preset doesn't exist

{
  "op": "service_response",
  "service": "/api/v1/shot_presets/recall",
  "result": false,
  "values": "Preset not found"
}

Response to the "recall a preset" request when Seervision Suite is not in control:

{
  "op": "service_response",
  "service": "/api/v1/shot_presets/recall",
  "result": false,
  "values": "Not in control of the PTU"
}

Response to the successful "recall a preset" request:

{
  "op": "service_response",
  "service": "/api/v1/shot_presets/recall",
  "result": true,
  "values": {}
}

The server will return an error message if preset does not exist, and an empty message otherwise.

Topic: get shot presets updates

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/shot_presets/updates"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/shot_presets/updates"
}

A client can subscribe to the changes in presets from the /api/v1/shot_presets/updates topic. Upon subscription, the client will receive one immediate message with the existing shot presets.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/shot_presets/updates",
  "msg": {
    "presets": [{
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "New shot preset",
      "position": {
        "x": 0.5,
        "y": 0.5
      },
      "zoom_level": 4.8
    }, {
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "Full body shot",
      "position": {
        "x": 0.3,
        "y": 0.6
      },
      "zoom_level": 1.7
    }]
  }
}

The messages sent through this topic will have the following format:

Field Required Description
presets yes An array of ShotPreset elements.

Tally state

This section defines services and topics related to the tally state of the system, i.e. whether the system is currently on program, in preview or none.

Service: get tally status

Request to get the tally state:

{
  "op": "call_service",
  "service": "/api/v1/tally_status/get"
}
Field Required Description
op yes The string "call_service".
id no A string identifying the call.
service yes A "/api/v1/tally_status/get" string.

Response message:

Response to the "get tally state" request:

{
  "op": "service_response",
  "service": "/api/v1/tally_status/get",
  "result": true,
  "values": {
    "status": "preview"
  }
}

The server will return the current status in the response, either "none", "preview" or "program".

Service: set tally status

Request message:

Request to set the tally state:

{
  "op": "call_service",
  "service": "/api/v1/tally_status/set",
  "args": {
    "status": "preview"
  }
}
Field Required Description
op yes The string "call_service".
id no A string identifying the call.
service yes A "/api/v1/tally_status/set" string.
args.status yes Either "none", "preview" or "program".

Response message:

Response to the "set tally state" request:

{
  "op": "service_response",
  "service": "/api/v1/tally_status/set",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Topic: tally status

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/tally_status"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/tally_status"
}

A client can subscribe to changes to the tally status from the /api/v1/tally_status topic. Upon subscription, the client will receive one immediate message with the current status.

Messages on the topic:

{
  "op": "publish",
  "topic": "/api/v1/tally_status",
  "msg": {
    "status": "preview"
  }
}

The server will publish the current status in the messages, either "none", "preview" or "program".

Tracking state

This section defines services and topics related to the tracking state of the system, i.e. whether the system is currently tracking someone or not.

Service: start tracking

Request message:

Request to start tracking:

{
  "op": "call_service",
  "service": "/api/v1/tracking/start",
  "args": {
    "target": "left"
  }
}
Field Required Description
op yes The string "call_service".
id no A string identifying the call.
service yes A "/api/v1/tracking/start" string.
args.target no Specifies tracking target.
  • If not provided, the system will start tracking either the previously tracked person, or, if the previously tracked target is no longer visible (or there was no target at all), the person closest to the middle of the frame.
  • If provided, the system will start tracking the person closest to the point the target specifies.
    • If target is "left", the person closest to the point in the center of the left border of the frame will be tracked.
    • If target is "right", the person closest to the point in the center of the right border of the frame will be tracked.
    • If target is "middle", the person closest to the middle of the frame will be tracked.
    • If target is "point", the target_point argument will be used.
args.target_point yes, if args.target is "point"
  • If args.target is not "point", this field must be omitted.
  • If args.target is "point", this field must be a Point2d identifying position on the stream. Both x and y values must be numbers between 0.1 and 0.9, inclusive. x identifies the horizontal position, and y identifies the vertical one. For example:
    • x = 0.1, y = 0.1: top left corner of the frame.
    • x = 0.1, y = 0.9: bottom left corner of the screen.
    • x = 0.9, y = 0.1: top right corner of the screen.

Response message:

Response to the "start tracking" request:

{
  "op": "service_response",
  "service": "/api/v1/tracking/start",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Service: stop tracking

Request to stop tracking

{
  "op": "call_service",
  "service": "/api/v1/tracking/stop"
}
Field Required Description
op yes The string "call_service".
id no A string identifying the call.
service yes A "/api/v1/tracking/stop" string.

Response message:

Response to the "stop tracking" request:

{
  "op": "service_response",
  "service": "/api/v1/tracking/stop",
  "result": true,
  "values": {}
}

The server will return an empty message in response.

Topic: get tracking state

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/tracking/state"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/tracking/state"
}

A client can subscribe to changes to the tracking state from the /api/v1/tracking/state topic. Upon subscription, the client will receive one immediate message with the current state.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/tracking/state",
  "msg": {
    "is_tracking": false
  }
}

The messages sent through this topic have the following structure:

Field Required Description
is_tracking yes A boolean. true if the system is currently tracking a person, and false otherwise.

Trigger zones

Trigger zones can be defined through the User Interface to trigger specific actions from the system on events fired by the zone. This section describes a service and a method that can be used to retrieve information about the trigger zones defined in the system.

Service: set trigger zone state

Request message:

This service changes the "enabled" state of a single trigger zone.

Request to change status of a single trigger zone:

{
  "op": "call_service",
  "service": "/api/v1/trigger_zones/set_status_of_single_zone",
  "args": {
    "zone_id": "756064a6f0c84610b2e63fea54a87c21",
    "is_enabled": true
  }
}

The args field passed with the request must have the following fields:

Field Required Description
zone_id yes A string, unique ID of the trigger zone that initiated the event.
is_enabled yes A boolean, true if the zone should be enabled, and false otherwise.

Response message:

Response to the "update trigger zone 'enabled' status" request:

{
  "op": "service_response",
  "service": "/api/v1/trigger_zones/set_status_of_single_zone",
  "result": true,
  "values": {}
}

The server will return an empty message in response if the zone was successfully updated.

Service: set state of all trigger zones

Request message:

This service changes the "enabled" state of a single trigger zone.

Request to change status of all trigger zones:

{
  "op": "call_service",
  "service": "/api/v1/trigger_zones/set_status_of_all_zones",
  "args": {
    "is_enabled": true
  }
}

The args field passed with the request must have the following fields:

Field Required Description
is_enabled yes A boolean, true if all trigger zones should be enabled, and false otherwise.

Response message:

Response to the "update trigger zones 'enabled' status" request:

{
  "op": "service_response",
  "service": "/api/v1/trigger_zones/set_status_of_all_zones",
  "result": true,
  "values": {}
}

The server will return an empty message in response if all zones got successfully updated.

Service: get trigger zones

Request message:

This service returns the list of trigger zones in the system.

Request to list trigger zones:

{
  "op": "call_service",
  "service": "/api/v1/trigger_zones/get_all"
}

This service call doesn't expect any arguments.

Response message:

Response to the "get all trigger zones" request:

{
  "op": "service_response",
  "service": "/api/v1/trigger_zones/get_all",
  "result": true,
  "values": {
    "trigger_zones": [{
      "id": "756064a6f0c84610b2e63fea54a87c21",
      "name": "Trigger Zone 1",
      "is_enabled": false
    }, {
      "id": "856064a6f0c84610b2e63fea54a87c21",
      "name": "Trigger Zone 2",
      "is_enabled": true
     }]
  }
}

The values returned will have the following fields:

Field Required Description
trigger_zones yes An array of TriggerZone elements.

Topic: get trigger zones

Message to initiate the subscription:

{
  "op": "subscribe",
  "topic": "/api/v1/trigger_zones/updates"
}

Message to cancel the subscription:

{
  "op": "unsubscribe",
  "topic": "/api/v1/trigger_zones/updates"
}

The /api/v1/trigger_zones/updates topic can be used to subscribe to changes to the trigger zones. It will publish a new message whenever a trigger zone is added, deleted, or renamed. Upon subscription, the client will receive one immediate message with the current trigger zones.

Example topic publication:

{
  "op": "publish",
  "topic": "/api/v1/trigger_zones/updates",
  "msg": {
    "trigger_zones": [
      {
        "id": "756064a6f0c84610b2e63fea54a87c21",
        "name": "Trigger Zone 1",
        "is_enabled": false
      },
      {
        "id": "856064a6f0c84610b2e63fea54a87c21",
        "name": "Trigger Zone 2",
        "is_enabled": true
      }
    ]
  }
}

The fields of the messages in this topic are:

Field Required Description
trigger_zones yes An array of TriggerZone elements.

Common object definitions

This section contains definitions of messages used in topic publications and service responses. Every message is an object with one or more strongly typed fields.

Container

Example of a Container message:

{
  "id": "4a6f0c",
  "name": "Container 1"
}

This object contains information about a container.

Field Required Description
id yes A string representing unique container ID.
name yes A string, the name of the container.

ContainerGroup

Example of a ContainerGroup message for a user-defined group:

{
  "group_id": "7c0849",
  "group_name": "Group 2",
  "color": "roquefort",
  "container_ids": ["995d22"]
}

Example of a ContainerGroup message for a default group:

{
  "group_id": "",
  "group_name": "",
  "color": "",
  "container_ids": ["52ac65"]
}

This object contains information about a container group. The message content differs based on whether it is a user-defined group, or a default group. All containers that appear in the UI as ungrouped belong to the default group.

Field Required Description
group_id yes A string representing unique group ID, or an empty string if it is a default group.
group_name yes A string, the name of the group. This string will be empty for a default group.
color yes A string defining group color. This string will be empty for a default group, or one of the predefined set of strings for a user-defined group.
container_ids yes An array of unique Container IDs belonging to this group. It is guaranteed that the order of the IDs matches the order in which the containers are displayed in the UI.

Point2d

Example of a Point2d message:

{
  "x": 0.5,
  "y": 0.5
}

This message is usually used to describe point position in the 2-dimensional coordinates.

Field Required Description
x yes A 32-bit IEEE float number, x coordinate.
y yes A 32-bit IEEE float number, y coordinate.

Preset

This object contains full information about a preset.

Static preset of the "speed" movement type:

{
  "id": "756064a6f0c84610b2e63fea54a87c21",
  "name": "Main stage",
  "type": "static",
  "transition_type": {
    "type": "speed",
    "speed": 4,
    "time": 0
  }
}

Static preset of the "time" movement type:

{
  "id": "756064a6f0c84610b2e63fea54a87c21",
  "name": "Main stage",
  "type": "static",
  "transition_type": {
    "type": "time",
    "speed": 0,
    "time": 5
  }
}
Field Required Description
id yes A string representing unique preset ID.
name yes A string, the name of the preset.
type no A string defining preset type.
  • Valid values are: an empty string, "static", "framing" or "tracking". They will all create a static preset where a particular state for pan, tilt, zoom and focus is stored.
  • Prior to v1.1, "framing" and "tracking" would create other preset types which are deprecated now. These values are kept for backward compatibility and will no longer be supported in future major versions.
  • Passing any other string as preset type will return an error.
transition_type yes An object of the PresetTransitionType type.

PresetTransitionType

"Speed" transition type example:

{
  "type": "speed",
  "speed": 5,
  "time": 0
}

"Time" transition type example:

{
  "type": "time",
  "speed": 0,
  "time": 5
}

This object defines the type of transition to be used to transition towards the selected preset.

Field Required Description
type yes A string defining type of the transition. The two transition types are:
  • "speed": the angular velocity in degrees/second that will be used to transition to the preset.
  • "time": the time (in seconds) the motion should take when transitioning to the preset.
speed yes, if type is "speed" A number defining the speed that will be used for transition. If transition type is "time", the server will send 0 in this field.
time yes, if type is "time" A floating-point defining the time in seconds of the motion to be used for transition. If transition type is "speed", the server will send 0 in this field.

On the server side, speed and time values will be validated, and might be adjusted to match the limits of the currently selected hardware.

ShotPreset

Example of a ShotPreset message:

{
  "id": "756064a6f0c84610b2e63fea54a87c21",
  "name": "New shot preset",
  "position": {
    "x": 0.5,
    "y": 0.5
  },
  "zoom_level": 4.8
}

This message is used to describe a shot preset.

Field Required Description
id yes A string, unique ID of the shot preset.
name yes A string with shot preset name.
zoom_level yes A number identifying zoom level in field-of-view degrees.
position yes A Point2d identifying shot position. Both x and y values should be numbers between 0.0 and 1.0, inclusive. x identifies the horizontal position of the shot, and y identifies the vertical one. For example:
  • x = 0.0, y = 0.0: top left corner of the frame.
  • x = 0.0, y = 1.0: bottom left corner of the screen.
  • x = 1.0, y = 0.0: top right corner of the screen.

TriggerZone

Example of a TriggerZone message:

{
  "id": "756064a6f0c84610b2e63fea54a87c21",
  "name": "Trigger Zone 1",
  "is_enabled": false
}

This message is used to describe a trigger zone.

Field Required Description
id yes A string, unique ID of the trigger zone.
name yes A string with trigger zone name.
is_enabled yes A boolean indicating whether the zone is enabled or not. When the zone is not enabled, it does not trigger any events.

TriggerZoneEvent

Example of a TriggerZoneEvent message with "person_entered" type:

{
  "zone_id": "756064a6f0c84610b2e63fea54a87c21",
  "type": "person_entered"
}

This message is used to describe an event triggered by a trigger zone.

Field Required Description
zone_id yes A string, unique ID of the trigger zone that initiated the event.
type yes A string identifying event type. Possible values are:
  • person_entered: gets triggered when a VIP enters the zone.
  • person_inside: gets triggered when a VIP stays in the zone for an amount of time, specified by the associated zone.
  • person_left: gets triggered when a VIP leaves the zone.
person_id yes A string identifying the person triggering the event.