# incredibleidea/griffith architecture

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

- Interactive diagram: https://gitdiagram.com/incredibleidea/griffith
- Repository: https://github.com/incredibleidea/griffith

## Overview

1. This is a TypeScript monorepo for a React-based web video player, organized with Yarn workspaces and Lerna. The root contains shared build/test config, while each package owns its own bundle and test setup.

2. The main consumer-facing library is `packages/griffith`. It provides the React player shell: video display, controller UI, timeline, volume, playback-rate/quality controls, and icon sets. Its architecture is component-heavy, with hooks and contexts used to share state across the player tree.

3. Inside `griffith`, the key state boundaries are explicit contexts for locale, message passing, object-fit behavior, video source selection, and player position. These contexts feed the UI components and keep display state separate from media-source logic.

4. Source handling is a central flow in `griffith`: the app passes a `sources` object, the player normalizes/chooses the active source, and then routes playback through the appropriate media strategy. The package also includes helpers for playlist parsing, buffering calculations, storage, and browser/UA handling.

5. `packages/griffith-utils` is the shared browser capability layer. It contains support checks such as MSE and native HLS detection, plus UA parsing, logging, and sequencing utilities. This package is a dependency boundary used to decide which playback path the player can take on a given browser.

6. `packages/griffith-mp4` is the custom MP4 streaming engine. Its data flow is: fetch MP4 data, probe/parse the MP4 container, extract sample and fragment information, generate fMP4 boxes/fragments, and append them through MSE. The package is split into MP4 parsing/probing, box builders, byte/stream utilities, and an MSE adapter.

7. `packages/griffith-hls` is the HLS playback plugin. It wraps `hls.js` and also contains helpers for generating a master M3U8 blob, which suggests it can adapt HLS manifests for browser playback. This is the HLS-specific streaming boundary parallel to the MP4/MSE path.

8. `packages/griffith-message` provides cross-window messaging primitives. It defines message/action/event constants and a helper for constructing the transport layer, which is used when playback or control needs to cross an iframe or embedded-window boundary.

9. `packages/griffith-standalone` is the non-React delivery format. It packages the player as a UMD build so an app can create and render a player instance directly in the browser without a React integration layer.

10. The repository includes a `null` package under `packages/griffith/null` for bundle aliasing. The README documents using it to exclude `griffith-hls` and `griffith-mp4` at build time, making the media plugins an optional deployment boundary for smaller bundles.

11. The `example` app demonstrates integration scenarios rather than being part of the core runtime. It has separate pages for MP4, HLS, inline, iframe, and fMP4 demos, which mirrors the project’s main architectural modes.

12. The `website` package is a Gatsby documentation site. It consumes the library structure and exposes usage, build options, technical details, and standalone docs; it is separate from the runtime packages and helps explain the intended integration boundaries.

13. Testing is broad and package-local, with Jest snapshots and unit tests around MP4 box generation/parsing, HLS helpers, message helpers, utility functions, and UI components. This reflects a design where most critical behavior is isolated into small, testable modules.

14. In architectural terms, Griffith is a layered player system: React UI at the top, shared player state and browser capability checks in the middle, and protocol-specific media engines underneath for MP4/MSE and HLS, with messaging and standalone packaging as supporting integration boundaries.

