0
# Video.js
1

2
Video.js is a comprehensive HTML5 video player framework designed for all web-based platforms, supporting common media formats including streaming formats like HLS and DASH. It provides a robust, full-featured player that works seamlessly across desktops, mobile devices, tablets, and Smart TVs with automatic fallback capabilities and cross-browser compatibility.
3

4
## Package Information
5

6
- **Package Name**: video.js
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install video.js`
10

11
## Core Imports
12

13
```javascript
14
import videojs from "video.js";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const videojs = require("video.js");
21
```
22

23
For ES6 with specific components:
24

25
```javascript
26
import videojs, { Component, Plugin } from "video.js";
27
```
28

29
CSS import:
30

31
```css
32
@import "video.js/dist/video-js.css";
33
```
34

35
## Basic Usage
36

37
```javascript
38
import videojs from "video.js";
39

40
// Initialize a player
41
const player = videojs("my-video", {
42
  controls: true,
43
  fluid: true,
44
  aspectRatio: "16:9",
45
  sources: [{
46
    src: "path/to/video.mp4",
47
    type: "video/mp4"
48
  }]
49
});
50

51
// Player is ready
52
player.ready(() => {
53
  console.log("Player is ready");
54
});
55

56
// Control playback
57
player.play();
58
player.pause();
59
player.currentTime(30); // Seek to 30 seconds
60
player.volume(0.8); // Set volume to 80%
61

62
// Clean up
63
player.dispose();
64
```
65

66
## Architecture
67

68
Video.js is built around several key architectural patterns:
69

70
- **Player Core**: Central `Player` class that manages media playback and coordinates all components
71
- **Component System**: Hierarchical UI component architecture with `Component` base class
72
- **Tech Layer**: Abstraction for different playback technologies (HTML5, Flash, etc.)
73
- **Plugin Architecture**: Extensible plugin system for adding functionality
74
- **Event System**: Comprehensive event handling for media and UI interactions
75
- **Track Management**: Support for video, audio, and text tracks with full accessibility features
76
- **Middleware**: Intercept and modify tech operations for advanced customization
77

78
## Capabilities
79

80
### Player Creation and Management
81

82
Core functionality for creating, configuring, and managing video player instances with full lifecycle control.
83

84
```javascript { .api }
85
/**
86
 * Create or retrieve a video player instance
87
 * @param id - Video element or element ID
88
 * @param options - Player configuration options  
89
 * @param ready - Callback when player is ready
90
 * @returns Player instance
91
 */
92
function videojs(id: string | Element, options?: VideoJsOptions, ready?: () => void): Player;
93

94
/**
95
 * Get existing player instance without creating new one
96
 * @param id - Video element or element ID
97
 * @returns Player instance or undefined
98
 */
99
videojs.getPlayer(id: string | Element): Player | undefined;
100

101
/**
102
 * Get all created players
103
 * @returns Object with all players keyed by ID
104
 */
105
videojs.getPlayers(): Record<string, Player>;
106

107
/**
108
 * Get array of all active player instances
109
 * @returns Array of player instances
110
 */
111
videojs.getAllPlayers(): Player[];
112
```
113

114
[Player API](./player.md)
115

116
### Component System
117

118
Hierarchical UI component system for building custom player interfaces and extending functionality.
119

120
```javascript { .api }
121
/**
122
 * Register a custom component for use in players
123
 * @param name - Component name
124
 * @param component - Component class
125
 * @returns Registered component class
126
 */
127
videojs.registerComponent(name: string, component: typeof Component): typeof Component;
128

129
/**
130
 * Get registered component class by name
131
 * @param name - Component name
132
 * @returns Component class
133
 */
134
videojs.getComponent(name: string): typeof Component;
135
```
136

137
[Component System](./components.md)
138

139
### Plugin System
140

141
Extensible plugin architecture for adding custom functionality to players.
142

143
```javascript { .api }
144
/**
145
 * Register a plugin with Video.js
146
 * @param name - Plugin name
147
 * @param plugin - Plugin function or class
148
 * @returns Registered plugin
149
 */
