(1.3.0) Cookbook

Collection of (hopefully) useful recipes for making bits of Open Stage Control layouts. Feel free to ask if you need a hand, and add anything to this page that you think isn’t explained well by the Open Stage Control documentation.

1 Sending multiple OSC messages with one button
2 Using image assets
3 Controlling ICE via the ICE API

Sending multiple OSC messages with one button

Create a button and set up as normal, other than the osc section of the inspector.
Set bypass to true in the osc section of the inspector to stop the button sending its default OSC messages.
In the onValue handler, in the scripting section of the editor, use the send function to send as many OSC messages as required.
1. The syntax looks like this: send('<the ip address>:<the port>', '</the/osc/address>', 'all', 'the', 'arguments'); (without < or > brackets)
2. A variable, value is available, which is replaced with the button’s new value.

e.g:

This sends /hello/1 and /hello/2 with the button’s new value as an argument to localhost:9000 whenever the button’s value changes.

Any other JavaScript can be used in this onValue property for basic logic, etc.
Feel free to ask if you’re doing something unusual.

References: https://openstagecontrol.ammd.net/docs/widgets/scripting/ , Two or more osc address on a toggle button

Using image assets

You can use the image widget for this.

For example, to use an image on a button:

Create a panel container widget to group the button and image widgets.
Within the panel, create button and image widgets.
1. Set both of their geometry settings to fill their parent containers, as in the screenshot below.
2. Make sure the button is on top of the image - i.e. above it in the project tree.
3. Style the button as required - it’s probably worth making the button mostly invisible, as in the screenshot below.
Set up the button’s OSC sending/behaviour as required.
Set the image’s value property in the value section of the inspector to the desired image.
1. The simplest way to do this is to convert the image to base64 using this utility: https://www.base64-image.de/. Upload an image, click “copy image”, and paste this into the the value property of the image component.
You should see the image appear after you click out of the value input.
Now clicking the image will actually click the button in front of it and send the required OSC.

Geometry settings

Button styling

You can follow similar steps to use an image elsewhere (without grouping it/creating the button etc.)

If we didn’t do the base64 conversion the image would have to be made accessible to the browser by the service, which is a bit annoying.

Alternate base64 conversion using WSL/bash: (echo "data:image/*;base64," && base64 [image file]) | tr --delete '\n' > a (without square brackets). Copy contents of new file 'a' into value property.

References: https://openstagecontrol.ammd.net/docs/customization/css-tips/, An image on a push button?

Controlling ICE via the ICE API

To interact with the ICE system through its API using OpenStageControl, follow these instructions:

1. API Key Initialisation:

Before you can send or receive any messages through the API, you first need to send a message containing your unique API key.
Locate your ICE API key:
1. Open ICE.
2. Navigate to: Config > Activate.
3. Within the activation window, you'll see your ICE license key.
4. Only send the last two segments of this key.
- For example, if your license key is XXXXXX-XXXXXX-XXXXXX-xxxxxx-09345D-0B7677, you'd send 09345D-0B7677.

2. Setup OpenStageControl Custom Module:

OpenStageControl allows for the creation of custom modules that can automate message sending. To do this:
1. Copy the provided code snippet below
2. Save it in a file named ice.js.
3. Replace the placeholder YOUR-KEY with your actual ICE API key from step 1.
4. Place this file in the directory: C:\igloo\igloo-core-service\open-stage-control\.

module.exports = {

    init: function(){

        // executed once when the server starts
        send('127.0.0.1', 10003, '/apikey?value=YOUR-KEY')

        app.on('sessionOpened', (data, client)=>{

            // executed each time a session is opened
           
            send('127.0.0.1', 10003, '/apikey?value=YOUR-KEY')

        })

    }
}

3. Modify the Configuration File:

Locate the config.json file in C:\igloo\igloo-core-service\.
Modify the file to include the custom-module parameter as shown below
Restart the igloo-core-service from windows services window.

  "openStageControl": {
    "launch": true,
    "port": 802,
    "theme": "C:\\igloo\\igloo-core-service\\open-stage-control\\igloo.css",
    "session": "C:\\igloo\\igloo-core-service\\open-stage-control\\default_session.json",
    "parameters": ["--custom-module", "C:\\igloo\\igloo-core-service\\open-stage-control\\ice.js"]
  },