Stream Deck & Companion for Live Events and Streaming

Introduction

The house lights fade to half, the walk-in music swells, the holding slide gives way to the opening video, and the host walks on to applause. To the audience it is one smooth moment. At the back of the room, one technician pressed one button.

That button sat on a Stream Deck, a small panel of keys that are each a tiny screen. Behind it ran Bitfocus Companion, free software that turns a key press into commands for the show's machines: the video switcher, the media server, the playback computers, the PowerPoint laptop, the audio console and the lighting desk. The deck is the hands. Companion is the brain.

This book teaches you to build and run that system on a show. It starts from nothing: what the hardware is, how show gear talks over a network, and how to get Companion running. It then teaches the craft of building buttons that show what the show is doing, and the decision at the heart of the job, which is how to lay your buttons out for the responsibilities you have on that show. After that it takes each department's gear in turn, from video switchers to lighting consoles, then builds whole cues, takes the system onto a film set and a live stream, shares control with other people, and ends with show day, when everything you built has to work in front of an audience.

It is written from working practice on corporate shows, concerts and film. Companion changes often and every venue is different, so the book teaches what stays true: plan from your job, label everything, test before doors, and always know how to run the show without the buttons.

What you will be able to do

By the end you will be able to explain what a Stream Deck and Companion each do; choose the right hardware for a job; set up a show network and connect Companion to the gear on it; build buttons with actions, feedbacks, variables and triggers; lay out your decks for your responsibilities and the run of the show; control video switchers, media servers, playback machines, PowerPoint computers, audio consoles and lighting consoles; build reliable cues; run Companion on film sets and streams; share control safely; and prepare, test and recover on show day.

How to Use This Book

Read it in order the first time. Chapters one to five are the foundation: the hardware, the network, installing Companion and connecting it to gear. Chapters six to nine teach the craft of building buttons and laying them out, and chapter nine, on how your job decides the layout, is the one the rest of the book leans on. Chapters ten to fifteen take each department's gear in turn; read the ones for your job first and come back to the others. Chapters sixteen to twenty-one put it all together, on shows, sets and streams.

Every chapter ends the same way: a procedure you can follow on the job, a table of failures with their causes and fixes, an exercise with its answers, and a checklist. Do the exercises with Companion open in front of you. It is free, it runs on an ordinary laptop, and it has a built-in emulator, so you can build and press buttons without owning a Stream Deck or any show gear.

The shows in the examples

The worked examples follow three invented productions. Brightwater Health 2027 is a corporate conference in a hotel ballroom, with a host, a chief executive, a panel and an awards segment. The Low Tides is a band playing a 3,000-seat theatre with an LED wall. The Night Shift is a television drama, the same one followed in Reboot's Introduction to 24 Frame Playback course. Every name, company and address in them is made up.

Keep a show notebook

Keep a show notebook from your first build. For every show, write down each machine's address and port, the connection labels you gave them, which department agreed to which buttons, the page numbers of your decks, and where the backup file lives. Write down every fault you meet and what fixed it. Within a few shows the notebook becomes the fastest tool you own, because the same problems come back.

A note on the words

The same thing goes by several names in this work. Companion itself calls a link to a machine a connection, where older guides and forum posts say instance. A Stream Deck key is also a button, and in Companion any panel that presses buttons, from a deck to a tablet, is a surface. A video switcher is also a production switcher, and the large screen-management systems are also called presentation switchers or image processors. An audio console is a desk or a mixer; a lighting console is a desk too. Where this book uses a word, it uses the one printed on the screen or the gear, and it explains the others the first time they appear. The glossary at the back collects them.

A note on versions

Companion is open-source software that is updated often, and its connections to each make of gear are written and updated by volunteers and manufacturers. Menus move and options are added between versions. Where this book describes a screen or a setting, check it against the version you are running, and read the help page that comes with each connection. The ideas do not change.

A note on safety

A button can start a video in front of two thousand people, open a live microphone or black out a room. Never test a new button during a show. Agree with each department which of their machines you may control and which buttons are theirs. Tape down every cable you run, keep the show network separate from the venue's, and always know how to run each machine from its own controls if the buttons stop.

What Stream Deck and Companion Are

A Stream Deck is a small panel of buttons with a picture on every key, and Bitfocus Companion is the free software that turns those buttons into commands for show gear. This chapter explains what each part does, why show technicians use them, and where they sit on a corporate show, a concert and a film set, so that every later chapter has a place to hang.

A Stream Deck is a small panel of buttons with a picture on every key, and Bitfocus Companion is the free software that turns those buttons into commands for show gear.

Why show techs use it

Picture the video position at Brightwater Health 2027, an invented corporate conference in a hotel ballroom. In front of the operator sit a vision switcher, two playback computers, a PowerPoint computer and a laptop full of notes. When the host, Dana Okafor, says "please welcome our CEO, Martin Lowe", four things must happen at once: the walk-up music plays, the camera on the lectern goes to the screens, the CEO's first slide appears on the confidence monitor and the lower third with his name comes up. Without a control panel, that is four hands on four keyboards.

Companion lets the operator put all of that on one button. The button can be labelled MARTIN WALK-UP, it can turn red when the camera is live, and it can be pressed with one finger while the operator watches the stage. That is the whole reason show technicians use it: fewer hands on fewer machines, fewer chances to press the wrong thing, and a panel that tells you what state the show is in.

The reasons repeat on every kind of show. The list below is what technicians who use Companion daily tend to name first.

Companion does not make a show safer by itself. A badly built button fires the wrong thing faster than a keyboard ever could. The rest of this book teaches how to build buttons that are worth trusting.

The buttons and the brain

Two parts work together, and beginners often mix them up. The Stream Deck is the hardware: a box of keys made by Elgato, each key a tiny screen under a clear button, connected to a computer by a USB cable. On its own it does nothing. It sends a message to the computer when a key goes down and when it comes back up, and it shows whatever picture the computer sends to each key.

Bitfocus Companion is the brain. It is software that runs on a computer, made by Bitfocus and released as open source under the MIT licence, so it costs nothing to download and use. Companion decides what each key looks like and what happens when it is pressed. When you press a key, Companion sends a command across the network to the gear: cut to camera 2 on an ATEM, play clip 4 on a playback machine, advance a slide. Bitfocus describes Companion as turning the Stream Deck and other controllers into a professional shotbox, a broadcast word for a panel of preset buttons.

Notice that the show gear sits at the end of that chain. A switcher does not need Companion to switch. Every machine keeps its own controls, and an operator who knows those controls can run the show by hand if Companion or the deck fails. Keep that idea in mind from the first button you build.

Companion does not only work with Elgato hardware. It can take presses from other panels, from a web page on a tablet, from a browser emulator and from other software. Companion calls anything that presses its buttons a surface. Chapter 2 covers the hardware and Chapter 20 covers tablets and remote panels.

One panel, many machines

The Stream Deck's value grows with the number of machines you run. With one machine, its own keyboard or panel is often enough. With three or more, you start to lose time moving between them, and mistakes start to come from reaching for the wrong keyboard.

Companion talks to each machine through a connection, which is Companion's word for one device it controls. Each connection uses a module: a small plugin written for that make of gear that knows the commands it accepts. Bitfocus lists more than 700 supported devices and programs. A single button can carry actions for one connection or for several, so one press can command one machine or many.

Whether a cue button fires one machine or several is the programmer's choice. Some operators keep every key to one machine so that a fault is easy to trace; others build a key that runs a whole moment across machines because the show calls for it. Both work. Chapter 16 teaches when each fits.

Patrice Augustin, who founded Reboot and runs video and playback on corporate shows, concerts and film, describes his layout like this: it depends first on his responsibilities. On a show where he runs one machine he may need a small panel or none at all. When he runs many, he usually has one Stream Deck for transport controls, the play, pause, stop, next and previous keys, and a second Stream Deck for all the cues. Chapter 9 builds that two-deck rig.

Where the Elgato app fits

Elgato sells the Stream Deck with its own free software, the Stream Deck app. The Elgato app is built around a single user at a computer: launching programs, switching scenes in streaming software, typing shortcuts. It is enough for some jobs, and Chapter 19 covers when.

Companion is built around show gear on a network. It has modules for vision switchers, media servers, playback software, audio and lighting consoles and much more, it can show the state of that gear on the keys, and it can run on a computer with no one sitting at it. This book is about Companion first.

The two programs should not fight over the same deck. Bitfocus advises closing the Elgato app before opening Companion, because Companion runs best when it has full control of the Stream Decks. If you need both, Bitfocus publishes a Companion plugin in the Elgato store, and Companion can also be told to leave some decks alone. Chapter 19 explains how.

What Companion does not do

New users sometimes expect Companion to do more than it does. Knowing its limits early saves a lot of confusion on the first show.

There is one more limit to remember. A module can only do what its authors built and what the device allows. If the ATEM module has no action for something, the button cannot do it. Read the module's help page before you promise a client a feature.

Where it sits on a show

On a show, Companion runs on a computer at the operator's position, connected by network cable to a show switch, and through that switch to the gear. The Stream Decks plug into that computer by USB, or reach it over the network. The gear may be beside the operator or in a rack backstage; the network makes the distance irrelevant.

At Brightwater Health 2027, the video position at FOH, front of house, the operating area facing the stage, holds the Companion laptop and two decks. The ATEM sits in the rack at FOH, the two playback computers sit beside it, and the PowerPoint computer sits at the lectern side of the stage with its own network cable back to the switch. One network, one Companion, many machines.

Audio and lighting technicians use Companion too, often for mic mutes, walk-in music, stings and simple lighting looks. Chapters 14 and 15 cover those departments, and Chapter 16 covers cues that run across them.

How to do it

1. List every machine you are responsible for on this show, by name and by job: switcher, playback, slides, media server, anything else.
2. For each machine, write the moments in the running order where you touch it, such as the walk-in, the opener or the awards.
3. Mark the moments where two or more machines must move together. Those are the moments a Companion button helps most.
4. Check that each machine has a way in: a Companion module, or a documented network, serial, MIDI or keystroke control.
5. Decide how many panels your responsibilities need. One machine may need none; many usually need one deck for transport and one for cues.
6. Write down how you would run each machine by hand if Companion failed, and keep that note at your position.

What goes wrong

Practice it

At Brightwater Health 2027 you run video at FOH. You are responsible for the ATEM at 10.0.0.20, Playback A at 10.0.0.31, Playback B at 10.0.0.32 and the PowerPoint computer at 10.0.0.40. The awards segment has eight winners, each with a walk-up sting, a name graphic and a photo slide.

The Hardware

Companion can be pressed from many kinds of panel, but most shows use Elgato's Stream Deck family. This chapter walks through that family, the keys, dials and touch strips on them, the panels that live in racks and under feet, the other surfaces Companion supports, and how to choose the right panel for the job you are hired to do.

Companion can be pressed from many kinds of panel, but most shows use Elgato's Stream Deck family.

The Stream Deck family

Elgato makes Stream Decks in several sizes. They share one idea: each key is a small colour LCD screen under a clear cap, so the software can draw a label, a colour or a picture on it. They differ in how many keys they have, whether they add dials or touch areas, and how they connect.

Companion's Stream Deck support lists the models it handles: the original 15-key Stream Deck, the Mini, the XL, the MK.2, the Pedal, the Stream Deck +, the Stream Deck + XL, the Neo, the Studio and the Stream Deck Modules with 6, 15 and 32 keys. Elgato sometimes changes a model's internal revision without notice, so a brand-new unit can occasionally need a Companion update before it works.

Elgato also sells a Network Dock that gives a desktop Stream Deck an Ethernet port, powered by PoE (power over Ethernet, where the network cable also carries power) or by USB-C. A deck on a Network Dock no longer needs a USB cable back to the computer. Elgato lists it as not compatible with the first-generation Stream Deck or the Studio, which has Ethernet built in. Companion can add Network Dock decks on its Surfaces page as remote surfaces.

Key counts and features change as Elgato releases new models. Before you buy for a show, check the model on Elgato's site and check Companion's surface module help page that the model is supported.

Keys, dials and touch strips

A key does two things for Companion. It reports a press when it goes down and a release when it comes back up, and Companion can run different actions on each. It also displays whatever Companion draws: text, a background colour, a picture, or a changing value such as a clip's remaining time. Chapters 6 and 7 cover building and colouring keys.

A dial, which Elgato calls an encoder, turns without end in either direction and can also be pushed like a key. In Companion a dial sits in the button grid like a key, and you switch on its turning actions by ticking "Enable Rotary Actions" on that button. Turning left and turning right then each get their own actions, which suits things that go up and down: a volume, a transition rate, a playback position.

The touch strip on the Stream Deck + is a narrow touch screen above the dials. Companion maps it to four buttons, one above each dial. A tap on the strip sends a press and a release together, so the strip cannot tell a short tap from a long hold. Since Companion 4.2, a sideways swipe on the strip changes page, and an up or down swipe can be used as a turn. Companion's own help warns that the strip can mistake a swipe for a tap, so do not put a critical press on a strip button that also takes swipes.

Physical keys are what make a Stream Deck useful at a show position. You can find them by touch, you feel the press, and a key does not fire when a cable brushes it. Touch areas and dials are useful additions, but the cue that must not go wrong belongs on a key.

Rack-mounted panels

Desktop decks sit on a table, which is fine at FOH but not in a flight case, a broadcast truck or a machine room. Shows that build their control into racks use panels designed to mount in the standard 19-inch equipment rack, the metal frame that holds switchers, servers and processors.

The Stream Deck Studio is Elgato's rack panel. Elgato describes it as built to slot into standard 19-inch racks and supplies rack brackets in the box. It has 32 keys and two push dials, connects by Ethernet at 100 Mb/s, and takes power from the network cable using PoE+ (IEEE 802.3at) or from a USB-C supply. Because it sits on the network, the panel can live in the rack while the Companion computer sits elsewhere. It also has an NFC reader, and Companion can write the value of a scanned NFC card into a custom variable that you choose in its surface settings.

The second route into a rack is to build your own panel. Elgato's Stream Deck Modules are bare circuit boards with 6, 15 or 32 keys and a USB-C port, with no case or stand. Elgato sells them for building into custom controllers, rack panels and installations, and publishes CAD drawings for designers. Companion treats a module the same as the desktop deck of the same size.

Whatever route you choose, label the panel's network cable and note its address on the IP sheet, as Chapter 3 teaches. A rack panel that loses its network cable looks dead even though Companion is running.

Feet and hands

Some jobs keep the operator's hands busy. A playback operator on The Night Shift may be holding a phone for an actor while a scene resets. A media server operator at The Low Tides may be riding a fader while a song starts. A foot pedal or a jog wheel gives them one more control without letting go of what they hold.

The Stream Deck Pedal has three pedals and connects by USB-C, with a cable of up to 5 m. In Companion, each pedal is a button like any other. The X-keys XK-3 USB foot pedal comes in a front-hinged version that lets you rest the ball of your foot on the main pedal without pressing it; a little more pressure clicks it. Companion also supports VEC USB foot pedals. Because any foot can reach a pedal, put only safe, simple actions on it: next slide, play, a talkback.

For hands, jog and shuttle wheels come from editing. Companion supports the Contour ShuttlePro (versions 1 and 2) and Shuttle Xpress, and the Blackmagic DaVinci Resolve Speed Editor and Replay Editor. Their wheels can write their position into Companion variables, which a button can use to scrub a clip or step through a list. Some X-keys panels add T-bars and jog wheels, which Companion supports in a limited way through custom variables.

Test every pedal at your position before the show with cables dressed the way they will be. A pedal under a desk is easy to kick, and the operator beside you may not know it is there.

Other surfaces Companion can use

Companion calls any device that presses its buttons a surface. Since Companion 4.3, support for each family of surfaces comes as a surface module that is installed and updated like the modules for show gear. Before Companion can see a new kind of panel, the right surface module must be installed and switched on, from the Surfaces page.

Bitfocus publishes surface modules for a wide range of hardware. Among them are the Loupedeck Live, Live S and CT, the Razer Stream Controller and Stream Controller X, most X-keys panels, the Xencelabs Quick Keys, the Blackmagic ATEM Micro Panel, the Mirabox Stream Dock, Ulanzi stream controllers, the Logitech MX Creative Console, the iDisplay Infinitton, generic MIDI controllers and Mackie Control surfaces. The full list, with the models each module covers, is on the Bitfocus developer site.

A few of these come with cautions printed in their own help pages. Loupedeck panels need their newer firmware and the Loupedeck software must be closed. The ATEM Micro Panel must not be used while Blackmagic's ATEM software is also running, because both programs listen to its presses and change its colours. The lesson is the same as for the Elgato app: one program owns a panel at a time.

Companion also has surfaces that need no hardware at all. The emulator is a grid of buttons in a web browser that behaves like a Stream Deck. The Web buttons page shows button pages on a tablet or phone. Companion Satellite is a small program that runs on another computer and forwards the decks plugged into it to your main Companion over the network. Chapter 20 teaches all three.

Choosing a deck for the job

Choose hardware from your responsibilities, not from the catalogue. Count the machines you run and the moments you touch them, then pick enough keys to hold what you need without paging during a busy moment. Paging is when you switch the deck to another set of buttons; Chapter 6 explains pages.

Whatever you choose, carry a spare of the same model, plus spare USB cables. A spare of the same size means your pages fit it without changes. Companion's surface groups, covered in Chapter 21, let you swap a dead deck for the spare without rebuilding any buttons.

Check the cable route too. USB cables have length limits, and a deck far from the computer may be better on a Network Dock, a Stream Deck Studio, or Companion Satellite on a second computer.

How to do it

1. List your responsibilities and count the moments in the running order where you press something.
2. Choose the number of decks and their sizes so that the busiest moment needs no page change.
3. Check on Elgato's site and in Companion's surface module help that each model you choose is supported, and what its dials or strips can do in Companion.
4. Add a spare of each model and spare cables to the kit list.
5. Plan the cable route from each deck to the Companion computer, and choose a Network Dock, Studio or Satellite where USB will not reach.
6. Before the show, plug in every deck and pedal at its final position and press every key once with nothing connected that could fire.

What goes wrong

Practice it

You are building the video position for The Low Tides at a 3,000-seat theatre. You run the media server and two playback machines, with timecoded songs and a few manual holds. The media server operator in the machine room backstage also needs six safe buttons.

How Show Gear Talks

Every Companion button is a message sent from one machine to another, and almost always across a network. This chapter teaches that network from the very beginning: what an IP address is, what a subnet and a port are, how TCP, UDP and OSC differ, why show networks use fixed addresses and their own switch, and why Wi-Fi is a risk. It ends with the other ways into gear when there is no network.

Every Companion button is a message sent from one machine to another, and almost always across a network.

Commands over a network

Think of a text message. You type a few words, you choose who it goes to by their phone number, and the phone network carries it. The person at the other end reads it and acts on it. A Companion button works the same way. When you press CUT TO CAM 2, Companion writes a short message in the language the ATEM understands, addresses it to the ATEM, and sends it down the network cable. The ATEM reads it and cuts.

Three things must be right for that message to arrive. The address must be correct, so the message goes to the ATEM and not to the playback computer. The path must exist, so there is a cable and a switch between the two machines. And the language must match, so the ATEM understands what it receives. Companion's module handles the language. You handle the address and the path, and that is what this chapter teaches.