150
videojs.registerPlugin<T = Plugin>(name: string, plugin: PluginFunction<T> | typeof Plugin): PluginFunction<T> | typeof Plugin;
151

152
/**
153
 * Remove registered plugin
154
 * @param name - Plugin name
155
 */
156
videojs.deregisterPlugin(name: string): void;
157

158
/**
159
 * Get registered plugin by name
160
 * @param name - Plugin name
161
 * @returns Plugin function or class
162
 */
163
videojs.getPlugin(name: string): PluginFunction | typeof Plugin;
164

165
/**
166
 * Get all registered plugins
167
 * @returns Object with all plugins
168
 */
169
videojs.getPlugins(): Record<string, PluginFunction | typeof Plugin>;
170
```
171

172
[Plugin System](./plugins.md)
173

174
### Tech System
175

176
Playback technology abstraction layer supporting multiple media engines and custom implementations.
177

178
```javascript { .api }
179
/**
180
 * Register a playback technology
181
 * @param name - Tech name
182
 * @param tech - Tech class
183
 */
184
videojs.registerTech(name: string, tech: typeof Tech): void;
185

186
/**
187
 * Get registered tech by name
188
 * @param name - Tech name  
189
 * @returns Tech class
190
 */
191
videojs.getTech(name: string): typeof Tech;
192

193
/**
194
 * Register middleware for tech operations
195
 * @param type - Middleware type
196
 * @param middleware - Middleware function or object
197
 */
198
videojs.use(type: string, middleware: MiddlewareFunction | MiddlewareObject): void;
199
```
200

201
[Tech System](./tech.md)
202

203
### Track Management
204

205
Comprehensive track management for video, audio, and text tracks with accessibility support.
206

207
```javascript { .api }
208
/**
209
 * Text track for subtitles, captions, descriptions
210
 */
211
class TextTrack {
212
  readonly kind: TextTrackKind;
213
  readonly label: string;
214
  readonly language: string;
215
  mode: TextTrackMode;
216
  readonly cues: TextTrackCueList;
217
}
218

219
/**
220
 * Audio track representation
221
 */
222
class AudioTrack {
223
  readonly id: string;
224
  readonly kind: string;
225
  readonly label: string;
226
  readonly language: string;
227
  enabled: boolean;
228
}
229

230
/**
231
 * Video track representation  
232
 */
233
class VideoTrack {
234
  readonly id: string;
235
  readonly kind: string;
236
  readonly label: string;
237
  readonly language: string;
238
  selected: boolean;
239
}
240
```
241

242
[Track Management](./tracks.md)
243

244
### Event System
245

246
Comprehensive event handling system for media events, user interactions, and component communication.
247

248
```javascript { .api }
249
/**
250
 * Add event listener
251
 * @param target - Event target
252
 * @param type - Event type
253
 * @param listener - Event handler function
254
 */
255
videojs.on(target: EventTarget, type: string, listener: EventListener): void;
256

257
/**
258
 * Add one-time event listener
259
 * @param target - Event target
260
 * @param type - Event type
261
 * @param listener - Event handler function
262
 */
263
videojs.one(target: EventTarget, type: string, listener: EventListener): void;
264

265
/**
266
 * Remove event listener
267
 * @param target - Event target
268
 * @param type - Event type
269
 * @param listener - Event handler function
270
 */
271
videojs.off(target: EventTarget, type: string, listener: EventListener): void;
272

273
/**
274
 * Trigger event on target
275
 * @param target - Event target
276
 * @param event - Event type or Event object
277
 * @param data - Event data
278
 */
