Making QLab Unstoppable

revised 10/2023: changed the file name of the Launch Agent plist

The Voxel uses QLab to control critical aspects of our building, such has HVAC and work lights. Similarly, for projects such as museum installations or interactive exhibits, a robust unattended QLab installation may be required.

Note that this list differs from the official A Computer Prepares - QLab 5 Edition instructions from Figure 53. Those instructions are optimized for a typical QLab Mac with an operator running intense shows.

Rather than optimizing for performance, these instructions are focused on configuring a QLab Mac for months of reliable unattended operation.

QLab Appliance Setup Checklist

This checklist generally assumes you are starting with a fresh Mac. If a well-loved Mac is being repurposed to an unattended use, it's a good idea to reinstall macOS.

macOS System Settings

Category	Setting	Value	macOS Version
Sound	Alert volume	0%
Sound	Play sound on startup	OFF
Sound	Play user interface sound effects	OFF
Sound	Play feedback when volume is changed	OFF
General - Software Update	Check for updates	OFF
General - Login Items	Open at Login	Remove all unnecessary items
General - Login Items	Allow in the Background	Remove all unnecessary items
General - Sharing	Screen Sharing	ON
General - AirDrop & Handoff	AirDrop	No One
General - AirDrop & Handoff	AirPlay Receiver	OFF
Desktop & Dock	Mission Control - Displays have separate Spaces	OFF
Desktop & Dock	Desktop & Stage Manager - Click wallpaper to reveal desktop	Only in Stage Manager	14.0 Sonoma
Energy Saver	Start up automatically after a power failure	ON
Energy Saver	Wake for network access	ON
Lock Screen	Start Screen Saver when inactive	Never
Lock Screen	Turn display off when inactive	Never
Lock Screen	Require password after screen saver begins or display is turned off	Never
Users & Groups	Automatically log in as	(your user account)

Add a QLab Launch Agent

A Launch Agent is a special instruction document for macOS. In this case, it asks the OS to open QLab 5 when the user logs in. After that, if QLab crashes or is quit by a user, it will automatically open QLab again.

Place this plist file in Users > (your user account) > Library > LaunchAgents. Typically the Library folder is hidden, so you must use the Go to Folder... pane to get there. In Finder, select the Go menu then choose Go to Folder... and type in ~/Library/LaunchAgents.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>KeepAlive</key>
	<true/>
	<key>Label</key>
	<string>com.figure53.QLab.5</string>
	<key>ProgramArguments</key>
	<array>
		<string>/Applications/QLab.app/Contents/MacOS/QLab</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>ProcessType</key>
	<string>Interactive</string>
</dict>
</plist>

QLab Preferences

In QLab, navigate to the QLab menu and choose QLab Preferences....

Setting	Value
At launch	Restore most recent workspaces
Automatically check for updates	OFF

In QLab, navigate to the Tools menu and choose Black out desktop backgrounds.

Program a Startup Group Cue

In your QLab Workspace, make a Timeline Group that starts your show. Though you might have cues on Wall Clock triggers, consider what the show's behavior should be if the power briefly went out after the times have passed. Program defensively.

In Workspace Settings > General, point the When workspace opens, start cue number option to your startup Group.

Make QLab Send Texts

It might be useful to be notified when QLab has been restarted. A Script Cue can be crafted to send text messages via the macOS Messages app on an internet-connected Mac. Messages may only be sent to iOS devices unless you have a cellular iPhone set up for Text Message Forwarding.

tell application "Messages"
	set myid to get id of first account
	set theBuddy to participant "+1 ??? ???-????" of account id myid
	send ("QLab launched @ " & time string of (current date)) to theBuddy
end tell