The network is the cables, the switch they plug into, and the settings on each machine that let them find each other. Most show networks use Ethernet: the familiar cable with a clip-in plug, called RJ45, running from each machine to a box called a switch. The switch passes each message to the cable that leads to the machine it is addressed to.

IP addresses and subnets

Every device on a network has an IP address, which works like a phone number. The common kind, called IPv4, is written as four numbers separated by dots, each number from 0 to 255. At Brightwater Health 2027, Companion lives at 10.0.0.10 and the ATEM at 10.0.0.20. When you add the ATEM to Companion, the address you type is 10.0.0.20, and every message for the ATEM goes there.

Two devices can only talk directly if they are in the same subnet, the same neighbourhood of addresses. The subnet mask says how much of the address names the neighbourhood and how much names the house. The most common mask on shows is 255.255.255.0. With that mask, the first three numbers are the neighbourhood and must match on every device, and the last number is the house and must be different on every device.

With a mask of 255.255.255.0, the last number can be anything from 1 to 254. The address ending in 0 names the whole subnet and the one ending in 255 is the broadcast address, which reaches every device at once, so neither is given to a device. That leaves 254 house numbers in the neighbourhood, more than any show position needs.

Some address ranges are set aside for private networks that never touch the internet. The internet standard RFC 1918 reserves three: 10.0.0.0 to 10.255.255.255, 172.16.0.0 to 172.31.255.255 and 192.168.0.0 to 192.168.255.255. Show networks use these. This book uses 10.0.0.x; you will also meet 192.168.0.x and 192.168.1.x, which many devices use out of the box.

Network settings on a computer also ask for a router or gateway, the device that passes messages to other networks such as the internet. A show network that is closed to the outside does not need one, and the field can be left empty. If the network has a gateway, the network's owner gives you its address.

A note on the mask's other spelling. You may see 10.0.0.20/24 instead of an address and a separate mask. The /24 means the first 24 bits, the first three numbers, are the neighbourhood. It is the same thing as 255.255.255.0.

Fixed and automatic addresses

A device can get its address in two ways. It can be given one by hand, called a static or fixed address, which stays the same until someone changes it. Or it can ask the network for one, using a service called DHCP. A DHCP server, often built into a router, hands out a free address to each device that asks. Home and office networks work this way, which is why a laptop usually connects without any setup.

Companion stores each device's address in its connection. If the ATEM's address changes overnight because a DHCP server handed it a new one, every ATEM button stops working until someone notices. Bitfocus's own setup advice is to use static addresses, or DHCP reservations, for the devices you control, so that their addresses do not change. A reservation is a DHCP setting that always gives the same device the same address.

When a computer is set to DHCP and finds no DHCP server, it gives itself an address of its own choosing, usually beginning 169.254. If you see a 169.254 address on the Companion computer, it is not on your show subnet and cannot reach your gear. Set it to a static address in your plan.

To set a static address, open the computer's network settings, choose the wired Ethernet adapter, change its IPv4 setting from automatic or DHCP to manual, and enter the address and mask from your plan. The names of these settings differ between Windows, macOS and Linux and between versions, but every system has them. Change only the wired adapter, so that Wi-Fi can stay as it is for email if the show allows it.

Ports

One computer can run many programs that listen to the network, so an address alone is not enough. If the IP address is the building, the port is the flat number: it says which program in that building the message is for. A port is a number from 1 to 65535.

Most gear listens on a port its maker chose, and the Companion module usually fills it in for you. The vMix module, for example, states that Companion uses vMix's TCP port 8099, and warns not to enter the Web Controller port in its place. The QLab module connects on port 53000 by default. Companion's own web page listens on port 8000 unless you change it.

Two programs cannot listen on the same port on one computer. If another program already holds port 8000, Companion's launcher lets you choose a different port. Write any port you change on the IP sheet.

Firewalls work on ports too. A firewall is software on a computer, or a box on a network, that blocks messages to ports it has not been told to allow. If a device can be reached by its address but Companion still cannot talk to it, a firewall on that device or on the Companion computer is a common cause.

TCP, UDP and OSC

Messages travel on the network in one of two main ways. TCP works like a phone call. The two machines first connect, then every message is checked on arrival, sent again if lost, and delivered in order. While the call is up, each side knows the other is there. UDP works like shouting across a room. The message is sent with no call set up and no check that it arrived. It is quick and simple, and on a good wired network almost every message arrives, but nothing tells the sender if one does not.

You rarely choose between them; the gear does. The ATEM uses UDP. The vMix module uses TCP. QLab accepts both, and its Companion module notes that its variables and feedback only work in TCP mode, because TCP lets QLab answer reliably. When a module gives you the choice, its help page says what each mode offers.

OSC, short for Open Sound Control, is a message format, not a third way of travelling. An OSC message carries an address that starts with a forward slash and names what to do, followed by values such as a whole number, a decimal number or some text. An invented example for a media server might be /layer/2/clip/4/play, or /fader/3 with the value 0.75. The OSC specification is transport-independent: OSC messages most often travel over UDP and can also travel over TCP.

OSC is popular in show software because it is readable and easy to add. Many media servers, playback programs, audio consoles and lighting consoles accept it. Each program's manual lists the OSC addresses it understands, and those addresses must be typed exactly, slashes and capital letters included.

A show network

A show network is a small, private network built for the show and nothing else. At Brightwater Health 2027 it is one switch in the FOH rack, with a cable to each device: the Companion laptop, the ATEM, both playback computers and the PowerPoint computer. The audio desk and lighting desk join it if their operators agree. Nothing else is plugged in, and it does not connect to the hotel's network.

For a network of this size, a simple gigabit switch of the unmanaged kind, one that needs no setup, is usually enough. Larger shows and touring systems use managed switches, which can be configured to separate departments into virtual networks. Those belong to the network technician; if you are given a port on one, ask which socket and which subnet are yours.

Why Wi-Fi is a risk on show networks

Wi-Fi shares the air with every phone, laptop and access point in the room. A ballroom full of conference guests, or a theatre full of concert fans, fills that air. Messages wait their turn, arrive late, or go missing, and a device can drop off the network for a few seconds and rejoin. A cue that fires a second late, or not at all, is a failed cue.

Bitfocus's own advice is to use wired networking with Companion whenever possible, because some devices react badly to the frequent disconnects Wi-Fi can bring. Hotel and venue guest Wi-Fi often stops connected devices from seeing each other at all, which breaks Companion entirely. If a tablet must use Wi-Fi for safe buttons, give it its own access point on the show network, keep its job small, and never put a show-critical cue on it.

Computers with two networks

A Companion computer may have a wired adapter on the show network and Wi-Fi on the internet at the same time. That works, as long as both are not on the same subnet. Companion's web interface listens on all of the computer's networks by default; the launcher lets you choose one, which Chapter 4 covers.

Addresses on paper

Every show network needs an IP sheet: one page that lists every device, its address, its mask, the port and protocol Companion uses to reach it, and who owns it. It is written before load-in, printed, and taped at each position. When something stops answering at five minutes to doors, the IP sheet is what lets anyone check it in seconds.

Notice the pattern in the plan. Each department or kind of device has its own block of numbers: the tens for control computers, the twenties for switchers, the thirties for playback, the forties for presentation, the fifties for audio and the sixties for lighting. A pattern makes an address easy to guess and a clash easy to spot. Playback A and B sit next to each other at 31 and 32 so that a third machine would naturally be 33.

Agree the plan with the other departments before the show. Audio and lighting often run their own networks for their own data, and their desks may already have addresses. A lighting desk at 10.0.0.60 on your switch is a decision the lighting designer makes with you, not one you make for them.

Keep the sheet with the Companion configuration file, update both together, and print a fresh copy whenever an address changes. An IP sheet that is out of date is worse than none, because people trust it.

Other ways in (serial, MIDI, HTTP, keystrokes)

Most show gear Companion controls today sits on a network. Some does not, and some offers more than one way in. Companion has modules for each of the common routes.

Keystrokes deserve a word of caution. A keystroke goes to whichever program is in front on the target computer. If a pop-up window has appeared over PowerPoint, the next-slide key goes to the pop-up. Chapter 13 teaches how to make keystroke control safe. On macOS, the VICREO Listener needs the Accessibility permission in System Settings before it can press keys.

Serial needs one more caution. A serial cable connects one device to one computer, so the Companion computer must be near the device or use a serial-to-network converter. Note the serial settings, such as the speed, on the IP sheet with the device.

How to do it

1. Read the IP sheet and find the address and mask set aside for the Companion computer, such as 10.0.0.10 and 255.255.255.0.
2. Plug a labelled Ethernet cable from the computer's wired port to the show switch.
3. In the computer's network settings, set the wired adapter's IPv4 to manual and enter the address and mask. Leave the router field empty unless the sheet gives one.
4. Confirm the computer shows the address you entered, not one beginning 169.254.
5. Open a terminal or command prompt and type ping followed by a device's address, such as ping 10.0.0.20, to check that replies come back. Press Control and C to stop it on macOS and Linux.
6. Repeat the ping for every device on the sheet, and mark each one as answering or not.
7. For any device that does not answer, check its cable, its switch port light, and its own address and mask before blaming Companion.

What goes wrong

Practice it

The Brightwater Health 2027 rental company delivers a second PowerPoint computer for the awards segment. Its network settings show IP address 192.168.0.112, mask 255.255.255.0, and its slide software is controlled by keystrokes through the VICREO Listener. Your show subnet is 10.0.0.x with mask 255.255.255.0.

Getting Companion Running

Before a single button can be built, Companion needs a computer, an install, a first launch and a few settings changed. This chapter covers which computer to run it on, how to install it, the launcher and the web setup page, plugging in a deck, the settings to change first, and how to keep the version stable through a show.

Before a single button can be built, Companion needs a computer, an install, a first launch and a few settings changed.

Which computer runs it

Companion runs on Windows, macOS and Linux, on a Raspberry Pi, and in a Docker container on a Linux server. Bitfocus's advice for a beginner is to start on your main computer, and to move to another computer later if needed, since the setup can be exported and imported.

Bitfocus does not support Raspberry Pi models older than the Pi 4. It lists the reasons: too little power to drive a Stream Deck, Ethernet sharing a USB bus with the decks, too little memory and too slow a processor. Do not save money on an old Pi for a show.

Companion can share a computer with other show software. Bitfocus notes that smaller setups often run vMix and Companion together. That fits a one-operator stream where vMix is the only machine. On a larger show, a separate Companion computer fits better: if the playback or PowerPoint computer freezes, Companion keeps running and can still command the backup machine.

Whatever computer you choose, check four things. It needs a wired Ethernet port, or a reliable adapter. It needs enough USB ports, and enough USB power, for your decks. It must not sleep, lock or install updates during the show. And you need a second computer, or a second Pi, set up the same way as a spare.

Installing and first launch

Download Companion from the Bitfocus website. Bitfocus offers a Stable build, which is tested and updated every few months, and a Beta build, which has newer features and occasional bugs. Start on Stable, and run Stable on shows.

On a computer with a screen, Companion opens with a small launcher window. Here you choose which network the web setup page is offered on, labelled GUI Interface, and the port, which is 8000 by default. Under the word Running, the launcher shows the address to open in a browser. The Launch GUI button opens that page on the same computer. The launcher also offers Start minimized and, on macOS and Windows, Run at login, which starts Companion when you log in.

The cog at the top right of the launcher opens deeper settings: the log level, a Developer section for module writers, Syslog for sending logs to a logging server, and a section called Dangerous Features. That section holds Shell command support, which lets buttons run commands on the computer, and Restricted modules. Both are off by default. Leave them off unless you know why you need them, because they let code run on the computer that hosts Companion.

On a Raspberry Pi there is no launcher. The first boot takes a few minutes while the system expands to fill the card. You then open the setup page from another computer at the Pi's address and port 8000, for example http://10.0.0.10:8000. On a headless install the launch settings are changed with Bitfocus's config tool from the command line.

The first time you open the setup page, Companion offers a Configuration Wizard. It walks through Surfaces, Button Grid, Buttons, Services, Usage Stats, Password and Timezone. You can run it again later from the Settings menu. Bitfocus recommends Google Chrome for the setup page and notes problems with the built-in browsers of older Android and iOS devices.

The setup page

Everything in Companion is built in a web page served by Companion itself, called the admin interface. You open it in a browser at the Companion computer's address and port 8000, such as http://10.0.0.10:8000, or at the address the launcher shows. It can be opened from another computer on the show network as well, which is useful when the Companion computer is in a rack.

The page has a sidebar on the left with every section of Companion, a large main panel in the middle and a second panel on the right for details and settings. On a wide screen you can drag the divider between them; on a narrow screen the panels combine. A help menu sits at the top right of the header.

Treat the admin interface as the keys to the show. Anyone who can open it can change or press any button. Bitfocus warns never to make it reachable from the internet, because doing so gives whoever finds it a way to run commands on your computer. On a show network that is closed to the outside, the risk is from people in the room; Settings to change first covers the password that keeps casual visitors out.

Plugging in a deck

Before plugging in, close the Elgato Stream Deck app if it is running. Then connect the deck by USB. Open the Surfaces page and the deck should appear in the list of configured surfaces with its model and a serial number. If it does not, press Rescan USB, or turn on Watch for new USB Devices so that Companion finds new decks by itself. On Linux, if Companion shows an alert about USB permissions, follow it to install the udev rules.

Click the deck in the list to open its settings. The ones to set on a show are its name, so that you know which deck is which, and the page it starts on.

Companion's button grid is 8 columns by 4 rows on a new install, the same as a Stream Deck XL. A deck with fewer keys shows part of the grid, starting at the top left unless you set an offset. The first column of a new page holds the page up, page number and page down keys that move a deck between pages; Chapter 6 explains them.

A good first test: open the Buttons page, type a word on one button, and watch it appear on the deck. Then press the key on the deck and watch the button flash in the browser. Hardware, software and the link between them are now working.

Settings to change first

Most of Companion's settings can stay as they are. A few are worth changing before you build anything, and a few belong to the computer rather than to Companion. Companion applies its settings as soon as you change them; there is no save button.

The computer needs its own settings. Turn off sleep, screen savers and screen locks on the Companion computer, or set them longer than the longest show day. Postpone system updates until after the show. Set the wired adapter to its static address from the IP sheet, as Chapter 3 showed. Close any program that does not need to run.

One more Companion setting deserves care. The PIN lockout on the Surfaces page can lock every deck after a time without use and ask for a PIN. That is useful for a deck in a public place, and a hazard for an operator who must press a cue after a long speech. If you turn it on, use Never pin code lock on the operator's decks.

Versions and keeping it stable

Companion changes often. At the time of writing, the Stable build is version 5.1. Since version 4.0, the modules for show gear are separate downloads that update on their own schedule, and since version 4.3 the surface modules for panels are too. Updating Companion does not update your modules for you; you update each one by hand from the Connections or Modules page.

That gives you control, and with it a responsibility. A module update can change how a device behaves, and a Companion update can change how the setup page looks or works. On a show, the safest version is the one you rehearsed on.

Each connection can run its own module version, so two ATEMs can even use different versions if one needs an older module. Companion marks modules that their maintainers have retired with a yellow Deprecated badge; when you see one, plan a move to the newer module after the show, not during it.

When you import a setup onto another computer, check on the Connections page that the module versions it needs are installed. Bitfocus's own guide reminds users to do this.

How to do it

1. Choose the computer and its spare, and check each has wired Ethernet and enough USB ports for your decks.
2. Set the wired adapter to its static address from the IP sheet, and turn off sleep, screen lock and automatic updates.
3. Download and install the Stable build of Companion.
4. Open Companion, choose the show network in GUI Interface, leave the port at 8000 unless the sheet says otherwise, and press Launch GUI.
5. Run the Configuration Wizard, set the Installation Name, and set the grid size for your largest deck.
6. Close the Elgato app, plug in each deck, give each a Surface Name and a Startup Page, and test one key on each.
7. Set the Admin UI Password and a backup rule, then export the setup and install the same versions on the spare.

What goes wrong

Practice it

You are setting up Companion for The Night Shift's playback department. The cart holds a MacBook, two playback computers and a monitor switcher. The cart sometimes sits idle for an hour while lighting is set, and the production office wants the laptop to install updates overnight.

Connections

A connection is Companion's link to one device. Until a device has a connection, no button can command it. This chapter explains what a connection is, how to add one, how to read its status, what to do when no module exists for your gear, and how to keep a show's connections tidy.

A connection is Companion's link to one device.

What a connection is

Think of a connection as an interpreter assigned to one person in a room. The interpreter knows that person's language, knows where they sit, and stays with them all day. When you want something from that person, you tell the interpreter. A Companion connection knows one device's control language and its address, and every button that commands that device goes through it.

Each connection is built on a module, the plugin written for a make of gear. The module supplies four things to your buttons: actions, the commands it can send; feedbacks, the states it can show on a key; variables, the values it can read back, such as a clip name or a time remaining; and often presets, ready-made buttons you can drag onto a page. Most modules are written and maintained by the Companion community.

Each device needs its own connection, even if two devices are the same model. Bitfocus's own example is two Barco E2 processors, which need two connections. On The Low Tides, Playback A and Playback B run the same software and still get one connection each, because each has its own address.

A module's help page is the first thing to read about any device. It lists what the module can do, which device models and software versions it has been tested with, and what must be set on the device for Companion to reach it. The ATEM module's help, for example, states that ATEMs must be controlled over a network and that USB control is not supported.

Adding a connection

Open the Connections page. The list on the right shows the modules you can add, with a search box. Since Companion 4.0, modules are downloaded from Bitfocus's module store rather than shipped inside Companion, so you may need to switch the list to show all available modules, not only the installed ones. On a computer with no internet, import the offline module bundle first from the Modules page.

Search for the device, choose it, and read its help from the same list before adding it. When you add it, a dialog asks which version of the module to use; installed versions are listed, and if the store is reachable Companion offers to install the latest. Then the connection's configuration opens in the right panel. Each module asks for what it needs. For the ATEM, the fields include Target IP, Model and Preset Style; Companion can also offer ATEMs it has found on the network. Fill in the fields and click Save.

Give every connection a clear label. The label appears wherever the connection is listed, and Companion also uses it in variable names, so a short, plain label such as atem or pbA makes later chapters easier. Labels like atem_1 or generic-tcp-udp_3 tell nobody anything at five minutes to doors.

Some devices must be told to accept remote control before any connection will work. QLab, for example, needs OSC access turned on in its own settings, and QLab 5 workspaces have an OSC passcode that must be entered in the Companion connection. The module's help page lists these steps; follow them on the device itself.

Reading connection status

Every connection shows a status in the Connections list. Learn to read it at a glance, because it is the first place to look when a button does nothing.

Hovering over a warning or an error shows the module's own message, which says more about what is wrong, such as a failed connection or a bad setting. A connection that stays red usually has one of the faults Chapter 3 describes: wrong address, wrong subnet, an unplugged cable, a firewall, or remote control switched off on the device.

For more detail, the menu at the end of each connection's row offers Help, Known Issues, Variables and View Logs. Variables is a quick live test: if the device's values, such as the input on program, change as the device changes, the connection is working. View Logs shows the module's own debug messages, which a module's authors may ask for when you report a bug.

