Viz Arc User Guide

Viz Arc Rest Service provides a Web API that allows you to trigger specific actions or control the Playlist.

The samples below assume that you have installed Viz Arc REST Service and that it's running on localhost and the REST Web API is configured to run on port 9004. The REST Web API port can be configured in the General Settings, under the Communication section.

A Swagger webapp that describes every API can be found at http://localhost:9004/swagger/.

This section contains the following examples:

Info: The samples below use curl command line tools to demonstrate usage and python to beautify the returned JSON output. Note that these tools are not required for the Web API to function correctly.

DataMap

You can set, read and delete DataMap variables through the Web API.

GET /api/v1/DataMap

Gets the list of all the key-value pairs.

curl -s -X GET http://localhost:9004/api/v1/DataMap | python -m json.tool

[
    {
        "key": "Hello",
        "value": "World!"
    },
    {
        "key": "WhiteListIPRanges",
        "value": "0.0.0.0/0"
    }
]

GET /api/v1/DataMap/{key}

Gets the key-value pair identified by the specified key.

curl -s -X GET http://localhost:9004/api/v1/DataMap/key | python -m json.tool

{
    "key": "Hello",
    "value": "World!"
}

POST /api/v1/DataMap

Adds a new key-value pair or an array of them to the DataMap. The payload must be sent as JSON body. If the key already exists the value is updated.

curl -s -H 'Content-Type: application/json' -d "{ 'Key': 'Hello', 'Value': 'World!' }" -X POST http://localhost:9004/api/v1/DataMap

{ 
    "Key": "key", 
    "Value": "hello"
}

DELETE /api/v1/DataMap/{key}

Delete a key/value pair by sending a DELETE message. For example, to delete "key2" use:

curl -s -X DELETE http://localhost:9004/api/v1/DataMap/key2 | python -m json.tool

200 OK

Executer

The Executer endpoints allows you to execute a specific action either by using its name or its ID.

POST api/v1/Executer

Executes the selected action. In order to identify a specific action, the user must specify the actionId, the projectId, the profileId and the executionType.

curl -s -H 'Content-Type: application/json' -d "{ 'actionId': 'a45dbfda-d197-49ff-9995-66d3c319e1fc', 'projectId': 'gh:Sunday_Elections', 'profileId': 'Profile-1', 'executionType': 'EXECUTE' }" -X POST http://localhost:9004/api/v1/Executer

200 OK

Projects

The Projects endpoint allows you to get a list of all available projects and to load a project.

Info: Viz Arc can store and read projects from two different locations: the Graphic Hub or the local file system. In order to distinguish the source of the project, the project's name is prefixed by the keywords "gh:" or "local:" (e.g. "gh:sunday_elections" or "local:sunday_elections").

Likewise, the "location" property in the responses, indicates whether the project resides on Graphic Hub (value "1") or on the file system (value "0").

GET api/v1/projects

Returns a list of all available Projects, first the projects located on the Graphic Hub, then the ones on the file system.

curl -s -X GET http://localhost:9004/api/v1/Projects | python -m json.tool

[
    {
        "name": "gh:Animations",
        "lastModified": "2023-05-09T13:53:32.4633996+00:00",
        "location": 1,
        "profileIndex": 0,
        "tabs": []
    },
    {
        "name": "local:Skating",
        "lastModified": "2023-05-11T07:53:51.80198+00:00",
        "location": 0,
        "profileIndex": 0,
        "tabs": []
    }
]

In the example above, two projects were found.

The name of the project is prefixed by the keywords "gh:" or "local:"; this prefix indicates whether the project is stored in the Graphic Hub or on the file system.

GET api/v1/projects/{id}

Returns the project with the specified id, if it exists. If two projects with the same name exist in the GH and the local disk, the one of the local disk will be returned first.

curl -s -X GET http://localhost:9004/api/v1/Projects/Animations | python -m json.tool

{
    "name": "gh:Animations",
    "lastModified": "2023-05-09T13:53:32.4633996+00:00",
    "location": 1,
    "profileIndex": 0,
    "tabs": []
}

Profiles

The Profiles endpoint allows you to retrieve information about the available Profiles, Channels and Engines.

GET /api/v1/profiles

Returns the entire list of profiles available in Viz Arc.

curl -s -X GET http://localhost:9004/api/v1/profiles | python -m json.tool

