How incredibleidea/griffith works
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: src/index.ts Player API · src/index.ts MP4 engine · package.json Build config · src/index.ts HLS plugin
Components 19
Workspace
Monorepo-level build, release, and shared tooling
- Build 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 · Main consumer-facing React player library entrypoint
packages/griffith/src/index.ts - Player state · Locale, message, object-fit, position, and video-source state boundaries
packages/griffith/src/contexts/LocaleProvider.tsx - UI shell · Player shell, controller, timeline, volume, icons, and video display components
packages/griffith/src/components/Player.tsx - Hooks · Shared hook utilities used across the player UI
packages/griffith/src/hooks/useBoolean.ts - Player utils · Formatting, buffering, storage, UA, playlist, and playback helpers
packages/griffith/src/utils/storage.ts - Source select · Normalizes source input and chooses the active playback target
packages/griffith/src/components/selectVideo.ts - Message bridge · 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 · MSE, native HLS, UA, logging, and sequencing support checks
packages/griffith-utils/src/index.ts - MP4 engine · Custom MP4 streaming path for fetching, parsing, fragmenting, and appending media
packages/griffith-mp4/src/index.ts - MP4 parse · Probe, parse, and inspect MP4 structure and track/sample metadata
packages/griffith-mp4/src/mp4/mp4Parse.ts - fMP4 build · Generates boxes, fragments, and byte buffers for MSE append
packages/griffith-mp4/src/fmp4/fmp4Generator.ts - MSE adapter · Wraps Media Source Extensions append and polyfill behavior
packages/griffith-mp4/src/mse/MSE.ts - HLS plugin · HLS playback boundary built around hls.js and manifest adaptation
packages/griffith-hls/src/index.ts - M3U8 helper · Builds master M3U8 blobs for HLS playback adaptation
packages/griffith-hls/src/utils/createMasterM3U8.ts
Delivery
Standalone packaging and bundle aliasing
- Standalone build · Non-React browser delivery format for direct player instantiation
packages/griffith-standalone/src/index.tsx - Null 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 · Integration demos for MP4, HLS, inline, iframe, and fMP4 usage
example/src/App.tsx - Docs site · Documentation site covering usage, build options, technical details, and standalone integration
website/gatsby-config.js
Connections 27
- 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