# thefocusman/videobrowser architecture

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

- Interactive diagram: https://gitdiagram.com/thefocusman/videobrowser
- Repository: https://github.com/thefocusman/videobrowser

## Overview

Video Browser is a lightweight MP4 metadata and sample-location reader that works on a stream rather than loading the whole file. The documented user flow is to provide a video stream, validate and parse MP4 metadata, then inspect tracks and enumerate or decode samples. The diagram follows the sampled parser and its format structures; the test/benchmark harness is excluded. README capability coverage is limited to MP4, the only format it documents. Unsampled internals are represented only where supported by the source index.

Main entry points: [`VideoBrowser/MP4Reader.cs`](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.cs) (MP4 Reader), [`VideoBrowser/MP4Reader.Containers.cs`](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.Containers.cs) (Container Parser), [`VideoBrowser/MP4Reader.TracksExplorer.cs`](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.TracksExplorer.cs) (Track Explorer), [`VideoBrowser/MP4BoxStructure.cs`](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4BoxStructure.cs) (Box Structures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Stream Entry"]
  node_reader["MP4 Reader<br/>[MP4Reader.cs]"]
  node_header["Header Contract<br/>[IFileHeader.cs]"]
end

subgraph group_parse["MP4 Parsing"]
  node_containers["Container Parser"]
  node_logger["Diagnostics<br/>[Logger.cs]"]
end

subgraph group_samples["Track Samples"]
  node_tracks["Track Explorer"]
  node_descriptions["AVC Description"]
end

subgraph group_format["Binary Format"]
  node_boxes["Box Structures<br/>[MP4BoxStructure.cs]"]
  node_fourcc["FourCC Tags<br/>[FourCC.cs]"]
  node_endianness["Endian Values<br/>[Endianness.cs]"]
  node_streamops["Stream Reads"]
end

node_caller(("Stream Client"))

node_caller -->|"creates reader"| node_reader
node_reader -->|"validates header"| node_header
node_reader -->|"parses moov"| node_containers
node_containers -->|"reads box layouts"| node_boxes
node_containers -->|"matches box tags"| node_fourcc
node_reader -->|"reads MP4 boxes"| node_boxes
node_reader -->|"checks format tags"| node_fourcc
node_reader -->|"exposes track queries"| node_tracks
node_tracks -->|"decodes samples"| node_descriptions
node_tracks -.->|"reads sample data"| node_streamops
node_reader -.->|"reads stream values"| node_streamops
node_containers -->|"logs box details"| node_logger
node_reader -->|"logs parse status"| node_logger
node_boxes -.->|"uses endian fields"| node_endianness

click node_reader "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.cs"
click node_header "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/IFileHeader.cs"
click node_containers "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.Containers.cs"
click node_boxes "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4BoxStructure.cs"
click node_fourcc "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/FourCC.cs"
click node_endianness "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/Endianness.cs"
click node_streamops "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/StreamExtentions.cs"
click node_tracks "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.TracksExplorer.cs"
click node_descriptions "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.DescriptionEntry.cs"
click node_logger "https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/Logger.cs"

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_reader,node_header,node_caller toneBlue
class node_containers,node_logger toneAmber
class node_tracks,node_descriptions toneMint
class node_boxes,node_fourcc,node_endianness,node_streamops toneRose
```

## Components

### Stream Entry

- [MP4 Reader](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.cs): `VideoBrowser/MP4Reader.cs`
- [Header Contract](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/IFileHeader.cs): `VideoBrowser/IFileHeader.cs`

### MP4 Parsing

- [Container Parser](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.Containers.cs): `VideoBrowser/MP4Reader.Containers.cs`
- [Diagnostics](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/Logger.cs): `VideoBrowser/Logger.cs`

### Track Samples

- [Track Explorer](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.TracksExplorer.cs): `VideoBrowser/MP4Reader.TracksExplorer.cs`
- [AVC Description](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4Reader.DescriptionEntry.cs): `VideoBrowser/MP4Reader.DescriptionEntry.cs`

### Binary Format

- [Box Structures](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/MP4BoxStructure.cs): `VideoBrowser/MP4BoxStructure.cs`
- [FourCC Tags](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/FourCC.cs): `VideoBrowser/FourCC.cs`
- [Endian Values](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/Endianness.cs): `VideoBrowser/Endianness.cs`
- [Stream Reads](https://github.com/thefocusman/videobrowser/blob/master/VideoBrowser/StreamExtentions.cs): `VideoBrowser/StreamExtentions.cs`

### Other components

- **Stream Client**

## Connections

- Stream Client → MP4 Reader: creates reader (evidence: `VideoBrowser/MP4Reader.cs`)
- MP4 Reader → Header Contract: validates header (evidence: `VideoBrowser/MP4Reader.cs`)
- MP4 Reader → Container Parser: parses moov (evidence: `VideoBrowser/MP4Reader.cs`)
- Container Parser → Box Structures: reads box layouts (evidence: `VideoBrowser/MP4Reader.Containers.cs`)
- Container Parser → FourCC Tags: matches box tags (evidence: `VideoBrowser/MP4Reader.Containers.cs`)
- MP4 Reader → Box Structures: reads MP4 boxes (evidence: `VideoBrowser/MP4Reader.cs`)
- MP4 Reader → FourCC Tags: checks format tags (evidence: `VideoBrowser/MP4Reader.cs`)
- MP4 Reader → Track Explorer: exposes track queries (evidence: `VideoBrowser/MP4Reader.TracksExplorer.cs`)
- Track Explorer → AVC Description: decodes samples (evidence: `VideoBrowser/MP4Reader.TracksExplorer.cs`)
- Track Explorer → Stream Reads: reads sample data
- MP4 Reader → Stream Reads: reads stream values
- Container Parser → Diagnostics: logs box details (evidence: `VideoBrowser/MP4Reader.Containers.cs`)
- MP4 Reader → Diagnostics: logs parse status (evidence: `VideoBrowser/MP4Reader.cs`)
- Box Structures → Endian Values: uses endian fields