# clvlabs/pyatemmax architecture

> Architecture diagram of the GitHub repository clvlabs/pyatemmax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clvlabs/pyatemmax
- Repository: https://github.com/clvlabs/pyatemmax

## Overview

##### Project type and purpose
- PyATEMMax is an open-source Python library (SDK) designed to monitor and control Blackmagic Design ATEM video switchers over the network. It provides a programmatic interface for exchanging commands and state updates with ATEM hardware.
- There is no “frontend” or “backend” in the web-app sense—instead there is a layered library that exposes connection management, protocol parsing/serialization, command handlers, state-data objects, and utility functions. Consumers are Python scripts or applications (the “examples” folder) that import PyATEMMax, connect to an ATEM switcher, issue commands, and react to events.

##### File structure
- Top-level directories:
- PyATEMMax/ – the core library
– ATEMConnectionManager.py: opens and manages the TCP/UDP socket
– ATEMBuffer.py, ATEMProtocol.py, ATEMProtocolEnums.py: low-level framing and parsing
– ATEMCommandHandlers.py & ATEMSetterMethods.py: high-level API for sending commands
– ATEMSwitcherState.py & StateData/: classes representing the switcher’s state (audio mixer, video mixer, macros, etc.)
– ATEMUtils.py, ATEMValueDict.py, ATEMConstant.py, ATEMException.py: shared constants, error types, and helpers
- docs/: static site (Jekyll) for online docs—separate from the runtime library
- examples/: sample Python programs showing how to use the library
- setup.py, setup.cfg, README-*.md: packaging and project metadata
- Patterns: layered architecture (Network → Protocol → Command API → State Model → Client code)

##### README for additional insights
- Purpose: port of an Arduino library to Python
- Provides online docs via GitHub Pages
- Clients (scripts and applications) import PyATEMMax, create a connection, subscribe to state changes, and invoke setter methods

##### Summary
- Important modules within each layer, and note any threading or callback mechanisms between Network and State Model

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client["Client/Application\n(examples/)"]:::external
    click Client "https://github.com/clvlabs/pyatemmax/tree/master/examples/"

    %% Command Layer (Public API)
    subgraph "Command Layer (Public API)"
        direction TB
        ATEMMax["ATEMMax.py\n(Package Entrypoint)"]:::api
        click ATEMMax "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMMax.py"
        ATEMCommandHandlers["ATEMCommandHandlers.py"]:::api
        click ATEMCommandHandlers "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMCommandHandlers.py"
        ATEMSetterMethods["ATEMSetterMethods.py"]:::api
        click ATEMSetterMethods "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMSetterMethods.py"
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        ATEMUtils["ATEMUtils.py"]:::util
        click ATEMUtils "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMUtils.py"
        ATEMValueDict["ATEMValueDict.py"]:::util
        click ATEMValueDict "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMValueDict.py"
        ATEMConstant["ATEMConstant.py"]:::util
        click ATEMConstant "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMConstant.py"
        ATEMException["ATEMException.py"]:::util
        click ATEMException "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMException.py"
    end

    %% State Model Layer
    subgraph "State Model"
        direction TB
        ATEMSwitcherState["ATEMSwitcherState.py"]:::state
        click ATEMSwitcherState "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMSwitcherState.py"
        StateData["StateData Modules"]:::state
        click StateData "https://github.com/clvlabs/pyatemmax/tree/master/PyATEMMax/StateData/"
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        ATEMBuffer["ATEMBuffer.py"]:::protocol
        click ATEMBuffer "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMBuffer.py"
        ATEMProtocol["ATEMProtocol.py"]:::protocol
        click ATEMProtocol "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMProtocol.py"
        ATEMProtocolEnums["ATEMProtocolEnums.py"]:::protocol
        click ATEMProtocolEnums "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMProtocolEnums.py"
    end

    %% Network Layer
    subgraph "Network Layer"
        direction TB
        ATEMConnectionManager["ATEMConnectionManager.py"]:::network
        click ATEMConnectionManager "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMConnectionManager.py"
        ATEMSocket["ATEMSocket.py"]:::network
        click ATEMSocket "https://github.com/clvlabs/pyatemmax/blob/master/PyATEMMax/ATEMSocket.py"
    end

    %% External Hardware
    Hardware["Blackmagic ATEM\nSwitcher (Hardware)"]:::external

    %% Documentation Generator
    Docs["Documentation Generator\n(docs/)"]:::docs
    click Docs "https://github.com/clvlabs/pyatemmax/tree/master/docs/"

    %% Connections
    Client -->|"imports API"| ATEMMax
    ATEMMax -->|"uses handlers"| ATEMCommandHandlers
    ATEMCommandHandlers -->|"invokes setters"| ATEMSetterMethods
    ATEMSetterMethods -->|"serializes & sends"| ATEMConnectionManager

    ATEMConnectionManager -->|"over TCP/UDP"| Hardware
    Hardware -->|"sends frames"| ATEMConnectionManager

    ATEMConnectionManager -->|"raw data"| ATEMBuffer
    ATEMBuffer -->|"frames"| ATEMProtocol
    ATEMProtocol -->|"parses events"| ATEMProtocolEnums

    ATEMProtocol -->|"updates"| ATEMSwitcherState
    ATEMSwitcherState -->|"state change"| Client

    %% Utility dependencies
    ATEMUtils --- ATEMConnectionManager
    ATEMUtils --- ATEMBuffer
    ATEMUtils --- ATEMCommandHandlers
    ATEMValueDict --- ATEMProtocol
    ATEMConstant --- ATEMProtocol
    ATEMException --- ATEMConnectionManager

    %% Documentation separate
    Docs -.-> ATEMUtils

    %% Styles
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef network fill:#a0c4ff,stroke:#0366d6,stroke-width:1px;
    classDef protocol fill:#ffb997,stroke:#d1495b,stroke-width:1px;
    classDef api fill:#b2f7ef,stroke:#008080,stroke-width:1px;
    classDef state fill:#cdb4db,stroke:#6a0dad,stroke-width:1px;
    classDef util fill:#ffcad4,stroke:#e63946,stroke-width:1px;
    classDef docs stroke-dasharray: 5 5,fill:none,stroke:#888;
```
