Introduction

The Avolites web API allows you to remotely control console functions via HTML, providing a way to create custom interfaces with specific layouts and capabilities. For example this could be used to link an Avolites console into an AV integration system, or a simple touch screen control could be created on a tablet for an Avolites console installed in a hotel function room. The API uses HTTP port 4430 to communicate, and returned information is sent using JSON formatted messages.

Developer API

You will find a full listing of all the functions we expose through the API at the link bellow.

Explore the API

Get/set commands

The most basic webAPI commands are Get and Set which are used to read and set properties on the console such as User Settings or configuration settings. “Get” can be sent from the address line of a browser for basic testing. In the examples in these instructions we will use 10.0.0.1 as the IP address of the console; you should change this to the IP address of your console. Obviously you need to have the console connected to the same network and using the same IP range as the computer you are using for testing, so for a console on 10.0.0.1 have your computer on 10.0.0.2 HTTP requests always use port 4430 and start with the path /titan/

Get Property Value

The get request allows you to read the value of a property on the console. For example, to get the current Titan version, enter the following request into a web browser (the string is case sensitive, you need to use the right capital letters). This is a simple way to test that you have working communication with the console.

http://10.0.0.1:4430/titan/get/System/SoftwareVersion

If everything is working the console will respond “14.0” Or to read the current show name: http://10.0.0.1:4430/titan/get/Show/ShowName The console will respond with the current show name "V10 Demo Show"

Set Property Value

To set the value of a property on the console, send a set request in a properly formatted HTTP POST message body. There is not a simple way to do this from a browser, you will need to install a browser extension or send from a script or application. For example the POST message below turns off the display of DMX address in the fixture buttons

POST /titan/set/Fixtures/ShowDmxAddress HTTP/1.1  
Host: 10.0.0.1:4430  
Cache‐Control: no‐cache  
Postman‐Token: 9b09529f‐d694‐7cbc‐0167‐ef60194359d2  
False  

This request would set the “ShowDmxAddress” property to false.

Scripts

Scripts are used to action methods on the console. Scripts use the HTTP GET method, where you pass parameters with the request string using a ?. If there is data to return, it comes back in JSON format, see section 1.4.4 for an explanation of JSON. For example the script “Process” fires an event based on the string and integer you pass to it: http://10.0.0.1:4430/titan/script/Playbacks/Select/Process?string=playback&int=1723 You must put “?” before the parameters, “&” between the parameters and include the type of each parameter.

Script Parameter Types

As well as the basic types Boolean, float, integer and string, some Titan-specific types are provided. You must use the correct capitalisation of the type names as shown in the examples.

Level The level is used to replace an existing value. For example this sets a master level at 50%: http://10.0.0.1:4430/titan/script/Masters/SetMasterLevel?string=playback&int=1&level=0.5&float=1.0&bool=false

Level Delta The level delta adds the specified level to an existing value. This would increase the master level by 50%: http://10.0.0.1:4430/titan/script/Masters/SetMasterLevel?string=playback&int=1&levelDelta=0.5&float=1.0&bool=false

TitanId The TitanId is a system generated number in Titan that can be used to uniquely identify any property in the system. You can obtain the TitanId values from the console using the Handle Request commands shown in the next section. For example this would fire the playback with TitanId 1723, at 50%: http://10.0.0.1:4430/titan/script/Playbacks/FirePlaybackAtLevel?titanId=1723&level=0.5&bool=false

User Number A User Number is a number that is assigned to a property in Titan that can be used for identification purposes. This number is automatically set by the console but can be changed by users. For example to stop a playback with User Number 20: 'http://10.0.0.1:4430/titan/script/Playbacks/KillPlayback?userNumber=20` If you send an invalid request, the console will return an error message which can be helpful to find out where you went wrong. For a successful request the console will return the result, or if there is no result it will return a blank page.

Handle requests

Handle requests are used to obtain information about any programmed handle on the console (fader, button or touch button). This can then be used on the remote device for display to the user or to obtain TitanId values for further use.

Get page handles

Use the syntax handles/{group name}/{page index} Gets all handles on a specified page (page index, starting at 0) in a specified group (group name). For example to get the first page of Colour palette handles (note that capital letters in the group name must match what is set on the console): http://10.0.0.1:4430/titan/handles/Colours/0 The console will return details of the handles which will look something like this (only the first handle is shown here). See the response section below for more information. [{"handleLocation":{"group":"Colours","index":0,"page":0},"prop erties":[{"Key":"lockState","Value":"Unlocked"}],"titanId":5331 ,"type":"paletteHandle","Active":false,"Legend":""}, ...

Get group handles

Use the syntax handles/{group name} Gets handles from all pages of the specified group (group name). For example to get all fixture handles (note capital letters): http://10.0.0.1:4430/titan/handles/Fixtures

Get all handles

Use the syntax titan/handles Gets all handles from all groups – every programmed handle on the console. This could be quite a big response! For example: http://10.0.0.1:4430/titan/handles

Response from handle requests

All get handle requests will return handle information in a JSON format. JSON (JavaScript Object Notation) is a simple syntax for exchanging data. For example this response gives information about a single handle (it has been split into separate lines to make it easier to read, when returned from the console everything is on one line):

[{
"handleLocation":{"group":"Fixtures","index":0,"page":1},  
"properties":[{"Key":"lockState","Value":"Unlocked"}],  
"titanId":1689,  
"type":"fixtureHandle",  
"Active":false,  
"Legend":""  
}]

Providers

The web API commands are organized using Providers, which manage functions and properties - each provider offers different functionality. In this section a couple of common providers have been detailed. The reference section lists all commands for each provider.

Playbacks

The Playbacks provider is responsible for playback functionality and contains functions to fire, record and modify playbacks.

FirePlayBackAtLevel Void FirePlaybackAtLevel(titanId Id, level Level, bool Refire)
Fires a playback with the specified level. This function forces the playback to a level and always loads it if it’s not loaded. If refire is set then it kills it before firing. Parameters: Id – Id of the playback to fire. This can be the titanID or userNumber. Level – the level to set the playback (0.5=50%, 1=100%). Refire – determines if the playback should refire if already loaded Example: http://10.0.0.1:4430/titan/script/Playbacks/FirePlaybackAtLevel?titanId=1684&level=1.0&bool=false
or using a userNumber rather than a titanId http://10.0.0.1:4430/titan/script/Playbacks/FirePlaybackAtLevel?userNumber=100&level=1.0&bool=false

KillPlayback Void KillPlayback(titanId Id)
Kills the specified playback. Parameters: Id – The Id of the playback to delete. Example: http://10.0.0.1:4430/titan/script/Playbacks/KillPlayback?titanId=1684

ToggleLatchPlayback Void ToggleLatchPlayback(titanId Id)
displays the contents of a cue. In the case of a cue list this would result in moving on to the next cue and displaying its contents. Parameters: Id – The playback Id of playback to toggle

Example: http://10.0.0.1:4430/titan/script/Playbacks/ToggleLatchPlayback?titanId=1684

KillAllPlaybacks void KillAllPlaybacks()
Deactivates all playbacks. Example: http://10.0.0.1:4430/titan/script/Playbacks/KillAllPlaybacks

Titan

The Titan Provider manages device connection information. DeviceInfo DeviceInfo is a property of the Titan provider, reporting the current connection status. This lists all connection types and is quite large. Example: http://10.0.0.1:4430/titan/get/Titan/DeviceInfo Returns: Returns the status of all connections to the console in JSON format.