# videojs/http-streaming architecture

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

- Interactive diagram: https://gitdiagram.com/videojs/http-streaming
- Repository: https://github.com/videojs/http-streaming

## Overview

##### Project Type and Purpose
- The project is a JavaScript library (VHS) that polyfills HTTP streaming protocols (HLS, DASH, and future formats) so that they work seamlessly with video.js on browsers that either lack or provide unreliable native support for such protocols.
- Its purpose is to parse manifests, load and process media segments, perform decryption/transmuxing (often via Web Workers), manage adaptive bitrate switching, and provide rich integration with the video.js player.

##### Analyzing the File Structure
- The top-level directories include:
– “src”: Contains core source code organizing all major modules, like manifest handling, playlist controllers, segment loaders, cue tags processing, and XHR integration.
– “test”: Contains unit and integration tests covering each aspect (e.g., loading manifests, segment handling, cue tags, error handling).
– “scripts”: Contains build scripts, configuration files and utility scripts that support development and might illustrate how different modules interact.
- Worker files are visible (e.g., “decrypter-worker.js” and “transmuxer-worker.js”) indicating parallel processing of heavy tasks.

##### Key System Components
a. Video.js Integration Layer:
– This is the front-facing API that video.js uses to invoke VHS functionality; identify the glue layer where video.js instantiates the VHS playback (e.g., via “videojs-http-streaming.js” and integration in the README examples).
b. Manifest and Playlist Handling Module:
– Modules such as “manifest.js”, “playlist.js”, “playlist-loader.js”, and “playlist-controller.js” which parse, select, and manage manifest files.
c. Media Segments Management:
– Modules like “segment-loader.js”, “media-segment-request.js”, and “playlist-selectors.js”, responsible for fetching and queuing media segments.
d. Transmuxing and Decryption:
– Highlight the worker processes (“decrypter-worker.js”, “transmuxer-worker.js”) that take over heavy processing tasks (decrypting segments and transmuxing transport streams to formats compatible with Media Source Extensions).
e. XHR and Networking:
– “xhr.js” and its associated hooks (explained in the README) that handle all network requests. Represent the customizable request/response hooks allowing global and per-instance alterations.
f. Utility and Helpers Layer:
– “util” folder modules (e.g., “logger.js”, “date-ranges.js”, “string.js”) that provide shared functionalities across various modules.
g. Adaptive Bitrate and Playback Monitoring:
– Components such as “playback-watcher.js”, “sync-controller.js”, “timeline-change-controller.js”, and “reload-source-on-error.js” which monitor playback status, handle buffering issues, and dynamically select renditions based on network conditions and player dimensions.
h. Error Handling and Statistics:
– “error-codes.js” and “vhs.stats” in runtime properties are used to communicate issues and performance statistics in real-time.

##### Relationships and Interactions
- Directional data flows starting from the video.js player, which calls the VHS API.
- The manifest and media segments are fetched via XHR (and modified via hook callbacks).
- Once segments are received, they’re sent to the decryption or transmuxing workers via message passing.
- Processed segments eventually make their way back into the source buffer attached to the video element.
- Additionally, auxiliary modules like “content-steering-controller.js” or “media-groups.js” interact in parallel to support multi-track options (e.g., captions, alternate audio).