279
videojs.trigger(target: EventTarget, event: string | Event, data?: any): void;
280
```
281

282
[Event System](./events.md)
283

284
### Utility Functions
285

286
Comprehensive utility functions for DOM manipulation, time handling, browser detection, and more.
287

288
```javascript { .api }
289
/**
290
 * DOM manipulation utilities
291
 */
292
videojs.dom: {
293
  isEl(element: any): boolean;
294
  createEl(tagName: string, properties?: object): Element;
295
  addClass(element: Element, className: string): void;
296
  removeClass(element: Element, className: string): void;
297
  hasClass(element: Element, className: string): boolean;
298
}
299

300
/**
301
 * Time utilities
302
 */
303
videojs.time: {
304
  createTimeRanges(start: number, end: number): TimeRanges;
305
  formatTime(seconds: number): string;
306
}
307

308
/**
309
 * Browser detection utilities
310
 */
311
videojs.browser: {
312
  IS_CHROME: boolean;
313
  IS_FIREFOX: boolean;
314
  IS_SAFARI: boolean;
315
  IS_IOS: boolean;
316
  IS_ANDROID: boolean;
317
}
318
```
319

320
[Utility Functions](./utilities.md)
321

322
## Core Types
323

324
```javascript { .api }
325
interface VideoJsOptions {
326
  controls?: boolean;
327
  fluid?: boolean;
328
  responsive?: boolean;
329
  aspectRatio?: string;
330
  width?: number;
331
  height?: number;
332
  autoplay?: boolean | string;
333
  preload?: "none" | "metadata" | "auto";
334
  poster?: string;
335
  sources?: Source[];
336
  tracks?: TextTrackOptions[];
337
  plugins?: Record<string, any>;
338
  techOrder?: string[];
339
  html5?: object;
340
  [key: string]: any;
341
}
342

343
interface Source {
344
  src: string;
345
  type: string;
346
}
347

348
interface TextTrackOptions {
349
  kind: TextTrackKind;
350
  src: string;
351
  srclang?: string;
352
  label?: string;
353
  default?: boolean;
354
}
355

356
type TextTrackKind = "subtitles" | "captions" | "descriptions" | "chapters" | "metadata";
357
type TextTrackMode = "disabled" | "hidden" | "showing";
358

359
interface Player {
360
  // Core playback methods
361
  play(): Promise<void>;
362
  pause(): void;
363
  currentTime(): number;
364
  currentTime(seconds: number): void;
365
  duration(): number;
366
  volume(): number;
367
  volume(level: number): void;
368
  muted(): boolean;
369
  muted(muted: boolean): void;
370
  
371
  // Source and poster management
372
  src(): Source[];
373
  src(source: string | Source | Source[]): void;
374
  poster(): string;
375
  poster(src: string): void;
376
  
377
  // Dimensions and display
378
  width(): number;
379
  width(width: number): void;
380
  height(): number;
381
  height(height: number): void;
382
  dimensions(width: number, height: number): void;
383
  
384
  // Fullscreen
385
  isFullscreen(): boolean;
386
  requestFullscreen(): Promise<void>;
387
  exitFullscreen(): Promise<void>;
388
  
389
  // Lifecycle
390
  ready(callback: () => void): void;
391
  dispose(): void;
392
}
393

394
interface Component {
395
  el(): Element;
396
  addChild(component: string | Component, options?: object): Component;
397
  removeChild(component: Component): void;
398
  on(type: string, listener: EventListener): void;
399
  trigger(event: string, data?: any): void;
400
  dispose(): void;
401
}
402

403
interface Plugin {
404
  player: Player;
405
  dispose(): void;
406
}
407

408
type PluginFunction<T = any> = (this: Player, options?: T) => void;
409

410
interface MiddlewareObject {
411
  callPlay?: () => any;
412
  callPause?: () => any;
413
  setSource?: (src: Source, next: (error?: any, src?: Source) => void) => void;
414
}
415

416
type MiddlewareFunction = (player: Player) => MiddlewareObject;
417
```