How devine-dl/pywidevine works
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.