# essential61/mp4analyser architecture

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

- Interactive diagram: https://gitdiagram.com/essential61/mp4analyser
- Repository: https://github.com/essential61/mp4analyser

## Overview

##### Project type + purpose (what you’re diagramming)
This repository is a **local desktop GUI application** written in **Python** using **TkInter**. Its purpose is to **open and parse media container files** and then **display their internal structure**:
- Matroska/WebM files (MKV)

So the “system” is not a distributed service architecture; it’s a **single-process application** with a **UI layer**, a **parsing/analysis core**, and **format-specific modules** plus **lookup tables** for decoding identifiers.

- **Runtime components inside the process**
- **Data flow**: file → parser → parsed structure → summarization → UI rendering

##### What the file tree tells you (how the code is organized)
Top-level structure:
- `src/mp4analyser.py` → likely the **entry point / launcher script**
- `src/mp4analyser/` → **MP4 parsing package**
- `core.py` → core parsing orchestration (file IO, traversal, parse loop)
- `summary.py` → building a human-readable summary or condensed view
- `util.py` → shared utilities (binary reading helpers, formatting, etc.)
- `src/mkvanalyser/` → **MKV/WebM parsing package**
- `mkv.py` → MKV parsing logic
- `idlookups.py` → EBML/MKV element ID lookups/mappings
- `images/` → screenshot (documentation only)
- `pyproject.toml` → packaging/build metadata; indicates this is a Python package distribution

This strongly suggests a modular design:
- One “app” entry point
- Two sibling analyser modules (MP4 and MKV)
- Each analyser uses lookups + utilities + (for MP4) ISO/non-ISO splitting + summary output

From README:
- TkInter UI
- Now parses Matroska/WebM too
- Runs on any platform with Python + TkInter

- **UI layer** (TkInter) as the primary interface

##### User / Desktop Environment
- “User” interacting with the TkInter app

##### TkInter GUI Application
- UI widgets for opening a file, tree display of structure, details pane, etc.
- This likely lives in/near the entry script (`src/mp4analyser.py`) plus package modules

##### File Type Detection / Dispatch
- A logical component (even if implemented inline) that decides:
- if MP4 → use `mp4analyser` package
- if MKV/WebM → use `mkvanalyser` package

##### MP4 Parsing Subsystem (`mp4analyser/`)
- `core.py` (parsing controller / traversal)
- `non_iso.py` (vendor/nonstandard parsing)
- `util.py` (binary IO helpers)
- `summary.py` (summary model generation)

##### MKV Parsing Subsystem (`mkvanalyser/`)
Similarly split:
- `mkv.py` (EBML/MKV parser)
- `idlookups.py` (element ID definitions; extensibility point)

##### Local File System
- The MP4/MKV file is read from disk; no network services are implied by the tree/README.

Optionally (but recommended), add:

**Runtime flow (happy path):**
##### User → TkInter GUI
- “Open file” action

##### TkInter GUI → File Type Detection
- passes selected filepath

##### File Type Detection → MP4 Parser OR MKV Parser
- “dispatch by header/signature/extension”

##### Parser → File System
- “read bytes / seek / stream”

##### iso/non_iso → mpeglookups
- callouts show that adding definitions happens here

##### MKV mkv.py → idlookups
- “resolve EBML element IDs to names/types”

##### Parser → summary
- `summary.py` produces condensed representation (tree + metadata)

##### summary → TkInter GUI
- GUI renders tree/structure + details

- Lookups → Parser: “unknown ID fallback”

##### Architectural patterns / principles present

- **Modular parsing by format**: `mp4analyser` vs `mkvanalyser` are separate subsystems.
- **Table-driven decoding**: `mpeglookups.py` and `idlookups.py` imply a “definitions/lookup” approach; this is the key extensibility mechanism.
- **Separation of concerns**:
- UI (TkInter) does presentation + user actions
- Parser core does traversal and reading
- Format modules do spec-specific decoding
- Summary module does “view model” creation

##### Relevant technologies
- **Python 3.7+**
- **TkInter** for GUI
- MP4: ISO/IEC 14496-12
- MKV/WebM: EBML/Matroska (implied by `mkvanalyser` naming)

