QLab 5Networking, MIDI, and Show ControlNetwork Cues

Network Cues

Network cues you to send messages from QLab to other software or devices using the network connections of your Mac. They can also be used to send control messages to QLab itself. Messages can be sent via TCP or UDP.

The Network cue can send three types of network messages:

  • OSC messages, which use the Open Sound Control protocol; a flexible, extensible, network-based messaging system designed as a sort of spiritual successor to MIDI.
  • Plain Text messages, which send plain ASCII text.
  • Hex Code messages, which send hexadecimal codes.

In addition, QLab includes the following collection of network device descriptions which allow a network patch to be configured to communicate with a specific device or program:

These network device descriptions include the full library of commands required to communicate with these devices or programs.1 When a network patch is configured to use one of these network device descriptions, the inspector shows a series of menus and controls specific to that description. This makes it easy to work with a device without having to constantly be referring to the device’s manual to look up specific commands or syntax. Examples are provided below.

Network cues require a license of any type.

The Inspector for Network Cues

When a Network cue is selected, the inspector shows the Basics tab and Triggers tab, used by all cues, as well as a Settings tab.

Settings

The controls in the Settings tab very depending upon two factors: the selected network patch, and whether or not the cue has a duration. The examples and screen shots in this section of the manual use a variety of combinations of settings in order to give a sense of the possible layouts.

Patch. This pop-up menu allows you to select a network patch for the cue to use. Clicking on the menu allows you to select one of the network patches already configured in the workspace, or (unpatched) if you want to ensure that the cue does not play when started. You can also choose Open Network Settings to edit patch list… to quickly get to Workspace Settings → Network → Network Outputs, or choose New patch with network device to quickly generate a new network patch and select it for use.

The contents of the lower portion of the Settings tab will change based upon the type of patch in use.

Fade. This pop-up menu will default to No Fade if the Network cue has no duration, or Resend if it does have a duration. This menu lets you set the Network cue to send its message just once (no duration, no fade), to send it repeatedly over time (duration, resend), or to perform a one-dimensional (1D) or two-dimensional (2D) fade to send more complex messages over time. These options are discussed more below.

Duration. You can edit the duration of the cue here, as well as in the Basics tab or in the Duration column of the cue list.

Send. Clicking this button will test-send your message and is the same as previewing the cue.

OSC Messages Without Durations

If the Network cue uses a patch configured to send an OSC message, the lower part of the Settings tab shows a single, large text field.

A Network cue with an OSC message

The text field allows to enter any single OSC command. OSC messages are made up of an address which is the part that looks like a web address, and zero or more arguments which follow the address. QLab uses the following formatting rules for OSC messages:

  • A single space separates the address from the first argument and arguments from each other
  • String arguments that are contain spaces must be “enclosed in quotation marks.”
  • Arguments made of only digits are assumed to be integers.
  • Arguments made of digits with a decimal separator are assumed to be floating point numbers (floats).
  • The following OSC 1.1 arguments are allowed:

    • \T is a boolean true.
    • \F is a boolean false.
    • \I is an impulse.
    • \N is a Null.

While OSC itself only supports using a period (a.k.a. a “full stop”) as a decimal separator, QLab is aware of the location settings on your Mac and will invisibly substitute a period in outgoing OSC messages if your Mac is set to use a comma as the decimal separator.

Examples

Here are a few examples showing proper OSC message formatting in QLab.

/my/groovy/message 2 10 12

This sends a message to address /my/groovy/message with three integers, 2, 10, and 12, as separate arguments.

/day/start "mornin', ralph" "morning', sam"

This sends a message to address /day/start with two strings, morning', ralph and mornin', sam, as separate arguments.

/osc/rocks \T

This sends a TRUE value to the address /osc/rocks.

OSC Messages With Durations

If the Network cue uses a patch configured to send an OSC message and the cue has a duration, the Fade control comes into play.

Resend

If the Fade pop-up menu is set to Resend, the cue sends its message repeatedly over its duration. The frequency that the message is sent is adjusted by the fps pop-up menu which has several options from 1 message per second up to 120 messages per second.

The cue in this screen shot will send its message 30 times per second for ten seconds:

A Network cue with a resending OSC message

1D Fade

If the Fade pop-up menu is set to 1D Fade, the cue also sends its message repeatedly over its duration, but allows you to configure the message to change over time.

A Network cue with a 1D float fade

This cue is set to use a 1D Fade, resending its message at 60 fps using floats. This means:

  • A single value will be faded over the duration of the cue,
  • That value will be updated and sent 60 times per second,
  • The value will include decimal values (to six decimal places.)

The right side of the tab displays a fade curve (which you can edit to suit your needs) and two text fields. The From field sets a starting value, and the To field sets a final value.

The text field fills the left side of the tab. Note that the OSC message includes the text #v#. This is a token, which is like a stand-in for an actual value.

When the cue runs, QLab calculates a fade starting at the From value and ending at the To value. Each time the message is sent, the calculated value is sent in place of the #v# token.

The token is most commonly used in the place of an argument, but if the OSC message that you’re sending includes a numerical value in the address, the token can be used there as well.

2D fade

If the Fade pop-up menu is set to 2D Fade, the cue allows you to fade two values at the same time over the duration of the cue.

A Network cue with a 2D integer fade

This cue is set to use a 2D Fade, resending its message at 100 fps using integers. This means:

  • Two values will be faded over the duration of the cue,
  • The values will be updated and sent 100 times per second,
  • The values will be integer values only; no decimals.

The right side of the tab shows a blue rectangular area inside which you can draw a path using your mouse or trackpad. The green control point represents the starting position of the fade, and the red control point represents the ending position. The Width and Height fields let you set the size of the rectangle, and therefore the values that will be sent. The center of the rectangle represents (0, 0), positive numbers are up and to the right, and negative numbers are down and to the left.

