# stremio/stremio-video architecture

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

- Interactive diagram: https://gitdiagram.com/stremio/stremio-video
- Repository: https://github.com/stremio/stremio-video

## Overview

##### Project type and purpose
- This is a JavaScript/Node.js library (package.json at project root, uses .npmignore) named “stremio-video.”
- Purpose: Provide an abstraction layer over multiple video player implementations (Chromecast, HTML5, IFrame, Shell, Stremio, Titan, Tizen, Vidaa, WebOS, YouTube) and higher-order wrappers (subtitles, streaming server, video params).

##### File structure
- Top-level: configuration files (.eslintrc, .gitignore, workflows), package.json, README.md, src/
- src/ contains:
– Core entrypoints: src/index.js, src/error.js, src/mediaCapabilities.js, src/platform.js, src/supportsTranscoding.js, src/tracksData.js
– Player implementations (one directory per platform): ChromecastSenderVideo/, HTMLVideo/, IFrameVideo/, ShellVideo/, StremioVideo/, TitanVideo/, TizenVideo/, VidaaVideo/, WebOsVideo/, YouTubeVideo/
– Higher-order wrappers (prefix “with…”): withHTMLSubtitles/, withStreamingServer/, withVideoParams/

- Pattern: A central abstraction (“core”) that dynamically selects or wraps specific video backends and applies cross-cutting concerns (subtitles, streaming, params).

##### README for additional insights
- The README is minimal: “Abstraction layer on top of different media players.”

a. Main components
1. Core Abstraction Layer
– src/index.js: exports public API
– Utility modules: mediaCapabilities, platform detection, error handling, transcoding support, track data
2. Video Player Modules
– One module per target platform (Chromecast, HTML5, IFrame, etc.)
3. Higher-Order Wrappers
– withHTMLSubtitles: subtitle parsing, conversion, rendering
– withStreamingServer: torrent conversion, server setup, param fetching
– withVideoParams: query and inject video parameters
4. External Platforms & Services
– Browsers (HTML5 video, IFrame), Smart TV environments (Tizen, WebOS, Vidaa), Chromecast, YouTube API, Stremio host
5. (Optional) Underlying libraries
– e.g., WebTorrent for streaming server, HLS.js for HTMLVideo, fetch/XHR

b. Relationships and interactions
– Consumer (app or Stremio addon) → imports stremio-video API
– Core Abstraction → selects appropriate Player Module based on platform / mediaCapabilities
– Player Module ↔ External Platform/Device
– Wrappers wrap core API to add functionality:
- withHTMLSubtitles → sits between Consumer and Core, intercepts subtitle data flow
- withStreamingServer → intercepts media source URLs, starts local server or torrent stream
- withVideoParams → appends auth tokens, metadata to stream URLs
– Utility Modules → used by Core and Wrappers for environment detection and error handling

c. Architectural patterns & design principles
– Strategy pattern: each Player Module implements a common interface but different behavior per platform
– Decorator / Higher-order functions: wrappers extend or modify the base player functionality
– Single Responsibility: modules are small and focused (detection, error, transcoding, parsing)
– Plug-in style: new player modules or wrappers can be added without core changes

