View on GitHub

atemOSC

Control ATEM video switchers with OSC

atemOSC is a network proxy, listening for commands following the OSC protocol and executing those commands on Blackmagic ATEM video switchers.

atemOSC Screenshot

Download the App

Download Latest Version

Download older or pre-release versions:

  1. Go to the releases page
  2. For a version that supports older versions of the Atem SDK, scroll down until you find the release for the version you want.
  3. Under Assets, select atemOSC_[version].dmg

Setup and Usage

After launching the application, enter the IP address of the switcher and which local port to listen on (default 3333), and then send OSC commands to the IP address of the computer running atemOSC that port. If you set an outgoing IP address and port, atemOSC will send status updates and feedback OSC messages to the IP address and port you specified.

If you are sending atemOSC messages from a queueing software or translation software on the same computer that atemOSC is running on, make sure to send messages to 127.0.0.1 (localhost) on the port that atemOSC is listening on.

If you are sending atemOSC messages from another device, you will need to send it to the IP address of the computer running atemOSC on the port that atemOSC is listening on. You can find the IP address of a macOS computer by going to System Preferences > Network or by running ifconfig in a terminal window.

If you would like to send OSC from AppleScript or Terminal commands, you can download and use the sendosc command. See the actionscript example in this repository for an example of using AppleScript and sendOSC. SendOSC also enables using AtemOSC with ControllerMate and X-keys.

If you would like to control your switcher using a MIDI board or device, consider pairing this software with OSCulator or MidiPipe. If you would like to control AtemOSC directly using MIDI, comment on Issue #111 to let us know.

If you would like to control your switcher using a mobile device, you can use TouchOSC or Open Stage Control.

Videos & Guides

Usage with Ableton Live and OSCulator (MIDI) by Jake Gosselin: https://www.youtube.com/watch?v=Xhbk1epkrLc

Usage with QLab by Jack Phelan: https://jackp.svbtle.com/atem-mini-qlab-and-osc

Usage with TouchOSC by John Barker: https://www.youtube.com/watch?v=jX7YI-DTMxM

Usage with OSCulator (MIDI) by John Barker: https://www.youtube.com/watch?v=HQm2KZYcPws

Usage with OSCulator (MIDI) by Morgan Warf: https://www.youtube.com/watch?v=ooaOz5Uytxs

Usage with ProPresenter and OSCulator (MIDI) by Tiffany Howard: https://www.youtube.com/watch?v=dHwSHa8UWVw


OSC API

The full list of the OSC-addresses available for your switcher can be obtained by going to the “OSC Addresses” tab once you’ve connected atemOSC to your switcher. The list below is just an overview of what the addresses may look like for a generic switcher.

All addresses must start with /atem/. atemOSC will ignore all OSC commands it receives whose address does not start with /atem/.

Multi-switcher support

If you only want to connect to a single ATEM switcher, leave the nickname field blank and use the addresses below as normal. By default, all commands without a nickname will be sent to the first switcher with no nickname.

If you connect multiple switchers to atemOSC, you will need to provide a nickname for each switcher and use that nickname in the address to specify which switcher to send the command to. If you add a nickname to a switcher, you must send the nickname in the address, and all feedback messages will contain the nickname in the address.

For example, /atem/my-switcher-1/transition/auto will trigger an automatic transition on the switcher whose nickname is my-switcher-1

Program and Preview Selection

By default, commands will be sent to the first mix effect block (M/E). To send commands on other mix effect blocks, use the address: /atem/me/$i/program <number>, where $i is 1, 2, 3, or 4

For preview selection /atem/preview $i can be used.

Also supports sending the input in the address instead of as a value (e.g. /atem/program/5)

Feedback: Enabled for all values

Note: The actual numbers vary greatly from device to device, be sure to check the in-app address menu

Note: You can fetch the names of each input by sending the /atem/send-status command (detailed later), this will return the short names of each input to /atem/input/$i/short-name and the long names to /atem/input/$i/long-name. After the initial fetch, you will also recieve updates when the short or long name is changed in ATEM Software Control.

Transition Control

By default, commands will be sent to the first mix effect block (M/E). To send commands on other mix effect blocks, use the address: /atem/me/$i/transition/..., where $i is 1, 2, 3, or 4

To set the transition type of the Auto transition:

To set rate for Auto transition:

Feedback: Enabled for /atem/transition/bar

Auxiliary Source Selection

Feedback: Enabled

Upstream Keyers

By default, commands will be sent to the first mix effect block (M/E). To send commands on other mix effect blocks, use the address: /atem/me/$i/usk/..., where $i is 1, 2, 3, or 4

USK Source

USK Luma Parameters

USK Chroma Parameters

USK DVE Parameters

