# vidstack/player architecture

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

- Interactive diagram: https://gitdiagram.com/vidstack/player
- Repository: https://github.com/vidstack/player

## Overview

##### Project type and purpose
- This is an open-source, monorepo JavaScript/TypeScript library for building production-ready video and audio players. It consists of:
- “vidstack” – the core web-components–based player engine and API
- “@vidstack/react” – a React wrapper on top of the core engine
- Its purpose is to let developers embed, customize, and extend rich media players (layouts, controls, providers for HLS, DASH, YouTube, etc.) in any JS framework.

##### File structure
- Top-level
- Configuration & metadata (.gitignore, tsconfig.json, pnpm-workspace.yaml, turbo.json)
- Scripts folder (.scripts) for release, sandbox, test automation
- CI workflows (.github/workflows) for build/test/publish
- Examples folder providing starter sandboxes
- packages/
- vidstack/
– src/core: low-level media API, state management, tracks, providers
– src/components: layouts, UI primitives, announcer, gesture handlers
– src/elements: Web Component definitions (customElements.define)
– styles: default and plyr-themed CSS bundles
– build & rollup configs → ESM, CJS, types
- react/
– src/components: React wrappers (hooks, layout components, primitives)
– src/providers: React context providers mapping to core’s implementations
– rollup & vite configs for React distribution

##### README for additional insights
- Emphasizes “build and ship a production-ready video or audio player,” with quickstarts for JS, React, Angular, etc.