[
    {
        "name": "Local",
        "channels": [
            {
                "name": "Local",
                "type": 1,
                "engines": [
                    {
                        "name": "localhost"
                    }
                ],
                "model": {
                    "engineConfigTuple": [
                        {
                            "item1": {
                                "name": "localhost",
                                "ipAddress": "127.0.0.1",
                                "port": 6100,
                                "launcherPort": 5644,
                                "webInterfacePort": 30010,
                                "webSocketPort": 30020,
                                ...

GET api/v1/profiles/{id | name}

Returns the profile specified by the id or name.

curl -s -X GET http://localhost:9004/api/v1/profiles/0 | python -m json.tool

{
    "name": "Local",
    "channels": [
        {
            "name": "Local",
            "type": 1,
            "engines": [
                {
                    "name": "localhost"
                }
            ],
            "model": {
                "engineConfigTuple": [
                    {
                        "item1": {
                            "name": "localhost",
                            "ipAddress": "127.0.0.1",
                            "port": 6100,
                            "launcherPort": 5644,
                            "webInterfacePort": 30010,
                            "webSocketPort": 30020,
                            ...

Web Application Sample Usage

Once the Viz Arc REST service is installed, it also hosts a Web Application that uses some of the APIs described above.

By selecting a Project and a Profile, we can see the Project's structure. By clicking on an action, Viz Arc REST Service executes it.

Keyer

The Keyer Enpoint is intended to be used to control the currently loaded precision keyer on a given output channel, through the external Loupedeck device. It allows to select a channel, restore a temporary preset and to restore the original action. It is intended to be used together with the Executer endpoint.

select

POST api/v1/Keyer/select

Selects the active keyer on a given channel (profileId and the channel must be specified on the POST call). When the parameter execute is true (its default value), the action is executed as well, thus sending the keyer values on the engine.

curl -s -H 'Content-Type: application/json' -d "{ 'profileId': 'Profile-1', 'channel' : 'cam1', 'execute' : false }" -X POST http://localhost:9004/api/v1/Keyer/select

When a Loupedeck device is connected, it shows the current keyer values of the selected channel.

{
  "profileId" : "Profile-1",
  "channel" : "cam1",
  "execute" : false
}

Select the last loaded keyer that was executed on Profile-1, on channel cam1. If case no action has been previously loaded through the Executer endpoint, this call returns with BadRequest.

save

The save endpoint allows to save a temporary keyer setting on the REST server. Please note that the temporary settings are going to be lost after a REST server restart. The temporary settings are associated to the profile and channel, so each combination of profile and channel can potentially have one temporary “preset”.

curl -s -H 'Content-Type: application/json' -d "{ 'profileId': 'Profile-1', 'channel' : 'cam1' }" -X POST http://localhost:9004/api/v1/Keyer/save

{
  "profileId" : "Profile-1",
  "channel" : "cam1",
}

Makes a copy of the current keyer loaded on profile Profile-1 and channel cam1. It is stored as a temporary preset and can be recalled through the restoreTemp preset.

restoreTemp

Restores the previously stored keyer preset, loads it on the respective output engine and loads it on the external control device (for example, Loupedeck).

curl -s -H 'Content-Type: application/json' -d "{ 'profileId': 'Profile-1', 'channel' : 'cam1' }" -X POST http://localhost:9004/api/v1/Keyer/restorePreset

{
  "profileId" : "Profile-1",
  "channel" : "cam1",
}

Restores the temporarily saved keyer preset loaded on profile Profile-1 and channel cam1.

restoreOriginal

Restores the original keyer preset, loads it on the respective output engine, and loads it on the external control device (for example, Loupedeck). The original preset is the action that was executed via the Executer endpoint.

curl -s -H 'Content-Type: application/json' -d "{ 'profileId': 'Profile-1', 'channel' : 'cam1' }" -X POST http://localhost:9004/api/v1/Keyer/restorePreset

{
  "profileId" : "Profile-1",
  "channel" : "cam1",
}

Restores the original keyer preset loaded on profile Profile-1 and channel cam1.

status

Returns the status of the currently loaded keyer. It returns whether the keyer has been modified compared to the original keyer that was executed through the Executer endpoint.

curl -s -H 'Content-Type: application/json' -d "{ 'profileId': 'Profile-1', 'channel' : 'cam1' }" -X POST http://localhost:9004/api/v1/Keyer/status

{
  "profileId" : "Profile-1",
  "channel" : "cam1",
}

Checks the status of the keyer preset loaded on profile Profile-1 and channel cam1. The response to the request looks as follows:

 {
    success = true,
    reason = "",
    modified = true,
}

success is true when a comparison was able to be processed.
reason is empty on success, otherwise it contains an error message.
modified is true when the current keyer settings are different from the original keyer settings.