{"id":26910474,"url":"https://github.com/mackenly/pyatemapi","last_synced_at":"2025-04-01T13:38:34.671Z","repository":{"id":45170395,"uuid":"513263331","full_name":"mackenly/PyATEMAPI","owner":"mackenly","description":"Python ATEM REST API","archived":false,"fork":false,"pushed_at":"2024-12-28T02:43:44.000Z","size":371,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-28T03:26:24.007Z","etag":null,"topics":["atem","atem-switcher","blackmagicdesign","bmd","broadcast","hacktoberfest","production","streaming"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/repository/docker/mackenly/pyatemapi/general","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mackenly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mackenly"}},"created_at":"2022-07-12T19:10:44.000Z","updated_at":"2024-12-28T02:43:47.000Z","dependencies_parsed_at":"2024-02-19T01:46:29.344Z","dependency_job_id":"0e2282e5-0520-48f1-a7dc-0b705c153df5","html_url":"https://github.com/mackenly/PyATEMAPI","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackenly%2FPyATEMAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackenly%2FPyATEMAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackenly%2FPyATEMAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackenly%2FPyATEMAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mackenly","download_url":"https://codeload.github.com/mackenly/PyATEMAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246648909,"owners_count":20811620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atem","atem-switcher","blackmagicdesign","bmd","broadcast","hacktoberfest","production","streaming"],"created_at":"2025-04-01T13:38:34.009Z","updated_at":"2025-04-01T13:38:34.658Z","avatar_url":"https://github.com/mackenly.png","language":"Python","funding_links":["https://github.com/sponsors/mackenly"],"categories":[],"sub_categories":[],"readme":"# PyATEMAPI\n\nPython Blackmagic Design ATEM REST API\n\n## Purpose\n\nTo 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.\n\n*Why build a web API for ATEM?*\n\nThis API allows developers to interact with ATEM Switchers without having to write desktop code. Instead, developers can now interact with\nan ATEM through the browser using simple web APIs with Javascript.\n\n## Roadmap / Features\n\n-   [x] Fully Documented in [Postman](https://documenter.getpostman.com/view/19380446/UzQpvT1y)\n-   [x] Web Example\n-   [x] Get tally data\n-   [x] Fade to black\n-   [x] Trigger Cut\n-   [x] Trigger auto transition\n-   [x] Set preview\n-   [x] Set program\n-   [x] DSK Tie\n-   [x] DSK Cut\n-   [x] Ping switcher\n-   [ ] Upload / manage media pool\n-   [ ] Audio control\n-   [x] Tested using ATEM Television Studio HD\n-   [x] [Docker Image](https://hub.docker.com/repository/docker/mackenly/pyatemapi/general)\n-   [ ] Support for options from env or config file\n-   [ ] Support for multiple switchers\n-   [ ] CI/CD Testing with GitHub Actions (will probably require creating or updating a more fully featured mocking tool like PyATEMSim but with better support)\n\n## Usage\n\nClone PyATEMAPI to your machine by running:\n\n```bash\ngit clone https://github.com/mackenly/PyATEMAPI.git\n```\n\nEnter the project's directory, then install the required packages by running:\n\n```bash\npip install -r requirements.txt\n```\n\nWhile 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`).\n\nThe 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).\n\nThe 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.\n\n\n```bash\npython server.py --ip 127.0.0.1 --passphrase Password1 --port 5555\n```\n\n\u003e [!WARNING]\n\u003e 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:\n\n\u003cdetails\u003e\n\u003csummary\u003eBest practices for passing in sensitive variables\u003c/summary\u003e\n\nIf 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:\n\n### Linux/Mac\n\n```bash\nread -s PASSPHRASE\nread SERVER_IP\npython3 server.py\n```\n\n### Windows\n\n```powershell\n$securedValue = Read-Host \"Passphrase\" -AsSecureString\n$bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($securedValue)\n$env:PASSPHRASE = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)\n$env:SERVER_IP = Read-Host \"Atem Device IP\"\npython server.py\n```\n\nNOTE: Some versions of powershell support `Read-Host \"Password\" -MaskInput` as well, which would reduce the above\ncommand to simply:\n\n```powershell\n$env:PASSPHRASE = Read-Host \"Passphrase\" -MaskInput\n$env:SERVER_IP = Read-Host \"Atem Device IP\"\npython server.py\n```\n\u003c/details\u003e\n\nAfter starting the server, you can use the web API to interact with the ATEM Switcher.\n\n## API Documentation\n\nThe API documentation is available through Postman at\n[https://documenter.getpostman.com/view/19380446/UzQpvT1y](https://documenter.getpostman.com/view/19380446/UzQpvT1y).\n\n## Demo\n\nTo 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.\n\n\u003cimg src=\"./assets/example-screenshot.jpg\" width=\"500\"\u003e\n\n## Example Request\nTo get the tally data from your ATEM switcher, you use Javascript, as shown below:\n\n```javascript\nfetch(\"http://localhost:5555/tally\", {\n  method: 'GET',\n  headers: {\n    'Authorization': 'MyPassword'\n  },\n})\n  .then(response =\u003e response.text())\n  .then(result =\u003e console.log(result))\n  .catch(error =\u003e console.log('error', error));\n```\n\nThe response should look something like this:\n```json\n[{'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}]\n```\n\nAgain, view [the API docs in Postman](https://documenter.getpostman.com/view/19380446/UzQpvT1y) for more examples and documentation.\n\n## Docker\n\nThe application can be run via Docker. Use the DockerHub registered container found on [mackenly/pyatemapi](https://hub.docker.com/repository/docker/mackenly/pyatemapi/general) 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.\n\n### Create an ENV file\n\nThe ATEM device ip and passphrase for the API will be pulled from environment variables. To do this we'll need to create\nand [env file](https://docs.docker.com/compose/environment-variables/env-file/) called `.env` which will be used by our\ndocker and docker-compose instructions later. Just create the `.env` file and edit it to have the following variables:\n\n```plaintext\nSERVER_IP=192.168.1.42\nPASSPHRASE=MySecretPassword\n```\n\n### Run from DockerHub\n\nYou can run the application from the built images in DockerHub.\n\n```bash\ndocker run -d -p 5555:5555 --env-file=.env mackenly/pyatemapi:latest\n```\n\n### Run with docker-compose\n\n```bash\ndocker-compose up -d\n```\n\nYou can also explicitly define the path to the env file if you are managing multiple configurations:\n\n```bash\ndocker-compose --env-file .env_alt up -d\n```\n\nYou can then bring the service down with a standard docker-compose down command:\n\n```bash\ndocker-compose down\n```\n\n### Build and run Docker container from source\n\n```bash\ndocker build -t pyatemapi .\ndocker run -d -p 5555:5555 --env-file=.env pyatemapi\n```\n\n## Testing\n\nIf you would like to test this API, you can use a tool called [PyATEMSim](https://github.com/jonknoll/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.\n\n## Contributing\n\nContributions are welcome. Please open an issue or pull request on [mackenly/PyATEMAPI](https://github.com/mackenly/PyATEMAPI).\n\nFiscal contributions can be made through [GitHub Sponsors](https://github.com/sponsors/mackenly).\n\n## License\n\n[The MIT License (MIT)](./LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmackenly%2Fpyatemapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmackenly%2Fpyatemapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmackenly%2Fpyatemapi/lists"}