# umirtech/bsparser-cpp architecture

> Architecture diagram of the GitHub repository umirtech/bsparser-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/umirtech/bsparser-cpp
- Repository: https://github.com/umirtech/bsparser-cpp

## Overview

bsparser-cpp parses compressed-video bitstreams into syntax structures and reports; it does not decode pixels. The main workflow accepts bytes, optionally demuxes a supported container, frames codec units, parses syntax with retained parameter-set state, and delivers typed results or reports. The README documents broad container and codec support; sampled code confirms dispatch/state behavior and several managers, but not every codec parser’s internal wiring, so those links are shown only at the subsystem level.

Main entry points: [`bsparser.hpp`](https://github.com/umirtech/bsparser-cpp/blob/main/bsparser.hpp) (C++ API and state), [`parser`](https://github.com/umirtech/bsparser-cpp/tree/main/parser) (Codec parsers), [`demux/demuxer.hpp`](https://github.com/umirtech/bsparser-cpp/blob/main/demux/demuxer.hpp) (Container demux), [`cli/bs_cli.cpp`](https://github.com/umirtech/bsparser-cpp/blob/main/cli/bs_cli.cpp) (CLI driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and demux"]
  node_demux["Container demux<br/>[demuxer.hpp]"]
  node_demuxers["Format demuxers<br/>[demux_all.hpp]"]
end

subgraph group_core["Parsing core"]
  node_api["C++ API and state<br/>[bsparser.hpp]"]
  node_framing["Unit framing<br/>[nal_framer.hpp]"]
  node_readers["Bit readers"]
  node_psm["Parameter-set state"]
  node_poc["Picture-order state"]
end

subgraph group_codec["Codec syntax"]
  node_parsers["Codec parsers"]
  node_syntax["Parsed syntax models"]
end

subgraph group_interfaces["Public interfaces"]
  node_cli["CLI driver<br/>[bs_cli.cpp]"]
  node_cpp_handlers["C++ handlers<br/>[bsparser.hpp]"]
  node_c_api["C ABI<br/>[bs_capi.cpp]"]
  node_c_convert["C struct conversion"]
  node_report["Report exporter<br/>[report.hpp]"]
  node_report_result["JSON or HTML report<br/>[report.hpp]"]
end

node_caller(("Application"))
node_bytes["Input bytes"]

node_caller -->|"provides"| node_bytes
node_bytes -.->|"demuxes"| node_demux
node_demux -->|"selects format"| node_demuxers
node_demux -.->|"returns stream"| node_api
node_caller -->|"calls parse"| node_api
node_cli -->|"demuxes input"| node_demux
node_cli -->|"invokes parsing"| node_api
node_api -->|"frames units"| node_framing
node_api -->|"dispatches units"| node_parsers
node_parsers -->|"reads bits"| node_readers
node_parsers -->|"builds models"| node_syntax
node_api -->|"stores parameter sets"| node_psm
node_parsers -->|"resolves dependencies"| node_psm
node_parsers -->|"derives picture order"| node_poc
node_api -->|"dispatches results"| node_cpp_handlers
node_caller -->|"calls C API"| node_c_api
node_c_api -->|"invokes parsing"| node_api
node_c_api -->|"converts results"| node_c_convert
node_cli -->|"builds report"| node_report
node_api -->|"parses for report"| node_report
node_report -->|"exports"| node_report_result

click node_demux "https://github.com/umirtech/bsparser-cpp/blob/main/demux/demuxer.hpp"
click node_demuxers "https://github.com/umirtech/bsparser-cpp/blob/main/demux/demux_all.hpp"
click node_cli "https://github.com/umirtech/bsparser-cpp/blob/main/cli/bs_cli.cpp"
click node_api "https://github.com/umirtech/bsparser-cpp/blob/main/bsparser.hpp"
click node_framing "https://github.com/umirtech/bsparser-cpp/blob/main/parser/nal_framer.hpp"
click node_readers "https://github.com/umirtech/bsparser-cpp/blob/main/bitstream/rbsp_bitstream_reader.hpp"
click node_parsers "https://github.com/umirtech/bsparser-cpp/tree/main/parser"
click node_syntax "https://github.com/umirtech/bsparser-cpp/tree/main/syntax"
click node_psm "https://github.com/umirtech/bsparser-cpp/blob/main/parser/hevc_parameter_set_manager.hpp"
click node_poc "https://github.com/umirtech/bsparser-cpp/blob/main/parser/hevc_reference_picture_manager.hpp"
click node_cpp_handlers "https://github.com/umirtech/bsparser-cpp/blob/main/bsparser.hpp"
click node_c_api "https://github.com/umirtech/bsparser-cpp/blob/main/capi/bs_capi.cpp"
click node_c_convert "https://github.com/umirtech/bsparser-cpp/blob/main/capi/bs_structs_conv.hpp"
click node_report "https://github.com/umirtech/bsparser-cpp/blob/main/cli/report.hpp"
click node_report_result "https://github.com/umirtech/bsparser-cpp/blob/main/cli/report.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_demux,node_demuxers toneBlue
class node_api,node_framing,node_readers,node_psm,node_poc toneAmber
class node_parsers,node_syntax toneMint
class node_cli,node_cpp_handlers,node_c_api,node_c_convert,node_report,node_report_result toneRose
class node_caller,node_bytes toneIndigo
```

## Components

### Input and demux

- [Container demux](https://github.com/umirtech/bsparser-cpp/blob/main/demux/demuxer.hpp): `demux/demuxer.hpp`
- [Format demuxers](https://github.com/umirtech/bsparser-cpp/blob/main/demux/demux_all.hpp): `demux/demux_all.hpp`

### Parsing core

- [C++ API and state](https://github.com/umirtech/bsparser-cpp/blob/main/bsparser.hpp): `bsparser.hpp`
- [Unit framing](https://github.com/umirtech/bsparser-cpp/blob/main/parser/nal_framer.hpp): `parser/nal_framer.hpp`
- [Bit readers](https://github.com/umirtech/bsparser-cpp/blob/main/bitstream/rbsp_bitstream_reader.hpp): `bitstream/rbsp_bitstream_reader.hpp`
- [Parameter-set state](https://github.com/umirtech/bsparser-cpp/blob/main/parser/hevc_parameter_set_manager.hpp): `parser/hevc_parameter_set_manager.hpp`
- [Picture-order state](https://github.com/umirtech/bsparser-cpp/blob/main/parser/hevc_reference_picture_manager.hpp): `parser/hevc_reference_picture_manager.hpp`

### Codec syntax

- [Codec parsers](https://github.com/umirtech/bsparser-cpp/tree/main/parser): `parser`
- [Parsed syntax models](https://github.com/umirtech/bsparser-cpp/tree/main/syntax): `syntax`

### Public interfaces

- [CLI driver](https://github.com/umirtech/bsparser-cpp/blob/main/cli/bs_cli.cpp): `cli/bs_cli.cpp`
- [C++ handlers](https://github.com/umirtech/bsparser-cpp/blob/main/bsparser.hpp): `bsparser.hpp`
- [C ABI](https://github.com/umirtech/bsparser-cpp/blob/main/capi/bs_capi.cpp): `capi/bs_capi.cpp`
- [C struct conversion](https://github.com/umirtech/bsparser-cpp/blob/main/capi/bs_structs_conv.hpp): `capi/bs_structs_conv.hpp`
- [Report exporter](https://github.com/umirtech/bsparser-cpp/blob/main/cli/report.hpp): `cli/report.hpp`
- [JSON or HTML report](https://github.com/umirtech/bsparser-cpp/blob/main/cli/report.hpp): `cli/report.hpp`

### Other components

- **Application**
- **Input bytes**

## Connections

- Application → Input bytes: provides
- Input bytes → Container demux: demuxes
- Container demux → Format demuxers: selects format
- Container demux → C++ API and state: returns stream
- Application → C++ API and state: calls parse
- CLI driver → Container demux: demuxes input
- CLI driver → C++ API and state: invokes parsing
- C++ API and state → Unit framing: frames units
- C++ API and state → Codec parsers: dispatches units
- Codec parsers → Bit readers: reads bits
- Codec parsers → Parsed syntax models: builds models
- C++ API and state → Parameter-set state: stores parameter sets
- Codec parsers → Parameter-set state: resolves dependencies
- Codec parsers → Picture-order state: derives picture order
- C++ API and state → C++ handlers: dispatches results
- Application → C ABI: calls C API
- C ABI → C++ API and state: invokes parsing
- C ABI → C struct conversion: converts results
- CLI driver → Report exporter: builds report
- C++ API and state → Report exporter: parses for report
- Report exporter → JSON or HTML report: exports