# igrigorik/videospeed architecture

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

- Interactive diagram: https://gitdiagram.com/igrigorik/videospeed
- Repository: https://github.com/igrigorik/videospeed

## Overview

Video Speed Controller is a browser extension for controlling HTML5 audio and video playback. Its main workflow detects media, applies site-specific handling, attaches an overlay controller, and lets users change playback through keyboard shortcuts or the overlay. Settings, per-site rules, persistent speed, and customized controls are additional product capabilities. The graph reflects documented features and source-index references; some wiring and unsampled subsystem details are not shown, so uncertain connections are omitted.

Main entry points: [`src/entries/inject-entry.js`](https://github.com/igrigorik/videospeed/blob/master/src/entries/inject-entry.js) (Content Entry), [`src/core/video-controller.js`](https://github.com/igrigorik/videospeed/blob/master/src/core/video-controller.js) (Video Controller), [`src/core/storage-manager.js`](https://github.com/igrigorik/videospeed/blob/master/src/core/storage-manager.js) (Storage Manager), [`src/ui/options/options.js`](https://github.com/igrigorik/videospeed/blob/master/src/ui/options/options.js) (Options Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Media Detection"]
  node_entry["Content Entry<br/>[inject-entry.js]"]
  node_media["Media Observer<br/>[media-observer.js]"]
  node_mutations["Mutation Observer"]
  node_sitehandlers["Site Handlers<br/>[index.js]"]
  node_youtube["YouTube Handler<br/>[youtube-handler.js]"]
  node_netflix["Netflix Handler<br/>[netflix-handler.js]"]
end

subgraph group_control["Playback Control"]
  node_action["Action Handler<br/>[action-handler.js]"]
  node_events["Event Manager<br/>[event-manager.js]"]
  node_classifier["Intent Classifier"]
  node_arbiter["Playback Arbiter<br/>[arbiter.js]"]
  node_speedarb["Speed Arbitration"]
  node_controller["Video Controller"]
  node_state["Media State<br/>[state-manager.js]"]
end

subgraph group_experience["User Experience"]
  node_controls["Overlay Controls<br/>[controls.js]"]
  node_shadow["Shadow UI<br/>[shadow-dom.js]"]
  node_drag["Drag Handling<br/>[drag-handler.js]"]
  node_visibility["Visibility Policy"]
end

subgraph group_settings["Settings And Storage"]
  node_options["Options Page<br/>[options.js]"]
  node_popup["Extension Popup<br/>[popup.js]"]
  node_settingscore["Settings<br/>[settings.js]"]
  node_storage["Storage Manager<br/>[storage-manager.js]"]
  node_bridge["Content Bridge<br/>[content-bridge.js]"]
  node_sync[("Chrome Sync Storage")]
end

node_viewer(("Viewer"))

node_entry -->|"initializes"| node_media
node_entry -->|"initializes"| node_mutations
node_entry -->|"uses"| node_sitehandlers
node_entry -->|"initializes"| node_action
node_entry -->|"initializes"| node_events
node_entry -->|"configures"| node_classifier
node_entry -->|"configures"| node_arbiter
node_entry -->|"configures"| node_speedarb
node_entry -->|"uses"| node_controller
node_entry -->|"initializes"| node_state
node_entry -->|"initializes"| node_settingscore
node_entry -->|"initializes"| node_storage
node_sitehandlers -->|"selects"| node_youtube
node_sitehandlers -->|"selects"| node_netflix
node_media -.->|"attaches"| node_controller
node_mutations -.->|"detects additions"| node_media
node_events -->|"dispatches actions"| node_action
node_events -->|"delegates decisions"| node_speedarb
node_action -.->|"adjusts playback"| node_controller
node_controller -->|"creates UI"| node_shadow
node_controller -->|"requests placement"| node_sitehandlers
node_controller -.->|"applies policy"| node_visibility
node_controls -.->|"triggers actions"| node_action
node_drag -->|"moves overlay"| node_shadow
node_viewer -->|"presses shortcuts"| node_events
node_viewer -->|"uses overlay"| node_controls
node_viewer -->|"drags overlay"| node_drag
node_viewer -->|"customizes settings"| node_options
node_options -->|"edits settings"| node_settingscore
node_options -->|"reads and writes"| node_storage
node_options -.->|"shares preferences"| node_popup
node_settingscore -.->|"persists settings"| node_storage
node_storage -->|"reads and writes"| node_sync
node_storage -->|"requests settings"| node_bridge
node_bridge -->|"exchanges settings"| node_storage

click node_entry "https://github.com/igrigorik/videospeed/blob/master/src/entries/inject-entry.js"
click node_media "https://github.com/igrigorik/videospeed/blob/master/src/observers/media-observer.js"
click node_mutations "https://github.com/igrigorik/videospeed/blob/master/src/observers/mutation-observer.js"
click node_sitehandlers "https://github.com/igrigorik/videospeed/blob/master/src/site-handlers/index.js"
click node_youtube "https://github.com/igrigorik/videospeed/blob/master/src/site-handlers/youtube-handler.js"
click node_netflix "https://github.com/igrigorik/videospeed/blob/master/src/site-handlers/netflix-handler.js"
click node_action "https://github.com/igrigorik/videospeed/blob/master/src/core/action-handler.js"
click node_events "https://github.com/igrigorik/videospeed/blob/master/src/utils/event-manager.js"
click node_classifier "https://github.com/igrigorik/videospeed/blob/master/src/core/intent-classifier.js"
click node_arbiter "https://github.com/igrigorik/videospeed/blob/master/src/core/arbiter.js"
click node_speedarb "https://github.com/igrigorik/videospeed/blob/master/src/core/speed-arbitration.js"
click node_controller "https://github.com/igrigorik/videospeed/blob/master/src/core/video-controller.js"
click node_state "https://github.com/igrigorik/videospeed/blob/master/src/core/state-manager.js"
click node_controls "https://github.com/igrigorik/videospeed/blob/master/src/ui/controls.js"
click node_shadow "https://github.com/igrigorik/videospeed/blob/master/src/ui/shadow-dom.js"
click node_drag "https://github.com/igrigorik/videospeed/blob/master/src/ui/drag-handler.js"
click node_visibility "https://github.com/igrigorik/videospeed/blob/master/src/core/controller-visibility.js"
click node_options "https://github.com/igrigorik/videospeed/blob/master/src/ui/options/options.js"
click node_popup "https://github.com/igrigorik/videospeed/blob/master/src/ui/popup/popup.js"
click node_settingscore "https://github.com/igrigorik/videospeed/blob/master/src/core/settings.js"
click node_storage "https://github.com/igrigorik/videospeed/blob/master/src/core/storage-manager.js"
click node_bridge "https://github.com/igrigorik/videospeed/blob/master/src/entries/content-bridge.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_entry,node_media,node_mutations,node_sitehandlers,node_youtube,node_netflix,node_viewer toneBlue
class node_action,node_events,node_classifier,node_arbiter,node_speedarb,node_controller,node_state toneAmber
class node_controls,node_shadow,node_drag,node_visibility toneMint
class node_options,node_popup,node_settingscore,node_storage,node_bridge,node_sync toneRose
```

## Components

### Media Detection

- [Content Entry](https://github.com/igrigorik/videospeed/blob/master/src/entries/inject-entry.js): `src/entries/inject-entry.js`
- [Media Observer](https://github.com/igrigorik/videospeed/blob/master/src/observers/media-observer.js): `src/observers/media-observer.js`
- [Mutation Observer](https://github.com/igrigorik/videospeed/blob/master/src/observers/mutation-observer.js): `src/observers/mutation-observer.js`
- [Site Handlers](https://github.com/igrigorik/videospeed/blob/master/src/site-handlers/index.js): `src/site-handlers/index.js`
- [YouTube Handler](https://github.com/igrigorik/videospeed/blob/master/src/site-handlers/youtube-handler.js): `src/site-handlers/youtube-handler.js`
- [Netflix Handler](https://github.com/igrigorik/videospeed/blob/master/src/site-handlers/netflix-handler.js): `src/site-handlers/netflix-handler.js`

### Playback Control

- [Action Handler](https://github.com/igrigorik/videospeed/blob/master/src/core/action-handler.js): `src/core/action-handler.js`
- [Event Manager](https://github.com/igrigorik/videospeed/blob/master/src/utils/event-manager.js): `src/utils/event-manager.js`
- [Intent Classifier](https://github.com/igrigorik/videospeed/blob/master/src/core/intent-classifier.js): `src/core/intent-classifier.js`
- [Playback Arbiter](https://github.com/igrigorik/videospeed/blob/master/src/core/arbiter.js): `src/core/arbiter.js`
- [Speed Arbitration](https://github.com/igrigorik/videospeed/blob/master/src/core/speed-arbitration.js): `src/core/speed-arbitration.js`
- [Video Controller](https://github.com/igrigorik/videospeed/blob/master/src/core/video-controller.js): `src/core/video-controller.js`
- [Media State](https://github.com/igrigorik/videospeed/blob/master/src/core/state-manager.js): `src/core/state-manager.js`

### User Experience

- [Overlay Controls](https://github.com/igrigorik/videospeed/blob/master/src/ui/controls.js): `src/ui/controls.js`
- [Shadow UI](https://github.com/igrigorik/videospeed/blob/master/src/ui/shadow-dom.js): `src/ui/shadow-dom.js`
- [Drag Handling](https://github.com/igrigorik/videospeed/blob/master/src/ui/drag-handler.js): `src/ui/drag-handler.js`
- [Visibility Policy](https://github.com/igrigorik/videospeed/blob/master/src/core/controller-visibility.js): `src/core/controller-visibility.js`

### Settings And Storage

- [Options Page](https://github.com/igrigorik/videospeed/blob/master/src/ui/options/options.js): `src/ui/options/options.js`
- [Extension Popup](https://github.com/igrigorik/videospeed/blob/master/src/ui/popup/popup.js): `src/ui/popup/popup.js`
- [Settings](https://github.com/igrigorik/videospeed/blob/master/src/core/settings.js): `src/core/settings.js`
- [Storage Manager](https://github.com/igrigorik/videospeed/blob/master/src/core/storage-manager.js): `src/core/storage-manager.js`
- [Content Bridge](https://github.com/igrigorik/videospeed/blob/master/src/entries/content-bridge.js): `src/entries/content-bridge.js`
- **Chrome Sync Storage**

### Other components

- **Viewer**

## Connections

- Content Entry → Media Observer: initializes (evidence: `src/entries/inject-entry.js`)
- Content Entry → Mutation Observer: initializes (evidence: `src/entries/inject-entry.js`)
- Content Entry → Site Handlers: uses (evidence: `src/entries/inject-entry.js`)
- Content Entry → Action Handler: initializes (evidence: `src/entries/inject-entry.js`)
- Content Entry → Event Manager: initializes (evidence: `src/entries/inject-entry.js`)
- Content Entry → Intent Classifier: configures (evidence: `src/entries/inject-entry.js`)
- Content Entry → Playback Arbiter: configures (evidence: `src/entries/inject-entry.js`)
- Content Entry → Speed Arbitration: configures (evidence: `src/entries/inject-entry.js`)
- Content Entry → Video Controller: uses (evidence: `src/entries/inject-entry.js`)
- Content Entry → Media State: initializes (evidence: `src/entries/inject-entry.js`)
- Content Entry → Settings: initializes (evidence: `src/entries/inject-entry.js`)
- Content Entry → Storage Manager: initializes (evidence: `src/entries/inject-entry.js`)
- Site Handlers → YouTube Handler: selects (evidence: `src/site-handlers/index.js`)
- Site Handlers → Netflix Handler: selects (evidence: `src/site-handlers/index.js`)
- Media Observer → Video Controller: attaches
- Mutation Observer → Media Observer: detects additions
- Event Manager → Action Handler: dispatches actions (evidence: `src/utils/event-manager.js`)
- Event Manager → Speed Arbitration: delegates decisions (evidence: `src/utils/event-manager.js`)
- Action Handler → Video Controller: adjusts playback
- Video Controller → Shadow UI: creates UI (evidence: `src/core/video-controller.js`)
- Video Controller → Site Handlers: requests placement (evidence: `src/core/video-controller.js`)
- Video Controller → Visibility Policy: applies policy
- Overlay Controls → Action Handler: triggers actions
- Drag Handling → Shadow UI: moves overlay (evidence: `src/ui/drag-handler.js`)
- Viewer → Event Manager: presses shortcuts (evidence: `README.md`)
- Viewer → Overlay Controls: uses overlay (evidence: `README.md`)
- Viewer → Drag Handling: drags overlay (evidence: `README.md`)
- Viewer → Options Page: customizes settings (evidence: `README.md`)
- Options Page → Settings: edits settings (evidence: `src/ui/options/options.js`)
- Options Page → Storage Manager: reads and writes (evidence: `src/ui/options/options.js`)
- Options Page → Extension Popup: shares preferences
- Settings → Storage Manager: persists settings
- Storage Manager → Chrome Sync Storage: reads and writes (evidence: `src/core/storage-manager.js`)
- Storage Manager → Content Bridge: requests settings (evidence: `src/core/storage-manager.js`)
- Content Bridge → Storage Manager: exchanges settings (evidence: `src/entries/content-bridge.js`)
