# mbebenita/broadway architecture

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

- Interactive diagram: https://gitdiagram.com/mbebenita/broadway
- Repository: https://github.com/mbebenita/broadway

## Overview

Based on our analysis of the file tree and README, this project is essentially a JavaScript H.264 video decoder (Broadway.js) that leverages native code compiled with Emscripten and optimized with WebGL. Its primary purpose is to decode H.264 streams (typically in .mp4 format) and display them on a web page via a canvas element, with part of the work possibly offloaded to Web Worker threads for performance.

##### Main components and layers
- Decoder Core: This includes the native H.264 decoding logic originally in C/C++ (found in the “Decoder/src” directory and associated files) which is compiled with Emscripten. Note the presence of both JavaScript and WebAssembly outputs (e.g., avc.wasm) along with build scripts (make.py) that convert the native code.
- JavaScript Wrappers & API Modules: These are represented by files like Decoder.js, Player.js, and YUVCanvas.js (or YUVWebGLCanvas.js). They expose the decoder functionality to higher-level JavaScript code. They define the API for actions like p.decode(h264Data) and the callback for frame decoding.
- Web Worker Integration: The design includes both main thread processing (as seen in one demo player) and background worker threads (for offloading decoding). Emphasize how the Player module optionally creates a worker (using the workerFile option) and communicates with it.
- Video Input & Output: On the input side, the system loads .mp4 files (e.g., mozilla_story.mp4, tree.mp4) which serve as the data source. After decoding, the decoded YUV (or optionally RGB) image frames are rendered on an HTML canvas element, using the Player’s canvas element and WebGL optimization.
- Supporting Tools & Templates: Other directories such as “templates” and “omxdl” contain reference files and pre-/post-processing scripts, which can be shown as auxiliary components or optional integration points.

##### Relationships and data flows
- Video File → Video Stream Loader: The video file is loaded (downloaded completely per the demo note) and its H.264 video stream is passed to the decoder.
- Decoder API / Worker Thread: The Player module instantiates a Decoder (or creates a Worker running Decoder.js). Data flows from the player into the Decoder’s decode method. Once a frame is decoded, a callback (p.onPictureDecoded) sends the frame data back to the player.
- Render Output: The Player module then uses a canvas element (with YUVCanvas or WebGL optimizations) to render the decoded video frames.
- Optionally, show how control flows between the main thread and worker thread if the “useWorker” parameter is true.

##### Architectural patterns and design principles
- Modularity: The system clearly separates decoding logic, API exposure, and rendering. The file tree shows distinct folders for Decoder and Player, as well as a clear separation between source files and compiled output.
- Concurrency/Worker Pattern: There is an option for offloading heavy decoding tasks to a background thread using Web Workers, which is crucial for UI responsiveness.
- Optimized Compilation: The use of Emscripten, WebAssembly (avc.wasm), and hand optimizations (with Closure Compiler and WebGL acceleration) is a core detail worth capturing.
- API Abstraction: Loose coupling between the video decoding engine and its JavaScript API methods (for instance, both Decoder.js and Player.js provide a unified module definition, supporting AMD/CommonJS patterns).

##### Relevant technologies, frameworks, and libraries
- Emscripten and WebAssembly for compiling native C/C++ decoding routines.
- JavaScript and Web Workers for asynchronous processing.
- WebGL for accelerated canvas rendering.
- HTML5 Canvas for video output.
- Google Closure Compiler for code optimization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Video Input"
        VF("Video File (.mp4)"):::input
        VL("Video Loader"):::processing
    end

    subgraph "Decoder & API Layers"
        subgraph "Decoder Core"
            ND("Native H.264 Decoder (Emscripten/WASM)"):::native
            WM("WASM Module"):::wasm
        end
        subgraph "JavaScript API Wrappers"
            JD("Decoder API (Decoder.js, avc.js)"):::js
            PM("Player Module (Player.js, YUVCanvas.js)"):::js
        end
    end

    subgraph "Worker Thread (optional)"
        W("Web Worker for Decoding"):::worker
    end

    subgraph "Rendering & Demos"
        CR("Canvas Renderer (HTML5 Canvas & WebGL)"):::browser
    end

    subgraph "Supporting Tools"
        BS("Build & Compilation (make.py)"):::tool
        TP("Templates & Pre/Post (DecoderPre.js,DecoderPost.js)"):::template
    end

    VF -->|"load_stream"| VL
    VL -->|"H.264_stream"| ND
    ND -->|"decoded_frame"| JD
    JD -->|"frame_callback"| PM
    PM -->|"render_output"| CR
    PM -->|"instantiate_worker"| W
    W -->|"offload_decoding"| ND
    ND -->|"uses"| WM
    BS -->|"compile"| ND
    TP -->|"support"| BS

    %% Click Events for Component Mapping
    click ND "https://github.com/mbebenita/broadway/tree/master/Decoder/src"
    click JD "https://github.com/mbebenita/broadway/blob/master/Player/Decoder.js"
    click JD "https://github.com/mbebenita/broadway/blob/master/Decoder/js/avc.js"
    click PM "https://github.com/mbebenita/broadway/blob/master/Player/Player.js"
    click PM "https://github.com/mbebenita/broadway/blob/master/Player/YUVCanvas.js"
    click WM "https://github.com/mbebenita/broadway/blob/master/Decoder/js/avc.wasm"
    click WM "https://github.com/mbebenita/broadway/blob/master/Player/avc.wasm"
    click VF "https://github.com/mbebenita/broadway/blob/master/Player/mozilla_story.mp4"
    click VF "https://github.com/mbebenita/broadway/blob/master/Player/tree.mp4"
    click CR "https://github.com/mbebenita/broadway/blob/master/Player/mp4.html"
    click CR "https://github.com/mbebenita/broadway/blob/master/Player/storyDemo.html"
    click CR "https://github.com/mbebenita/broadway/blob/master/Player/treeDemo.html"
    click CR "https://github.com/mbebenita/broadway/blob/master/Player/screen.css"
    click BS "https://github.com/mbebenita/broadway/blob/master/Decoder/make.py"
    click TP "https://github.com/mbebenita/broadway/blob/master/templates/DecoderPre.js"
    click TP "https://github.com/mbebenita/broadway/blob/master/templates/DecoderPost.js"

    %% Styles
    classDef input fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef processing fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef native fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef js fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
    classDef worker fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef browser fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef tool fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef template fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef wasm fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
