Expanding The 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. Currently, Spikemark only has two preloaded OSC libraries. One OSC Library is Figure 53’s QLab and the other is ETC’s EOS family of lighting consoles. If you are looking to build a library of commands for a different control platform with spikemark, you will need to build your new OSC library in the XML format defined below. Let’s go over everything that you can have control of when you build your new OSC command library.

1. OSC Library Name

2. OSC Library Description

3. OSC Library Version Number

4. OSC Command Name

5. OSC Command Address

6. Address’s Parameters and Arguments

7. Input Field for the value of the Parameters and Arguments

8. Descriptions of Parameters and Arguments

9. Data Type of Parameters and Arguments.

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>

This structure may seem complex, but let us demystify it for you. Even though the Qlab and EOS Libraries are already built, let’s go through the process of adding a new OSC library into Spikemark. Spikemark needs to be told where to place information when you are building a new OSC Library. Let’s start a new library that we will call “Brand New Library”. Open up your favorite Text Editor that will let you save as an XML file with a file extension of .xml. Keep following along to import your first command into your new OSC Library.

Start with the two lines below.

<osc></osc> - This is the root tag that contains all of the other tags.

<osc>

</osc>

Next we will input the descriptors that are displayed in the OSC Library in Spikemark.

• <libraryName>Brand New Library</libraryName>

• <libraryDescription>A collection of amazing OSC commands</libraryDescription>

• <libraryVersion>1</libraryVersion>

The white text below you can change to anything you like.

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

Now let’s add our first command block. You will repeat this step for each command you want to send to a software capable of being controlled by an OSC Command. Let’s make our first command to control the X Scale Factor of a video cue. The Command Address is what will be sent to the software you are trying to control. The Command Address can be found from the manufacturers website of the software that will be controlled from Spikemark. The Command Address consists of two parts: Parameters and Arguments. We indicate Parameters with { } and Arguments with [ ]. For our example, the Command Address for controlling the X Scale of a video cue will be noted as: /cue{cueNum}/scaleX[scaleFactor]. The cueNum is the parameter and the scaleFactor is the attribute for this Command Address.

• <command></command> - This tag can be repeated an infinite number of times inside the <osc></osc> tag, each one representing a different OSC Command.

  • A Command will contain:

    • <name>Cue X Scale Factor</name> This tag holds the name of your command.

    • <address>/cue{cueNum}/scaleX[scaleFactor]</address> tag. This tag contains what will be sent over OSC. Each OSC Address uses the same structure /method/{parameter}/method/[argument]. In this example, we are using the “Cue” method with the parameter “{cueNum}” and the method “scaleX” with the argument “[scaleFactor]”.

    • <parameter>cueNum</parameter> You can have multiple parameter tags, but there needs to be the same number of parameters that exist in the <address></address> tag

    • <argument>scaleFactor</argument> You can have multiple argument tags, but there needs to be the same number of arguments that exist in the <address></address> tag.

<osc>
	<libraryName>Custom QLab Library</libraryName>
	<libraryDescription>A collection of amazing OSC commands</libraryDescription>
	<libraryVersion>1</libraryVersion>
	<command>
		<name>Cue X Scale Factor</name>
		<address>/cue/{cueNum}/scaleX[scaleFactor]</address>
		<parameter>
			
		</parameter>
		<argument>
			
		</argument>
	</command>
</osc>

In each Parameter and Argument tag, there will be 4 additional tags to give information for:

• <name></name> - This tag must match what is entered for the Parameter or Argument in the <address></address> tag

• <description></description> - This is the description that will be displayed next to each Parameter and Argument

• <dataTypes></dataTypes> - This tag describes the type of data that is allowed. The valid values for this tag are float, integer, or string

• <default></default> - This tag is required for both Parameters and Arguments. This will be the default value for the Parameter and the Argument

• <optional><optional> - If an argument is required, this tag can be omitted. If an argument is not required, a tag with the value of True can be added

<osc>
	<libraryName>Custom QLab Library</libraryName>
	<libraryDescription>A collection of amazing OSC commands</libraryDescription>
	<libraryVersion>1</libraryVersion>
	<command>
		<name>Load Cue At</name>
		<address>/cue/{cueNum}/LoadAt[sec]</address>
		<parameter>
			<name>cueNum</name>
			<description>The cue that will be loaded.</description>
			<dataType>float</dataType>
			<default>1</default>		
		</parameter>
		<argument>
			<name>sec</name>
			<description>The amount of time it will take to load</description>
			<dataType>float</dataType>
			<default>1</default>		
		</argument>
	</command>
</osc>

Congratulations! You just added your first command in a new OSC Library. Repeat for each command you want to add into your OSC Library. Once you have added all the commands for this library, save your new library as an XML file with the file extension .xml and save it in “C:\Users{user}\Documents\Spikemark\OSC Libraries” to have it saved where the other OSC Libraries are saved for Spikemark.

Once you have saved your new OSC Library, you can recall it by Clicking on the “+” button on an OSC movement

Then, Click “Browse”.

Select your newly created .xml file and use your new commands.