swadhin / vidolib public
/ vidolib / docs / ARCHITECTURE.md
swadhinbiswas docs: add open-source community contributor guide, architectural specification, roadmap, manifesto, and web examples · 7/23/2026
076cd4d
41 lines · 2.5 KB
Raw Download

media-runtime Architecture Specification

Overview & Core Principles

media-runtime is a zero-copy, worker-isolated, hardware-first TypeScript media engine for modern web browsers.

       +----------------------------------------------------------------+
       |                         Host Application                       |
       +----------------------------------------------------------------+
                                       |
    +----------------------------------------------------------------------+
    |                         @media-runtime/ui                            |
    +----------------------------------------------------------------------+
                                       |
    +----------------------------------------------------------------------+
    |                        @media-runtime/core                           |
    |  [Player] <---> [Clock] <---> [Pipeline] <---> [Plugin Registry]    |
    +----------------------------------------------------------------------+
          |                   |                  |                   |
    +-----------+     +---------------+    +------------+    +---------------+
    |  stream/  |     |  containers/  |    |  codecs/   |    |   renderer/   |
    |  buffer/  |     |  (10 demuxers)|    | (Hardware) |    | (WebGL/WebGPU)|
    +-----------+     +---------------+    +------------+    +---------------+
          |                   |                  |                   |
    +-----------+     +---------------+    +------------+    +---------------+
    | manifest/ |     |    worker/    |    |    audio/  |    |   subtitle/   |
    |   abr/    |     |  (Transfer)   |    | (Worklet)  |    | (ASS/SRT/VTT) |
    +-----------+     +---------------+    +------------+    +---------------+

Key Architectural Pillars:

  1. Hardware Decode Priority Chain:
    WebCodecs API → Native <video>/MSE → WASM Royalty-Free Only (AV1/VP8/VP9/Opus/FLAC) → FFmpeg WASM (Opt-in Plugin)
  2. Strict Codec Licensing Boundary:
    Patented codecs (H.264, H.265/HEVC, AC-3, EAC-3, DTS) are restricted to hardware-decoders or native browser execution to eliminate patent pool liability.
  3. Zero-Copy & Off-Main-Thread Processing:
    Heavy demuxing and decoding tasks execute inside dedicated Web Workers using Transferable ArrayBuffers and VideoFrame references.
  4. Security Hardened Parsers:
    All 10 container parsers treat network inputs as hostile, enforcing upper bounds on byte allocations and undergoing fuzz testing.