SPX v.1.1.4 introduced support for API key. The key can be any "secret string" and it must be manually added to the config.json file. An example:
By default the config has an empty string as the value which means "no restrictions", any computer in the network can send API commands to SPX. If the config has any value in the "apikey" setting, this same key must be passed as an URL parameter. An example:
SPX API is useful for example with a Stream Deck or similar physical device. You can create buttons for several things such as
- Loading a named project and rundown
- Navigating up/down the rundown
- Playing/stopping selected items
- Playing/stopping items by ID
- Modifying graphics live while on-screen
- And more...
Also additional software can be created to control SPX graphics by utilizing these API capabilities. These small software controllers or custom user-interfaces are called SPX Extensions.
An example extension project for developers
You can download a zip file that contains an example extension and a template as shown in the below GIF animation. The package has subfolders for templates and plugins so please unzip these to their corresponding folders within the SPX installation folder.
The extension can
- play the graphic into the SPX renderer
- increment a number on-screen
- stop the template
The template comes with two custom functions that can be triggered externally with the help of the SPX control API.
Set the number value directly. If the given parameter is not a number it will be interpreted as zero (0). The below example sets the value to 50.
Modify current value. The parameter can be positive (such as 1) or negative (such as -1). The below increments the value by 10.
These URL's can for example be added to the Stream Deck and counters can be incremented or decremented with dedicated hardware buttons.
A single value is straightforward to pass as a basic string parameter.
Larger collection of values can be sent to the template function by utilizing JSON.stringify() and encodeURI() functions in the extension when sending data to the template via the SPX server's invokeTemplateFunction API endpoint.
The data in the template can be converted back to a JSON object with decodeURI() and JSON.parse() functions for further processing.
Executing functions in SPX Extensions over the API
SPX version 1.2.2 introduced invokeExtensionFunction API-endpoint which uses SPX's internal messaging system to pass commands from API to server and onwards to extensions. This requires the HTML/HEAD of the extension to have the following properties linked from the SPX server:
With this mechanism extensions can be controlled externally (such as using the Stream Deck). The example extension above has a function sendCmd and with parameter increment it will increment the number on screen. This can be executed with the following API endpoint:
A larger collection of values can be sent to the function by utilizing JSON.stringify() and encodeURI() methods to stringify JSON data, see above.