##### Architectural Patterns to Highlight
- A modular design where core functionalities are separated into clearly defined modules.
- Use of Web Workers decouples heavy compute tasks (decrypting and transmuxing) from the main UI thread.
- An XHR layer that allows for pre- and post-processing (via hooks) to facilitate extensibility.
- Adaptive streaming logic that uses runtime statistics (bandwidth, throughput) to make quality-level decisions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Components
    VideoPlayer("Video.js Player"):::integration
    VHSCore("VHS Core API"):::core
    BufferUpdate("Source Buffer Update"):::core

    %% Subgraph: Manifest & Playlist Handling
    subgraph "Manifest & Playlist Handling"
        manifest("Manifest.js"):::core
        playlist("Playlist.js"):::core
        playlistLoader("Playlist Loader"):::core
        playlistController("Playlist Controller"):::core
        playlistSelectors("Playlist Selectors"):::core
    end

    %% Subgraph: XHR & Networking
    XHRModule("XHR Module"):::network

    %% Subgraph: Media Segments Management
    subgraph "Media Segments Management"
        segmentLoader("Segment Loader"):::core
        mediaSegmentReq("Media Segment Request"):::core
        vttSegmentLoader("VTT Segment Loader"):::core
    end

    %% Subgraph: Transmuxing & Decryption
    subgraph "Transmuxing & Decryption"
        decrypter("Decrypter Worker"):::worker
        transmuxer("Transmuxer Worker"):::worker
        segmentTransmuxer("Segment Transmuxer"):::worker
    end

    %% Subgraph: Adaptive Bitrate & Playback Monitoring
    subgraph "Adaptive Bitrate & Playback Monitoring"
        playbackWatcher("Playback Watcher"):::adaptive
        syncController("Sync Controller"):::adaptive
        timelineController("Timeline Change Controller"):::adaptive
        reloadOnError("Reload Source on Error"):::adaptive
    end

    %% Utility & Helpers and Error Handling
    Utility("Utility & Helpers"):::utility
    ErrorHandling("Error Handling & Stats"):::error

    %% Data Flow Connections
    VideoPlayer -->|"initiates"| VHSCore
    VHSCore -->|"parseManifest"| manifest
    manifest -->|"fetchManifest"| XHRModule
    XHRModule -->|"fetchSegments"| segmentLoader
    segmentLoader -->|"processSegment"| decrypter
    decrypter -->|"processedSegment"| BufferUpdate
    BufferUpdate -->|"updateBuffer"| VideoPlayer

    %% Adaptive influences
    playbackWatcher -->|"adaptStream"| manifest
    playbackWatcher -->|"monitorPlayback"| segmentLoader

    %% Error Reporting
    XHRModule -->|"reportError"| ErrorHandling
    segmentLoader -->|"reportError"| ErrorHandling
    decrypter -->|"reportError"| ErrorHandling

    %% Core utilities
    VHSCore -->|"utilize"| Utility

    %% Click Events
    click VHSCore "https://github.com/videojs/http-streaming/blob/main/src/videojs-http-streaming.js"
    click manifest "https://github.com/videojs/http-streaming/blob/main/src/manifest.js"
    click playlist "https://github.com/videojs/http-streaming/blob/main/src/playlist.js"
    click playlistLoader "https://github.com/videojs/http-streaming/blob/main/src/playlist-loader.js"
    click playlistController "https://github.com/videojs/http-streaming/blob/main/src/playlist-controller.js"
    click playlistSelectors "https://github.com/videojs/http-streaming/blob/main/src/playlist-selectors.js"
    click segmentLoader "https://github.com/videojs/http-streaming/blob/main/src/segment-loader.js"
    click mediaSegmentReq "https://github.com/videojs/http-streaming/blob/main/src/media-segment-request.js"
    click vttSegmentLoader "https://github.com/videojs/http-streaming/blob/main/src/vtt-segment-loader.js"
    click decrypter "https://github.com/videojs/http-streaming/blob/main/src/decrypter-worker.js"
    click transmuxer "https://github.com/videojs/http-streaming/blob/main/src/transmuxer-worker.js"
    click segmentTransmuxer "https://github.com/videojs/http-streaming/blob/main/src/segment-transmuxer.js"
    click XHRModule "https://github.com/videojs/http-streaming/blob/main/src/xhr.js"
    click playbackWatcher "https://github.com/videojs/http-streaming/blob/main/src/playback-watcher.js"
    click syncController "https://github.com/videojs/http-streaming/blob/main/src/sync-controller.js"
    click timelineController "https://github.com/videojs/http-streaming/blob/main/src/timeline-change-controller.js"
    click reloadOnError "https://github.com/videojs/http-streaming/blob/main/src/reload-source-on-error.js"
    click Utility "https://github.com/videojs/http-streaming/tree/main/src/util/"

    click ErrorHandling "https://github.com/videojs/http-streaming/blob/main/src/error-codes.js"

    %% Styles
    classDef integration fill:#FFDDCC,stroke:#333,stroke-width:2px;
    classDef core fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef network fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef worker fill:#FFE6AA,stroke:#333,stroke-width:2px;
    classDef adaptive fill:#E0CCFF,stroke:#333,stroke-width:2px;
    classDef utility fill:#DFFFD6,stroke:#333,stroke-width:2px;
    classDef error fill:#FBB,stroke:#333,stroke-width:2px;
```
