Python Blackmagic Design ATEM REST API
To provide a web API for interfacing with ATEM Switchers. The API is designed to be as simple as possible and to be as flexible as possible.
Why build a web API for ATEM?
This API allows developers to interact with ATEM Switchers without having to write desktop code. Instead, developers can now interact with an ATEM through the browser using simple web APIs with Javascript.
- Fully Documented in Postman
- Web Example
- Get tally data
- Fade to black
- Trigger Cut
- Trigger auto transition
- Set preview
- Set program
- DSK Tie
- DSK Cut
- Ping switcher
- Upload / manage media pool
- Audio control
- Tested using ATEM Television Studio HD
- Docker Image
- Support for options from env or config file
- Support for multiple switchers
- CI/CD Testing with GitHub Actions (will probably require creating or updating a more fully featured mocking tool like PyATEMSim but with better support)
Clone PyATEMAPI to your machine by running:
git clone https://github.com/mackenly/PyATEMAPI.gitEnter the project's directory, then install the required packages by running:
pip install -r requirements.txtWhile in the directory of the project, run python server.py to start the server. Pass in as parameters the IP address --ip of the ATEM switcher, optionally a simple passphrase --passphrase for high level authentication, and optionally the port --port to run the server on (defaults to 5555).
The passphrase is optional. If you do not include a passphrase, one will not be required. If you do use a passphrase, make sure to pass it in with your requests in the Authorization header (see below for an example).
The port is also optional. If you do not include a port, the server will run on port 5555. If running via Docker, you can also map the port to a different port on the host machine using docker.
python server.py --ip 127.0.0.1 --passphrase Password1 --port 5555Warning
Passing sensitive data in the command line will result in the passphrase being in plaintext in command line history logs such as in .bash_history, other Linux/Mac shell histories, or $env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine in Windows. This probably doesn't matter for most users, but if you're concerned about it, you can use the following methods to pass in sensitive data:
Best practices for passing in sensitive variables
If running on native python, best practice is to read these variables in with the read command in Linux/Mac or the Read-Host command in Windows:
read -s PASSPHRASE
read SERVER_IP
python3 server.py$securedValue = Read-Host "Passphrase" -AsSecureString
$bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($securedValue)
$env:PASSPHRASE = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
$env:SERVER_IP = Read-Host "Atem Device IP"
python server.pyNOTE: Some versions of powershell support Read-Host "Password" -MaskInput as well, which would reduce the above
command to simply:
$env:PASSPHRASE = Read-Host "Passphrase" -MaskInput
$env:SERVER_IP = Read-Host "Atem Device IP"
python server.pyAfter starting the server, you can use the web API to interact with the ATEM Switcher.
The API documentation is available through Postman at https://documenter.getpostman.com/view/19380446/UzQpvT1y.
To demonstrate and test the API, a basic web controller example is provided. To run the example, enter the web-example directory, modify the constant at the top of script.js with the values you're using to run the server, and then open the index.html file in a browser.
To get the tally data from your ATEM switcher, you use Javascript, as shown below:
fetch("http://localhost:5555/tally", {
method: 'GET',
headers: {
'Authorization': 'MyPassword'
},
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));The response should look something like this:
[{'source': 1, 'preview': False, 'program': True}, {'source': 2, 'preview': False, 'program': False}, {'source': 3, 'preview': True, 'program': False}, {'source': 4, 'preview': False, 'program': False}, {'source': 5, 'preview': False, 'program': False}, {'source': 6, 'preview': False, 'program': False}, {'source': 7, 'preview': False, 'program': False}, {'source': 8, 'preview': False, 'program': False}]Again, view the API docs in Postman for more examples and documentation.
The application can be run via Docker. Use the DockerHub registered container found on mackenly/pyatemapi or build it yourself using the container definition. Some users run this locally on Synology NAS devices, which allow you to run Docker images, on a Raspberry Pi, or within a dedicated Docker server with other production automation apps.
The ATEM device ip and passphrase for the API will be pulled from environment variables. To do this we'll need to create
and env file called .env which will be used by our
docker and docker-compose instructions later. Just create the .env file and edit it to have the following variables:
SERVER_IP=192.168.1.42
PASSPHRASE=MySecretPassword
You can run the application from the built images in DockerHub.
docker run -d -p 5555:5555 --env-file=.env mackenly/pyatemapi:latestdocker-compose up -dYou can also explicitly define the path to the env file if you are managing multiple configurations:
docker-compose --env-file .env_alt up -dYou can then bring the service down with a standard docker-compose down command:
docker-compose downdocker build -t pyatemapi .
docker run -d -p 5555:5555 --env-file=.env pyatemapiIf you would like to test this API, you can use a tool called PyATEMSim. In the directory of the simulator, simply run python atem_server.py and you will be able to interact with the simulated ATEM switcher's provided IP and port via this API. This simulator doesn't provide all the functionality of a real switcher and seems to have issues with input numbers, so don't rely on it for important testing.
Contributions are welcome. Please open an issue or pull request on mackenly/PyATEMAPI.
Fiscal contributions can be made through GitHub Sponsors.