Companion also counts connection states in internal variables, such as $(internal:instance_errors) for the number of connections with an error, and the status of each connection by its label. Companion also has internal feedbacks that show a connection's status on a key. Chapters 7 and 8 use these to build a status key, so a red key on the deck warns you before you press a cue that cannot land.

When there is no module (generic TCP/UDP/OSC/HTTP)

Bitfocus lists more than 700 supported devices and programs, but some gear will still be missing. If the device has a documented control protocol, you can usually reach it with one of the generic modules. They send exactly what you type and nothing more, so they need the device's protocol manual beside you.

A generic connection is less helpful than a dedicated one. It usually knows nothing about the device's state, so keys cannot turn red when something is live unless you build that yourself from the replies. Test every command on the device in prep, write each one on the button's notes, and keep the protocol manual with the show files.

Bitfocus asks users of the generic modules to request a proper module for their device, on the companion-module-requests page on GitHub, so that others benefit. Some community members can be hired to write modules, and Bitfocus will quote for module work.

Never invent a command. If the manual does not list it, or you cannot test it before the show, it does not go on a button.

Keeping connections tidy

A show's Connections page should read like its IP sheet: one line per device, a clear label, the right address, and nothing left over from the last job. A tidy page is faster to check before doors and easier for a colleague to take over.

When the list grows, Companion's collections help. Click Create Collection above the connections table, name it, and drag connections into it. Collections can sit inside other collections. Each collection has its own enable switch, and switching a collection off disables every connection inside it; when it is switched back on, each connection returns to the state it had.

One connection per device is also a courtesy to the device. Some gear accepts only a limited number of control connections, and a forgotten duplicate connection, or a second Companion pointed at the same device, can use up a slot another operator needs. Check the device's manual if you are sharing gear with another department.

Updating a connection's module is done from its configuration panel, with the pencil next to the version number. Saving restarts the connection. Do it outside show week, as Chapter 4 explains, and test every button that uses the connection afterwards.

How to do it

1. Find the device on the IP sheet and ping its address from the Companion computer.
2. On the Connections page, search for the device's module and read its help, including anything that must be switched on at the device.
3. Enable remote control on the device as the help page describes.
4. Add the connection, choose the module version, give it a clear label, enter the address and any other settings, and click Save.
5. Wait for the green tick. If it stays red or yellow, hover over it, read the message and fix the cause.
6. Open the connection's Variables and change something on the device to see the values follow.
7. Build one test button with one harmless action, such as setting preview rather than program, press it, and confirm the device responds.

What goes wrong

Practice it

At Brightwater Health 2027 you add connections for the ATEM at 10.0.0.20, Playback A at 10.0.0.31 and Playback B at 10.0.0.32. The venue also has a house projector that has no Companion module, but its manual lists text commands over TCP. After adding everything, the ATEM shows a green tick, Playback A shows a red triangle and Playback B shows a green tick.

Building a Button

A button is the smallest unit of show control: one key, one label, one or more commands. This chapter walks through building one in Bitfocus Companion, from where it sits on a page to what it sends on press and release, how its commands are ordered, how it looks, and how to copy and reuse it. Everything here is checked against Companion 5.1.2, the current release in November 2026.

A button is the smallest unit of show control: one key, one label, one or more commands.

Pages, rows and keys

Open Companion's admin page in a browser and click the Buttons tab. What you see is a grid of empty squares. Each square is a button, and the grid is one page. A Stream Deck plugged into the Companion computer shows part of that page on its keys: press a key on the deck and Companion runs whatever is on the matching square. The deck is only a window onto the grid. The buttons themselves live in Companion.

A new Companion installation starts with one page, and you can add as many as you like; Companion has allowed unlimited pages since version 3.5. Pages are listed in the Pages tab on the right of the grid, where you can add, reorder and name them. Name every page. A page called "BW Awards" tells you, and the next operator, exactly what it holds. A page called "7" does not.

The grid has a size, set in Settings under Button Grid with Configure Grid Size. A new installation uses 8 columns by 4 rows, which is 32 buttons, the same shape as a 32-key Stream Deck XL. The grid can grow in all four directions, so you can add rows above or columns to the left of what you already have. A smaller deck, such as the 15-key Stream Deck MK.2 with three rows of five keys, shows the top-left corner of the page unless you move it with that surface's Horizontal Offset in grid and Vertical Offset in grid settings on the Surfaces page.

Every button has an address written as page/row/column, for example 1/0/1. Rows and columns count from 0, so 1/0/0 is the top-left button of page 1 and 1/0/1 is the one to its right. You will see these addresses on the yellow top bar of each key (if the top bar is turned on) and you will type them whenever one button needs to point at another.

Moving between pages is done with buttons too. New pages put three navigation buttons in the first column: Page up, Page number and Page down. Pressing Page number takes the deck back to its startup page. If you clear them and later want them back, the Page actions menu (the three dots next to the page selector) has Recreate navigation buttons. Companion also has internal actions, Surface: Set to page, Surface: Increment page number and Surface: Decrement page number, so any button can jump a deck to a chosen page.

One warning from the Companion guide is worth learning before the first show: be careful when reordering pages or inserting a page into the middle of the list. Anything that points at a page by its number, such as a Surface: Set to page action, is not updated for you, and existing buttons can break. Add new pages at the end, and only reorder before the show is built.

The kinds of button

Click an empty square and Companion asks what kind of button to create. Most of the time the answer is a regular button.

The three page buttons have built-in behaviour. To restyle one, open it and use Edit to Convert to Normal Button, which turns it into a regular button with the matching actions already filled in. That conversion is one way and cannot be undone.

Every button also has a Notes field near the top of the editor. Nothing typed there appears on the key. Use it to write why the button exists and what it fires: "Opener. Cuts ATEM to Playback A, takes clip 1 on A and B. Owner: video." Notes are what let you, or someone covering for you, understand a show file months later.

Starting from a preset

A connection is Companion's link to one piece of gear, covered in chapter 5. Many connections come with presets: ready-made buttons with a label, actions and feedbacks already set. They live in the Presets tab on the right of the grid, grouped by connection. Drag one onto a square and you have a working button. The Blackmagic ATEM module, for example, offers preset buttons for each input on preview and on program, already coloured to show which input is live.

Since Companion 5.1, presets can be placed two ways, chosen with the When placed toggle at the top of the Presets tab. Linked, the default where the module supports it, keeps the button tied to the preset: when the module improves the preset, the button updates too. You can still switch a linked button to another connection of the same module, and change the values that make it different, such as which input it selects. Copy places a one-off button you can edit freely. A linked button can be turned into a normal button at any time with Edit at the top of the editor; that cannot be undone.

Presets are written by the module author, so you cannot create your own. Not every module has them. The Companion guide's suggestion for building your own library is to keep pages of finished buttons and export them, which the last section of this chapter covers.

Actions on press and release

An action is one command sent to one connection: cut the ATEM, take a clip on Playback A, press the right-arrow key on the PowerPoint computer. A button can carry many actions, from many connections. You add them in the button's actions area by searching in the box or browsing with the folder button. As well as the modules' actions, Companion has its own internal actions for things like waiting, changing pages and setting variables.

A button has separate groups of actions for different moments. Press actions run when the key goes down. Release actions run when it comes back up. Most show buttons need only press actions, because you want the command to leave the moment your finger lands.

Duration groups are added with Add duration group. Each has a time and a choice, Execute while held, that decides whether it fires while you are still holding or when you let go. As soon as a button has a duration group, its Release actions are renamed Short release actions, because they now run only on a short press.

Holding is a useful safety tool. Put a dangerous command, such as a fade to black on the ATEM, in a duration group of 1,000 milliseconds with Execute while held ticked, and nothing happens unless the operator holds the key for a full second. A brush of the finger does nothing. Chapter 16 returns to protecting the dangerous buttons.

Many module actions have a Learn values button beside them, which Companion describes as capturing the current values from the device. Set the ATEM to the transition you want, press Learn values on the action, and the action's options fill in to match. A few modules also support the Action Recorder, which builds a list of actions while you operate the device itself. Very few modules support it, so check the module's Help first.

To try a button without a deck, choose the Press tool in the toolbar above the grid and click the button: it runs its actions, exactly as if pressed on a surface. Older versions pressed a button on Shift-click; Companion 5.1 replaced that with the Press tool. Because the press sends live commands, only test on gear that is safe to move, never on anything feeding the room or the stream.

Order and delays

When a button has several actions, it matters when each one leaves. By default, actions at the top level of a list are sent concurrently: all at once, in parallel, as fast as Companion can send them. For most buttons that is what you want. A key that takes the same clip on Playback A and Playback B should fire both together.

To hold something back, add the internal action Wait. Its setting is Time expression (ms), a time in milliseconds, so 1,000 is one second and 500 is half a second. A Wait delays every action that comes after it in the list. Since Companion 3.5 this replaces the separate delay setting older versions had on each action.

For more control, add the internal action Action Group. It holds other actions, including more groups, and its Execution mode decides how they run.

Sequential has one catch, stated in Companion's own tooltip: if a module does not report when a particular action has finished, the next action starts immediately. Many modules do report it, but not all. If the order is critical, test the button on the rig and, where a device needs time to settle, put a Wait in.

Here is a worked example from Brightwater Health 2027. The opener video sits in clip 1 on both playback machines, and the ATEM has Playback A on input 3. The opener key needs the video on screen first and the clip rolling a moment later, so nobody sees a frozen first frame cut away from.

The two takes leave together, so A and B stay in step, and the ATEM cuts a fifth of a second later. Whether that delay belongs there, and how long it is, depends on the machines; rehearse it and adjust it. The point is that the order is written on the button, not left to luck.

Companion also has Logic: If statement, which runs its Then actions only when its conditions are true and its Else actions otherwise, and Logic: While loop, which repeats while its conditions are true. The guide warns that a While loop with no Wait inside repeats as fast as it can, up to hundreds of times a second, flooding your devices with commands; a Wait of even 100 milliseconds inside the loop prevents that.

Once a button is running, a green play arrow appears among its status icons while actions are still running or queued, for example during a Wait. Right-click the button in the grid and choose Abort Actions to stop what is still pending, and the internal actions Actions: Abort button runs and Actions: Abort all button and trigger runs do the same from another key. Keep an abort key on the page if you build long sequences.

Buttons that step

A stepping button does something different each time it is pressed. In Companion this is done with steps, which since version 3.0 replace the older Latch setting. Open a button and click Add step: a second tab of actions appears. The first press runs Step 1, the next press runs Step 2, and the button keeps cycling. You can add as many steps as you need, and each step has its own press and release actions.

How a button moves between steps is set with Step Progression in the button's options.

Steps are handy, and they carry a risk on a show: a stepping button only knows how many times it has been pressed, not what the device is actually doing. If a Play/Pause key is on step 2 and someone pauses the machine with its own mouse, the next press sends the wrong command. Two ways round it both work. One is separate keys, PLAY and PAUSE, which always send the same thing. The other is a stepping key whose step follows the device, using Step Progression set to Expression with a variable the module reports. Use separate keys for anything that goes to air, and stepping keys where a wrong press is harmless.

The current step is visible: with the top bar on, the key shows its step, and the internal feedback Button: Check step can change the key's colour on a chosen step, which chapter 7 covers.

Naming and colour

A label is the operator's only guide to what a key does, often read in the dark, at speed, out of the corner of an eye. Good labels are short, in capitals or a consistent case, and name the outcome, not the mechanism: "OPENER" not "PB A CLIP 1 TAKE". Colour then tells you the family the key belongs to before you have read a word.

Companion 5.0 rebuilt how buttons are drawn. Instead of one fixed style, a button is a stack of graphics elements, layered like an image editor, edited in the button's Style tab. A new button starts with a Background element, which is a Box filling the whole key, and a Text element on top. Elements higher in the list are drawn over the ones below.

The Text element's Button text string holds the label. To force a second line, type a backslash and n where the break should go, so OPENER\nVIDEO prints on two lines. Font can be Default or Monospace; Monospace keeps numbers lined up, which suits timers. Weight is Normal or Bold, and Styles adds italic, underline or strikethrough.

Text size changed in 5.0. Text Size is now a percentage of the Text element's height, and Shrink to fit, when ticked, lets Companion shrink the text below that size if it would not otherwise fit, down to a tenth of the element's height. Set a comfortable size, tick Shrink to fit, and a short label stays big while a long one still fits. Colour sets the text colour, and Outline Colour draws a contrasting edge round each letter, which keeps text readable over a picture.

Images go in an Image element. You can upload a file straight onto the button or pick one from the Image Library in the sidebar. The library takes standard formats such as PNG, JPEG and SVG, and its page notes that square images of 72 by 72 pixels or larger generally look best, since Companion scales them to fit. Older Companion versions spoke of a PNG background; today the same job is an Image element. Use the library when the same picture appears on many keys: replace it once and every key follows. Fill Mode sets whether the picture is fitted whole, fills the key and crops, or is cropped without scaling.

Since 5.1, the Pinned view in the elements list gathers the properties you change most often, the text, its size and colour, and the background colour, in one place. Leave Pinned selected and every button you click opens straight onto its label and colours, which makes relabelling a page of keys quick.

The Canvas, at the bottom of the elements list, controls the frame around the key. Decoration can show the Top bar, with the button's location and its current step; Border when pressed, which hides the bar and draws a coloured border while the key is down; or None. The global default lives in Settings under Buttons. Show status icons controls the small icons in the top-right corner.

Leave status icons on for show buttons. A red triangle on the OPENER key during the line check tells you Playback A has dropped off the network before you find out on the cue.

A colour plan for the show

Decide colours once per show and write them on the paperwork. The exact colours are yours; the discipline is that each colour means one thing everywhere on every deck.

Keep red and green out of resting colours, because they belong to tally, which chapter 7 explains. A key that is red all the time teaches the operator to ignore red.

Copying, importing and reusing

Most of a show file is copies of a few good buttons. The toolbar above the grid chooses what a click does. Select, the default, opens a button in the editor; you can also drag a box across the grid, Shift-click a range or Ctrl-click (Cmd-click on a Mac) to select several. Multi adds each click to the selection, which is easiest on a touchscreen. Arrange lets you drag buttons to new places. Press runs a button's actions.

The second group of tools rearranges: Copy, Move, Swap and Delete. Pick a tool, click the button, then click where it should go, which can be on another page. The tool stays active, so you can stamp the same button several times; press Escape to go back to Select. Right-clicking a button gives Copy, Cut, Paste here, Swap here, Paste as reference and Clear, and when several buttons are selected the menu acts on all of them. The usual keyboard shortcuts work when the grid has focus: Ctrl or Cmd with C, X and V to copy, cut and paste, Delete to clear after a confirmation, and Page Up and Page Down to change page.

A Button reference, added in 5.1, is a live copy rather than a duplicate. Its only setting, Mirrored location, is the address of the button to mirror, such as 1/0/1. It looks exactly like that button and pressing it presses that button. Put one CUT key on page 1 and a reference to it on every other page, and there is only one CUT to maintain. If the location is empty or invalid the key shows Unresolved Reference.

Whole pages travel too. The Page actions menu has Export page, which saves that page's buttons to a file. The Import / Export page saves or loads a whole configuration as a .companionconfig file, in Compressed (the default and the smallest), JSON or YAML format. On import, the Full import tab chooses which parts of a file to bring in, and the Buttons and Triggers tabs import just some pages or triggers and can remap their connections, so a page built for one ATEM can be pointed at the ATEM on the next show.

The guide's advice is to export your current configuration before any import, in case you make a mistake. Two details catch people out. When you import a page into a different page number, button references are not adjusted, so check them. And since Companion 4.0 modules are separate downloads, so the computer you import onto needs the right module versions installed; the Connections page lets you choose and install them.

Over time, build a library: a page of transport keys, a page of ATEM keys, a page of PowerPoint keys, each exported to a file named for what it holds. A new show then starts from tested buttons rather than from an empty grid.

How to do it

1. Write down what the key must do in one sentence, and which machines it touches, before opening Companion.
2. On a named page, click the square where the key belongs and choose Regular button, or drag a preset if one does the job.
3. Add the press actions in the order they should leave. Add a Wait where a machine needs time, or an Action Group set to Sequential where order matters.
4. If the key is dangerous, move its action into a duration group with Execute while held, so it fires only on a deliberate hold.
5. Label it with the outcome, in the show's colour for its family, with status icons left on. Write what it does in Notes.
6. Test it with the Press tool or the deck on gear that is safe to move, watching each machine respond in the right order.
7. Export the page, and copy the key with Copy or a Button reference wherever else it is needed.

What goes wrong

Practice it

Brightwater Health 2027. You are building the key that starts the awards segment. When pressed, the awards sting must roll on Playback A and Playback B (clip 5 on both), and half a second later the ATEM must cut to Playback A on input 3. The director also wants a FADE TO BLACK key on the same page that cannot be fired by accident.

Buttons That Show State

A key that only sends commands leaves you guessing whether they arrived. A key that shows state tells you what is live, what is next and how long is left, so you can work by looking at the deck instead of turning round to every screen. This chapter covers feedbacks, tally colours, time and state on the key, and how much one key can carry, as they work in Companion 5.1.2.

A key that only sends commands leaves you guessing whether they arrived.

Feedbacks

A feedback is a rule that changes how a key looks, on its own, based on what is happening. The Companion guide's examples are exactly the ones a show needs: a key that turns red when a camera goes live, shows a different label when a mixer channel is muted, or lights up while a layer is on air. Nobody presses anything; the key changes because the gear changed.

The information comes back from the gear. When you add a connection, many modules do not only send commands, they also listen to the device and keep track of its state. The ATEM module knows which input is on program and which is on preview. The QLab module, in TCP mode, knows which cue is running. That state is what feedbacks read. It follows that feedback only works when the connection is talking both ways: if a device cannot report its state, or the module does not ask, the key cannot show it.

Feedbacks are added in the button editor, in the feedbacks list under the actions. Some modules' feedbacks have a Learn values button too, which fills the feedback's options from the device's current state.

Feedback is information, never a guarantee. A green key means Companion believes something, based on the last thing the device reported. Before doors, check each feedback against the device itself once: put Camera 2 on preview at the ATEM and make sure the right key turns green.

How a feedback changes a key

Companion 5.0 changed how feedbacks work, because buttons are now built from layered elements (chapter 6). A boolean feedback no longer sets a single button style. It overrides properties on chosen elements while its condition is true. Each feedback has a Style Overrides table. Click the plus sign to open Add Element Properties, pick which element to affect, such as the Background or the Text, pick which properties to change, such as Colour, and set the value. While the feedback is true, those values replace the element's own.

A feedback with no overrides does nothing, and Companion says so. One feedback can carry several overrides: turn the Background red and the Text white together, so the change is unmistakable.

Order matters when two feedbacks change the same property. Feedbacks are applied from the top of the list down, so the one lower in the list wins. The guide flags that this is the opposite of Companion 4.x, where the higher one won. A file built under 4.x is converted automatically to target the standard Text, Image and Background elements so it looks the same, but if you rearrange feedbacks after upgrading, remember the new rule. Put the most important state, usually program tally, at the bottom so it beats everything else.