##### Container: “TkInter App” containing “MP4 Parser” and “MKV Parser”
3. **Component**: break MP4 Parser into `core/iso/non_iso/lookups/summary/util`; break MKV Parser into `mkv/idlookups`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Context (Local Machine)
  %% =========================
  subgraph "Local Machine (Desktop)"
    U["User"]:::external

    subgraph "Runtime: Single Python Process (Python 3.7+)"
      EP["Entry Point: mp4analyser.py\n(TkInter GUI launcher + app wiring)"]:::app

      GUI["TkInter GUI\n(File Open Dialog + Tree View + Details Pane)"]:::ui
      DISPATCH["File Type Detection / Dispatch\n(MP4 vs MKV/WebM)"]:::dispatch

      %% -------------------------
      %% MP4 subsystem
      %% -------------------------
      subgraph "MP4 Parsing Subsystem (mp4analyser/)"
        MP4_CORE["core.py\n(Parse orchestrator + traversal)"]:::parser
        MP4_ISO["iso.py\n(ISO/IEC 14496-12 box parsing)"]:::parser
        MP4_NONISO["non_iso.py\n(Non-ISO/vendor box parsing)"]:::parser
        MP4_UTIL["util.py\n(Binary I/O helpers, formatting)"]:::util
        MP4_LOOKUPS["mpeglookups.py\n(Box definitions + ID/name/field tables)\n(Extensible)"]:::lookup
        MP4_SUMMARY["summary.py\n(Summary / condensed view builder)"]:::summary

        MP4_TREE[("Parsed MP4 Box Tree\n(in-memory model)")]:::model
        MP4_VIEWMODEL[("MP4 Summary Model\n(tree + metadata)")]:::model
      end

      %% -------------------------
      %% MKV subsystem
      %% -------------------------
      subgraph "MKV/WebM Parsing Subsystem (mkvanalyser/)"
        MKV_PARSER["mkv.py\n(EBML/Matroska parser)"]:::parser
        MKV_LOOKUPS["idlookups.py\n(Element ID definitions)\n(Extensible)"]:::lookup

        MKV_TREE[("Parsed MKV Element Tree\n(in-memory model)")]:::model
      end

      ERR["Errors / Unknown IDs\n(unsupported box/element fallback)"]:::error
    end

    FS[("Local File System\nMP4 / MKV files")]:::storage

    subgraph "Build/Install Boundary"
      PKG["pyproject.toml\n(Packaging / distribution metadata)"]:::build
    end
  end

  %% =========================
  %% Runtime data flow
  %% =========================
  U -->|"opens_file"| GUI
  EP -->|"creates_ui"| GUI
  GUI -->|"selected_filepath"| DISPATCH

  DISPATCH -->|"dispatch_mp4"| MP4_CORE
  DISPATCH -->|"dispatch_mkv"| MKV_PARSER

  MP4_CORE -->|"reads_bytes/seek"| FS
  MKV_PARSER -->|"reads_bytes/seek"| FS

  MP4_CORE -->|"uses_helpers"| MP4_UTIL
  MP4_CORE -->|"parses_box_payloads"| MP4_ISO
  MP4_CORE -->|"parses_box_payloads"| MP4_NONISO

  MP4_ISO -->|"resolve_defs"| MP4_LOOKUPS
  MP4_NONISO -->|"resolve_defs"| MP4_LOOKUPS
  MP4_LOOKUPS -->|"unknown_id_fallback"| ERR

  MP4_CORE -->|"builds"| MP4_TREE
  MP4_TREE -->|"summarize"| MP4_SUMMARY
  MP4_SUMMARY -->|"produces"| MP4_VIEWMODEL
  MP4_VIEWMODEL -->|"render_tree+details"| GUI

  MKV_PARSER -->|"resolve_element_ids"| MKV_LOOKUPS
  MKV_LOOKUPS -->|"unknown_id_fallback"| ERR
  MKV_PARSER -->|"builds"| MKV_TREE
  MKV_TREE -->|"render_tree+details"| GUI

  MP4_CORE -->|"parse_errors"| ERR
  MKV_PARSER -->|"parse_errors"| ERR
  ERR -->|"display_error/status"| GUI

  %% =========================
  %% Click events (mapped paths)
  %% =========================
  click EP "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser.py"
  click MP4_CORE "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser/core.py"
  click MP4_ISO "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser/iso.py"
  click MP4_NONISO "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser/non_iso.py"
  click MP4_LOOKUPS "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser/mpeglookups.py"
  click MP4_SUMMARY "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser/summary.py"
  click MP4_UTIL "https://github.com/essential61/mp4analyser/blob/master/src/mp4analyser/util.py"
  click MKV_PARSER "https://github.com/essential61/mp4analyser/blob/master/src/mkvanalyser/mkv.py"
  click MKV_LOOKUPS "https://github.com/essential61/mp4analyser/blob/master/src/mkvanalyser/idlookups.py"
  click PKG "https://github.com/essential61/mp4analyser/blob/master/pyproject.toml"
  click MP4_CORE "https://github.com/essential61/mp4analyser/tree/master/src/mp4analyser/"
  click MKV_PARSER "https://github.com/essential61/mp4analyser/tree/master/src/mkvanalyser/"

  %% =========================
  %% Styles (color coding)
  %% =========================
  classDef external fill:#ECEFF1,stroke:#455A64,stroke-width:1.5px,color:#263238
  classDef app fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
  classDef ui fill:#BBDEFB,stroke:#0D47A1,stroke-width:1.5px,color:#0B2D5B
  classDef dispatch fill:#D1C4E9,stroke:#4527A0,stroke-width:1.5px,color:#1A237E
  classDef parser fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
  classDef util fill:#F1F8E9,stroke:#558B2F,stroke-width:1.5px,color:#33691E
  classDef lookup fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
  classDef summary fill:#E0F7FA,stroke:#00838F,stroke-width:1.5px,color:#006064
  classDef model fill:#FFFFFF,stroke:#546E7A,stroke-width:1.2px,color:#263238
  classDef storage fill:#FCE4EC,stroke:#AD1457,stroke-width:1.5px,color:#880E4F
  classDef error fill:#FFEBEE,stroke:#C62828,stroke-width:1.5px,color:#B71C1C
  classDef build fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
```