The text field fills the left side of the tab. Here, the OSC message includes two tokens, #x# and #y# When the cue runs and the fade animates, the X-axis value will replace the #x# token and the Y-axis value will replace the #y# token.

If Live Preview is on, QLab will transmit OSC messages as you click and drag so that you can see or hear the results in real time.

If you hover your mouse over the path, you can click and drag to move, resize, and edit the path. Control points can be moved or deleted, and the whole curve can be moved or scaled. Clicking on an unoccupied spot in the rectangle adds a control point to the end of the curve, so you can click on points one by one instead of dragging to create a curve. If you make a mistake while editing a curve, just choose Undo from the Edit menu.

2D OSC fading mouseover

Plain Text Messages

If the Network cue uses a patch configured to send a Plain Text message, the lower part of the Settings tab shows a single, large text field.

A Network cue with a plain text message

Plain text messages cannot be given a duration, and so cannot be faded or resent. Only ASCII characters can be used in plain text messages.

Hex Code Messages

If the Network cue uses a patch configured to send a Hex Code message, the lower part of the Settings tab shows a single, large text field.

A Network cue with a hexadecimal message

Plain text messages cannot be given a duration, and so cannot be faded or resent. Only hexadecimal symbols can be used in plain text messages; the numerals 0 through 9 and the letters A through F.

Network Device Description messages

If the Network cue uses a patch configured with a network device description, the lower part of the Settings tab can show a variety of pop-up menus, text fields, checkboxes, sliders, 1D fade curves, and 2D fade curves. The specific controls that are available depend upon the network device description in use.

When using Network cues to communicate with another computer running QLab, or to send OSC messages from QLab back to itself, this option provides a very simple interface for accessing the commonly used OSC commands that QLab recognizes. Enter a cue number, and choose a command to send. Some commands have additional arguments, and additional fields will appear when those commands are chosen.

QLab 5 - Workspace GO

A Network cue with a QLab OSC message

ETC EOS Family - Channel 10 at 50%

A Network cue with an ETC EOS OSC message

ETC EOS Family - Fade channel 10 from 50% to 0%

A Network cue with a 1D fading ETC EOS OSC message

d&b DS100 (Soundscape) - Fade input 1 from downstage left to upstage right

A Network cue with a 2D fading d&b Soundscape OSC message

Yamaha Rivage - Enable delay on input channel 8

A Network cue with a Yamaha Rivage OSC message

If you would like us to create a network device description for a specific network-controllable device or program, please contact us at support@figure53.com and tell us about it. We may be able to create a description, and if so we may be able to include it in a subsequent release of QLab.

Network Cues and Cue Templates

As discussed in the section on Cue Templates in this manual, cues can be given a customized default state. Newly created cues in a workspace come into existence using this default state. If, for example, most of the Network cues in your workspace will be used to start a cue on an ETC console, you might configure the Network cue template like this:

An ETC-specific Network cue template

Then, every new Network cue would start off looking like that, and would need only a cue numbered to be entered in the Settings tab in order to be used.

However, if your QLab workspace communicates with several different OSC-controllable devices, say an ETC console, a d&b DS100, and another remote copy of QLab, you might find yourself wishing there were a way to make multiple cue templates. To address this need, follow these steps:

  1. In Workspace Settings → Network → Network Outputs, set up a network patch for each device that your workspace will communicate with.
  2. In Workspace Settings → Templates → Cue Templates, select the Network cue, click on the Settings tab, and choose one of the network patches.
  3. Configure the rest of the Settings tab as you would like cues which use that patch to appear.
  4. Now, select a different network patch and configure the Settings tab for the defaults that you want associated with that patch.
  5. Repeat for each network patch in your workspace.
  6. Finally, select whichever network patch you plan to use most often, and leave the cue template set to use that patch.

Now, newly created Network cues will appear using that patch and all its associated settings, but if you switch the cue to another patch, the default settings you created in the cue template will suddenly appear. In this way, you can capture the default state of each type of Network cue that you plan to use.

Broken Cues and Warnings

Network cues can become broken or warned for the following reasons:

No Patch

The cue has no network patch assigned. Assign a network patch to clear this warning.

Incomplete network patch

The cue has a network patch assigned, but something is wrong with it. The network patch will have warnings of its own, listed in the Warnings tab of the Workspace Status window, which you can use to figure out what’s wrong with it. Either fix the network patch or select a new network patch to clear this warning.

Missing message.

Fill in a valid message in the Settings tab of the inspector to clear this warning.

Missing values.

The cue uses a network device description and one or more parameters have no value. Fill in values for every control in the Settings tab of the inspector to clear this warning.

Invalid hex codes.

The cue is configure to send hexadecimal values, but contains at least one character that is invalid. Edit the message in the Settings tab of the inspector to clear this warning.

Missing image file.

This non-breaking warning will appear on a Network cue which had a 2D fade background image assigned which QLab is not able to locate. Replace the image or click Remove Background in the Settings tab of the inspector to clear this warning.

License required

A license of any kind must be installed to use Network cues.


  1. All trademarks are the property of their respective owners, and their inclusion in this manual and in QLab does not represent any official relationship between Figure 53, LLC and any other entity. The inclusion of a particular device or program should not be construed as an endorsement, and omission of a device or program should not necessarily be construed as an admonishment. Every effort has been made to ensure that these network device descriptions are accurate and functional, but it is impossible to make a complete guarantee since manufacturers may change their devices or command libraries without notice.

Still have a question?

Our support team is always happy to help.

Business Hours
M-F 9am-7pm (ET)
Current time at our headquarters