##### Final advice
- Be very detailed: break down the Core package into its sub-domains (api/state/providers/components/elements/styles).
- Build and publish pipelines as part of the architecture.
- Don’t try to lump everything; separate into as many logical components as needed to show extension and dependency surfaces.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Tooling & Configuration
    subgraph "Monorepo Tooling & Configuration"
        direction TB
        PNPM["pnpm-workspace.yaml"]:::tech
        TURBO["turbo.json"]:::tech
        TSC["tsconfig.json"]:::tech
        SCRIPTS[".scripts/"]:::tool
        CIWF[".github/workflows/"]:::tool
    end

    %% Core Library
    subgraph "Core Library (packages/vidstack)" 
        direction TB
        CORE_API["Core API & state management"]:::code
        MEDIA_STATE["Media controllers & events"]:::code
        PROVIDERS["Provider interfaces & implementations"]:::code
        UI_COMP["UI components & layouts"]:::code
        WC_DEF["Web Component definitions"]:::code
        WC_BUNDLES["Bundled element entrypoints"]:::code
        STYLES["Styling bundles"]:::code
        CORE_BUILD["Build & Rollup/Vite configs"]:::tool
        CORE_PKG["package.json"]:::tech
        CORE_TSC["tsconfig.json / tsconfig.build.json"]:::tech
    end

    %% React Wrapper
    subgraph "React Wrapper (packages/react)"
        direction TB
        REACT_COMP["React component wrappers"]:::code
        REACT_LAYOUTS["React-specific layouts"]:::code
        REACT_PROVIDERS["React provider contexts"]:::code
        REACT_HOOKS["Hooks & utilities"]:::code
        REACT_BUILD["Rollup & Vite configs"]:::tool
        REACT_PKG["package.json"]:::tech
        REACT_TSC["tsconfig.json / tsconfig.build.json"]:::tech
    end

    %% Examples & Sandboxes
    subgraph "Examples & Sandboxes"
        direction TB
        EX_ROOT["examples/"]:::code
        CORE_SANDBOX["Core sandbox templates"]:::code
        REACT_SANDBOX["React sandbox templates"]:::code
    end

    %% Release & Publishing
    subgraph "Release & Publishing"
        direction TB
        NPM_VIDSTACK["packages/vidstack/npm/"]:::code
        NPM_REACT["packages/react/npm/"]:::code
        REL_SCRIPT[".scripts/release.js"]:::tool
        RUN_ON_CHANGE[".scripts/run-on-change.js"]:::tool
        TEST_ESM[".scripts/test-node-esm.js"]:::tool
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NPM_REG["npm registry"]:::external
        GITHUB["GitHub (source & CI)"]:::external
        DOCS["Documentation website"]:::external
    end

    %% Dependencies & Flows
    REACT_COMP -->|"depends on"| CORE_API
    REACT_LAYOUTS --> CORE_API
    REACT_PROVIDERS --> PROVIDERS
    REACT_HOOKS --> CORE_API

    CORE_BUILD -->|"bundles"| WC_BUNDLES
    CORE_BUILD -->|"uses config"| CORE_TSC
    REACT_BUILD -->|"bundles"| REACT_COMP
    REACT_BUILD -->|"uses config"| REACT_TSC

    CIWF -->|"triggers"| CORE_BUILD
    CIWF -->|"triggers"| REACT_BUILD
    CIWF -->|"runs"| RUN_ON_CHANGE
    CIWF -->|"runs"| TEST_ESM
    REL_SCRIPT -->|"publishes to"| NPM_REG

    SCRIPTS --> CIWF
    PNPM --> CORE_BUILD
    TURBO --> CORE_BUILD
    TSC --> CORE_BUILD

    EX_ROOT --> CORE_SANDBOX
    EX_ROOT --> REACT_SANDBOX
    CORE_SANDBOX --> CORE_API
    REACT_SANDBOX --> REACT_COMP

    NPM_VIDSTACK -->|"published"| NPM_REG
    NPM_REACT -->|"published"| NPM_REG
    GITHUB --> CIWF
    GITHUB --> DOCS

    %% Click Events
    click PNPM "https://github.com/vidstack/player/blob/main/pnpm-workspace.yaml"
    click TURBO "https://github.com/vidstack/player/blob/main/turbo.json"
    click TSC "https://github.com/vidstack/player/blob/main/tsconfig.json"
    click SCRIPTS "https://github.com/vidstack/player/tree/main/.scripts/"
    click CIWF "https://github.com/vidstack/player/tree/main/.github/workflows/"
    click CORE_API "https://github.com/vidstack/player/tree/main/packages/vidstack/src/core/"
    click MEDIA_STATE "https://github.com/vidstack/player/tree/main/packages/vidstack/src/core/api/"
    click PROVIDERS "https://github.com/vidstack/player/tree/main/packages/vidstack/src/providers/"
    click UI_COMP "https://github.com/vidstack/player/tree/main/packages/vidstack/src/components/layouts/"
    click WC_DEF "https://github.com/vidstack/player/tree/main/packages/vidstack/src/elements/define/"
    click WC_BUNDLES "https://github.com/vidstack/player/tree/main/packages/vidstack/src/elements/bundles/"
    click STYLES "https://github.com/vidstack/player/tree/main/packages/vidstack/styles/player/"
    click CORE_BUILD "https://github.com/vidstack/player/tree/main/packages/vidstack/build/"
    click CORE_BUILD "https://github.com/vidstack/player/blob/main/packages/vidstack/rollup.config.ts"
    click CORE_BUILD "https://github.com/vidstack/player/blob/main/packages/vidstack/vite.config.ts"
    click CORE_PKG "https://github.com/vidstack/player/blob/main/packages/vidstack/package.json"
    click CORE_TSC "https://github.com/vidstack/player/blob/main/packages/vidstack/tsconfig.json"
    click CORE_TSC "https://github.com/vidstack/player/blob/main/packages/vidstack/tsconfig.build.json"
    click REACT_COMP "https://github.com/vidstack/player/tree/main/packages/react/src/components/"
    click REACT_LAYOUTS "https://github.com/vidstack/player/tree/main/packages/react/src/components/layouts/"
    click REACT_PROVIDERS "https://github.com/vidstack/player/tree/main/packages/react/src/providers/"
    click REACT_HOOKS "https://github.com/vidstack/player/tree/main/packages/react/src/hooks/"
    click REACT_BUILD "https://github.com/vidstack/player/blob/main/packages/react/rollup.config.ts"
    click REACT_BUILD "https://github.com/vidstack/player/blob/main/packages/react/vite.config.ts"
    click REACT_BUILD "https://github.com/vidstack/player/blob/main/packages/react/analyze.config.ts"
    click REACT_PKG "https://github.com/vidstack/player/blob/main/packages/react/package.json"
    click REACT_TSC "https://github.com/vidstack/player/blob/main/packages/react/tsconfig.json"
    click REACT_TSC "https://github.com/vidstack/player/blob/main/packages/react/tsconfig.build.json"
    click EX_ROOT "https://github.com/vidstack/player/tree/main/examples/"
    click CORE_SANDBOX "https://github.com/vidstack/player/tree/main/packages/vidstack/.templates/sandbox/"
    click REACT_SANDBOX "https://github.com/vidstack/player/tree/main/packages/react/.templates/sandbox/"
    click NPM_VIDSTACK "https://github.com/vidstack/player/tree/main/packages/vidstack/npm/"
    click NPM_REACT "https://github.com/vidstack/player/tree/main/packages/react/npm/"
    click REL_SCRIPT "https://github.com/vidstack/player/blob/main/.scripts/release.js"
    click RUN_ON_CHANGE "https://github.com/vidstack/player/blob/main/.scripts/run-on-change.js"
    click TEST_ESM "https://github.com/vidstack/player/blob/main/.scripts/test-node-esm.js"

    %% Styles
    classDef code fill:#bbdefb,stroke:#1976d2,color:#0d47a1
    classDef tool fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef tech fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef external fill:#ffccbc,stroke:#d84315,color:#bf360c
```
