PyATEMMax Protocol Extensions

What It Is

A custom fork of PyATEMMax — a Python library for communicating with Blackmagic ATEM video switchers over their proprietary UDP protocol. The upstream library covers the basics, but many features available in the native ATEM Software Control were simply missing. I reverse-engineered the protocol using Wireshark and added them.

The work started while building the browser-based ATEM control panel for AV Site, but the library itself is independent — it’s a general-purpose Python library for talking to any ATEM.

Why I Built It

The web control interface needed features that PyATEMMax didn’t support — chroma key sampling, DVE positioning, flying key animations, and more. Without these, the browser interface would always be a limited version of the real thing. Rather than waiting for the library maintainers, I figured out the protocol myself.

How It Works

The process was the same for each missing feature: use the native ATEM Software Control to trigger the feature while capturing traffic in Wireshark, then break down the hex dumps. Every ATEM command has a 4-byte identifier (like CACC for chroma, KeDV for DVE) followed by parameter bytes — typically big-endian 16-bit integers. By comparing packets with different values, you can isolate which bytes control what.

The first one I tackled was the chroma sample toggle — a single command with a clear on/off state. That proved the methodology. From there I worked through chroma sample cursor positioning (two commands sent together for X/Y coordinates), the complete modern chroma key parameter set (the library’s existing implementation was outdated), DVE position/size/rotation with border and shadow controls, and the 9-direction Run To Infinite flying key grid — where the existing library command was actually broken and had to be fixed through fresh packet analysis.

The modified library is bundled directly into the AV Site Docker image, so every deployment location has the full feature set automatically.

What Was Added

• Chroma sample toggle and cursor positioning
• Complete modern chroma key parameters
• DVE position, size, rotation, border, and shadow controls
• Run To Infinite 9-direction flying key grid (fixed broken upstream command)
• Fade to Black disable toggle
• Media pool operation research

Tech Stack

• Language: Python
• Analysis: Wireshark, hex dump comparison
• Protocol: Blackmagic ATEM UDP (proprietary, undocumented)
• Integration: Bundled in AV Site Docker image

Gallery

Screenshots and screen recordings coming soon.

Related Journal Entries

Coming soon — Wireshark capture methodology, decoding the CACC command, fixing the broken RFlK command.