# cinecert/asdcplib architecture

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

- Interactive diagram: https://gitdiagram.com/cinecert/asdcplib
- Repository: https://github.com/cinecert/asdcplib

## Overview

##### Project Type and Purpose
- Type: C++ Native Library + Command-Line Tool Suite
- Purpose: Parse, wrap/un-wrap, and manipulate SMPTE D-Cinema (ST 429) MXF files, IMF Essence Components (AS-02/ST 2067-5) and Dolby Vision PHDR tracks.
- Libraries Provided:
– libkumu (platform abstraction)
– libasdcp (ST 429 DCP + JPEG-2000)
– libas02 (ST 2067-5 IMF/AS-02)
– libphdr (Dolby Vision PHDR, optional)

##### File Structure
- Top-Level Build & CI:
– Autotools (configure.ac, Makefile.am, autogen.sh)
– CMake (CMakeLists.txt, README.cmake)
– Win32 Makefiles (win32/)
– CI workflows (.github/workflows/ci.yml, .gitlab-ci.yml)
- Registers:
– XML definitions under registers/ (Dolby, RDD47, etc.)
- Source Tree (src/):
– Core platform module: KM_* (.fileio, .log, .prng, .sha1, .xml, .mutex, .platform)
– Parsers & containers: KLV, MXF, MXFTypes, JP2K, JXS, MPEG, PCM, PHDR, ACES, MDD, Metadata, TimedText, ST2052, ST2095 PinkNoise
– High-level standards modules: AS_DCP_*.cpp/h, AS_02_*.cpp/h
– Utility generators & encoders: AtmosSyncChannel_*, SyncEncoder, WavFileWriter
– CLI tools: asdcp-*.cpp, as-02-*.cpp, kmfilegen.cpp, kmuuidgen.cpp, kmrandgen.cpp, wavesplit.cpp, blackwave.cpp, pinkwave.cpp, j2c-test.cpp, etc.
– Test harnesses & scripts (sh, pl)

##### README for Additional Insights
- Key features & intended users (D-Cinema & IMF toolchains).
- Build variations: Autotools vs. CMake vs. Win32.
- Libraries vs. executables.
- External dependencies (via m4 macros): libexpat, OpenSSL, Xerces.

##### Main Components
a. Build & CI Layer
– Autotools, CMake, Win32
– GitHub Actions / GitLab CI
b. External Dependencies
– Expat, OpenSSL, Xerces (XML parsing, cryptography)
c. Platform Abstraction (libkumu)
– File I/O, logging, threading, mutexes, PRNG, SHA-1, UUID, XML support
d. Core Format Modules
– Container & KLV: MXF, MXFTypes
– Essence Parsers/Streams: JP2K, JXS, MPEG, PCM, ACES codestream, PHDR, TimedText, PinkNoise
e. Standards Libraries
– libasdcp (ST 429 + JPEG-2000 DCP)
– libas02 (ST 2067-5 AS-02 IMF)
– libphdr (Dolby Vision PHDR)
f. Command-Line Tools
– asdcp-wrap, asdcp-unwrap, asdcp-info, asdcp-test, asdcp-util
– as-02-wrap, as-02-unwrap, as-02-info
– kmfilegen, kmuuidgen, kmrandgen, wavesplit, blackwave, pinkwave, j2c-test
g. Registers Loader
– On startup, XML registers are loaded into dictionaries used by container/metadata modules.

##### Relationships & Data Flow
- CLI tools → link against Standards Libs (libasdcp, libas02, libphdr)
- Standards Libs → use Core Format Modules + Registers
- Core Format Modules → depend on libkumu for platform services + external libs
- Build System → compiles all layers, orchestrates dependency resolution
- CI Pipelines → invoke build, run tests

