Custom OSC Command Library

The nice thing about the command library is that each library is written in a simple XML format, allowing each library to be easily edited and created. When Spikemark was installed on your computer, a new folder was added at C:\Users{user}\Documents\Spikemark\OSC Libraries and some starter libraries were added. These starter libraries can be expanded or new custom libraries can be added. Spikemark has three preloaded OSC libraries Figure 53’s QLab, ETC’s EOS family of lighting consoles, and Spikemark's own OSC library. If you are looking to build a library of commands for a different control platform, you will need to build your new OSC library in the XML format defined below.

Parts Of The Command Library

Command library parts
  1. OSC library name

  2. OSC library description

  3. OSC library version

  4. OSC command names

  5. OSC command address'

  6. OSC command parameter and argument names

  7. OSC command parameter and argument values

  8. OSC command parameter and argument descriptions

  9. OSC command parameter and argument data types

Command Library Format

A command library has the following basic structure:

<osc>
    <libraryName>Custom Lib</libraryName>
    <libraryDescription>A collection of amazing OSC commands</libraryDescription>
    <libraryVersion>1</libraryVersion>
    <command>
            <name>Cue Volume</name>
            <address>/cue/{cueNum}/volume[level]</address>
            <parameter>
                    <name>cueNum</name>
                    <description>The cue that will have its volume adjusted.</description>
                    <dataType>float</dataType>
                    <default>1</default>                
            </parameter>
            <argument>
                    <name>level</name>
                    <description>The new volume level for the cue.</description>
                    <dataType>integer</dataType>
                    <dataType>string</dataType>
                    <default>1</default>        
                    <optional>True</optional>                
            </argument>
    </command>
</osc>

Building A Custom Library

To build a custom library, you will need to create a new XML file with a .xml extension. Then in that file every library must have a root element of <osc> and the root element must have the following child elements:

  • <libraryName>: The name of the library.

  • <libraryDescription>: A description of the library.

  • <libraryVersion>: The version of the library.

<osc>
    <libraryName>Brand New Library</libraryName>
    <libraryDescription>A collection of amazing OSC commands</libraryDescription>
    <libraryVersion>1</libraryVersion>
</osc>

Once the basics are in place, you can start adding commands to the library. Every command will be encapsulated in a <command> element and must have the following child elements:

  • <name>: The name of the command.

  • <address>: The OSC address of the command.

<command>
    <name>Stop Running Cue</name>
    <address>/cue/stop</address>
</command>

Additionally, each command can have a list of parameters and arguments. Parameters are values that go in the OSC address, while arguments are values that get sent with the OSC message. Parameters are denoted in the OSC address with curly braces {}, and arguments are denoted in the OSC address with square brackets []. For example, in the address /cue/{cueNum}/volume[level], cueNum is a parameter and level is an argument.

Parameters are encapsulated in a <parameter> element and must have the following child elements:

  • <name>: The name of the parameter. This must match the name in the OSC address.

  • <description>: A description of the parameter.

  • <dataType>: The data type of the parameter. This can be integer, float, or string.

  • <default>: The default value of the parameter.

<parameter>
    <name>cueNum</name>
    <description>The cue that will have its volume adjusted.</description>
    <dataType>float</dataType>
    <default>1</default>
</parameter>

Arguments are encapsulated in an <argument> element and must have the following child elements:

  • <name>: The name of the argument. This must match the name in the OSC address.

  • <description>: A description of the argument.

  • <dataType>: The data type of the argument. This can be integer, float, or string.

  • <default>: The default value of the argument.

  • <optional>: A boolean value indicating if the argument is required. If this is set to True then it does not need to be filled out.

<argument>
    <name>level</name>
    <description>The new volume level for the cue.</description>
    <dataType>integer</dataType>
    <default>1</default>
    <optional>True</optional>
</argument>

You can add as many commands as you want to the library by adding more <command> elements to the root <osc> element. Also, each command can have as many parameters and arguments as you want by adding more <parameter> and <argument> elements to the <command> element.

Last updated

Was this helpful?