Hover over the icon beside the Style Overrides heading to see which type a feedback is. Since 5.1, value feedbacks can restyle a key. The guide's example turns text red when a level goes above minus 6: the override is the expression $(this:value) > -6 ? 0xff4040 : 0xffffff, which returns red if the value is above minus 6 and white otherwise.

There is now a second route to a key that reacts. Every property of every element can be an expression instead of a fixed value, switched with the button at the end of its row, and it redraws whenever a variable it uses changes. A Text element's Colour can be an expression that returns red or green; its Enabled field can be blink(500) to make it flash. The guide's advice is to use whichever is clearer for the button. Feedbacks suit state that comes from a connection, and several changes that switch on and off together as one rule. Expressions suit a single property driven by a variable.

Feedbacks Companion provides itself

Companion's internal connection supplies feedbacks that do not depend on any device. These are the ones you will use most on a show.

Connection: Check Status deserves a key of its own for every machine you depend on. Built once per connection, the row of keys reads like a dashboard: Playback A green, Playback B green, PowerPoint orange. Companion also shows the same problem on each affected key, with the red and orange triangles among its status icons. Between the two, a dropped machine is visible on the deck before its cue, not on it.

Tally colours

Tally is the light that says what is live. It comes from television, where a red lamp on top of a camera tells the camera operator and the presenter that the camera is on program, the output going to air, to the screens or to the stream. Preview, the source lined up to go next, is shown in green. Switcher panels use the same language: the program row lights red and the preview row green. On a deck, tally means the keys follow the same rule.

The ATEM module shows how a module carries tally. Its feedbacks include Tally: Program, which by default turns the key's background red with white text when the ATEM reports the chosen input as on program, and Tally: Preview, which by default turns it green with black text when the input is on preview. It also has ME: One ME program source and ME: One ME preview source, which check one mix effect bus only. The module's preset buttons for program and preview use a black key with white text that turns green for preview and red for program.

Keep tally colours for tally. If a red background means program on the ATEM keys, nothing else on any deck should rest in red. Then a single glance answers the question every operator asks most: what is on the screens right now?

