QLab and StageCaller

StageCaller by Disappointed Pig LLC  is an iOS or Android app that allows mobile phones to play locally stored sound recordings in response to OSC or MIDI triggers, sent over a wireless network.

It’s now perfectly possible that you might be using this, or a system like it, in a room with a 1000 or more wi-fi enabled phones belonging to audience members. It’s therefore wise to recognize that what worked perfectly in the dress rehearsal, in an empty theatre, may not work so well once the audience are in.

This chapter is primarily about using all the features available in QLab 4.1 and later, to try to get operation of QLab and StageCaller as reliable as possible. It assumes you have StageCaller set up and working correctly for basic operation (If you don’t, then skip to page 2 of this tutorial and we’ll go through how to set it up from scratch).

We will be looking at how we can use a heartbeat from StageCaller to automatically switch to backup recordings if the phone becomes unavailable and to have a second line of backup if the phone is working but for some reason, it can’t be heard. e.g The actor has brought the wrong phone onto the stage or the phone has been dropped in the seconds between the last heartbeat being received and the cue firing.

Here it is in action:

How it works:

When the workspace opens the cue numbered nhb is triggered.

whenworkspace opens

This triggers a fire all children group with 2 Network Cues with OSC messages:

/cue/s*/armed 0

which will disarm any cue whose cue number begins with s. If we ensure that all the OSC cues that control StageCaller are numbered s1, s2…. etc, then all those cues will be disarmed when there is no heartbeat being sent from the mobile phone running StageCaller

/cue/b*/armed 1

will arm all the cues whose number begins with b. Numbering all the backup cues with numbers beginning b e.g.b1, b2….etc. will ensure that those cues are armed when the heartbeat is not present.

When the heartbeat is switched on, in StageCaller, an OSC message you define is sent to QLab, at the interval you set.

The message is set to:


sending every 5 seconds.

SC heartbeat settings

This triggers the group cue numbered hb. This is fundamental to the way the workspace operates so here it is in close up:

When the heartbeat OSC message is received by QLab, (/cue/hb/start) cue hb is triggered. Cue hb has a trigger option set to hard stop and restart if it receives a second trigger, while it is playing.

second trigger

When the cue triggers it sends 2 OSC messages to QLab

/cue/s*/armed 1
/cue/b*/armed 0

Which arms the StageCaller cues and disarms the backup cues, and also starts a 6-second pre-wait on another group. (Sometimes you may want  to extend this pre-wait by a couple of seconds, particularly if reception of the heartbeat is erratic)

StageCaller is set to send a heartbeat every 5 seconds, so in the normal course of events, the pre-wait will never complete as the second action trigger will restart the cue before this happens.

If the heartbeat is lost then the second trigger won’t happen, the pre-wait will complete, triggering :

/cue/b*/armed 1
/cue/s*/armed 0

Which disarms the StageCaller cues and arms the backups.

You can log all this OSC activity in the Workspace Status Window. If you leave this running you can cut and paste the data to a text file, and analyze it to see if there are any periods in your show where heartbeats are not received.

The programming structure for any cue involving StageCaller is identical


The OSC to trigger a StageCaller sound is contained in a fire all group cue, with its (Normally disarmed) backup audio cue.

The OSC message sent to StageCaller has a duration that exceeds the maximum duration the cue might be played for. Durations on network cues are a new feature in QLab 4.1. A duration means the OSC message will be sent repeatedly (approx 20 times a second). This has 2 huge advantages in use with StageCaller.

If the phone misses an OSC trigger then it may well get one of the repeats.

It enables us to leave the sound in StageCaller as a one-shot (Play 1 time, x1). When the sound completes the next OSC message it receives will trigger it again, so it effectively loops. This is better than setting it to loop within StageCaller. If the wireless communication is lost while the sound is being played, it’s only going to play out once, thus avoiding a phone that cannot be silenced.

Here are the complete settings for the action for this cue on StageCaller.


The sound SC Cordless Phone Ring is triggered when /cue/1/start is received from QLab and continues until  /cue/1/stop is received, or the sound file ends, as the play is set to its default of 1 time. The action volume and the device ( your phone) volume are set to maximum.

When Cue 1 is triggered the cue list advances to the safety cue, ready to play a backup of last resort cue, should the phone not be audible, because it is offstage, in the actor’s briefcase instead of a pocket, or just hasn’t worked.

If no sound is heard after triggering cue 1 the operator can just press GO again to trigger this backup cue. After a few seconds (set in the pre-wait of the GoTo cue in cue 1) the cue list automatically advances past this backup cue as it is assumed it is no longer required.

The backup cue also includes a cue to stop the main cue, to avoid the possibility of 2 sounds being heard.

Finally, a stop cue silences any cue that might be playing, by stopping any audio within QLab and sending a /cue/1/stopOSC message to StageCaller. Again this Network Cue is given a duration so the message will be sent 20 times.

Here’s a demo of what happens when the safety cue is required:

You can repeat that structure for every StageCaller cue.

As a final refinement, we can add our own OSC logging. The built-in OSC log in QLab can get quite data-dense on a show that has a lot of OSC. We can just log a single event to a text file every time the heartbeat dies and every time it recommences.


Whenever the heartbeat is not received by QLab the cue numbered nhb fires. In addition to the arming and disarming of cues described earlier, we have now added a log cue, which adds the current time and a HEARTBEAT DEAD message to a text file:

tell application id “com.figure53.QLab.4” to tell front workspace
do shell script “date ‘+%H:%M:%S HEARTBEAT DEAD’>>$HOME/Desktop/SCheartBeats.txt”
end tell

It then arms the LOG RECEIVED cue, so that when the heartbeat reception resumes the LOGGER cue in that group can add the time and a HEARTBEAT LIVE message to the text file.

tell application id “com.figure53.QLab.4” to tell front workspace
do shell script “date ‘+%H:%M:%S HEARTBEAT LIVE’ >> $HOME/Desktop/SCheartBeats.txt”
end tell

As soon as this log is written it disarms the logger, so the next event written will be the next time that the heartbeat dies.

The log file (SCheartBeats.txt) can be opened from the desktop. (You need to close it, and open it again, to see new entries). It will look something like this:


Here is the logging system in action:

You can download the QLab demo workspace and sounds here

You can download the StageCaller sounds and actions used in the demo here

Put them in your Dropbox folder

You can restore them to your phone from the StageCaller Settings page.


On the next page is the promised quick guide to basic set up of  StageCaller with QLab.

Chapter Author: Mic Pool

StageCaller is a registered trademark  of disappointed Pig LLC