QLAB Buddy

Run a whole show in your browser, with no hardware. Each device runs its real firmware, compiled to WebAssembly and rebuilt from source on every commit that touches it.

• In the rig: a virtual QLab, a QLAB Buddy, an RF Relay, a Buddy Mini and a Universal Controller.
• The Universal Controller has no screen, so its motors and servos are drawn as bars and dials that move when a cue lands.
• Try this (the row at the top) walks you through it: press GO, fire the smoke effect, run a motor, fire a prop from Go Button, teach the relay a remote, then unplug the Buddy and watch the Mini carry on.
• The director panel underneath drives the rest: the Buddy’s buttons, VIEW-only access, #timer/ directives, battery and radio states, and the relay’s setup menu.

Who fires the relay? With QLab as the show, QLab fires it directly and the Buddy only watches; its Devices row flashes when the relay reports back. Switch to Go Button (the tab above the cue list) and the Buddy fires the tagged cues itself, because Go Button can’t reach the relay.

Fire your RF props from QLab with a stock Flipper Zero. No extra hardware, no WiFi. A small Mac app hears your QLab /rf/ cues and tells a Flipper on the Mac’s USB cable to transmit the remote you learned. It answers the same cues as the hardware RF Relay, so your QLab file needs no changes.

• The Flipper stays stock. Nothing is flashed onto it. The app uses the subghz commands already in its firmware, and it stays a normal Flipper for everything else.
• Spares swap in easily. A Princeton code lives on the Mac. Any other signal fires from its file on the Flipper’s SD card, which the app copies over when you import it. A slot whose file is missing is refused with not on the Flipper’s SD card.
• It shows on the Buddy’s Devices screen under the name you give it (default Flipper Zero).
• PING and /ping need UDP. Set Transport (Settings → Connection) to UDP or TCP and UDP. On the default, TCP, every QLab cue still fires; it just won’t answer /ping.

Which one should you use?

Starting from scratch? Take the relay. This app is for when you already own a Flipper and don’t want another box.

Download for macOS Version 0.1.34 · Apple silicon · macOS 12+

Download the beta Beta · newer than the release above, and not promoted yet

Beta: built, but not yet run through a show. Take it if you are testing, not if you are running a show. An installed copy can follow the beta channel by itself: Settings → Connection → Offer beta builds.

Install it

Your browser may warn the download is uncommon or from an unidentified developer. That is because the app isn’t signed with a paid Apple certificate, not because anything is wrong. Keep it.

Updates are your call. When a newer build is on this site, it shows a notification and an Install Update item in the menu. It never installs on its own, because installing restarts the app and cuts off any transmission in progress.

Setting it up

1. Learn your remotes on the Flipper with its Sub-GHz app: Read, press the remote, Save. Name each one. Then back out to the Flipper’s main menu.
2. Plug the Flipper in and open Settings from the RF Relay menu bar item. It opens on the Slots tab. Click Import from Flipper; it reads the signal straight off the SD card over USB. No qFlipper, no copying files.
3. Save, then test. Each row has its own Test button; Test OFF sits at the bottom for a slot with an OFF code. The receiver should trip. The row number is the slot number QLab uses.
4. Point QLab at it. The QLab tab lists the four steps to patch a Network cue, each with its own copy buttons, plus Copy all steps.

Cues

Cues and durations read the same as on the hardware RF Relay, so one cue file works with either. Two differences: a passcode set in the app is required on every cue, and a hold over 60 s is cut to 60 s instead of refused. See how a duration is written and the OSC command chart.