Where $i can be 1, 2, 3, or 4 depending on the capability of your ATEM switcher

Feedback: Enabled for ‘/atem/usk/$i/on-air’, ‘/atem/usk/$i/tie’, ‘/atem/usk/$i/source/’, ‘/atem/usk/$i/luma/’, and ‘/atem/usk/$i/chroma/*’

Downstream Keyers

DSK Source

DSK Parameters

Where $i can be 1, 2, 3, or 4 depending on the capability of your ATEM switcher

Feedback: Enabled for ‘/atem/dsk/$i/on-air’ and ‘/atem/dsk/$i/tie’

Audio

Supports both standard and Fairlight audio mixers.

Feedback: Enabled for all values

Additional TouchOSC feedback - Every time the mix changes, 3 messages are sent:

Media Players

Feedback: None

SuperSource (when available)

Feedback: None

Macros

Feedback: Enabled for /atem/macros/max-number, /atem/macros/$i/name, /atem/macros/$i/description, and /atem/macros/$i/is-valid. Also available On-Request (you can send the command to get the value in a return message)

HyperDeck

Feedback: Enabled for clip, clip-time, timeline-time, state, single-clip, and loop. The state of the HyperDeck is available as a string value at /atem/hyperdeck/$i/state, and is sent out automatically when the state changes. State will be one of play, record, shuttle, idle, or unknown.

Recording

Feedback: Recording state sent to address /atem/recording/state, will contain a string that is one of idle recording stopping

Other

Type Casting

For your convenience, atemOSC will cast certain types to the correct type for certain endpoints

TouchOSC Support

Due to the limited capabilities of the TouchOSC client, atemOSC supports an alternative form of passing values. For any method listed above that requires a string or int value, you can pass the string or int as part of the address instead of as a value. For example, you can send /atem/transition/type/wipe instead of /atem/transition/type wipe, or send /atem/usk/1/source/fill/3 instead of /atem/usk/1/source/fill 3. Additionally, any command sent with one of these alternative addresses and a float value of 0.0 will be ignored, as that represents a button release and commonly causes issues. If you would like to trigger a change on button release instead of button press, simply flip the values in the TouchOSC Editor.


Common Issues

I want to use <insert feature here> that AtemOSC does not support yet

Problem

There are a lot of features that AtemOSC does not yet support, most noteably camera control and advanced USK settings.

Solution

You are free to open an issue or comment on and existing issue, but the quickest solution for you is to create a macro in ATEM Software Control that accomplishes the task you would like and call the macro using AtemOSC.

Auto and cut commands don’t seem to work, or look buggy, when combining atemOSC with MIDI control

Problem

A lot of MIDI controls send two signals when a button is pressed, one signal when you press down, and another when you release. If you connect the button the /atem/transition/auto or cut, atemOSC recieves both events and attempts to send the transition command to the switcher twice. This can cause buggy behavior or just not work at all.

Solution

Tune your MIDI software to send only one of the two signals, either ok button press (rising edge) or button release (falling edge). See #120 for instructions for OSCulator.

I want to send feedback messages to multiple devices with different IP address

Problem

Occasionally, you may want to send output messages to many devices on the same network, but this does not seem possible because the feedback IP address field only accepts one IP address

Solution

Set the IP address to be the broadcast address for your network. This will cause feedback messages to be sent to every device on the network. For a typical network, the broadcast address is calculated by replacing the last octet with 255 (e.g. for a 192.168.1.x network, the broadcast address is 192.168.1.255). However, the broadcast address may be different if the subnet mask is not 255.255.255.0. You may be able to use this subnet calculator to calculate the broadcast address for your network.


Contributing

I welcome pull requests, but recommend that you open an issue first so that we can discuss the bug or feature before you implement it.

Acknowledgements


Developer Resources

Build and run app locally

  1. Download and install XCode
  2. Clone repository or download the repository ZIP
  3. Double click the .xcworkspace file to open in XCode
  4. Click on the project, go to the “Signing & Capabilities” tab, change the Team to your personal team, and change Signing Certificate to “Sign to Run Locally”
  5. Click the play button in the top left to run

Find what line a crash occured on given a crash report (on MacOS)

People like to send crash reports in issues. You can use this method to find out which line of the program crashed from just the crash report and version number.

  1. Download the atemOSC.debug.zip file associated with the release that crashed and unzip it
  2. At a command line, cd into the unzipped folder (Usually ~/Downloads/atemOSC.debug)
  3. Copy the crash report into a file (e.g. crash.log) and save it to the unzipped folder
  4. Copy the find_crash bash script from the root of this repository into that folder as well
  5. Run ./find_crash crash.log, replacing crash.log with whatever your crash report file is named
  6. The script should tell you which line in which file caused the crash