##### Architectural Patterns & Design Principles
- Layered Architecture – clear separation: Platform → Format Parsers → Standards → CLI
- Modular Libraries – libkumu (foundation), libasdcp/libas02/libphdr (domain), CLI (presentation)
- Plugin-style extensions – optional AS-02 and PHDR components compiled separately
- Data-flow orientation – parsing pipelines for essence codestreams & sequences

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Layer
    subgraph "Build & CI Layer"
        AUT["Autotools"]:::buildCI
        CMAKE["CMake"]:::buildCI
        WIN32["Win32 Makefiles"]:::buildCI
        CI["CI Workflows"]:::buildCI
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EXPAT["libexpat"]:::externalDeps
        OPENSSL["OpenSSL"]:::externalDeps
        XERCES["Xerces"]:::externalDeps
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction (libkumu)"
        KM_FILEIO["KM_fileio"]:::platform
        KM_LOG["KM_log"]:::platform
        KM_XML["KM_xml"]:::platform
    end

    %% Core Format Modules
    subgraph "Core Format Modules"
        CORE_KLV["KLV/MXF"]:::core
        JP2K["JP2K Parser"]:::core
        PHDR_SEQ["PHDR Sequence Parser"]:::core
    end

    %% Standards Libraries
    subgraph "Standards Libraries"
        LIBASDCP["libasdcp"]:::standards
        LIBAS02["libas02 (optional)"]:::standards
        LIBPHDR["libphdr (optional)"]:::standards
    end

    %% CLI Tools
    subgraph "CLI Tools"
        CLI_DCP["AS-DCP Tools"]:::cli
        CLI_AS02["AS-02 Tools"]:::cli
        CLI_UTIL["Utilities & Encoders"]:::cli
    end

    %% Registers Loader
    subgraph "Registers Loader"
        REG["Registers Loader"]:::registers
    end

    %% OS
    OS["Operating System / Filesystem"]:::external

    %% Relationships
    CLI_DCP -->|"links"| LIBASDCP
    CLI_AS02 -->|"links"| LIBAS02
    CLI_DCP -->|"links"| LIBPHDR
    LIBASDCP -->|"uses"| CORE_KLV
    LIBAS02 -.->|"optional uses"| CORE_KLV
    LIBPHDR -.->|"uses"| PHDR_SEQ
    CORE_KLV -->|"depends on"| KM_FILEIO
    CORE_KLV -->|"depends on"| KM_LOG
    CORE_KLV -->|"depends on"| KM_XML
    KM_FILEIO -->|"calls"| OS
    KM_LOG -->|"calls"| OS
    KM_XML -->|"parses"| OS
    EXPAT -->|"parses XML"| KM_XML
    OPENSSL -->|"crypto"| KM_XML
    XERCES -->|"XML Parsing"| KM_XML
    REG -->|"loads XML"| CORE_KLV
    REG -->|"loads XML"| LIBASDCP
    AUT -->|"builds"| LIBASDCP
    CMAKE -->|"builds"| LIBASDCP
    WIN32 -->|"builds"| LIBASDCP
    CI -->|"runs build/tests"| LIBASDCP

    %% Click Events
    click AUT "https://github.com/cinecert/asdcplib/blob/master/configure.ac"
    click CMAKE "https://github.com/cinecert/asdcplib/blob/master/CMakeLists.txt"
    click WIN32 "https://github.com/cinecert/asdcplib/blob/master/win32/Makefile.am"
    click CI "https://github.com/cinecert/asdcplib/blob/master/.github/workflows/ci.yml"
    click EXPAT "https://github.com/cinecert/asdcplib/blob/master/m4/ax_lib_expat.m4"
    click OPENSSL "https://github.com/cinecert/asdcplib/blob/master/m4/ax_lib_openssl.m4"
    click XERCES "https://github.com/cinecert/asdcplib/blob/master/m4/ax_lib_xerces.m4"
    click KM_FILEIO "https://github.com/cinecert/asdcplib/blob/master/src/KM_fileio.cpp"
    click KM_LOG "https://github.com/cinecert/asdcplib/blob/master/src/KM_log.cpp"
    click KM_XML "https://github.com/cinecert/asdcplib/blob/master/src/KM_xml.cpp"
    click CORE_KLV "https://github.com/cinecert/asdcplib/blob/master/src/KLV.cpp"
    click JP2K "https://github.com/cinecert/asdcplib/blob/master/src/JP2K.cpp"
    click PHDR_SEQ "https://github.com/cinecert/asdcplib/blob/master/src/PHDR_Sequence_Parser.cpp"
    click LIBASDCP "https://github.com/cinecert/asdcplib/blob/master/src/AS_DCP.cpp"
    click LIBAS02 "https://github.com/cinecert/asdcplib/blob/master/src/AS_02.h"
    click LIBPHDR "https://github.com/cinecert/asdcplib/blob/master/src/AS_02_PHDR.cpp"
    click CLI_DCP "https://github.com/cinecert/asdcplib/blob/master/src/asdcp-wrap.cpp"
    click CLI_AS02 "https://github.com/cinecert/asdcplib/blob/master/src/as-02-wrap.cpp"
    click CLI_UTIL "https://github.com/cinecert/asdcplib/blob/master/src/kmfilegen.cpp"
    click REG "https://github.com/cinecert/asdcplib/tree/master/registers/"

    %% Styles
    classDef buildCI fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef externalDeps fill:#FFC0C0,stroke:#333,stroke-width:1px
    classDef platform fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef standards fill:#90EE90,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef cli fill:#F4A460,stroke:#333,stroke-width:1px
    classDef registers fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