The app ignores /rf/slots and /springboard/*, so RF Springboard can’t use a Flipper. On a 0.13.0 hardware relay, a bare decimal in the path is still read as clock notation: /rf/1/0.5 means 5 seconds there, not half of one. Write it as an argument (/rf/1 0.5) or with a unit until 0.13.1.

Before a show

• Leave the Flipper on its main menu. Sitting inside its Sub-GHz app can hold the radio.
• Check the menu bar reads RF Relay ●. A filled dot means connected.
• Run Pre-Show Check from the menu bar item’s More menu. It tests the port, the config, the Flipper and every slot.
• Close qFlipper. It takes over the USB connection.
• Flipper not answering? Unplug it and plug it back in. The app reconnects by itself.

With QLab on the same Mac, no WiFi is in the trigger path: the cue goes down the USB cable. From another machine it crosses your network first. The trade-off: the Mac must be on, which for a QLab rig it already is.

Once flashed, every board updates itself wirelessly, over the air (OTA). You tap a button on the Buddy; nothing installs on its own.

• The Buddy downloads its own update and, from 0.13.1, each prop’s too.
• It checks the prop’s file against the published checksum, then hands it to the prop over your own network.
• The prop never needs the internet. If the Buddy can’t hold the file, the prop downloads it itself, as before.

Updating a paired prop

Open DEVICES on the Buddy. A prop with a newer version shows a green UPDATE chip beside it. Tap it once; there is no confirm step.

• Each row also shows the prop’s firmware, after its address.
• The chip appears within seconds of the Buddy starting. The Buddy checks again every 10 minutes.
• Give it time. An update can take a few minutes. A real failure takes up to about six minutes to show its red code, so a slow venue network isn’t mistaken for a broken flash.
• A prop on the show hotspot downloads through the Buddy’s own WiFi connection.
• An RF Relay on 0.13.2 Beta 22 or later is never offered REVERT to a build older than Beta 22. It stores its slots in a new format, and older firmware would start with every slot empty.

GO runs the next cue. PANIC fades out and stops everything that is playing. The Buddy and the Mini can send both, but only to the show the Buddy is connected to.

From the Mini: the REMOTE page 0.13.2

A big green GO with ◀ and ▶ either side, under the cue the playhead is on. It appears only while the Buddy’s OSC Access is set to CTRL.

Built not to fire by accident

• A slow press sends nothing. Holding BOOT between 0.6 and 5 s does nothing.
• After PANIC the button rests a moment, so letting go doesn’t also send GO.
• No show connected: nothing is sent. The status bar says GO not sent - not connected or PANIC not sent - no show.
• VIEW mode in OSC Access silences both. It also removes the Mini’s REMOTE page.
• RF Springboard silences both while the grid is up.

Why they never reach another rig’s show: see Two Buddies, One Venue.

RF Springboard turns the Buddy’s screen into a panel of big buttons, one for each remote your RF Relays have learned. Tap a button and the relay sends that remote’s signal.

No QLab, Mac or cue list needed. Hand the Buddy to a performer, or leave it on a table for guests to press.

Needs the Buddy and its relays on 0.13.2 from Beta Firmware. QLab Detection needs relay firmware 0.13.2 Beta 22 or later.

Setting it up

1. Teach an RF Relay your remotes. Each learned slot becomes a button with the slot’s name. See RF Relay.
2. Open the page. Tap the cog, then RF Springboard.
3. Tap Launch Springboard. The grid fills the screen and the relays lock.

The grid

Just buttons, plus a small Status Dot bottom-left: green with a network, red without. Up to nine buttons fit on the 3.5″ and sixteen on the 4.3″ and 7″; more scroll.

• Buttons are ordered by relay, then slot.
• New or deleted slots on a relay show up by themselves within ten seconds.
• BOOT sends nothing to QLab while the grid is up: no GO, no PANIC.

Hiding buttons and adding remotes

Tap Buttons on the page. Each tap on a button steps it on → disabled → hidden. Tap DONE when finished.

• Disabled stays on the grid, dimmed. A tap says This prop can’t be activated right now.
• Hidden leaves no gap.
• Both are remembered, even for a relay that is switched off.
• ADD REMOTE (one tile per relay): tap it, then press the remote’s button near that relay within 15 s. It goes into the first free slot.

ADD REMOTE results: New remote added, No remote heard - try again, That relay has no free slots or Could not reach the relay.

Getting back out

Hold the Status Dot for 3 s. A gold ring fills as you hold. On the 3.5″, holding BOOT for 3 s also works. The 4.3″ and 7″ have only the dot.

• Owner’s PIN set? A PIN card appears first. A wrong PIN shakes red; there is no lockout. It closes after 20 s untouched.
• You land on the RF Springboard page. The springboard is still running, but the relays are released.
• Launch Springboard returns to the grid. So does leaving the page untouched for 2 minutes.
• Back ends RF Springboard: the Buddy goes to LIVE and unlocks the relays.

After a power cut: a Buddy that was showing the grid comes back to the grid (locked, if a Guest PIN is set). One that was on the RF Springboard page comes back to LIVE, springboard off.

Several relays can share one grid, up to 200 buttons in all. The addresses the Buddy uses to talk to a relay are in the OSC Command Chart; they are not for QLab cues.

The status bar along the bottom tells you, at a glance, how the Buddy is connected. Its colours follow the fleet’s colour language.

• The dot and its label sit bottom-left on every view. The label names the path in use: WiFi, LAN, Hotspot and so on.
• A blue top edge means a show is open.
• A breathing dot means the network is up but no show is open yet.
• The middle names the open workspace.

Status bar	What it means
Blue, white dot: Show open, internet not confirmed	Cues work. Only the clock and updates wait on the internet.
Blue, green dot: Show open, internet confirmed	Green dot: all healthy. Before 0.13.2 this dot was gold.
Green, WiFi: On WiFi, no show yet	Green: network fine, still looking for a show.
Grey, LAN: Cabled to a Mac	Always grey with a white dot on a cable. The clock and updates still reach the internet.
Grey, Hotspot: Show hotspot, nothing joined	The show hotspot is up and empty.
Green, Hotspot: Show hotspot, device joined	Green: a prop, Mac or phone has joined.
Yellow, Pairing: Pairing	Yellow: Pair Devices is on and no show is open.
Grey, No WiFi: Never set up	No network saved yet. Tap the cog → WiFi.
Red, No WiFi: Connection lost	Red: the saved network is lost, or WiFi is off with no cable. Plug in USB-C, or tap the network in Settings → WiFi.

Short notices can replace the workspace name for a moment: GO not sent - not connected in red, or API Sync From and an address in yellow when another Buddy offers its API settings.

The show hotspot is the Buddy’s own WiFi network. Use it in a venue with no router, or one you’d rather not trust. Your Mac or iPhone joins it to reach the show, and props can live on it too.

Open it from the cog, then Hotspot.

Using it

• Turn it on or off by holding Hold To Turn On / Hold To Turn Off. A tap does nothing.
• Move props onto it with the Move button on a prop’s row, or Move All.
• Rename it or change the password by tapping either one. Props already on it follow the change.
• A Mac or phone on it gets internet through the Buddy, whenever the Buddy is on a WiFi. Props on it update the same way.
• No WiFi set on the Buddy? A prop you pair is given the show hotspot instead.

Two hotspots, one radio

The Buddy also has a fixed pairing hotspot. Only one runs at a time.

• Pairing borrows the radio. Props on the show hotspot drop off while you pair, and come back after. The Buddy warns you first.
• Two rigs never clash. Every Buddy’s show hotspot has its own name and password out of the box.

The status bar shows the hotspot grey while empty and green once something joins. See Reading the Status Dot.

Props go where the Buddy goes. Switch the Buddy to another WiFi and every paired prop that is on moves with it. No re-pairing, no walking round the stage.

Use it to move a rig from your workshop network to the venue’s.

1. Save the new network. Tap the cog, WiFi, then +.
2. Tap it. The row reads Checking - tap to cancel while the Buddy tests the network and password itself.
3. The props move. The row reads Moving 3 devices..., then Connecting.... Each prop restarts onto the new WiFi.
4. Check the addresses. Open DEVICES. The new router gives each prop a new one. Update any QLab Network Patches or Go Button tags to match.

• Safe to back out. The props hear nothing until the check passes. Cancel during Checking, or a failed check, changes nothing.
• Hotspot props stay put. Props on the show hotspot don’t move.

A prop that missed the move

A prop that was off or out of range still has the old network. DEVICES shows a yellow bar: 1 Device Not On This WiFi - Tap + To Pair.

1. Tap +. It opens Pair Devices.
2. Power the prop on. After about a minute it gives up on the old network and the Buddy brings it over by itself. No SYNC needed.
3. Close Pair Devices. Do it once the prop has arrived. It keeps its name and the last number of its address.

Two performers, two Buddies, one venue WiFi. Each rig keeps to itself. There is no password or team key to set up.

• Props are yours alone. Another Buddy’s props never appear on your DEVICES list. Unpaired props still show, so you can pair them.
• Addresses never clash. Each Buddy hands out addresses from its own place in the pool.
• GO and PANIC stay on your show. See GO and PANIC.
• Props refuse the other rig’s cues. An RF Relay or Universal Controller ignores cues from another Buddy or its QLab Mac.
• The Buddy stays on its own show. It sticks to the file and Mac it knows. If more than one Mac offers a show, it asks you with the workspace picker.
• The Mini’s REMOTE drives only its own Buddy’s show. On another rig’s copy of the file its buttons grey out.
• API Sync asks first. You get Accept Sync or Deny Sync. See Magic API.

Pair on one Buddy at a time. Both pairing hotspots are called QLAB Buddy.

The Buddy reconnects by itself to the last show it used on each network, QLab or Go Button. If it sees shows on two or more Macs on a new network, it asks you to pick one.

In a busy rig you can lock it to exactly one show on one machine.

Workspace picker

Open Settings → Workspace. Every show the Buddy can see is a row.

• Gold edge and a LOCKED tag: the locked row, pinned to the top.
• Green edge: the show in use.
• A locked Buddy ignores every other host, even one that answers first.
• No shows listed? Tap Enter IP Manually and type the machine’s address, such as 192.168.1.42. Useful when the network stops the Buddy finding shows by itself.
• QLab minimised is fine. Only closing the workspace disconnects the Buddy.

The Buddy can show a clock next to the cue name: a countdown to a curtain, a stopwatch across an act, or how long the show has run. What you get depends on the app running the show.

From QLab: tags in cue Notes

Type a tag into a cue’s Notes. When that cue fires, the clock does what the tag says. The Buddy hides the tags from the notes it shows, so they never clutter the screen.

What the colours mean

• Green: counting down, time left.
• Yellow: the last five minutes.
• Red: past zero. The clock goes negative to show how far over.
• Grey: counting up.

The Buddy, the Mini and the RF Relay all show the same colours.

• Clear it by hand: tap the timer area on the Buddy’s screen at any time.
• Closing the QLab file clears the clock on the Buddy, the Mini and the RF Relay.
• A WiFi drop does not. The clock keeps running, because a blip is not the end of the show.
• A Mini or relay powered up mid-countdown picks up the clock where it actually is.

Section times: #timer/lap 0.13.2

Find out how long each part of your show took. Tag the cue where each part begins. When the clock stops, the Buddy writes the times into a cue’s Notes: one line per section, then the total.

A four-cue show

After the run, Cue 4’s Notes read:

#timer/end
#timer/log
QLab Buddy Timer Log - Test Show - 09/21/2026 4:51 PM
  Intro         00:03.10
  First trick   00:06.25
  Second Trick  00:04.02
Total           00:13.37

• The name after #timer/start heads the log.
• A bare #timer/lap names the section after its cue, such as 2 Fountain.
• Start with a time, like #timer/25:00, and the log ends with a Target line: over by, under by, or on time.
• The log cue must be one the playhead comes to rest on, not one the show auto-continues past. The last cue is the tidy choice.
• The Buddy learns the log cue the first time the playhead rests on it, and remembers it for that workspace, through a power cycle too.

#timer/end
#timer/log
QLab Buddy Timer Log - Close-Up Set - 09/21/2026 8:04 PM
  Opener         00:03.40
  Card Fountain  00:06.05
  Mentalism      00:09.50
  Closer         00:06.12
Total            00:25.47
Target           00:25.00   over by 00:00.47

Turn on writing

Nothing is written until you allow it, once per rig:

1. On one Buddy: Settings → OSC Access → Timer Log → ON. Only one unit should write. A Buddy in VIEW mode can do it.
2. In QLab: tick Edit on the Buddy’s passcode row. Workspace Settings → Network → OSC Access.

Either way, the log also prints to the debug console after every run. Filter on [lap].

On the screen

• Stand the playhead on the #timer/log cue and the Buddy shows the log in place of the cue, live during a run.
• The open section is yellow, and the bottom line reads So far. With a set time, the Target line shows how you stand.
• Drag to scroll. The edge arrows are off on this screen, so a drag never moves the playhead.
• On LIVE, under the cue name: NOW names the section running, and NEXT in yellow names the one this cue will start.
• The Mini shows the log once it has been written into the cue.

A show never needs the internet. Cues, show detection, props and pairing all work on a WiFi with no internet, or on a bare USB-C cable.

What does use the internet

• The clock in the status bar.
• Firmware updates. See Firmware Updates.
• Magic API feeds. Each row reads No Internet until it is back. See Magic API.
• A Mac or phone on the show hotspot, which gets internet only while the Buddy has it.

The clock

With internet, the Buddy, the Mini and the RF Relay set their clocks and time zone by themselves.

No internet? The Buddy’s clock reads --:-- --. Tap it to set it by hand:

1. Type the time. Four digits.
2. Pick AM or PM. Then tap OK.

• A hand-set time lasts until the Buddy restarts. The board has no battery to keep time.
• Tap the clock to hide it, and again to bring the keypad back.
• Once the Buddy has found your time zone online, tapping the clock does nothing.

RF Relay only · firmware 0.13.0 and later. A relay still on 0.12.6 has no meter until it takes the update.

Four small segments at the bottom right of the RF Relay’s status bar. They show how busy the radio band is right now, so interference shows up before a cue misses, not after.