# devine-dl/pywidevine architecture

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

- Interactive diagram: https://gitdiagram.com/devine-dl/pywidevine
- Repository: https://github.com/devine-dl/pywidevine

## Overview

##### Main Components
- Library Core (pywidevine package): This is the heart of the project and is composed of several modules:
- cdm.py: Manages CDM sessions, opening/closing sessions, generating license challenges, and parsing license responses.
- device.py: Handles the loading and management of devices/provisions.
- pssh.py: Creates and parses PSSH (Protection System Specific Header) data.
- key.py and session.py: Deal with key extraction, representation, and session state.
- serve.py & remotecdm.py: Provide servable CDM API server functionality and remote operations.
- license_protocol.proto and its generated pb2 artifacts: Define and implement the protocol for license messages.
- CLI Interface (pywidevine/main.py): Acts as the entry point for command-line usage and interacts directly with the core library.
- Configuration & Deployment Elements:
- YAML configuration files (e.g., serve.example.yml) offer user-friendly configuration for running the server.
- GitHub actions and pre-commit hooks indicate CI/CD and code quality practices.
- External Dependencies and Interactions:
- External License Server (invoked via HTTP requests as seen in usage examples).
- External clients that might call the servable API endpoints provided by serve.py.

##### Relationships and Data Flow
- Client Code / CLI Usage:
- The client (script or CLI) creates a Device instance (via device.py) by loading the provision file.
- It then creates a CDM instance (via cdm.py) using the device data.
- A session is opened, and the CDM creates a license challenge using a PSSH header (from pssh.py).
- The challenge is then sent externally (via a POST API call) to a License Server, and the received license is then parsed back into the session.
- Finally, keys are extracted (using key.py and session.py) and the session is closed.
- API Server Setup:
- The serve.py module exposes API endpoints that mirror these interactions to allow remote CDM functionality.
- Protocol Handling:
- The use of license_protocol.proto (and corresponding pb2 files) represents the formal contract for messages exchanged with the license server or amongst internal modules.

##### Architectural Patterns
- Modularity: Clear separation into modules for device handling, session and key management, protocol parsing, and serving.
- Layered Architecture: The library acts as an abstraction layer over the complex operations (CDM functionality) while the CLI and API modules simply orchestrate these operations.
- Extensibility: The structure supports adding features like Privacy Mode, Service Certificates, and remote CDMs, which are indicated in the README.
- External Communication: The interaction with the external License Server is captured using network calls (HTTP requests).

##### Important Technologies and Frameworks
- Python (compatible with Python 3.8+).
- Protocol Buffers for message definitions (via .proto files and generated pb2 code).
- YAML configurations for server setups.
- CI/CD integrations (GitHub workflows, pre-commit, etc.) which, while not part of runtime architecture, indicate project quality practices.

##### Final Advice
- That every component is clearly labeled with its purpose (e.g., “CDM Manager”, “Device Provision Loader”, “PSSH Handler”).
- CLI/Client Code → Library Core (Initialization)
- Library Core → External License Server (License challenge/response)
- API Server ↔ Library Core (Remote operations)
- Aim for sufficient detail so that another engineer can trace the license acquisition flow from device provisioning to session management and network communication with the license server.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Nodes
    A["CLI Interface"]:::internal
    C["External License Server"]:::external
    D["YAML Config"]:::config
    E["GitHub Workflows"]:::cicd
    F["Pre-commit Config"]:::cicd

    %% Main Library Core Subgraph
    subgraph "pywidevine Package (Library Core)"
        LC["pywidevine Package"]:::internal
        B1["Device Provision Loader"]:::internal
        B2["CDM Manager"]:::internal
        B3["PSSH Handler"]:::internal
        B4["Key Manager"]:::internal
        B5["Session Manager"]:::internal
        B6["Protocol Handler"]:::internal
        B7["API Server"]:::internal
        B8["Remote CDM Ops"]:::internal
    end

    %% Top Level Flow
    A -->|"load_and_createCDM"| LC

    %% Library Core Internal Relationships
    LC -->|"init_CDM"| B1
    LC -->|"init_CDM"| B2
    LC -->|"init_CDM"| B3
    LC -->|"init_CDM"| B4
    LC -->|"init_CDM"| B5
    LC -->|"init_CDM"| B6
    LC -->|"init_CDM"| B7
    LC -->|"init_CDM"| B8

    B1 -->|"initialize_session"| B2
    B2 -->|"create_licenseChallenge"| B3
    B2 -->|"licenseReqResp"| C
    B2 -->|"format_licenseMessages"| B6
    B2 -->|"extract_keys"| B4
    B2 -->|"manage_session"| B5
    B2 <-->|"remote_ops"| B7
    B2 <-->|"remote_ops"| B8

    %% Configuration Relationship
    D -->|"load_serverConfig"| B7

    %% CI/CD Relationships (non-runtime indicators)
    E -.->|"build_tests"| B2
    F -.->|"code_quality"| B2

    %% Click Events
    click A "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/main.py"
    click LC "https://github.com/devine-dl/pywidevine/tree/master/pywidevine/"
    click B1 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/device.py"
    click B2 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/cdm.py"
    click B3 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/pssh.py"
    click B4 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/key.py"
    click B5 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/session.py"
    click B6 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/license_protocol.proto"
    click B7 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/serve.py"
    click B8 "https://github.com/devine-dl/pywidevine/blob/master/pywidevine/remotecdm.py"
    click D "https://github.com/devine-dl/pywidevine/blob/master/serve.example.yml"
    click E "https://github.com/devine-dl/pywidevine/blob/master/.github"
    click F "https://github.com/devine-dl/pywidevine/blob/master/.pre-commit-config.yaml"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#1f78b4,stroke-width:2px;
    classDef external fill:#F7D6AE,stroke:#d95f02,stroke-width:2px;
    classDef config fill:#CFF7AE,stroke:#33a02c,stroke-width:2px;
    classDef cicd fill:#E0E0E0,stroke:#555,stroke-width:2px;
```
