How mbebenita/broadway works
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.