srcomp-live

A bridge between the SRComp REST API and OSC controlled devices. OSC is a de-facto standard for theatrical automation. Being able to directly interface these to SR's automation software allows for using industry standard tools such as Qlab, MagicQ & OBS.

Installation

srcomp-live can be installed directly from PyPi with:

pip install srcomp-live

If you (wrongly) believe that YAML is a better configuration format, support for YAML files can be included by running:

pip install srcomp-live[yaml]

This will provide the srcomp-live command that is used to interact with the package.

Configuration

Here is an example configuration file that sets a theoretical lighting controller to red 10 seconds before the start of a match and white if the match ends unexpectedly.

{
    "api_url": "http://compbox.srobo/comp-api/current",
    "api_type": "srcomp",
    "devices": {
        "lighting": "192.168.0.2:8000"
    },
    "actions": [
        {
            "time": -10,
            "device": "lighting",
            "message": "/set_color/{match_num}",
            "args": ["#FF0000"],
            "description": "Set the color of the lighting to red"
        }
    ],
    "abort_actions": [
        {
            "device": "lighting",
            "message": "/set_color",
            "args": ["#FFFFFF"],
            "description": "Set the color of the lighting to white"
        }
    ],
    "match_slot_lengths": {
        "pre": 60,
        "match": 150,
        "post": 90
    }
}

The configuration contains a number of sections. The api_url key is the URL of the API endpoint to access to get information about the current match. The api_type key is the type of API to use. Supported values are "srcomp", "livecomp", "srcomp_compensated", and "livecomp_compensated"

The devices section contains a list of devices that can be controlled by the system. Each device is given a name and an address to send OSC messages to. The name is used in the actions and abort_actions sections to specify which device to send the action to.

The actions section contains a list of the actions that will be executed within the match. The keys available in each action are listed below.

The abort_actions section has the same set of keys as the actions section, except for the time key. These actions are all executed if the system detects a match unexpectedly end or the time within a match decrease. This can be used to stop sound effects and set lighting to an out of match state when match is delayed.

The match_slot_lengths section contains the lengths of the different sections of a match slot in seconds. These are used to validate that the actions fall within the match slot and to allow test-mode to correctly simulate the match.

Templating

The active match number can be included in the OSC message or arguments by using the {match_num} template. This will be replaced with the current match number when the action is executed.

To allow templating the match number into integer and float arguments, the template string {<match_num:int>} or {<match_num:float>} can be used. This will be replaced with the current match number when the action is executed, but as a number rather than a string.

Running

Once the configuration file has been created, there are a few tools available to test this configuration. To try out the configuration, you can use the command:

srcomp-live --test-mode <config>

This will run the configuration in test mode, where the actions will be executed as if they were being run during a match, without needing to connect to the SRComp API.

If you want to test the abort actions, you can use the command:

srcomp-live --test-abort <config>

This will run all the configured abort actions, and then exit.

To run the configuration, where the actions will be executed based on the current match state, you can use the command:

srcomp-live <config>

When running in normal mode, the program will continue to run until it is stopped with Ctrl+C.

While running, the program will log messages to the console. These messages will include a message a few seconds before each action is performed and a message when the action is run. If the program detects that a match has unexpectedly ended or the time has gone backwards, it will log a warning message.

Useful cues

See also:

• QLab OSC documentation
• MagicQ OSC documentation