Main entry points: [`packages/griffith/src/index.ts`](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/index.ts) (Player API), [`packages/griffith-mp4/src/index.ts`](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/index.ts) (MP4 engine), [`package.json`](https://github.com/incredibleidea/griffith/blob/master/package.json) (Build config), [`packages/griffith-hls/src/index.ts`](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-hls/src/index.ts) (HLS plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Workspace"]
  node_root_build["Build config<br/>workspace config<br/>[package.json]"]
end

subgraph group_player["Player core"]
  node_griffith_entry["Player API<br/>react package<br/>[index.ts]"]
  node_griffith_contexts["Player state<br/>context layer<br/>[LocaleProvider.tsx]"]
  node_griffith_components["UI shell<br/>component tree<br/>[Player.tsx]"]
  node_griffith_hooks["Hooks<br/>[useBoolean.ts]"]
  node_griffith_utils["Player utils<br/>player helpers<br/>[storage.ts]"]
  node_griffith_source["Source select<br/>source flow<br/>[selectVideo.ts]"]
  node_griffith_message["Message bridge<br/>cross-window<br/>[MessageContext.tsx]"]
end

subgraph group_media["Media engines"]
  node_griffith_utils_pkg["Browser utils<br/>capability layer<br/>[index.ts]"]
  node_griffith_mp4["MP4 engine<br/>fMP4/MSE plugin<br/>[index.ts]"]
  node_mp4_parse["MP4 parse<br/>container parsing<br/>[mp4Parse.ts]"]
  node_mp4_fmp4["fMP4 build<br/>fragment builder<br/>[fmp4Generator.ts]"]
  node_mp4_mse["MSE adapter<br/>append pipeline<br/>[MSE.ts]"]
  node_griffith_hls["HLS plugin<br/>[index.ts]"]
  node_hls_manifest["M3U8 helper<br/>manifest helper"]
end

subgraph group_integration["Delivery"]
  node_griffith_standalone["Standalone build<br/>UMD package<br/>[index.tsx]"]
  node_griffith_null["Null alias<br/>bundle alias<br/>[null.cjs.js]"]
end

subgraph group_docs["Examples and docs"]
  node_example_app["Example app<br/>demo app<br/>[App.tsx]"]
  node_website_site["Docs site<br/>gatsby docs<br/>[gatsby-config.js]"]
end

node_root_build -->|"workspace"| node_griffith_entry
node_root_build -->|"workspace"| node_griffith_utils_pkg
node_root_build -->|"workspace"| node_griffith_mp4
node_root_build -->|"workspace"| node_griffith_hls
node_root_build -->|"workspace"| node_griffith_message
node_root_build -->|"workspace"| node_griffith_standalone
node_griffith_entry -->|"state"| node_griffith_contexts
node_griffith_entry -->|"ui"| node_griffith_components
node_griffith_entry -->|"hooks"| node_griffith_hooks
node_griffith_entry -->|"helpers"| node_griffith_utils
node_griffith_entry -->|"source"| node_griffith_source
node_griffith_entry -->|"bridge"| node_griffith_message
node_griffith_source -->|"capability check"| node_griffith_utils_pkg
node_griffith_source -->|"mp4 path"| node_griffith_mp4
node_griffith_source -->|"hls path"| node_griffith_hls
node_griffith_mp4 -->|"parse"| node_mp4_parse
node_griffith_mp4 -->|"fragment"| node_mp4_fmp4
node_griffith_mp4 -->|"append"| node_mp4_mse
node_griffith_hls -->|"manifest"| node_hls_manifest
node_griffith_standalone -->|"wraps"| node_griffith_entry
node_griffith_null -.->|"alias"| node_griffith_mp4
node_griffith_null -.->|"alias"| node_griffith_hls
node_example_app -->|"uses"| node_griffith_entry
node_example_app -->|"demo"| node_griffith_mp4
node_example_app -->|"demo"| node_griffith_hls
node_website_site -->|"docs"| node_griffith_entry
node_website_site -->|"docs"| node_griffith_standalone

click node_root_build "https://github.com/incredibleidea/griffith/blob/master/package.json"
click node_griffith_entry "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/index.ts"
click node_griffith_contexts "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/contexts/LocaleProvider.tsx"
click node_griffith_components "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/components/Player.tsx"
click node_griffith_hooks "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/hooks/useBoolean.ts"
click node_griffith_utils "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/utils/storage.ts"
click node_griffith_source "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/components/selectVideo.ts"
click node_griffith_message "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/contexts/MessageContext.tsx"
click node_griffith_utils_pkg "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-utils/src/index.ts"
click node_griffith_mp4 "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/index.ts"
click node_mp4_parse "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/mp4/mp4Parse.ts"
click node_mp4_fmp4 "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/fmp4/fmp4Generator.ts"
click node_mp4_mse "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/mse/MSE.ts"
click node_griffith_hls "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-hls/src/index.ts"
click node_hls_manifest "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-hls/src/utils/createMasterM3U8.ts"
click node_griffith_standalone "https://github.com/incredibleidea/griffith/blob/master/packages/griffith-standalone/src/index.tsx"
click node_griffith_null "https://github.com/incredibleidea/griffith/blob/master/packages/griffith/null/null.cjs.js"
click node_example_app "https://github.com/incredibleidea/griffith/blob/master/example/src/App.tsx"
click node_website_site "https://github.com/incredibleidea/griffith/blob/master/website/gatsby-config.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_build toneBlue
class node_griffith_entry,node_griffith_contexts,node_griffith_components,node_griffith_hooks,node_griffith_utils,node_griffith_source,node_griffith_message toneAmber
class node_griffith_utils_pkg,node_griffith_mp4,node_mp4_parse,node_mp4_fmp4,node_mp4_mse,node_griffith_hls,node_hls_manifest toneMint
class node_griffith_standalone,node_griffith_null toneRose
class node_example_app,node_website_site toneIndigo
```

## Components

### Workspace

Monorepo-level build, release, and shared tooling

- [Build config](https://github.com/incredibleidea/griffith/blob/master/package.json): workspace config · Shared TypeScript, Rollup, Jest, and Lerna setup for the monorepo · `package.json`

### Player core

Main React player package and its internal architecture

- [Player API](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/index.ts): react package · Main consumer-facing React player library entrypoint · `packages/griffith/src/index.ts`
- [Player state](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/contexts/LocaleProvider.tsx): context layer · Locale, message, object-fit, position, and video-source state boundaries · `packages/griffith/src/contexts/LocaleProvider.tsx`
- [UI shell](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/components/Player.tsx): component tree · Player shell, controller, timeline, volume, icons, and video display components · `packages/griffith/src/components/Player.tsx`
- [Hooks](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/hooks/useBoolean.ts): react hooks · Shared hook utilities used across the player UI · `packages/griffith/src/hooks/useBoolean.ts`
- [Player utils](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/utils/storage.ts): player helpers · Formatting, buffering, storage, UA, playlist, and playback helpers · `packages/griffith/src/utils/storage.ts`
- [Source select](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/components/selectVideo.ts): source flow · Normalizes source input and chooses the active playback target · `packages/griffith/src/components/selectVideo.ts`
- [Message bridge](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/src/contexts/MessageContext.tsx): cross-window · Cross-window messaging context for iframe or embedded-window control · `packages/griffith/src/contexts/MessageContext.tsx`

### Media engines

Protocol-specific playback engines and browser capability boundaries

- [Browser utils](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-utils/src/index.ts): capability layer · MSE, native HLS, UA, logging, and sequencing support checks · `packages/griffith-utils/src/index.ts`
- [MP4 engine](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/index.ts): fMP4/MSE plugin · Custom MP4 streaming path for fetching, parsing, fragmenting, and appending media · `packages/griffith-mp4/src/index.ts`
- [MP4 parse](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/mp4/mp4Parse.ts): container parsing · Probe, parse, and inspect MP4 structure and track/sample metadata · `packages/griffith-mp4/src/mp4/mp4Parse.ts`
- [fMP4 build](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/fmp4/fmp4Generator.ts): fragment builder · Generates boxes, fragments, and byte buffers for MSE append · `packages/griffith-mp4/src/fmp4/fmp4Generator.ts`
- [MSE adapter](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-mp4/src/mse/MSE.ts): append pipeline · Wraps Media Source Extensions append and polyfill behavior · `packages/griffith-mp4/src/mse/MSE.ts`
- [HLS plugin](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-hls/src/index.ts): HLS plugin · HLS playback boundary built around hls.js and manifest adaptation · `packages/griffith-hls/src/index.ts`
- [M3U8 helper](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-hls/src/utils/createMasterM3U8.ts): manifest helper · Builds master M3U8 blobs for HLS playback adaptation · `packages/griffith-hls/src/utils/createMasterM3U8.ts`

### Delivery

Standalone packaging and bundle aliasing

- [Standalone build](https://github.com/incredibleidea/griffith/blob/master/packages/griffith-standalone/src/index.tsx): UMD package · Non-React browser delivery format for direct player instantiation · `packages/griffith-standalone/src/index.tsx`
- [Null alias](https://github.com/incredibleidea/griffith/blob/master/packages/griffith/null/null.cjs.js): bundle alias · Stub package used to exclude optional media engines at build time · `packages/griffith/null/null.cjs.js`

### Examples and docs

Demo app and documentation site

- [Example app](https://github.com/incredibleidea/griffith/blob/master/example/src/App.tsx): demo app · Integration demos for MP4, HLS, inline, iframe, and fMP4 usage · `example/src/App.tsx`
- [Docs site](https://github.com/incredibleidea/griffith/blob/master/website/gatsby-config.js): gatsby docs · Documentation site covering usage, build options, technical details, and standalone integration · `website/gatsby-config.js`

## Connections

- Build config → Player API: workspace · Root workspace config governs the main player package
- Build config → Browser utils: workspace · Shared package builds are coordinated from the monorepo root
- Build config → MP4 engine: workspace · MP4 engine is built and tested as a workspace package
- Build config → HLS plugin: workspace · HLS plugin is built and tested as a workspace package
- Build config → Message bridge: workspace · Messaging package is part of the workspace release
- Build config → Standalone build: workspace · Standalone delivery package is built from the same monorepo
- Player API → Player state: state · Player entry composes explicit state contexts
- Player API → UI shell: ui · Player entry renders the main UI tree
- Player API → Hooks: hooks · Player entry and UI components share hook utilities
- Player API → Player utils: helpers · Player logic uses shared formatting, storage, and playback helpers
- Player API → Source select: source · Player entry normalizes and selects media sources
- Player API → Message bridge: bridge · Player shell integrates cross-window messaging
- Source select → Browser utils: capability check · Source selection depends on browser support and UA detection
- Source select → MP4 engine: mp4 path · Selected sources can route into the MP4 streaming engine
- Source select → HLS plugin: hls path · Selected sources can route into the HLS playback plugin
- MP4 engine → MP4 parse: parse · MP4 engine probes and parses container metadata
- MP4 engine → fMP4 build: fragment · Parsed MP4 data is transformed into fMP4 fragments
- MP4 engine → MSE adapter: append · Fragments are appended through the MSE boundary
- HLS plugin → M3U8 helper: manifest · HLS plugin can build or adapt master manifests
- Standalone build → Player API: wraps · Standalone build wraps the player runtime for direct browser use
- Null alias → MP4 engine: alias · Null bundle can replace the MP4 engine at build time
- Null alias → HLS plugin: alias · Null bundle can replace the HLS plugin at build time
- Example app → Player API: uses · Demo pages exercise the main player package
- Example app → MP4 engine: demo · Example app includes MP4-specific integration flows
- Example app → HLS plugin: demo · Example app includes HLS-specific integration flows
- Docs site → Player API: docs · Docs site explains the core player API and usage
- Docs site → Standalone build: docs · Docs site covers standalone browser delivery
