Controlling Zoom with QLab

Theatre Technology

Learn how to use QLab to control Zoom using ZoomOSC.

In today's post we are going to cover how to control Zoom with Qlab, or really any other OSC enabled software using ZoomOSC. Also be sure to stay tuned to the end of the article where I cover some limitations we ran into so you don’t make the same mistakes. In one recent project that I worked on we needed to automate zoom to control various aspects of the virtual production. In zoom as we well know there are lots of things that you need to manage to keep things running smoothly like muting, unmuting, spotlighting, pinning, and toggling between gallery and speaker view.

The World of Zoom


Zoom


While you can have a dedicated zoom person to manage all of these parameters during a presentation, this would quickly get overwhelming. As the number of participants increase, or the complexity of the show goes up you will quickly realize you will need some way to automate the process.

Zoom OSC


Zoom OSC


Thankfully there is an application called ZoomOSC that allows us to control nearly every aspect about zoom using the OSC protocol. If you are new to OSC or need a refresher on how it works check out this video here where I cover the basics and get you up to speed on it. ZoomOSC is both windows and mac compatible, although there are a few features that only work on one or the other, but for the most part either operating system will do. I will leave a link to the ZoomOSC website below where you can grab the application and read up on any additional documentation.

ZoomOSC replaces your normal zoom application so in order to join a meeting you are going to want to enter the meeting info directly into the ZoomOSC application. Once connected a window will popup that will function exactly as zoom would. However, we now have access to a plethora of OSC commands. First we need to configure the OSC connection. 

ZoomOSC Configuration


Zoom OSC Configuration


In the ZoomOSC settings window we can configure some parameters. The Transmission IP and port are used for outputting information about the zoom instance, so if you have a computer that needs to listen to data this is where you would configure that. More commonly we are only interested in sending OSC commands to ZoomOSC and all we need to do is take note of the receiving port, which by default is port 9090 although you can change that to whatever works for you.

Configuring QLab Network


QLab config


Now that we have ZoomOSC configured to receive OSC commands let's hop on over to Qlab and see how we can start sending commands. First, we need to configure our network destination in the Qlab settings. All we need to do is type in the ip address of the computer that is running ZoomOCS, in my case I am using localhost since both ZoomOSC and Qlab are running on the same computer. Lastly we need to enter the port number of ZoomOSC and we are good to go!

OSC Structure


Let’s now take a look at the OSC structure that ZoomOSC uses. When you download the ZoomOSC application it also comes with a very nice PDF that outlines all the commands you can use. Starting with the overarching OSC structure any command we wish to send to ZoomOSC needs to begin with /zoom. To target a user we have a couple of different ways. We can use a targetID, their username, the users index in gallery view, their zoom id, or if you need to send a command to yourself you can use “me”. Additionally you can target groups of users using, all, targets, panelists, and attendees.

Now that we have addressed which target we want to control, let's look at some of the commands we can send. Since there are lots of possible commands, I am just going to cover the most useful ones. You can control the video and microphone commands using videoOn, videoOff, mute, and unMute, each of these commands also offer a toggle version which will switch the current value.

One command we used a lot in our last project was the spotlight feature which highlights a certain user's view for the rest of the people in the meeting. You can use: spot, addSpot, unSpot, and toggleSpot. Likewise you can also pin a user instead using pin, addPin, unPin, and togglePin. 

You are also able to change the display mode by using setGalleryView and setSpeakerView to toggle those related options as well as switch between the pages while in gallery mode. 

There are some more high level commands that you can use such as making another user a host, promoting users to panelists, and renaming participants. There is also a plethora of other commands we can use from screen sharing to changing the device configuration. If you can do it in zoom there is probably also a way to do it within ZoomOSC.

Putting It All Together


Let’s now take a look at an example at how we would form an entire OSC message that combines the command and the user target. Say we have a user named Travis and we want to spotlight their video for everyone else in the meeting. Since we know that their name is Travis we can start to form the OSC command using the username target which will look like this. We then need to attach the ZoomOSC user command that we want to use, and in this example we will use spot. Lastly, we need to send a data payload over OSC that is the user name we want to target. And with that when we press go on that cue Travis’s video will be spotlight for everyone else to see. For the most part we can just switch the command to whatever we want and keep the target the same to do different things.

ZoomOSC Limitations


This brings us to some limitations of ZoomOSC. The first main limitation is that while ZoomOSC has a great free version there are many features that are only available if you pay. Another issue that we run into often when using ZoomOSC is that it is just a wrapper for zoom and it cannot do anything that you could already do. For example, if you tried to unmute a user it will either require pre-approved consent or the user to manually click accept each time you run a cue. Another thing to watch out for is that the computer running ZoomOSC should be a co-host or else most commands won’t work.