ZoomOSC Setup Guide
Don't know where to start? We've got you covered!
ZoomOSC is an incredibly powerful tool for online performance. At a technical level, ZoomOSC is a modified version of Zoom that adds a bidirectional OSC engine which allows you to send OSC commands to control different functions in a Zoom meeting (such as spotlighting or muting) while also receiving information about participants (such as the order of people in Gallery View).
ZoomOSC can be a linchpin in a larger production workflow that requires a media server and/or broadcast encoder. Video designers with experience in media servers have been able to create advanced show programming.
Since ZoomOSC is a technical utility, and not a product, we are distributing it for free and only monetizing consultations and trainings designed to help get productions or creatives unfamiliar with these workflows comfortable using the utility.
ZoomOSC can be used with both serialized (cued) shows or non-linear control surfaces. From the perspective of video flow, a suggested methodology is to have ZoomOSC in communication with a media server. That way, ZoomOSC can send and receive data and the ZoomOSC window/s can be screen-captured.
We recommend using the multi-display mode of the Zoom interface because you can see a gallery view and a full-screen view simultaneously.
After applying video overlays and effects using the media server, the aggregate AV feed can be sent to an encoder (ex: VMix), potentially using NDI, and then the show's "program output" can be sent to a remote audience on platforms like YouTube and Vimeo via RTMP, or it can be looped back into the Zoom meeting for a program monitor within the call.
Case Study (Mad Forest)
4 ZoomOSC Operators
(1) Video operator controlling the spotlight or Gallery/Active view in step with video effects from the Isadora programming
(2) Virtual camera operator using a non-linear control surface (a small Isadora patch that translated keyboard commands into OSC packets) to fire the hundreds of camera cuts used in the show
(3) Director using a non-linear control surface to live mix an improvised portion of the show
(4) Backup operation should any of the other operators lose power or internet
To get started with ZoomOSC, follow the steps below. Please note that the steps for getting started are the same if you are using MacOS or Windows 10 except for Step 1.
To use ZoomOSC, you have to store participants in the program's memory. Once you do this, you can call functions (ex: /zoom/spot 1) on participants using their ZoomOSC ID.
At any time, you can see the list of participants you've previously stored with the command, /zoom/list.
If your talent changes their username - you will not have control over them again unless you call update or modify your "performance_config.txt" file and call load.
If you don't know the names of the Zoom participants ahead of time - Calling update and saving the program's memory to disk using /zoom/save is an easy way to externalize the participant data to other applications using "performance_config.txt"
If someone disconnects from the meeting and then rejoins - As an operator, you don't have to do anything to regain control of the participant for the purposes of calling commands. ZoomOSC automatically tracks information about users in the background, provided they rejoined with the same username.
If you want to get creative, you can have your talent swap usernames (or you can do it for them) as part of an improvisational programming scheme. There are enough building blocks to build very powerful control patches!
3 Ways to Store Participants
Option 1: Live Update
ZoomOSC will look at all the participants in the Zoom meeting and store them in memory, associating their usernames with a ZoomOSC ID, a placement in a zero-indexed list of participants
Option 2: Build as you Go
As users join the Zoom meeting, use the include command to append them to the end of memory, preserving your previous controls but adding new users.
Option 3: Save and load Preset from Disk
ZoomOSC will look for performance_config.txt and load its contents into memory.
This file is created by calling /zoom/save, which takes the contents of ZoomOSC’s participant memory and stores them into the text file - (If you don’t see the file, try calling update, then save)
The idea of this text file is that you can just write in the Zoom usernames of the participants you want to have control of, and you can order the file so that you can have persistent bindings between ZoomOSC IDs and Zoom participants that you can use for multiple rehearsals or performances.
(Take the contents of memory and save to disk)
(Take the contents of "performance_config.txt" on disk and load it into memory)
1) Run the ZoomOSC Installer
Install the program to a location on your computer, such as Documents, that does not require administrator privileges (for simplicity).
1) Run the ZoomOSC.app Program
Hold the Control key and right click on the ZoomOSC.app file and click Open. Then, click Open Anyway.
2) When you run ZoomOSC, you will see a console and Zoom interface
The console contains information about the operation of the program that you can use to debug. The Zoom interface operates much like the regular Zoom platform, with a few modifications.
3) Join your Zoom Meeting
The simplest way to accomplish this is to click Only Join. Enter the meeting ID with no spaces, your username, and the meeting password.
Alternatively, sign in with an account that is not associated with a “Log in with…” interface (e.g. "Log in with Google"). Please create a free Zoom account to use for running this application that does not require that sign in system. You can still use your organization’s premium account, if you have one, to create the meetings and get access to those features, but you should log into the application with this new account.
4) Control ZoomOSC
Use your favorite OSC Controller (TouchOSC, Isadora, QLab, Bitfocus Companion, etc.) to control ZoomOSC. Send commands to the IP Address that ZoomOSC is running on (127.0.0.1 if running the controller on the same computer as ZoomOSC). ZoomOSC uses UDP port 8000.
(the return channel)
Applications can now receive OSC back from ZoomOSC. Presently, ZoomOSC sends OSC packets to port 1234 on the software loopback, 127.0.0.1, on Windows or whatever IP is specified in the TXIP box on MacOS.
The most powerful feature of the return channel is the ability to track participants throughout the Gallery View. You can build upon this framework to create an automatic switching engine to simulate ISO feeds of the Zoom participants.
To use the “galtrack” system:
Make sure ZoomOSC is named "ZoomOSC" in the Zoom call
Have all participants turn off video (if any were on)
If you are using a program monitor, “Hide Self View”/turn off ZoomOSC’s video feed
Load participants into memory with /zoom/load or /zoom/update
Have participants turn on video
Listen to /zoomosc/gallery/order to receive the ZoomOSC IDs of everyone in the gallery view in the order in which they appear from top left to bottom right
You can also build reactive programming off of things like /zoomosc/sound/off to fire events in your Isadora patch, for example, when such an action occurs.
GLSL Live Gallery ISO Feed Simulator
(Automatically crop and identify the gallery)
Liminal has created a free open-source GLSL Shader for automatically cropping the Zoom gallery view. In addition, we have implemented a set of user actors to use with Isadora to automatically create ISO feeds of the talent in the Zoom call. We encourage you to give these tools a try!