Metadata-Version: 2.2
Name: srcomp-live
Version: 1.0.0
Summary: An interposer between the SRComp REST API and OSC controlled devices.
Author: Will Barber
License: MIT License
        
        Copyright (c) 2025 Will Barber
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/WillB97/srcomp-live
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32.3
Requires-Dist: python-osc<2,>=1.8.3
Provides-Extra: dev
Requires-Dist: poethepoet<1,>=0.0.1; extra == "dev"
Requires-Dist: ruff<0.4,>=0.3.0; extra == "dev"
Requires-Dist: mypy==1.9.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6; extra == "dev"
Provides-Extra: yaml
Requires-Dist: PyYAML<7,>=6; extra == "yaml"

# 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:
```bash
pip install srcomp-live
```

If you (wrongly) believe that YAML is a better configuration format, support for YAML files can be included by running:
```bash
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.

```json
{
    "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.

| Key | Description |
| --- | --- |
| time | The relative number of seconds after the start time of the match to execute this action |
| device | The name of the device configured in the `devices` section to send this action to |
| message | The OSC message to send |
| args | A list of one or more arguments to send along with the OSC message |
| description | A description to include in the log message when executing the action |

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:
```bash
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:
```bash
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:
```bash
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

Program | Action | OSC Message
--- | --- | ---
MagicQ | Jump to Cue | `/pb/<playback>/<cue>`
MagicQ | Activate playback | `/pb/<playback>/go`
MagicQ | Release playback | `/pb/<playback>/release`
QLab | Connect to workspace | `[/workspace/<id>]/connect` `<password-string>`
QLab | Run cue | `[/workspace/<id>]/go`
QLab | Run specific cue | `[/workspace/<id>]/go/<cue>`
QLab | Stop cue | `[/workspace/<id>]/stop`
QLab | Immediately stop all cues | `[/workspace/<id>]/hardStop`/`[/workspace/<id>]/panic`
QLab | Jump to cue | `[/workspace/<id>]/select/<cue>`

See also:
- [QLab OSC documentation](https://qlab.app/docs/v5/scripting/osc-dictionary-v5/)
- [MagicQ OSC documentation](https://secure.chamsys.co.uk/help/documentation/magicq/osc.html)