Tally is not only for switchers. A playback key can show which clip is running, a QLab key can turn red while its cue is playing (the QLab module has feedbacks such as Show Cue # is Running), and a mic key can show muted or open. Use the same meaning. Red is what the audience is seeing or hearing now; green is what is lined up.

Some decks do not have full colour screens. The Companion guide notes that some surfaces show a button's state more simply, with a coloured LED or a ring of lights, and Companion normally picks which element to use for that. If it picks the wrong one, set that element's External Usage to Colour so the LED follows the tally colour.

Time and state on the key

A key's text can hold a variable as well as a fixed label, and the variable updates on the key as it changes. Chapter 8 covers variables fully. Here are the ones that matter most for showing state: the time, what is on program, and what is playing.

The part before the colon is the connection's label, which you set when you add the connection. The QLab module's own Help calls its default label qlabfb, so either keep it or rename it to something short before you build keys on it. Each module's variables are listed under Variables in the connection's menu on the Connections page.

A Text element can also be switched to Expression mode, which does calculations. The guide's example is a countdown to a 19:30 show start: secondsToTimestamp(max(0, timeDiff($(internal:time_hms), '19:30:00')), 'HH:mm:ss'). Put that on a key with the Monospace font and the digits do not jump about as they change. A countdown to a speaker's end time, a clock showing the show's local time, and the remaining time on a clip are the three most useful time keys on a corporate show.

Since Companion 5.0 a Gauge element shows a number as a bar or a ring that fills as the value rises. It has Minimum and Maximum, and Colour stops that change the fill colour at chosen values. A gauge across the bottom of a playback key, filling as the clip plays and turning orange near the end, tells you more at a glance than any number. It needs a variable the module provides, such as QLab's seconds elapsed and total run time.

The key's own state is visible too. With the top bar on, a stepping key shows its step, and while a key is held the top bar fills with colour or, in Border when pressed mode, a border is drawn. The guide notes that this pressed look stays on if a key was pressed by an action without a matching release, which is a clue when a key looks stuck.

Time keys for Brightwater Health 2027

Too much on one key

A Stream Deck key is small; the guide's own aspect-ratio previews exist because keys come in several shapes, most of them square. It is tempting to put a label, a clock, a gauge, an icon and two feedbacks on one key. On a show, the operator reads the key from half a metre away, in the dark, while listening to the director. One key should answer one question.

A working rule is two lines of text at most, one colour that means something, and one optional gauge or dot. If a key needs more, it needs a neighbour. Information keys that only show state, such as CLOCK or PGM, can have no actions at all; give them a resting colour that is clearly different from keys that fire things, so nobody presses one expecting a cue.

Blinking is the loudest thing a key can do, and it stops meaning anything if it is used everywhere. Keep blink() for faults that need you now, such as a playback machine in error, and nowhere else.

How to do it

1. Check the ATEM connection is OK and that its state is updating: change preview on the ATEM and watch the module's preview variable change on the Variables list.
2. On each input key, add the ATEM feedback Tally: Preview, pick the key's input, and check its overrides set the Background to green.
3. Add Tally: Program below it, so it wins when an input is on both, with overrides for a red Background and white Text.
4. Set every key's resting Background to a colour that is neither red nor green.
5. Put each input on preview and then on program at the switcher, and check the matching key changes each time.
6. Add a Connection: Check Status key for the ATEM, so a dropped connection is visible before a stale tally misleads anyone.

What goes wrong

Practice it

The Night Shift. On a hotel-room set, Leo watches the news on a wall TV fed from Playback A, and his laptop on the desk shows a looping clip from Playback B. The director wants to know at a glance which machine is playing, and the first assistant director wants to see when the news clip will end so the line about Nora Vance lands on time.

Variables and Triggers

Variables let a key show and use information that changes: the time, the clip on air, the next presenter. Triggers let Companion act without anyone pressing a key: at a time of day, when a value changes, when Companion starts. Together they turn a panel of buttons into a small control system, and they need care, because a trigger can fire a command when nobody is watching. Everything here is checked against Companion 5.1.2.

Variables let a key show and use information that changes: the time, the clip on air, the next presenter.

What a variable is

A variable is a named box that holds a value. The name stays the same while the value inside changes. On a show, plenty of things change all the time: the clock, the input on program, the cue running in QLab, the slide number. Companion keeps each of those in a variable, so a key, an action or a trigger can use the current value without anyone retyping it.

Every variable is written the same way: a dollar sign, then in brackets the source and the name with a colon between, such as $(internal:time_hms). The source is internal for Companion's own variables, the connection's label for a module's variables, or custom for the ones you make. You can see most of them on the Variables page, split by type. Any input field that accepts variables shows a small variables icon; fields without it usually do not.

Connection variables are read-only and only exist if the module provides them; not every module does. Look under Variables in the connection's menu on the Connections page to see exactly what each one offers. The internal variables include the date and time, from $(internal:time_hms) to $(internal:date_monthname), and the health of your connections, such as $(internal:instance_errors), the number of connections in error, and $(internal:connection_atem_status) for one connection labelled atem, which reads good, warning, error or disabled.

Because a connection variable starts with the connection's label, pick short, clear labels when you add connections and keep them for the run of the show: atem, pbA, pbB, ppt. Every key that shows $(pbA:...) depends on that label.

Variables on keys

The most common use is text on a key. In a Text element, the Button text string in Variables mode is plain text with variables dropped in. PGM $(atem:pgm1_input) shows the word PGM and the name of the ATEM input on program. When the input changes, the key changes.

Variables also go inside action and feedback options wherever the variables icon appears. A key that sends the PowerPoint computer to a slide number can take that number from a variable. A feedback can compare a module's variable with a value. And with a button reference (chapter 6), even the location being mirrored can contain a variable.

Companion also gives each button some values about itself under this, such as $(this:page), $(this:row), $(this:column), $(this:step) and $(this:actions_running). They are useful when you copy one key across a page and want each copy to know where it is, and they are what makes a key like $(this:page)/0/0 point at the top-left key of its own page.

Page variables, added in 5.1, belong to a page and are shared by all its buttons as $(page:name). They are made in the Page Variables tab next to the grid. On Brightwater Health 2027, a page variable called presenter could hold Dana Okafor on one page and Martin Lowe on a copy of it, so the same buttons label themselves for each speaker. Page variables travel with the page when it is exported. Triggers do not belong to a page, so they cannot read page variables, though they can set them.

Custom variables

Custom variables are the ones you create, on the Variables page. Each has a name, a Current value, a Startup value used when Companion restarts, and a Persist value option that keeps the current value across a restart. The guide notes that persisting increases disk activity, so use it only where losing the value would hurt.

A custom variable can hold text, a number, true or false, a list or a structured object. The value field has a switch: T for text, or the curly-bracket symbol for JSON, where you type a number, true or false, or a list such as ["Dana Okafor","Martin Lowe"]. Text is easier to enter in text mode.

Three internal actions change them: Custom Variable: Set value, Custom Variable: Reset to startup value, and Custom Variable: Write current value to startup value. Set value accepts an expression, and inside it $(this:current) is the variable's current value, so $(this:current) + 1 counts up by one. Some module actions also return a result, and those actions offer a Store Action Result option that writes the result into a custom, page or local variable.

The guide's own description of what custom variables are good for includes aliases for values you may need to change, so you update them once rather than in hundreds of places. On a show, that is the clip number for the opener, or the slide number where the awards section starts. When the client moves the awards slide, you change one variable instead of six buttons.

Local variables, available since 4.1, live inside one button, trigger or expression variable as $(local:name) and cannot be read from outside it. They can take a value you set, the result of an expression, or the state of a feedback, which lets one key build its own logic without cluttering the shared list.

Expressions

An expression is a small formula. Where a normal field only swaps variables into text, an expression can do maths, compare values, make decisions and format text. Text inside an expression is quoted, numbers are not, and true and false are written as words.

The question mark form is the one you will use most: a condition, then what to return if it is true, a colon, and what to return if it is false. Expressions work in button text in Expression mode, in any element property, in the value of Custom Variable: Set value, in the internal feedback Variable: Check boolean expression, in expression variables and local variables, and in trigger conditions. Since 4.3, modules can support expressions in any action or feedback field, shown by an expression toggle beside the field; not every module has been updated yet.

The guide points out the most common confusion. In a normal text field, Cam $(atem:input_1_name) prints the word Cam and the variable. In an expression field the whole field is one formula, so the same text is an error; text must be in quotes. If a field shows an error, check which mode it is in.

Expression variables, made on the Variables page, hold an expression that recalculates automatically. Build a countdown once as an expression variable and every key that shows it reads the same number.

Triggers

A trigger is a set of actions that runs when something happens, instead of when someone presses a key. Triggers live in the Triggers tab. Click Add Trigger, give it a name, and fill in its three parts. A new trigger starts disabled, so it cannot run until you are ready.

The events available in Companion 5.1.2, as named in the program, are these.

Conditions are checked again at the moment an event fires, so they always see the current value. The Actions part can do anything a button does. To make a trigger do exactly what a key does, use Button: Trigger press and release and point it at the key; its Hold duration (ms) option holds the key down first, for keys with long-press actions. The trigger's edit panel also has a Test actions button, which runs its actions now.

Triggers can be grouped into collections, and the internal actions Trigger: Enable or disable trigger and Trigger: Enable or disable trigger collection switch them from a key. That gives you a TRIGGERS ON / OFF key on the utility page, with the internal feedback Trigger: When enabled or disabled to show which it is.

Here is a worked trigger for Brightwater Health 2027. Doors open at 08:30 and the walk-in loop must be on screen before then. A trigger named WALK-IN AUTO has the event Time of Day at 08:25 on the show day, the condition Variable: Check value with show_mode equal to show, and the action Button: Trigger press and release on the WALK-IN key. If anyone is in rehearsal mode, nothing happens. Two more triggers worth having on most shows are a Startup trigger that runs Surface: Set to page so each deck opens on its home page, and an On condition becoming true trigger, using Connection: When matches specified status, that turns on a warning variable when a playback machine goes into error.

Another example comes from the Allen & Heath SQ module, whose Help describes a sceneRecalledTrigger variable that changes every time a scene is recalled on the desk, intended for use in triggers. An On variable change trigger watching it can update a key showing the current scene, or remind the video operator that audio has moved on. This only works if the module provides such a variable, which is why the module's Help is always the first place to look.

Using them safely

A key does nothing until a person decides to press it. A trigger fires on its own, when you may be looking the other way, during rehearsal, or while the client is mid-sentence. That is the reason triggers start disabled, and it should shape every one you build.

Tell the show caller, and the other departments, about every trigger that can affect their world. A walk-in loop that rolls by itself at 08:25 is a cue like any other and belongs on the paperwork. The same goes for the reverse: if audio has a trigger watching your machines, you need to know.

Variables bring their own care. A key that displays a variable shows the last value Companion received; if the connection drops, the value may be stale. Keep status keys beside the ones that matter. Be careful with names: actions and keys that point at a custom variable or a connection label by name need checking if you rename them, and pages that are reordered break anything that points at a page by number. And avoid loops between local variables that depend on each other, which the guide warns will use excess processor time.

Finally, every machine keeps its own controls. Variables and triggers can make the deck feel like it runs the show, and it does not. If Companion stops, the operator at each machine must still be able to play, stop and switch by hand.

How to do it

1. Create a custom variable show_mode with a startup value of rehearsal, and a key that sets it to show and another that sets it to rehearsal, each with a feedback showing the current mode.
2. Build and test the key the trigger will press, such as WALK-IN, on safe gear.
3. In the Triggers tab, click Add Trigger, name it for what it does, and write its purpose in Notes.
4. Add the event Time of Day with the time and the show day.
5. Add the condition Variable: Check value, show_mode equal to show.
6. Add the action Button: Trigger press and release, pointing at the WALK-IN key.
7. Use Test actions with the gear safe, then enable the trigger, and put the automatic cue on the paperwork and tell the show caller.

What goes wrong

Practice it

Brightwater Health 2027. The awards segment has eight awards. Each has a sting on the playback machines (clips 11 to 18) and a name on the next-up screen. The producer wants the deck to show which award is next, and wants the house music in the break to stop at exactly 10:58 so the VOG can call people back at 11:00.

Your Job Decides the Layout

There is no standard Stream Deck layout, because there is no standard job. What goes on the keys depends first on what you are responsible for on this show, and then on the run of the show. This chapter teaches that order of thinking, the two-deck rig many operators use, one deck for transport and one for all the cues, and full worked layouts for a corporate conference, a concert, a television drama, an audio technician and a lighting technician.

There is no standard Stream Deck layout, because there is no standard job.

Start from your responsibilities

Patrice, Reboot’s founder, has controlled video switchers, media servers, playback machines and PowerPoint computers from Companion on corporate shows, concerts and film sets. Asked how he lays out a deck, his answer starts somewhere other than the deck: "It depends first of all on my responsibilities. Some shows we might have only one and on others many. Stream Deck and Companion come particularly in handy when you have more than one. So depending on the demands of the show and my responsibilities is how I program. But usually I have one Stream Deck for transport controls and one for all cues."

That is the order this chapter teaches. First, write down what you are responsible for on this show: which machines are yours, which moments in the show you must make happen, and which you only need to know about. Second, take the run of show, the running order of every segment and cue, and work out what you press, when, and on whose call. Only then open Companion. A deck laid out before those two lists exist is a deck laid out for a different show.

A responsibility is something that is yours if it goes wrong. On one show you may be responsible only for playback. On the next you may run playback, the slides and the switcher together. The machines can be identical on both shows; the layouts will not be, because the jobs are different.

Put the answers on paper with the IP plan for the show. The examples in this chapter use one plan throughout: Companion 10.0.0.10, ATEM 10.0.0.20, Playback A 10.0.0.31, Playback B 10.0.0.32, PowerPoint computer 10.0.0.40, audio desk 10.0.0.50, lighting desk 10.0.0.60, all on subnet mask 255.255.255.0. The audio layout adds the audio team's QLab computer at 10.0.0.51.

One responsibility

With one responsibility, you run one system. The media server operator on a concert, or the playback operator on a small corporate show, may own a single machine. Companion still helps, but its job is smaller: it gives that machine's most-used controls big, labelled, lit keys, and shows the state you would otherwise read off a screen.

A single 15-key Stream Deck MK.2 often covers one responsibility, and the machine's own interface does the rest. The two-deck pattern still holds when the cues are many: a few transport keys that never move, and the cues on their own deck in run order. When the cues are few, they can share one deck with transport, as long as transport keys stay in the same place on every page; a Button reference (chapter 6) does that without copying.

The trap with one responsibility is building a deck that copies the whole machine. If a function is used once in prep, leave it in the machine's own software. The deck is for the show.

Many responsibilities

Companion earns its place when you hold several jobs at once. Without it, an operator running a switcher, two playback machines and a slide computer has four keyboards and mice and four places to look. With it, one hand works one panel that reaches every machine, and each key shows what its machine is doing.

Many responsibilities change the layout in three ways. First, keys must say which machine they touch, by label and colour, because PLAY on the playback machine and NEXT on the slides look alike in the dark. Second, a single show moment may need several machines at once, which is where one key firing several machines comes in. Third, the operator's attention is split, so state on the keys matters more: the deck has to tell you what is live without you looking up.

Many responsibilities are also when the second deck pays for itself. Keeping transport and cues apart means the hand that rolls and stops playback never has to hunt across a page of cues, and the cue page can change without moving it.

The two-deck rig

The rig Patrice usually works with is two decks: one for transport controls and one for all the cues. Transport means the controls you use again and again on whatever is playing: play, pause, stop, next, previous and their relatives. Cues are the moments of this show, each happening once, in order.

The value of the split is muscle memory. Play is in the same place on the first night and the last, on this show and the next, so your hand finds it without looking. The cue deck is free to be rebuilt for every show and to change page as the show moves on, and nothing on it can push transport somewhere else.

Setting up two decks in Companion

Plug in both decks and open the Surfaces page. Each deck appears as its own surface. In each surface's settings, give it a Surface Name, such as TRANSPORT and CUES, so you never confuse them in actions that choose a surface. Set each one's Startup Page, with Use Last Page At Startup off, so after a restart the transport deck comes up on its transport page and the cue deck on the first page of the show.

Since Companion 4.2, a surface or surface group can be limited to certain pages, under Page Permissions in its settings. Limit the transport deck to its one page, and even a stray page action cannot move it. Limit the cue deck to the show's pages, and it cannot wander onto a setup page during the show. The page buttons on the cue deck then step through the permitted pages in the order you selected them.

New pages come with page up, page number and page down in the first column. On the transport page, clear them, because that deck never changes page. A 15-key MK.2 shows the top-left three rows of five of the grid, so build the transport page in that corner. On a big show with many cues, two Stream Deck XLs side by side can be joined in a surface group, which the Companion guide describes as treating them as a single 16 by 4 device on the same page.

Two decks also need two spares, or one spare that can stand in for either. Chapter 21 covers spares and backups. A surface group helps here too: the guide notes that groups give a stable identity, so you can swap a failed deck into the group without changing any buttons.

One key, one machine or many

Should one cue key fire several machines, or one? Patrice's answer is "however you program it": it is the programmer's choice. Both are right in the right place, and good layouts use both.

A useful middle path is a mixed layout: build the combined cue key for the moment, and keep each machine's own keys within reach, on the transport deck or on a device page, so you can finish a cue by hand if one part of it fails. Chapter 16 goes further into building cues, ordering the actions within them, and standby and go.

Mirrored main and backup machines are a special case of one key, several machines. When Playback A and Playback B run the same clips, every transport key fires both, so B is always in the same place as A and can be cut to air at any moment. Commands at the same level of a button's action list are sent together (chapter 6), which is what keeps A and B in step.

Pages by device or by the run

There are two ways to organise pages, and most shows use both. Pages by device give each machine its own page: an ATEM page, a Playback page, a PowerPoint page. Pages by the run follow the show: an opening page, a keynote page, an awards page, each holding the cues for that part, in order.

The combination that suits the two-deck rig is this. The transport deck has one fixed page. The cue deck's show pages follow the run, so the next cue is always on the page in front of you, top-left to bottom-right in show order. Device pages exist too, for setup and for fixing things, but they are kept out of the cue deck's page permissions during the show and reached from the Companion admin page or the emulator instead.

The Companion guide notes two layouts people use with several surfaces: give each surface its own pages, or share pages and give each surface its own area of the page with the offset in grid settings. The two-deck rig in this chapter gives each deck its own pages, which keeps the transport page clear of cues.

Within a run page, keep one rule: a row is a segment, read left to right. When the show caller says the next cue, it should be the key to the right of the last one you pressed. And when the running order changes, which it will, move the keys, do not relabel them in place, so each key keeps the actions that match its label.

Worked layout: Brightwater Health 2027

Brightwater Health 2027 is a corporate conference, a general session in a hotel ballroom. Dana Okafor hosts and Martin Lowe, the CEO, gives the keynote. There is a walk-in, a VOG (voice of god, the off-stage announcer) to open the show, an opener video, an awards segment and a panel of five. The show caller calls the cues.

In this layout you are the video operator with many responsibilities: the ATEM switcher feeding the screens, two PlaybackPro Plus machines (Playback A main, Playback B a mirrored backup), and the PowerPoint computer, controlled through a VICREO Listener running on it. Audio and lighting are other operators' jobs.

The ATEM inputs are Camera 1 wide on input 1, Camera 2 on the lectern on input 2, Playback A on input 3, Playback B on input 4 and the PowerPoint computer on input 5. The VICREO Listener sends key presses on the slide computer, and PowerPoint's own shortcuts do the rest: Right arrow or N for the next slide, Left arrow or P for the previous one, and B to black the screen and back.

The transport deck, a 15-key Stream Deck MK.2

Every PB key fires both machines with the matching PlaybackPro Plus action: Take clip to Program, Play from current location (Program), Pause playback (Program), Stop Program playback (Kill), Goto last 10 seconds, Previous Clip (Preview) and Next Clip (Preview). The PPT keys each send one key with the Listener's Single key action. The status keys use Connection: Check Status, one per connection. B TO AIR sets the ATEM's program to input 4 and sits in a duration group with Execute while held, so it needs a full second's hold. CLOCK shows $(internal:time_hm). Playback keys rest in blue, slides in a second colour, status keys in grey, and B TO AIR in orange.

The cue deck, a 32-key Stream Deck XL, page BW SHOW

The whole run fits on one page, so this show has a single page in the cue deck's permissions. Each row is one segment read left to right. The keys behind the labels look like this.

Notice what is not on the deck: the VOG mic, the walk-in music and the house lights. They belong to audio and lighting, and they stay on those operators' desks. The VOG key is there only as a reminder of where the show is, with no actions behind it. Notice too that the camera keys carry ATEM tally, red on program and green on preview, so the deck always shows what the room is seeing.

In the BACK TO SLIDES key the order is reversed: the ATEM cuts away first and playback stops second, so the audience never sees the video freeze or go black. That kind of choice is why each cue key is written down and rehearsed.

Worked layout: The Low Tides

The Low Tides are an invented band playing a 3,000-seat theatre, with an LED wall behind them fed by a media server. Most songs are timecoded: the band's playback rig sends timecode, a running clock that the media server follows, so each song's visuals start and move in step with the music without anyone pressing a key.

In this layout you have one responsibility: the media server, Resolume Arena. Its Companion module talks to Resolume over OSC and its REST API; its Help notes that feedback needs the REST API, and that an optional OSC listener adds transport variables such as elapsed time, remaining time and clip name, and tracks the active column. In this show file each song is one column in Resolume, so triggering a column starts that song's look.

With timecode doing the work, the deck is for everything timecode does not do: the walk-in and the house looks, the songs that are not timecoded, and taking over if timecode drops out. It is also for the moments nobody can predict at a concert, such as a song played twice or dropped from the set. Agree with the director when you may press a song key while timecode is running; chapter 11 covers timecode and keys together.

The transport deck, a 15-key Stream Deck MK.2

For a media server, transport is moving through columns rather than play and pause. PREV COL and NEXT COL use the module's Composition Previous Column and Composition Next Column actions. TAP TEMPO and RESYNC use Tap Tempo and Resync Tempo, for the songs that follow the band's tempo. WALL UP, WALL 50 and WALL BLACK set Composition Opacity Change, and CLEAR ALL uses Clear All Layers; the last two are hold-to-fire in orange. TIME LEFT and CLIP NAME show the module's transport variables from its Variables list, if the OSC listener is enabled.

The cue deck, a 32-key Stream Deck XL, page LT SET

Each song key uses Connect Column for that song's column, and is labelled with its number, its title and TC if it runs from timecode, so you know at a glance which songs need your hand. Songs without TC, such as 3 LIGHTHOUSE, are the ones you fire on the director's call. Where the module's feedback can follow the active column, the live song's key lights red; check the module's feedback list for the one that does this. SAFE LOOK, bottom right in orange, puts up a plain look you can hold on if anything goes wrong.

Here the run of the show is the set list. When the band changes the set list in the afternoon, move the keys into the new order rather than editing the columns behind them, and walk the new order with the director before doors.

Worked layout: The Night Shift

The Night Shift is an invented television drama, the same series Reboot's 24 Frame Playback course follows. On set, the playback operator puts content on every screen the camera sees and makes it act on cue. Here the responsibility is two on-set screens in a hotel room: the wall TV, where Leo Marchetti watches the news, fed from Playback A, and the laptop on the desk, fed from Playback B. Maya's phone with the RIDEWELL app, and the call from Nora Vance, come from a phone system that chapter 17 covers.

Film work changes the layout in three ways. The two screens often need different timing, so each machine has its own transport row as well as a row that fires both. Every take returns to the same starting point, which crews call back to one, so that key is the most pressed on the deck. And the set is dark and quiet, so the deck must not light the scene or be seen in a reflection.

The transport deck, a 15-key Stream Deck MK.2

Each key uses one PlaybackPro Plus action: Play from current location (Program) to roll, Pause playback (Program), Goto In (Program) for back to one, Step Forward (Program) to move a frame at a time, and Loop Temp (Toggle) for loops. ROLL BOTH and BACK TO ONE BOTH fire the same action on both machines together. DECK DIM uses the internal action Surface: Set to brightness on both decks, so you can drop the decks to a glow when the camera is near; a second press, or a step, brings them back.

The cue deck, a 32-key Stream Deck XL, page SC 14 HOTEL

On a film set the run is the call sheet, the day's list of scenes in shooting order, so the cue deck has one page per scene and the pages follow the call sheet. Each content key uses Load clip (id) into Preview, so the clip is ready without going to the screen; A ROLL on the transport deck then takes it on action. The SCENE 14 and TAKE keys are information for you and for the script supervisor's questions; TAKE + adds one to a custom variable.

Patrice's point about responsibilities shows here. On a day with only the wall TV, Row 2 of the transport deck and the laptop row disappear and the deck gets simpler. On a day with four screens and a phone, the same two-deck rig carries them all, because the layout was built from the job.

An audio layout

Audio technicians use Companion too. This layout is built from the Companion module documentation and the consoles' published protocols, not from Reboot's own show experience, so treat it as a starting point and check every key against the module's Help and your console. In live sound, the A1 is the lead audio engineer who mixes the show, usually at FOH, the front-of-house position in the audience.

The scene is Brightwater Health 2027 again, from the A1's side. The responsibilities are the mics (Dana Okafor's headset, Martin Lowe's lectern mic, two handhelds for the awards, five panel mics), the VOG mic, walk-in and break music, the awards stings, and the audio from the playback machines. The console is a Yamaha CL5 at 10.0.0.50. Music and stings play from QLab on the audio team's computer at 10.0.0.51.

The transport deck, a 15-key Stream Deck MK.2

NEXT CUE NAME shows $(qlab:n_name), the cue at QLab's playhead. RUNNING CUE shows $(qlab:r_name), and TIME LEFT shows $(qlab:r_left). Q GO can use the QLab feedback Colours for GO status, which shows when QLab's double-GO protection is holding off a second GO. Q PANIC is hold-to-fire: the QLab Help explains that a panic is a brief fade out leading into a hard stop, and a second panic is an immediate hard stop.

The cue deck, a 32-key Stream Deck XL, page BW AUDIO

Music and sting keys use QLab's Start (Cue/ID) for a named cue, so each key always plays its own cue whatever QLab's playhead is doing. Mic keys switch the input channel's on key on the CL5; on Yamaha consoles a channel's on/off is its mute, and the console's parameter list for the CL and QL series includes the input channel fader on parameter. Give each mic key a feedback from the module so it shows whether the channel is on, and use the same tally meaning as video: red while the mic is open to the room. Scene keys recall a console scene and are hold-to-fire, because a wrong scene can change every channel at once.

Other consoles change the actions, not the thinking. The Allen & Heath SQ module's Help lists mutes for channels, groups, mixes, DCAs and mute groups, fader levels, soft keys, scene recall, a current-scene variable and a variable that changes on every scene recall, for use in triggers. The Allen & Heath dLive module controls mutes and faders and recalls scenes when connected to the MixRack, and cue lists and Go Next/Previous when connected to the surface.

The console stays the master. The A1 must see every mute on the console as well as on the deck, and must be able to undo any key by hand on the desk. Build mic keys as separate ON and OFF, or with a feedback-driven key, rather than a step that counts presses, so a mute made on the console is never reversed by the deck's next press.

A lighting layout

Lighting technicians use Companion as well, and this layout, like the audio one, is built from the module documentation and the consoles' manuals rather than from Reboot's own experience. On most shows the lighting operator presses GO on the console. A deck suits a lighting tech who runs lighting alongside another job, who needs a few specials within reach, or who wants information on keys.

Brightwater Health 2027 uses an ETC Eos family console at 10.0.0.60, with the cues for the general session in one cue list. The ETC Eos module's Help says to enable OSC RX and OSC TX on the console and to set the console's IP as the Target IP. It connects on port 3032, or port 3037 with the Use TCP SLIP option. Its User ID setting chooses which console user Companion's commands run as. Use a different user from the operator's, the Help advises, if someone is working the console at the same time, otherwise their command lines can conflict.

The transport deck, a 15-key Stream Deck MK.2

LX GO uses Key: Go, which runs the next cue in the current list, the same as the console's Go button, and LX STOP/BACK uses Key: Stop/Back. LIVE CUE shows $(eos:cue_active_num) and $(eos:cue_active_label); PENDING CUE shows $(eos:cue_pending_num) and $(eos:cue_pending_label), so the deck says what is live and what GO will run next. BLACKOUT uses Key: Blackout and is hold-to-fire. The house and stage keys use Run Macro or Group Intensity, depending on how the lighting programmer built the show. COMMAND LINE shows $(eos:cmd), the console user's command line.

The cue deck, a 32-key Stream Deck XL, page BW LX

Each cue key uses Run Cue with the list and cue number on its label, so a key always runs its own cue, even if the console's pending cue has moved. This suits a lighting tech who also has another job and works from the show caller's numbers. AUDIENCE SUB uses Submaster Bump; the module's Help suggests the press and hold state on press and release on release, so the audience light is up only while the key is held.

On The Low Tides, the lighting is more likely to be run on a grandMA3 and played by hand to the music. The grandMA3 module's Help describes control over OSC, which must be set up on the console under In and Out with Receive and Receive Command ticked, and lists running commands, toggling executor buttons, running quickeys, calling macros and selecting sequences and groups. A deck there carries effects and specials on executor buttons for the operator to play, not a cue list. Chapter 15 covers lighting consoles and who presses GO.

From layout to show

A layout is finished when it is on paper and has been run. Print each deck's key map like the tables in this chapter, tape a copy by the decks, and give one to the show caller, so when they say "standby opener" you both know which key that is.

The same rig will look different on every show, because the job will be different. That is the point Patrice makes: start with what you are responsible for, follow the run, and let the layout fall out of those two.

How to do it

1. List your responsibilities: the machines that are yours, the ones you only watch, who calls your cues, and the backup for each machine.
2. From the run of show, list every moment you must make happen, in order, and mark which machines each one touches.
3. Sort the controls you use again and again into transport, and the one-off moments into cues.
4. Lay out the transport deck from your library, the same as on your last show where you can, with status keys and protected keys in fixed places.
5. Lay out the cue deck by the run, one segment per row, left to right, and decide for each cue whether it fires one machine or several.
6. Name the surfaces, set startup pages and page permissions, and set the show's colours, with red and green kept for tally.
7. Print the key maps, rehearse every key on safe gear, and give a copy to the show caller.

What goes wrong

Practice it

The Low Tides have added a second show, and this time you hold two responsibilities: the Resolume media server as before, and an ATEM (10.0.0.20) switching two cameras to side screens for IMAG, image magnification, the live close-up of the band. Songs still run from timecode, except 3 LIGHTHOUSE, 6 SLACK WATER and 11 DRIFT, which you fire on the director's call.

Controlling Video Switchers

The video switcher decides what the audience sees, so the buttons that drive it are the most watched buttons on the show. This chapter shows how Companion talks to the switchers you will meet, ATEM, vMix, Barco E2 and S3, Analog Way and Ross, what each one lets you do from a deck, and what must always stay on the switcher's own panel.

The video switcher decides what the audience sees, so the buttons that drive it are the most watched buttons on the show.

Controlling video switchers

A video switcher, also called a production switcher (a vision mixer in British broadcast), takes many video sources in and sends a chosen few out. Cameras, playback machines, the PowerPoint computer and graphics all arrive as inputs. The switcher puts one of them on program, the output the audience and the stream see, and lets the operator line up the next one on preview, the output only the crew sees. A cut swaps preview and program instantly; an auto transition does it with a dissolve or a wipe over a set time.

On a big show the person switching sits behind a full hardware panel. Companion does not replace that panel. It adds keys for the moves that are repeated, awkward, or belong to someone else: a playback operator who needs to take the opener video to the screens, a stage manager who needs a single key for the walk-in look, or a technical director who wants one press to set three screens at once. On a small show, a compact switcher plus a Stream Deck may be the whole control surface.

Every switcher Companion controls is reached the same way: the switcher has an IP address on the show network, Companion has a connection for it, and the connection's module turns your button actions into the switcher's own protocol. The words change from maker to maker, so learn the common ideas first.

Two kinds of switcher exist on show sites. Production switchers, such as Blackmagic ATEM, vMix, Ross Carbonite and Ross Acuity, mix cameras for a program feed. Presentation switchers, also called screen management systems or image processors, such as the Barco E2 and S3 and Analog Way LivePremier, Midra 4K and Alta 4K, build layered looks across wide LED walls and projection screens. Both are controlled from Companion, but the second group thinks in screens, layers and stored presets rather than in a single program bus.

ATEM

Blackmagic Design ATEM switchers, from the ATEM Mini range up to the Constellation and 2 M/E models, are the most common switchers you will drive from Companion. The Companion module for ATEM says it should work with all models. It must reach the switcher over the network; the module's help states plainly that USB control is not supported, even though the ATEM Mini can talk to its own software over USB.

Getting connected

An ATEM needs a fixed IP address so that panels and software always know where to find it. That address is set in Blackmagic ATEM Setup. On the Brightwater Health 2027 show plan, the ATEM is 10.0.0.20 and Companion is 10.0.0.10, both with subnet 255.255.255.0. Add an ATEM connection in Companion, type 10.0.0.20 as the target IP, and the status should turn green.

If it does not, the module's own advice is to rule Companion out first: open ATEM Software Control on the same computer and see whether it can connect. If the Blackmagic software cannot reach the switcher either, the fault is the network, usually an address on a different range. Companion's discovery list can show ATEMs that you still cannot connect to, so a switcher appearing in the list proves nothing about the addresses.

What the ATEM module can do

Macros are an ATEM's own stored sequences, recorded on the switcher. A macro can do many things in order, such as set four sources, run a transition and bring on a key. A Companion button that runs a macro keeps the logic inside the switcher, which is useful when the switcher operator also uses the same macro from the hardware panel. The module notes one catch: Companion cannot always see that a zero-length macro ran, so its key may never show the macro as running. Give the macro a one-frame pause and the feedback works.

The module also works around a multiviewer detail. In a layout with four large quadrants, the ATEM still numbers its windows on an underlying four-by-four grid, so the quadrants are windows 1, 3, 9 and 11, not 1 to 4. Changing window 2 does nothing you can see in that layout.

vMix

vMix is switching and streaming software that runs on a Windows computer. Inputs can be cameras, NDI sources, video files, PowerPoint and titles. The Companion module for vMix talks to it over vMix's TCP API on port 8099. The module's settings warn not to type the vMix Web Controller port into that field, and not to set the Web Controller itself to 8099, because the two would clash.

Most of the state Companion shows for vMix, the tally colours, the input names and the timers, comes from vMix's API on a timer called the polling interval. The module's help gives the default as 250 milliseconds and the minimum as 100 milliseconds. A shorter interval makes the keys respond faster; a longer one eases the load on a busy vMix computer. If vMix's processor use climbs when Companion connects, slow the polling down.

Every vMix shortcut, the commands vMix itself documents for its API, is available as a Companion action, and any of them can also be sent as a custom command. That makes vMix one of the most complete things Companion controls: cut, fade, overlays, lists, replay, recording and streaming all live in the same module. Streaming with vMix has its own chapter later in the book.

Because vMix often runs on the same computer as other software, keep its connection simple: Companion on a separate computer at 10.0.0.10 where you can, vMix at its own fixed address, and the vMix computer's own keyboard shortcuts left in place as a way back if the network drops.

Barco E2 and S3

Barco's Event Master range includes the E2, the S3-4K and the EX expansion unit. Barco describes the S3-4K as a compact version of the E2 that uses the same cards. They are screen management systems: one frame drives an LED wall, side screens and confidence monitors, each as its own screen destination with layers, plus aux destinations for single feeds. They are programmed and run from Barco's Event Master Toolset software or an Event Master controller.

The Companion module for this range is called Barco EventMaster. It uses the official EventMaster JSON API, and its help notes two traps. First, the API is not available in the simple simulator; you need a hardware frame or Barco's virtual box simulator to build buttons ahead of the show. Second, a green status only means the address answered a ping. It does not prove the API is responding, so test a button before trusting the connection.

The module's settings include an authentication mode, where you enter an operator ID or the super user password if the frame is set to need one, and a choice called Enable Live Updates. With it on, the frame sends Companion a notification whenever content changes, so tally and variables update within about half a second instead of waiting for the next poll. For that to work, the notification port on the Companion computer, port 3000 by default, must be open to incoming TCP connections; on Windows the help says to set the network profile to Private.

On The Low Tides concert, the E2 drives the LED wall and two IMAG side screens. The video director runs the frame from Event Master Toolset. The media server operator has a deck with three keys that recall the song looks the director built, labelled with the song names, and one key that recalls the house look for changeovers.

Analog Way

Analog Way builds presentation switchers: the LivePremier series, which includes the Aquilon models, and the Midra 4K and Alta 4K series. They are operated from WebRCS, Analog Way's control software that runs in a web browser. Companion offers two modules for them, and choosing the right one matters.

The AWJ module connects the same way WebRCS does; the help says Companion appears to the device as another WebRCS client. It reads the device's features when it connects, so its menus only offer the inputs, screens and memories your device has. That also means you must be connected to build buttons. To program ahead of the show, the module help points to Analog Way's free simulators.

The most important idea in the AWJ help is selection synchronisation. In WebRCS you usually select something first, a screen or a layer, and then act on it, for example by pressing Take. Every WebRCS client keeps its own selection. If the operator's WebRCS has screen 1 selected and Companion has screen 2 selected, the same Take button does different things depending on where it is pressed. Turning on selection sync, in Companion and in the operator's WebRCS, makes them share one selection. The other way is to build Companion keys with direct commands, such as transition screen 1, that do not depend on any selection. The help advises not to mix the two methods on one deck.

Ross

Ross Video switchers, the Carbonite and Graphite, Acuity and Vision ranges, along with Ultrix routers and some openGear cards, are controlled from Companion through the Ross Video RossTalk module. RossTalk is Ross's own text command protocol. Ross's documentation says Carbonite accepts RossTalk commands on port 7788 automatically, and the module uses port 7788 by default.

The module's actions follow the switcher's own words: cut and auto transition, XPT for a crosspoint, MEM to recall a memory, the sequencer, keyers, fade to black and custom controls, which are sequences stored on the switcher. A TCP Keep Alive setting holds one connection open and shows its status continuously. Two actions on Acuity and Vision, set video mode and reset switcher, interrupt the switcher's output; the help says to use them with care, and on a show they belong nowhere near a deck.

The RossTalk help describes commands and ready-made buttons. It does not describe tally feedback, so if you want keys that show what is on air from a Ross switcher, check what the module version you have installed offers before you promise it to the director.

Tally on the deck

Tally is the signal that tells everyone which source is live. On a camera it is the red light the operator and presenter see. On a Companion key it is a colour that follows the switcher: by the usual convention, red means the source is on program, green means it is on preview. Companion gets this from a feedback, a rule the module offers that changes the key's look when the switcher's state matches.

Two details make tally on presentation switchers worth learning. The Barco module can show tally for a source anywhere, or only on one screen destination, such as LED MAIN program, so a key can light only when the source is on the main wall. The Analog Way AWJ help says its source tally follows visibility: it will not light if the layer is off the screen, has no area, is fully masked or fully transparent.

Tally on the deck is a guide, not a guarantee. It shows what the switcher reported last. If the network drops, the key keeps its last colour or turns to the module's disconnected look. The program monitor is the final word; glance at it after every important press.

What stays on the panel

Every switcher keeps its own controls, and on a show they stay within reach. The hardware panel, the switcher's software or its front-panel buttons are the way back when Companion, its computer or the network fails. Plan the deck so that losing it costs convenience, never the show.

Agree with the switcher operator before the show who presses what. If the playback operator's deck can take the opener to program, the technical director must know that, and the two of you must agree the cue word. Two people able to cut the same bus without a plan is how a camera ends up live in the middle of a video.

How to do it

1. Confirm the switcher's IP address on the show's address sheet, for example the ATEM at 10.0.0.20, and that the Companion computer is on the same range with the same subnet mask.
2. Check the switcher's own software can reach it from the network, such as ATEM Software Control, Event Master Toolset or WebRCS.
3. Add the connection in Companion, enter the address and any settings the module asks for, such as a port, an operator ID or live updates, and wait for a green status.
4. Drag the module's presets for preview and program sources onto a test page, then check one press on preview with the switcher operator watching.
5. Add tally feedbacks so each source key shows red on program and green on preview, and confirm the colours match the multiviewer.
6. Build the show keys, such as a macro, preset or look per segment, label them in the show's own words, and test every one before doors.
7. Agree with the switcher operator which keys you will press and which moves stay on the panel, and write it on the running order.

What goes wrong

Practice it

Brightwater Health 2027. An ATEM at 10.0.0.20 switches four cameras, the PowerPoint computer and Playback A for the IMAG screens and the stream. You run playback and have a Stream Deck on Companion at 10.0.0.10. The technical director has asked you to take the opener video to program yourself on her cue, because she will be talking the camera operators through the first walk-on.

Controlling Media Servers

A media server plays the content on the LED walls and projection, often in layers, often locked to timecode. This chapter shows how Companion triggers and watches Resolume, Disguise, Watchout, Millumin and Pixera, what each one has to have switched on before it will listen, and how Companion buttons work alongside timecode instead of against it.

A media server plays the content on the LED walls and projection, often in layers, often locked to timecode.

Controlling media servers

A media server is a computer, or a dedicated machine, that plays video content to screens. Where a playback machine plays one clip full screen, a media server places content on a map of the actual screens: a curved LED wall, three projectors blended into one picture, the floor, the set. It can stack layers, run effects and play a whole show on a timeline. On The Low Tides concert, the media server feeds the LED wall behind the band with a different look for every song.

Media servers are usually run by their own operator from their own software. Companion earns its place in three ways: it gives the operator a physical key for each song, scene or cue, so they are not hunting with a mouse in the dark; it shows the time left on a clip on the key; and it lets someone else, such as a show caller or a playback operator, fire one agreed cue without touching the server.

Almost every media server needs control switched on before it will accept commands from the network. That is the step people forget. The server is running, Companion's connection is set, and nothing happens, because the server was never told to listen.

Resolume

Resolume Arena is media server software built around a grid. Rows are layers, stacked over each other; columns hold clips. Trigger a column and every layer plays the clip in that column, so one column is one complete look. Concert video operators often build one column per song or per section of a song.

Resolume can be controlled two ways, and the Companion module uses both. OSC, Open Sound Control, is a network message format used widely in show software; Resolume's documentation says it is switched on in the OSC tab of Preferences and listens on port 7000 by default. The REST API is Resolume's web interface, switched on as the webserver in Preferences, on port 8080 by default in the module. The module help says feedbacks need the REST API; most other actions fall back to OSC if no REST port is set.

One status detail catches people. OSC has no reply, so if you only give the module an OSC port, it shows OK whether Resolume is listening or not. With the REST port filled in, the status turns to an error if Resolume is not answering, which is far more useful at lineup.

The module can also listen for OSC sent back from Resolume. Turn on its OSC listener, port 7001 by default, and in Resolume's OSC preferences turn on OSC Output pointed at the Companion computer on that port. That gives per-layer variables for the clip name, elapsed time, remaining time and progress, and a progress-bar feedback that changes colour as a clip nears its end.

Disguise

Disguise, still often called d3, is a media server platform that runs on its own hardware and is programmed in its designer software. A Disguise show is a timeline of tracks divided into sections, with cues tagged on the timeline. It is common on concert tours, large corporate events and broadcast.

Disguise's help describes OSC transport control in four steps. First, an OscDevice; Disguise includes one called osc 1 in the Devices manager. Second, in the transport controls, add a new event transport and choose EventTransportOSC. Third, in that transport's settings, select the OSC device. Fourth, click disengaged in the transport window; it flashes green when transport control is engaged. Until that last step, OSC commands are ignored.

The Companion module for this is Disguise OSC. Its settings hold a send port and a receive port, 7401 and 7400 by default in the module, which must match the ports set on the Disguise OSC device. The module help warns that full functionality needs Disguise set to always send OSC feedback; Disguise's own help describes the feedback mode choices as always send or only send changes.

A second module, Disguise Multi Event Transport Control, uses Disguise's Multitransport Manager. Commands are sent as JSON over a telnet connection, and the setup is done in Disguise: create a Multitransport Manager, assign transports and tracks, then add an event transport with a listening port. Whichever module you use, agree with the Disguise programmer which transport Companion is allowed to drive.

Watchout

Dataton Watchout plays content across many displays from a timeline. In Watchout 6 and earlier, a production computer holds the show and display computers play it; once the show is distributed, the display computers can run as a display cluster without the production computer. Watchout 7 reorganised the system around a Director and an Asset Manager.

Companion has a module for each. The Dataton Watchout module controls Watchout 6 production computers and display clusters. Its code connects to port 3040 for a production computer and port 3039 for a display cluster, and Dataton's protocol guide confirms 3039 for the cluster. The guide also gives a quick test: open a telnet connection to that port, type ping and press Return, and Watchout replies with a Ready message and its version.

The Watchout 6 module's actions are Run, Pause, Kill, Reset, Jump to time, Jump to cue, Go online, Enter Standby, Set Input, Load Show and Layer Conditions. Loading a show takes the full path on a production computer and only the show name on a display cluster, and the help says names must use basic ASCII characters only. In its feedback modes the production computer sends status updates on its own, whenever a task changes or every few seconds.

The Dataton Watchout 7 module connects to the Director's HTTP API on port 3019, with live updates for playback state. It can play, pause or stop a timeline, jump to a time or a cue, send values to show inputs and load shows. Because Watchout 7 reuses its internal IDs, the module help notes that the same buttons can work across different shows, with timeline names updating on the keys. One trap: for inputs to work through the API, the Key field must be set on the variable in Watchout, because the API matches the Key and not the Name.

Millumin

Millumin is media server software for Mac, popular in theatre, dance and corporate shows. Like Resolume, it is organised in layers and columns, and it also has timelines. The Companion module sends OSC to Millumin on port 5000 by default; the port is set in Millumin under Interactions, Manage devices, OSC tab. Feedback, such as the time remaining on a layer, needs Millumin set to send OSC back to Companion and the layer named in the Companion action.

The actions cover what an operator needs on a show: launch a column by number or name, next and previous column, play media on a layer, play, pause and stop the timeline, go to a named timeline segment, restart, pause and stop media, and stop all columns.

Pixera

Pixera, from AV Stumpfl, is a media server platform with a timeline-based workflow, used on large projection and LED shows. Its API is switched on by adding an API access port in Pixera's settings and choosing the JSON/TCP protocol. Pixera's help says only JSON/TCP supports all the API's return values reliably. You choose the port number; the Companion module's default is 1400, so either use 1400 in Pixera or type your chosen number into the module.

The AV Stumpfl Pixera module works on timelines: transport mode, next and previous cue, go to timecode, go to a cue by name or index, blend to a timecode or cue, and timeline opacity and fades. Its feedbacks colour a key by timeline state and put the timeline's timecode or time remaining on the key. A raw API action can send any Pixera JSON command; the module itself labels that function use at your own risk.

Buttons and timecode

Timecode is a running clock, hours, minutes, seconds and frames, sent from one machine to others so they stay in step. On The Low Tides, the band plays to a click track, and each song's playback session sends timecode to the lighting desk and the media server. The LED wall's content moves on the beat because it follows the same clock as the music.

When a show runs on timecode, the clock is in charge, not the buttons. Companion does not need to fire each look; the media server's timeline does that as the timecode arrives. Pressing a play or jump key while the server is chasing timecode can fight the clock, and the result depends on how the server is set up. Before you build keys for a timecoded show, ask the media server programmer how the timeline follows timecode and which keys are safe to press.

A clear rule for the deck helps. Keys that only show information can be pressed by anyone. Keys that move the timeline or change a look on a timecoded show are pressed by the media server operator, or on the operator's call. Put the safe look key somewhere the operator can find without looking, and agree what it does before the first song.

How to do it

1. Ask the media server operator which actions you may trigger and from which transport, timeline or layer.
2. On the server, switch on network control: OSC in Resolume or Millumin, an engaged OSC transport in Disguise, an API port in Pixera, or the HTTP API on a Watchout 7 Director.
3. Note the server's IP address and the port it listens on, and set any feedback the server sends back to the Companion computer's address.
4. Add the connection in Companion with the same ports, and use a two-way method, such as Resolume's REST port, so a dead server shows as an error.
5. Build a test key for one harmless action, such as a column or cue name on the key, and confirm it reads correctly.
6. Build the show keys in the order of the set or the running order, with names matching the server's cue names.
7. Agree with the operator what happens on timecode and which keys stay theirs, and test every key in rehearsal, never in the show.

What goes wrong

Practice it

The Low Tides, 3,000-seat theatre. Resolume Arena drives the LED wall with one column per song. Songs 1 to 9 run on timecode from the playback rig; song 10, an acoustic number, and the encore are called live. The media server operator wants a deck with song names and time remaining, and a safe look in case anything fails.

Controlling Playback Machines

A playback machine plays the videos, stings and walk-in loops a show depends on, and it plays them once, on cue, in front of everyone. This chapter covers the playback software you will drive from Companion, QLab, PlaybackPro Plus, ProPresenter, VLC and others, the A and B machine practice that protects the show, and how to lay out a transport deck.

A playback machine plays the videos, stings and walk-in loops a show depends on, and it plays them once, on cue, in front of everyone.

Controlling playback machines

A playback machine is a computer or a recorder whose job is to play prepared files on cue: the opener video, the award stings, the walk-in loop, the sponsor reel, the countdown. Its output goes into the video switcher, and often its audio goes to the audio desk. On Brightwater Health 2027, Playback A at 10.0.0.31 and Playback B at 10.0.0.32 feed two ATEM inputs and two channels on the audio desk.

Playback operators control their machines from Companion every day. A physical key for play, pause and stop is faster and surer than a mouse click on a laptop in a dark control position. The key can also show what is loaded and how much time is left, so the operator can call stand by and the remaining time to the show caller without looking away from the screens.

Every playback machine needs to be told to accept network control, and each does it differently. The common pattern is the same as any show gear: a fixed IP address, a setting switched on in the software, a port, sometimes a password, and a matching connection in Companion.

QLab

QLab, from Figure 53, is Mac show-control software that runs sound, video and lighting cues from a cue list. Its central idea is the GO button: the playhead sits on the next cue, and GO fires it and moves to the one after. On corporate shows QLab often plays walk-in music, VOG announcements and video stings, and the playback operator builds a cue for each moment in the running order.

QLab listens for OSC on port 53000. In QLab 5, OSC access is set per workspace, under Network and OSC Access in Workspace Settings. New QLab 5 workspaces get a random OSC passcode, and the module help says QLab 5 needs a passcode to work reliably from Companion. Copy the passcode from the workspace settings into the module's OSC Passcode field. QLab ignores commands after too many wrong passcodes in a row, so the module stops retrying when it sees a wrong one; enter the right passcode and save to start it again.

The module used here is the QLab Advance module, whose help is headed QLabFB. Its help says to tick Use TCP? in the connection, because variables and feedback only work over TCP. With TCP on, keys can show the playhead cue's name and number, the running cue's name and time remaining, and colour the key with the cue's own QLab colour.

Two of those matter for safety. Set Minimum Go stops a second GO within a set time from firing the next cue, which protects you from a bounced finger. Show Mode locks the workspace against editing; run the show in it. Reset is not a stop key: it clears every cue and sends the playhead to the top, so keep it off the live page.

PlaybackPro

PlaybackPro Plus, from DT Videolabs, is Mac playback software built for live events. It works like a small switcher for clips: you load a clip into preview, check it, then Take it to program, the output feeding the screens. It is a common choice for corporate playback, and its ready-made Goto last 10, 20 and 30 seconds commands are made for checking the end of a clip before the show.

The Companion module is listed as PlaybackPro Plus. Its settings are the target IP and a choice of TCP or UDP. The module's code connects on TCP port 4647, which other show-control makers also document as PlaybackPro Plus's default. Remote control over the network must be allowed in PlaybackPro itself; check the setting in the version you have.

The module's help lists actions and ready-made buttons but no feedbacks or variables, so its keys will not show what is playing or time left. Watch PlaybackPro's own screen for that, or put the countdown somewhere else, such as a timer on the switcher's multiviewer.

ProPresenter

ProPresenter, from Renewed Vision, presents slides, lyrics, video and stage displays, and is used at corporate events, conferences and churches. On a corporate show it may play the walk-in loop and the speaker lower thirds, and drive a stage display with the next slide and a countdown clock for the presenter.

Companion has two ProPresenter modules. The newer one, listed as ProPresenter API, uses ProPresenter's public API, needs only Enable Network switched on in ProPresenter's network settings, and the IP address and port shown there. Its help says versions older than 7.9.2 need the older module, listed as ProPresenter, which connects the way the mobile remote app does. For that one, open ProPresenter's network settings and switch on Enable Network, Enable ProPresenter Remote and Controller, and note the controller password, port and IP address.

The useful actions on a show are next and previous slide, a specific slide, clear actions such as Clear All, Clear Slide and Clear to Logo, timers and messages, and triggering media and props. The older module's help notes that ProPresenter gives no feedback for whether a timeline is playing, so a key cannot show it, and that on Windows a Clear All loses the current slide position in some versions. Both are reasons to watch the ProPresenter screen as well as the deck.

VLC

VLC is a free media player that plays almost any file. It is not show playback software, but it turns up on small shows, in breakout rooms and as a quick backup. The Companion module for VLC talks to VLC's web interface.

To switch it on, open Tools then Preferences in VLC, tick the Web option on the Main interfaces page, and set a password under Main interfaces then Lua. The module help says VLC must be closed and restarted before the password takes effect. The module's default port is 8080. A simple test from the help: if you can reach VLC from a web browser with those details, the module will work.

The module offers Play, Play ID for a playlist item, Stop, Pause / Resume, Seek To, Next, Previous, Full Screen, Loop and Repeat, and variables for the playing item's name and the time remaining. One trap from the help: VLC gives no error for a Play ID that is not in the playlist, it simply plays the current item. A key labelled for the opener can play the wrong clip without any warning.

Other playback machines

Two more machines you will meet. Mitti, from imimot, is Mac cue playback software for events and theatre. To connect it, set Settings, OSC/UDP Controls to Enable in Mitti and enter the Mitti computer's address in Companion; for feedback, set Mitti to send to Companion, which the module listens for on port 51001 by default. Its module offers play, stop, panic, next and previous cue, play a cue by name or number, Goto 30, 20 and 10, and variables for the cue's time left.

Blackmagic HyperDeck recorders also play back, and are common on shows with an ATEM. The module offers play, stop, go to a clip or a timecode and record, with feedback for transport status and clip. The help warns that older HyperDecks, made before 2023, accept only one controller at a time, including an ATEM or another copy of Companion; if Companion cannot connect, disconnect the other controllers first.

A and B machines

On a show that cannot stop, playback runs on two machines. A is the main; B is the backup. Both hold the same files in the same order with the same settings, both feed the switcher on separate inputs, and both are started together, so B is always at the same point in the clip as A. If A freezes or crashes in the middle of the opener, the switcher cuts to B and the audience sees, at worst, a cut.

Companion makes A and B practical, because one key can send the same command to both machines. On Brightwater Health 2027, the PLAY key holds two actions: play on the Playback A connection at 10.0.0.31 and play on the Playback B connection at 10.0.0.32. The same goes for pause, stop, next and previous. Pressing once keeps the two in step far better than two mouse clicks ever could.

Feedback is what turns A and B from a hope into a backup. Put a key for each machine that shows its own state, playing, paused or stopped, and its own time remaining. If the two times drift or one shows stopped, you know before the switcher needs B. Agree with the technical director the call for switching to B, such as "Go to B", and who makes it.

Whether one key fires both machines or each machine has its own keys is the programmer's choice, and both have a place. For the transport, one key for both is the practice, because that is what keeps them in step. For recovery, separate keys per machine are essential, so you can stop and re-cue B while A carries the show.

The transport deck

Transport means the commands that move playback: play, pause, stop, next, previous and the moves around them. When a show has several machines and many cues, a common layout is one Stream Deck for transport and a second for all the cues. The transport deck never changes during the show; the cue deck follows the running order. Your hands learn where play and stop are, and they are always in the same place.

A transport deck works best when it is laid out like the transport on any player, and when the dangerous keys are hard to hit by accident. A 15-key deck in three rows of five might look like this for an A and B rig on PlaybackPro Plus, whose module has the last-ten-seconds command.

The top row only shows information and is safe to press. The middle row is the show itself, with play in a position the hand finds without looking. Stop sits alone in a corner with blank keys beside it, and in a strong colour, so it is pressed on purpose. The re-cue keys work on one machine each, for recovery. A cue deck alongside it holds a key per running-order moment, such as OPENER, WALK-ON DANA, AWARDS STING and SPONSOR REEL, each loading the right clip on both machines.

Before the show, play every clip through on both machines, check that A and B start and end together, and check the end of each clip with the last-ten-seconds key. During the show, Companion is the way you press, not the only way. Each playback machine keeps its own controls, and its keyboard, mouse and screen stay within reach.

How to do it

1. Copy the same files into the same folder structure on both machines, build identical cue lists or playlists, and check versions and settings match.
2. Give each machine a fixed address, for example Playback A 10.0.0.31 and Playback B 10.0.0.32, and switch on network control in the software, with the passcode or password noted.
3. Add two connections in Companion, named clearly as Playback A and Playback B, and confirm both show a green status.
4. Build the transport keys so each holds the same action twice, once per connection, and add state and time feedback from each machine on its own key.
5. Build separate re-cue keys for each machine for recovery, and put stop in a corner away from play.
6. Play every clip on both machines, watch both on the multiviewer, and confirm they start and end together.
7. Agree with the technical director the call to switch to B and who makes it, and rehearse it once before doors.

What goes wrong

Practice it

Brightwater Health 2027. You run Playback A at 10.0.0.31 and Playback B at 10.0.0.32, both on QLab 5, feeding two ATEM inputs. The show opens with a 90-second opener video, then Dana Okafor walks on. Later the awards segment uses five stings.

Controlling PowerPoint Computers

Most corporate shows still run on slides, and the slides still run on a computer that someone has to advance at exactly the right moment. This chapter shows the ways Companion can drive a PowerPoint or Keynote machine, how that sits beside the presenter's own clicker, and how to keep a main and a backup computer showing the same slide.

Most corporate shows still run on slides, and the slides still run on a computer that someone has to advance at exactly the right moment.

Controlling PowerPoint computers

Picture the general session of Brightwater Health 2027. Martin Lowe, the CEO, walks on for his keynote with a clicker in his hand. His slides live on a laptop at the tech table, the presentation computer, often called the PPT machine whatever software it runs. Its output goes into the video switcher and up onto the screens. At the same table a graphics operator watches the script, because Martin sometimes forgets to click, sometimes clicks twice, and the awards segment later in the day has forty slides that must land on the beat of the music.

A presentation computer is the simplest machine on the show to understand and one of the easiest to get wrong. It does one thing: show the next slide when told. The difficulty is that it can be told by several hands at once, the presenter's clicker, the operator's keyboard and Companion, and it has no idea which of them is right. Everything in this chapter is about making sure the slide on screen is the slide the script says.

PowerPoint was built to be driven by a person at a keyboard, not by a network. That shapes how Companion reaches it. There are three routes, and you will meet all three on shows.

Whatever the route, the computer keeps its own keyboard and mouse, and the operator keeps their hands near them. Companion adds a button panel; it does not take the computer away from the person responsible for it. In the IP plan used through this book the PPT machine sits at 10.0.0.40 and Companion at 10.0.0.10, both on subnet 255.255.255.0.

Key presses from Companion

Companion cannot press keys on another computer by itself. It needs a helper program running on the PPT machine, a listener, that waits for commands on a network port and turns them into key presses inside the logged-in desktop session. Companion has a module for each listener. Two are widely used.

Setting one up follows the same three steps. Install and start the listener on the PPT machine. On a Mac, give it permission under System Settings, Privacy and Security, Accessibility; without that permission it cannot send keystrokes, and Bitfocus warns that keyboard control then silently does nothing. Then add the matching connection in Companion with the PPT machine's address, 10.0.0.40, and the port. Finally put a single key, such as Right Arrow, on a button and press it while you watch the PPT machine.

Both listeners are powerful. Bitfocus Listener's own documentation warns that with shell commands, AppleScript or file opening switched on, anyone who can reach it can run programs on that computer, and that its traffic is not encrypted. New installs ship with those three off. Leave them off unless the show needs them, keep the show network closed, and on VICREO set a password. Both listeners let the person at the PPT machine switch off whole classes of command.

The keys PowerPoint understands

Once Companion can press keys, the buttons are simply the slideshow shortcuts PowerPoint already has. These are the ones Microsoft lists for PowerPoint on Windows, on a US keyboard layout.

Note the word animation. If a slide has builds, bullet points that fly in one at a time, every Next press reveals one build before the deck moves on. The script might say slide 12, but slide 12 might take four presses. Ask for the final deck early, step through it once, and write the press count beside each cue on your script.

A go-to-slide button is two actions on one key: the number, then Enter. VICREO's help notes that for PowerPoint on a Mac you can send the number keys to the PowerPoint process by name and add a delay of about 30 milliseconds before Enter. That delay is set in the button's action list, which chapter 6 covers.

The focus trap

A key press goes to whichever window is in front. If a software update notice, a chat message or a battery warning pops up on the PPT machine, your Next press lands in that window and the slide does not move. Prepare the machine before doors: notifications off, updates paused, sleep off, other applications closed. Both listeners have a way round this on macOS: they can bring a named application, such as Microsoft PowerPoint, to the front before pressing the key. VICREO can also bring a window to the foreground on Windows with a licence.

Modules that talk to PowerPoint directly

Key presses work with any software, but they are blind: Companion presses Right Arrow and has no way of knowing whether the slide moved. Several Companion modules talk to PowerPoint through an add-in or a companion program instead, and some of them report back. Each needs its own software on the PPT machine, so check the module's help page and test on the show computer, never on the day.

The value of these modules is the feedback. A button that shows the current slide number, say 12 of 40, tells you at a glance whether Martin's clicker double-fired. A button that goes red when the slideshow is not in presentation mode tells you someone pressed Esc. Chapter 7 shows how to put that state on a key.

The cost is another piece of software on a computer that is often the client's own laptop, or a hire machine imaged that morning. Add-ins depend on the PowerPoint version, and some only run on Windows. On a show where the speakers bring their own laptops five minutes before they speak, key presses are usually the only route that will work in time.

Presenter remotes and Companion

Presenters like to hold their own clicker. It lets them pace their talk, and many will not walk on without one. A presenter remote is a small handheld transmitter with a USB receiver that plugs into the PPT machine. The computer sees the receiver as an ordinary USB keyboard, so pressing forward simply sends a key such as Right Arrow, and no driver is needed. Two you are likely to meet on corporate shows are the Logitech Spotlight and the DSan PerfectCue family. Logitech sells the Spotlight as plug-and-play through its USB receiver, but it can also pair by Bluetooth instead, so ask which way a presenter's clicker is connected before you go looking for a receiver.

Because a clicker is just another keyboard, it and Companion both talk to the same slideshow, and both are obeyed. That is useful and dangerous in equal measure. If Martin clicks and the operator presses Next a moment later to help, the deck jumps two slides. Agree with the presenter, in rehearsal, who advances. Common arrangements are below.

The cue-light receiver

A cue-light presenter system such as the DSan PerfectCue goes further. Its receiver sits at the tech table, flashes a light each time the presenter presses forward, back or blank, and passes those presses to the computer. DSan's guide for the PerfectCue Micro says the receiver appears to the computer as a standard keyboard and by default sends Right Arrow, Left Arrow and B, and that the keys can be changed with DSan's free programming app. The receiver has two USB ports, which is the basis of main and backup control in the next section.

Companion has a DSan PerfectCue module. Its configuration notes that it reaches the PerfectCue through a Global Caché TP2SL and a DSan TP-2000X, network interface units, over TCP, by default to port 4999. It offers Forward, Reverse, Black Out on and Black Out off, and reads back the forward, reverse and blank lights. That lets an operator's Companion button go through the same receiver as the presenter's handheld, so both machines behind it step together, and lets the deck show when the presenter pressed.

Main and backup

On any show that matters, there are two PPT machines running the same deck: a main and a backup. Both outputs go into the switcher. If the main crashes, freezes or shows a dialog box, the video operator cuts to the backup and the audience sees one slide change. That only works if the backup is on the same slide as the main at every moment. Keeping them there is called mirroring or keeping them in sync.

The deck file must be the same file. Copy it to both machines from one source, check the file name and the slide count on both, and when a speaker sends a late change, update both before either goes live. Then the presses must reach both.

There are three ways to make every press reach both machines.

One Companion button, two actions. Build two listener connections, one to the main and one to the backup, and give each Next button a Next action for each machine. Watch both connection statuses: if one connection is down, only one machine steps.

Dual-output presenter receiver. A receiver with two USB ports, such as the PerfectCue Micro, feeds the same keys to both computers. A press the receiver misses is missed by both, which keeps them together.

Presentation manager. Software such as APS runs on each machine, and Companion sends the same command to each. Each copy needs its own connection in Companion and must have the same deck open.

Machines drift out of step for ordinary reasons: one was slower to open a video, one missed a press while it was busy, an operator touched one keyboard. Check the two outputs on the multiviewer at every pause. A go-to-slide button that sends the same number to both machines is the fastest way to bring them back together; with a slide-number feedback on each, you can see the disagreement before the switch happens.

Whether one Next press should fire both machines or each machine should have its own buttons is the programmer's choice. One press for both is faster and is usual for main and backup. Separate buttons per machine let you correct one without touching the other. Many operators build both: a pair of combined buttons on the cue deck, and a page of per-machine buttons for repairs.

Keynote and other slide software

Keynote, Apple's slide software, is common with presenters who bring a Mac. It answers to keys in the same way. Apple's Keynote guide for Mac lists Right Arrow or Space for the next slide or build, Left Arrow to go back, a slide number then Return to jump to a slide while playing full screen, and Esc to stop. Apple's guide for Keynote on iPad lists B for a black screen; test it on the show Mac. Pressing the question mark key during a Keynote show displays every shortcut, which is the quickest way to check on the machine in front of you.

The VICREO module comes with ready-made presets for Keynote and for PowerPoint on the Mac, so a basic transport page can be dragged onto a deck. On a Mac, sending the key to the named application, Keynote or Microsoft PowerPoint, rather than to whatever window is in front, avoids the focus trap.

Keynote can also be driven by AppleScript, the Mac's scripting language, and Bitfocus Listener can run AppleScript sent from Companion. Script commands vary between Keynote versions, and Listener turns AppleScript off by default because it can run anything. Treat it as an advanced route and test the exact script on the show machine.

Other slide software turns up too. Google Slides runs in a browser, and there is a Companion module for a separate Google Slides controller app that opens presentations, moves slides and manages the speaker notes window. PDF decks open in Adobe Acrobat or similar, which APS can also drive. ProPresenter, used heavily in houses of worship and some corporate work, has its own network control and is covered with playback software in chapter 12.

For any of these, the rule is the same: find out which keys or commands the software accepts on that exact computer, build the buttons, and test every one on the show file before doors.

Watching the show computer

A PPT machine that has stopped responding still shows its last slide, so the screen looks fine until someone presses Next. The VICREO Listener, with a licence, includes a process watchdog: it watches named programs on the PPT machine, such as POWERPNT.EXE on Windows or Keynote on a Mac, and reports whether each is running, in front and responding. Its Process state feedback can turn a button red when PowerPoint stops or hangs.

Bitfocus Listener can report basic system information, such as processor and memory use, to Companion. Either way, a status key per PPT machine on your cue deck, green when all is well, gives you warning before the audience gets it.

How to do it

1. Get the final deck early. Copy the same file to the main and backup machines from one source and confirm the file name and slide count match on both.
2. Prepare both machines: notifications off, automatic updates paused, sleep and screen saver off, unrelated applications closed, power adapters plugged in.
3. Install and start the same listener on both machines. On a Mac, grant it Accessibility permission. Leave shell commands, AppleScript and file opening switched off unless you need them.
4. Give each machine its address on the show network, for example main 10.0.0.40 and backup 10.0.0.41, and add one listener connection in Companion for each. Confirm both show as connected.
5. Build Next, Previous, Black and Go to slide buttons that each carry one action per machine, and a separate page with the same buttons for each machine alone.
6. Step through the whole deck on both machines with the buttons while watching both outputs on the multiviewer. Write the press count for slides with builds beside each cue on your script.
7. Agree with each presenter, in rehearsal, who advances. If they keep a clicker, connect its receiver so both machines receive its presses and test it from where they will stand.
8. At every pause in the show, compare the two outputs and correct drift with the go-to-slide button before the next segment.

What goes wrong

Practice it

At Brightwater Health 2027 you run slides for the general session. Martin Lowe insists on his own Logitech clicker for his keynote. The awards segment has 40 slides timed to stings from audio, and is run by the operator. A main machine and a backup machine both feed the switcher.

Controlling Audio Consoles

Audio technicians use Companion to put mutes, scene recalls and playback on buttons beside the console. This chapter explains what Companion can do on the mixing desks you will meet, how each one is connected, and the rules that keep a button panel from ever putting a live microphone in the wrong state. The first of those rules is that the sound engineer owns the desk.

Audio technicians use Companion to put mutes, scene recalls and playback on buttons beside the console.

Controlling audio consoles

An audio console, also called a mixing desk or just the desk, takes every microphone and playback source on the show, sets their levels and sends the mix to the speakers. The front of house position, FOH, is where the desk sits, usually facing the stage from the back of the room. The engineer who mixes there is the A1. On a corporate show the A1 mixes the presenters' radio microphones, the playback from video and the VOG, the voice of god, the off-stage announcer who says ladies and gentlemen, please welcome.

Modern digital desks can be controlled over the network. The makers publish a protocol for that so that tablet apps, installation systems and products such as Companion can move faders, mute channels and recall scenes. A scene, called a snapshot on some desks, is a stored state of the whole desk or a chosen part of it, recalled in one go. A DCA, a digitally controlled amplifier, is a control fader that turns a group of channels up or down together, for example all five panel microphones.

What audio technicians put on Companion is usually small and repetitive. These uses come up again and again in the module help pages.

The desk keeps its own faders, buttons and screen. Every Companion button does something the A1 could also do on the surface, and the surface always wins. In the IP plan used in this book the audio desk is at 10.0.0.50 and Companion at 10.0.0.10. Most desks come from the factory with a different address, so the A1 sets the desk onto the show network, or the show network is built around the desk's address.

The A1 owns the desk

A Companion button that mutes a channel reaches into someone else's mix. On a live show, the A1 is responsible for every sound the audience hears, and they will not accept a button they have not seen, programmed by someone they have not spoken to. Nor should they. The etiquette is simple and it is not optional.

There is a technical reason behind the etiquette as well. The help page for the Allen & Heath Avantis module repeats Allen & Heath's warning that MIDI connections are not aware of console user profiles or restrictions. A function the A1 has locked on the surface may still be reachable from Companion. Several protocols have the same blind spot. Treat a Companion connection to a desk as privileged access: a closed network, a locked Companion, and only the buttons that were agreed.

Yamaha

Yamaha digital desks are everywhere in corporate and theatre work: the CL and QL series, the TF series, the DM3 and DM7, and the flagship Rivage PM. Companion reaches them through the Yamaha Remote Control Protocol module, written by Andrew Broughton and supported through the checkcheckonetwo community forum, not by Yamaha. Its readme lists Rivage PM, CL1, CL3, CL5, QL1, QL5, TF1, TF3, TF5, TF-Rack, DM3, DM5 and DM7, and some Yamaha I/O racks.

The module offers selected set commands, such as mutes and levels, and recall and store of scenes. Its help page notes that it works only with a connected desk, not with Yamaha's offline Editor software. It can pick up a channel's colour from the desk and colour the button to match, which keeps the deck readable alongside the desk's own scribble strips.

The module also has a macro learn function: you start recording on a Companion button, operate the desk, and the operations are stored on that button. That is a convenient way to build a button, and a convenient way to build a button nobody checked. Record macros with the A1 beside you, and play them back once in rehearsal before they are trusted.

Store scene is the one command to keep off a show deck. A store overwrites the A1's saved scene with whatever the desk is doing now. Recall is what operators need; store belongs to the A1 at the desk.

dLive, Avantis, SQ and Qu

Allen & Heath desks range from the small Qu, CQ and SQ to the Avantis and the large dLive system. Each family has its own Companion module, and each uses Allen & Heath's MIDI over TCP/IP protocol: the desk listens on a network port for MIDI messages, the language music gear has used for decades, carried over the network instead of a five-pin cable.

Two details from these help pages matter on a show. First, some dLive actions, Mute Toggle and the fader increment and decrement, need to know the desk's current state. On the first press after connecting, the module asks the desk for the value and waits up to one second; if the desk does not answer, the action is skipped and a warning is logged. Adding a feedback for that channel caches the value so the first press works at once.

Second, the Avantis module will not guess. Timed and relative fader moves need a known starting level, and if it does not know the level, the help page says it refuses the move rather than guess with live audio. Its connection variables tell you whether the command path is online and, separately, whether the state it shows is synchronised. Do not trust a level or a mute on a key until synchronisation reports ready.

The dLive defaults are 192.168.1.70 for a MixRack and 192.168.1.71 for a surface, which will not match a show network like 10.0.0.0. Agree with the A1 which address the desk will use; never change the desk's network settings yourself.

DiGiCo

DiGiCo desks, the SD range and Quantum, are common on concerts and large corporate shows. The Companion DiGiCo module uses OSC, Open Sound Control, a network message format carried over UDP, and it pretends to be DiGiCo's own iPad control app. That is why setup starts on the desk, where the A1 has to add it.

The help page walks through it. On the desk, System, External Control is enabled and a device of type DiGiCo Pad is added with the Companion computer's address, not the desk's. Its examples use UDP port 7000 for the desk to send and 7001 for it to receive. A Commands Allowed file for the desk family must be loaded, otherwise the desk shows that no commands are enabled. Bundles are set off and Suppress OSC Retransmit on. In Companion, the destination is the desk's local IP address shown in the External Control window, and the ports mirror the desk's.

Every step of that happens in the desk's system menus, during the A1's setup time. Ask for it at the advance stage, not at line check. The module can also pass traffic through to a DiGiCo iPad on the same network, so the A1 does not lose their tablet because Companion is connected.

Once connected, the module controls channels, outputs, snapshots and macros. On and off actions offer Off, On and Toggle where the desk supports them; Toggle reads the current value before sending the opposite. DiGiCo macros are a natural fit for Companion: the A1 builds the macro on the desk, tested and named, and Companion only fires it.

Midas and Behringer

The Behringer X32 and the Midas M32 share a design and a Companion module. Its help page lists mutes and fader levels for channels, aux inputs, effects returns, buses, matrices and mains; send levels and mutes; mute groups; channel trim and head-amp gain; scribble-strip names and colours; loading the desk's internal cues, scenes and snippets; the built-in recorder, which Behringer calls the tape deck; and talkback. A fader move can take a fade time; running another action on that value cancels the first fade.

The Behringer WING has its own module with a long list of actions: faders, pan, sends, mutes, solo, gain, EQ, scene recall, talkback, the USB player and recorder, and the WLive SD card recorder. One point from its help page matters a great deal in practice: the WING supports only one active subscription at a time, and the most recent subscriber is the only one that gets updates. If the A1 uses another application that subscribes to the desk, the two can fight, and one of them will show the wrong state. Ask what else is connected before you add Companion.

The WING module lists Format Card and Delete Session among its recorder actions. Those belong nowhere near a show deck. When a module offers commands that destroy data, leave them out entirely, and if a button must exist, protect it as chapter 16 describes.

Other desks have modules too: the Behringer X Air, the Soundcraft Ui series and other Allen & Heath models among them. The same approach applies to all of them: read the module's help page, set the desk's network control on with the A1, and test each button against the show file.

Mic mutes

A microphone that is open when it should be closed broadcasts a private remark to the whole room. One that is closed when it should be open leaves the CEO talking to nobody. Mic mutes are the most sensitive buttons in audio, and the most commonly put on Companion. Treat them with the most care.

The principle is that mutes must fail safe. If Companion, the network or the deck fails, nothing on the desk should change and the A1 must still have full control of every channel at the surface. A Companion button is a convenience on top of the desk, never the only way to mute a microphone.

On Brightwater Health 2027 the panel of five shares a mute group on the desk. The A1 agrees one Companion key for it: Mute Panel and Unmute Panel as two separate keys, each with a feedback from the desk that turns the key red while the group is muted. Dana Okafor's host mic and the VOG are on the deck as display keys only, showing state and level, with no action.

Even a good button can be pressed at the wrong time. The A1 decides whether any mute key lives on a deck outside their own reach, and many will say no. That is a normal answer.

Walk-in music and stings

Walk-in music plays while the audience arrives. A sting is a short musical hit, a few seconds long, under an award name or a speaker's walk-on. Both are classic Companion buttons, because they are fired on a cue from the script and must be instant.

Where they play from decides which machine the button talks to. Many desks have a built-in USB player or recorder, and the modules reach it: the Behringer X32 tape deck's play, stop and pause; the WING USB player's play, stop, pause, previous and next; the Avantis USB playback and recording. On most larger shows the music comes from a playback computer running QLab or similar, which chapter 12 covers; there the Companion button fires the playback software, and the desk channel only carries the audio.

Either way, the volume belongs to the A1. A sting button should start the sound, not set the fader. If a walk-in needs to fade out at doors close, agree with the A1 whether the fade is theirs on the desk, a timed fader action they have approved, or a fade built into the playback cue.

Stings need to land on the beat of the announcement, so they often sit on a combined cue with the slide and the lights, described in chapter 16. Test the timing in rehearsal at show level, never during the show.

How to do it

1. At the advance, ask the A1 whether they want Companion on the desk, what for and who will press it. Note the desk model and software version.
2. Read the Companion module's help page for that desk and send the A1 the settings it needs, such as External Control on a DiGiCo or the MIDI channel on an Allen & Heath.
3. Sit with the A1 and list every button: label, action, channel, mute group or scene number, and who presses it. Get their yes on the list.
4. Agree the desk's address on the show network, for example 10.0.0.50, and let the A1 set it. Add the connection in Companion and confirm its status is OK.
5. Build display keys first, with feedbacks showing the desk's state. Check they follow the desk when the A1 moves a fader or presses a mute on the surface.
6. Build the agreed action keys with explicit Mute and Unmute actions, and leave Store, Format and Delete commands off the deck.
7. Test every key with the A1 watching, at line check, with the speakers safe. Change nothing after they sign it off.

What goes wrong

Practice it

On Brightwater Health 2027 the A1 runs a Yamaha CL5 at 10.0.0.50. The producer asks you to put the panel mics, the host mic, the award stings and the scene changes on your Companion deck so the A1 can concentrate on mixing.

Controlling Lighting Consoles

Lighting consoles have their own operators, cue lists and Go buttons, and Companion can reach almost all of them. This chapter shows how Companion connects to the grandMA, ETC Eos, ChamSys and Hog consoles, how it can drive lights with no console at all, and why the most important lighting decision is who presses go.

Lighting consoles have their own operators, cue lists and Go buttons, and Companion can reach almost all of them.

Controlling lighting consoles

A lighting console, or LX desk, stores every look in the show as a cue. Cues sit in order in a cue list, and the operator presses Go to move to the next one, with whatever fade time the designer set. The person who designs the lighting is the LD, the lighting designer; on smaller shows the LD also runs the desk, and on larger ones a programmer or board operator does. The desk sends its output to the lights over DMX, a control signal with 512 channels per universe, or over the network as Art-Net or sACN, which carry DMX universes over Ethernet.

Lighting technicians use Companion for the same reasons as everyone else: buttons in a second place, state on a key, and one press that fires several things. The common uses are below.

In the IP plan used in this book the LX desk is at 10.0.0.60 and Companion at 10.0.0.10. Lighting networks are often kept separate from the show control network, because Art-Net and sACN can carry a lot of traffic. Ask the LD where Companion should join, and never plug into the lighting network without them knowing.

The rules from the audio chapter apply with equal force. The LD owns the desk and the show file. Every Companion button that touches lighting is agreed with them, and the most important of those rules is this: never fire lighting cues from a deck the LD has not approved.

grandMA, ETC Eos, ChamSys and Hog

Each major console family has its own Companion module, and each module reaches the desk in a different way. Read the help page, set the desk side with the LD, and test on the show file.

grandMA2 and grandMA3

MA Lighting's grandMA consoles run large concerts, television and corporate shows. The grandMA2 module connects by Telnet, a plain text command connection, and the help page reminds you to switch on Telnet Remote in the console's global settings first. It can run any command-line command, press and release console keys, turn encoders and spin the wheel, and it shows the last response from the console in a variable.

The grandMA3 module uses OSC. The console's IP, OSC port and prefix are set in the module and must match an OSC line on the console, set up under In and Out, with Receive and Receive Command ticked; the module's help page says it will not work otherwise. MA's own manual explains that the prefix, a short word with no slashes, means the console only processes messages that start with it, and that Receive Command is what allows command line commands over OSC. The module can select sequences, groups and MAtricks, call macros and plugins, run quick keys and commands, and toggle executor buttons.

Run Command is the most powerful action on either module. It types into the console's command line as if the operator did. On a running show, a command typed by Companion lands in the same command line the programmer is using. Agree with the LD exactly which commands are allowed, and prefer macros and executors they have built and named.

ETC Eos

ETC's Eos family, from the Element and Ion to the Eos Ti and Apex, is the standard in theatre and common in corporate work. The Companion module talks OSC over TCP, on port 3032, or port 3037 when Use TCP SLIP is set. The help page shows where OSC RX and TX are switched on in the console's setup, which moved between software versions.

The module has a setting that matters for etiquette: the User ID. Eos lets several users work on one show, each with their own command line. The help page advises using a different User ID for Companion if someone will be running the console while it is being controlled, otherwise their command lines can conflict. Give Companion its own user, agreed with the LD.

The actions include Go and Stop/Back, which behave like the console's own buttons, Run Cue, Run Macro, Fire Preset, channel, group and submaster intensity, key presses and custom commands. Feedbacks colour a key when a chosen cue is pending or active, and when the connection changes. Variables show the active and pending cue number and label, the show name and the command line. A Go key that shows the pending cue number is one of the most useful lighting keys there is.

ChamSys MagicQ and QuickQ

ChamSys MagicQ consoles and the free MagicQ PC software are common with rental companies and on tours. There are two Companion modules: one using OSC, with feedback, and an older one using UDP, with a default port of 6553 in its help page. The OSC module can set and adjust playback levels, Go, flash, pause and release playbacks, jump to a cue, control execute buttons and faders and the 10 Scene controls, and send remote commands.

Its help page is unusually frank about limits, and they are worth learning. The Desk Black Out action presses the console's blackout button; what that does depends on how the console's DBO function is set, which the module cannot read. On some settings Black Out Off does not end the blackout, and on one it taps tempo instead. The blackout feedback shows what Companion last sent, never what the rig is doing. Do not rely on that key to tell you whether the stage is dark. ChamSys QuickQ, the simpler range, has its own module with playback levels, Go, flash, pause, release and 10 Scene.

High End Hog 4

The Hog 4 family, now supported by ETC, takes OSC from tablet apps such as TouchOSC. ETC's support article on setting up the iHog OSC app recommends console input port 7001 and output port 7002, says the two must differ, and shows where to enable OSC in and out in the console's network settings. The Companion module can Go on a cue in a cue list, Go, halt, release and resume cue lists, scenes and macros, press master and hardware keys, set master fader levels and send MIDI notes. Its help page says it does not yet read status back, so Hog keys cannot show cue state.

Other consoles have modules too, among them Obsidian ONYX over OSC, and MA's MIDI Show Control over Ethernet. Whatever the desk, confirm in its module's help page what it can and cannot do.

Lighting with no console

Not every show has a lighting console. A small corporate breakout, a press conference, a product launch with four LED fixtures, a film set with a few practical lamps: often the lights need only a handful of states, on, off, a colour, a level. Companion can send DMX itself, over the network, through its generic Art-Net and sACN modules. Each fixture's DMX channels are then set from Companion buttons, and the lights listen to a network-to-DMX node or take Art-Net or sACN directly.

Each module sends one universe; for more universes you add more connections. Values run from 0 to 255 on each of the 512 channels, and both modules can fade to a new value over a set time.

Two cautions. First, if a lighting console is also on the network, Companion and the console can both send the same universe. With sACN the receiver takes the source with the higher priority; the Companion module sends at priority 100 by default, which is also the usual default, so the two may merge or fight. Never send onto a universe the LD is using unless they have set it up for you. Second, Art-Net broadcast sends every packet to every device on the network; the module's help page keeps it to small or dedicated lighting networks, and unicast is the better habit.

On The Night Shift, a practical lamp in Nora Vance's office set is on a small dimmer fed by sACN. The gaffer, who heads the electrical department on a film set, agrees a single Companion key that fades it from 0 to 70 percent over two seconds and a second key that fades it back. Chapter 17 covers light from the deck on film sets in detail.

A console-free rig still has an owner. On a show it is the LD or the lighting technician; on a film set it is the gaffer. The same agreement applies: they say which channels Companion may touch and what each button does.

Who presses go

On a show, cues are called. In a theatre the stage manager calls them over the headset: standby lights cue 42, then lights cue 42 go, and the board operator presses Go on the word. On a corporate show the show caller or producer does the same for lights, sound, video and slides. On a concert the LD often runs the show by eye and ear, or the songs are timecoded so the console runs cues from the music, as on The Low Tides.

Companion makes it easy to put a lighting Go on a button anywhere: on the video operator's deck, on a combined cue, on a tablet. That ease is the danger. A Go fired twice skips a cue; a Go fired by the wrong person at the wrong moment puts the stage in the wrong look in front of the audience. Who presses go is decided by the LD and the show caller, not by the person who programmed the deck.

When a lighting cue is part of a combined Companion cue, the same rule holds: the LD approves that key before it exists, and approves it again if anything on it changes. Chapter 16 covers building those combined cues; this is the lighting part of the agreement.

Treat some lighting keys as dangerous: blackout, release all, anything that clears or overwrites, and Run Command with free text. Leave them off show decks, or protect them as chapter 16 describes. And remember that the console keeps its own Go button, its own faders and its own operator. If Companion fails, the show continues from the desk.

How to do it

1. Ask the LD whether they want Companion on the lighting desk, what for, and who will press each key. Note the console, its software version and which network Companion should join.
2. Read the module's help page and give the LD the console-side settings it needs, such as Telnet Remote on a grandMA2, an OSC line with Receive Command on a grandMA3, or a separate User ID on Eos.
3. Let the LD set the console's network side. Add the connection in Companion with the console's address, for example 10.0.0.60, and confirm its status is OK.
4. Build display keys first: active and pending cue where the module offers them. Check they follow the desk when the operator presses Go.
5. Build only the action keys the LD agreed, using cue, macro or executor numbers from their show file. Leave blackout, release all and free-text commands off the deck.
6. Test each key with the LD watching, in a rehearsal or a dark stage session, never during the show. Change nothing after they approve it.

What goes wrong

Practice it

The Low Tides play a 3,000-seat theatre. The LD runs a grandMA3 at 10.0.0.60, with most songs timecoded. The video director asks for a lighting Go and a blackout key on the video deck for the encore, and the tour manager wants a house-lights key at the merchandise stand.

Building Cues

A cue is one planned moment of the show: the lights change, the video rolls, the slide moves on, all at the instant the caller says "go". This chapter teaches how to turn the show's paperwork into Companion buttons that fire those moments cleanly, whether one press moves one machine or five, and how to keep the buttons that can end a show out of reach of a stray finger.

A cue is one planned moment of the show: the lights change, the video rolls, the slide moves on, all at the instant the caller says "go".

What a cue is

On a show, a cue is a numbered, written moment when something changes. "Video cue 4: play the opener" is a cue. "Lights 12: house to half" is a cue. Every cue has three parts: what changes, which machine changes it, and the moment it happens. The moment is usually set by a person called the show caller, often the stage manager or the producer, who speaks on headset ("comms") and says "standby" before the cue and "go" when it fires.

Companion turns a cue into a button. You put the cue number and a short name on the key, you load it with the actions that make the change, and when the caller says "go" you press it. The earlier chapters taught how to build a button and how to talk to each kind of machine. This chapter is about the decisions above that: how many machines one cue button should drive, how to arrange the buttons so they follow the show, and how to keep the dangerous ones safe.

One button, many machines

The question every new programmer asks is whether one cue button should fire several machines at once, or whether each button should drive one machine. Patrice's answer, from corporate shows, concerts and film sets, is that it is however you program it. Companion lets a single button hold actions from many connections, so both ways are open to you. The choice belongs to the programmer, and the show decides which one fits.

One button, one machine

Here each key does one thing on one device: "PB-A PLAY", "ATEM CUT", "PPT NEXT". Nothing happens that is not written on the key. If the opener video needs Playback A to roll and the ATEM to cut to it, you press two keys in order, or two people each press their own.

This fits when cues are loose and the timing is decided live, when the order can change at any moment, when several operators share the work, and when you are new to a show and still learning it. It is also the easiest layout to troubleshoot: if a key misbehaves you know exactly which machine to look at. Most transport decks are built this way, one key per command per machine, because transport is about live control rather than planned moments.

One button for several machines

Here one key holds a whole cue. At Brightwater Health 2027 the key "C7 OPENER" might roll Playback A at 10.0.0.31, cut the ATEM at 10.0.0.20 to that input, and recall a lighting cue on the desk at 10.0.0.60, all from one press. The caller says "go" once and three departments move together.

This fits when a moment has to land in several places at exactly the same time, when the cue is rehearsed and will not change, and when one person owns all the machines involved. It also fits moments that are too fast for two hands: a video that must start on the same frame the switcher cuts to it.

When each fits

Most working decks mix the two. Patrice's habit on a show with many machines is two decks: one for transport, built one key per command, and one for all the cues, where a key may drive one machine or several depending on the cue. Chapter 9 covers that layout. Whatever you choose, the label must tell the truth. A key that fires three machines says so, for example "C7 OPENER PB+ATEM+LX", so the next person, or you at two in the morning, knows what it will do.

Cues follow the paper

Every cue button starts on paper. The paper is the run of show from the producer and the cue sheet for your department. Your buttons copy the paper: the same numbers, the same names, the same order. When the caller says "standby video 7", you look for a key that says 7, not a key you named "OPENER THING".

Before you program anything, write your cue sheet. For each cue note the number, the name, what changes, which machines, what triggers it (the caller, a line spoken on stage, timecode), and any note about timing. Then build the buttons from the sheet. If the paper changes, change the sheet first and the buttons second, never the other way round.

That is the general session at Brightwater Health 2027, cut short. The "Machines" column is where you decide, cue by cue, whether the button drives one machine or several. Cue 6 is called many times during the awards, so it wants its own key that can be pressed again and again without stepping forward, while cue 3 happens once.

Laying the cue page out

Lay cue keys in show order, left to right and top to bottom, the way you read a page. Put the cue number first in the label, then a short name. Group a segment on one row if you can: the walk-in cues on the top row, the opener and host on the next, the awards on the next. Leave a blank key between segments if it helps the eye. Colour keys by department or by type, and keep the same colour meaning across every show you do, as chapter 6 taught.

Large shows outgrow one page. Then the page becomes the segment: page 3 "GENERAL SESSION", page 4 "AWARDS", page 5 "CLOSE". Name each page. Put a page-change key in the same corner of every page so your hand learns where it lives.

Order and timing in a cue

When one button drives several machines, the order and timing of its actions matter. Chapter 6 introduced actions, delays and order on a single button. Here is how those tools behave inside a cue.

In current versions of Companion the actions at the top level of a button run in what the user guide calls Concurrent mode: they all start together, in parallel, except where you insert the built-in "Wait" action, which delays every action that follows it. The Wait action replaced the older per-action delays in Companion 3.5. For finer control there is an "Action Group", which can hold other actions and run them Concurrent (together) or Sequential (one after the other, each waiting for the last to finish).

Sequential mode has a catch the user guide spells out: not every module tells Companion when an action has completed. With a module that does, sequential order is reliable. With one that does not, Companion cannot know when to start the next action, so test the sequence and, where the gap matters, use a Wait.

Why timing matters between machines

Machines do not respond at the same speed. A playback machine may need a few frames to start rolling. A switcher cut is almost instant. A lighting cue has its own fade time set on the desk. If the opener key starts Playback A and cuts the ATEM at the same instant, the audience may see a frame of black or a frozen first frame before the video moves. The usual fix is to start the playback first, then add a short Wait before the switcher cut. Find the right gap in rehearsal, by watching program output, not by guessing.

Note the timing on the cue sheet: "PB-A play, wait 200 ms, ATEM cut". If someone rebuilds the button later, the paper tells them why the wait is there.