d. Key technologies
– JavaScript / Node.js
– Browser APIs (HTML5 Video, IFrame)
– Smart TV SDKs (Tizen, WebOS)
– WebTorrent or custom streaming code (withStreamingServer)
– Subtitle formats (SRT, WebVTT)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer
    Consumer["Consumer App"]:::consumer

    %% Wrappers
    subgraph "Higher-Order Wrappers"
        direction TB
        WVP["withVideoParams"]:::wrapper
        WSS["withStreamingServer"]:::wrapper
        WHS["withHTMLSubtitles"]:::wrapper
    end

    %% Core & Utilities
    subgraph "Core Abstraction & Utilities"
        direction TB
        CoreAPI["Core API (src/index.js)"]:::core
        ErrorMod["Error Handling\n(src/error.js)"]:::core
        MediaCap["Media Capabilities\n(src/mediaCapabilities.js)"]:::core
        PlatformDet["Platform Detection\n(src/platform.js)"]:::core
        TranscodeSup["Transcoding Support\n(src/supportsTranscoding.js)"]:::core
        TracksData["Tracks Data\n(src/tracksData.js)"]:::core
    end

    %% Player Modules
    subgraph "Player Modules (Strategy Implementations)"
        direction TB
        Chromecast["ChromecastSenderVideo"]:::player
        HTML5["HTML5 Video"]:::player
        IFrame["IFrame Video"]:::player
        ShellVid["Shell Video"]:::player
        StremioVid["Stremio Video"]:::player
        StremioSel["selectVideoImplementation"]:::player
        Titan["Titan Video"]:::player
        Tizen["Tizen Video"]:::player
        Vidaa["Vidaa Video"]:::player
        WebOS["WebOS Video"]:::player
        YouTube["YouTube Video"]:::player
    end

    %% External Platforms
    subgraph "External Platforms & Services"
        direction TB
        Browser["Browser APIs"]:::external
        SmartTV["Smart TV SDKs"]:::external
        ChromecastSvc["Chromecast Device"]:::external
        YouTubeAPI["YouTube API"]:::external
        StremioHost["Stremio Host"]:::external
    end

    %% Connections
    Consumer -->|"calls"| WVP
    WVP -->|"decorate"| WSS
    WSS -->|"decorate"| WHS
    WHS -->|"invoke"| CoreAPI

    CoreAPI -->|"selectImplementation"| Chromecast
    CoreAPI -->|"selectImplementation"| HTML5
    CoreAPI -->|"selectImplementation"| IFrame
    CoreAPI -->|"selectImplementation"| ShellVid
    CoreAPI -->|"selectImplementation"| StremioVid
    CoreAPI -->|"selectImplementation"| Titan
    CoreAPI -->|"selectImplementation"| Tizen
    CoreAPI -->|"selectImplementation"| Vidaa
    CoreAPI -->|"selectImplementation"| WebOS
    CoreAPI -->|"selectImplementation"| YouTube

    CoreAPI -.->|uses| ErrorMod
    CoreAPI -.->|uses| MediaCap
    CoreAPI -.->|uses| PlatformDet
    CoreAPI -.->|uses| TranscodeSup
    CoreAPI -.->|uses| TracksData

    Chromecast <-->|"stream"| ChromecastSvc
    HTML5 <-->|"play"| Browser
    IFrame <-->|"embed"| Browser
    ShellVid <-->|"shell exec"| Browser
    StremioVid <-->|"connect"| StremioHost
    StremioSel -->|"helper"| StremioVid
    Titan <-->|"play"| SmartTV
    Tizen <-->|"play"| SmartTV
    Vidaa <-->|"play"| SmartTV
    WebOS <-->|"play"| SmartTV
    YouTube <-->|"API calls"| YouTubeAPI

    %% Click Events - Core & Utilities
    click CoreAPI "https://github.com/stremio/stremio-video/blob/master/src/index.js"
    click ErrorMod "https://github.com/stremio/stremio-video/blob/master/src/error.js"
    click MediaCap "https://github.com/stremio/stremio-video/blob/master/src/mediaCapabilities.js"
    click PlatformDet "https://github.com/stremio/stremio-video/blob/master/src/platform.js"
    click TranscodeSup "https://github.com/stremio/stremio-video/blob/master/src/supportsTranscoding.js"
    click TracksData "https://github.com/stremio/stremio-video/blob/master/src/tracksData.js"

    %% Click Events - Wrappers
    click WVP "https://github.com/stremio/stremio-video/blob/master/src/withVideoParams/index.js"
    click WSS "https://github.com/stremio/stremio-video/blob/master/src/withStreamingServer/index.js"
    click WHS "https://github.com/stremio/stremio-video/blob/master/src/withHTMLSubtitles/index.js"

    %% Click Events - Player Modules
    click Chromecast "https://github.com/stremio/stremio-video/blob/master/src/ChromecastSenderVideo/index.js"
    click HTML5 "https://github.com/stremio/stremio-video/blob/master/src/HTMLVideo/index.js"
    click IFrame "https://github.com/stremio/stremio-video/blob/master/src/IFrameVideo/index.js"
    click ShellVid "https://github.com/stremio/stremio-video/blob/master/src/ShellVideo/index.js"
    click StremioVid "https://github.com/stremio/stremio-video/blob/master/src/StremioVideo/index.js"
    click StremioSel "https://github.com/stremio/stremio-video/blob/master/src/StremioVideo/selectVideoImplementation.js"
    click Titan "https://github.com/stremio/stremio-video/blob/master/src/TitanVideo/index.js"
    click Tizen "https://github.com/stremio/stremio-video/blob/master/src/TizenVideo/index.js"
    click Vidaa "https://github.com/stremio/stremio-video/blob/master/src/VidaaVideo/index.js"
    click WebOS "https://github.com/stremio/stremio-video/blob/master/src/WebOsVideo/index.js"
    click YouTube "https://github.com/stremio/stremio-video/blob/master/src/YouTubeVideo/index.js"

    %% Styles
    classDef consumer fill:#f9f,stroke:#333,stroke-width:1px
    classDef wrapper fill:#f96,stroke:#933,stroke-width:1px
    classDef core fill:#6cf,stroke:#036,stroke-width:1px
    classDef player fill:#9f6,stroke:#393,stroke-width:1px
    classDef external fill:#ddd,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
