0
# Player API
1

2
The Player is the core class in Video.js that provides complete media playback control and serves as the central coordinator for all video player functionality.
3

4
## Capabilities
5

6
### Player Creation
7

8
Create and configure video player instances with comprehensive options.
9

10
```javascript { .api }
11
/**
12
 * Create or retrieve a video player instance
13
 * @param id - Video element or element ID 
14
 * @param options - Player configuration options
15
 * @param ready - Callback when player is ready
16
 * @returns Player instance
17
 */
18
function videojs(id: string | Element, options?: VideoJsOptions, ready?: () => void): Player;
19

20
/**
21
 * Get existing player instance without creating new one
22
 * @param id - Video element or element ID
23
 * @returns Player instance or undefined
24
 */
25
videojs.getPlayer(id: string | Element): Player | undefined;
26

27
/**
28
 * Get all created players
29
 * @returns Object with all players keyed by ID
30
 */
31
videojs.getPlayers(): Record<string, Player>;
32

33
/**
34
 * Get array of all active player instances
35
 * @returns Array of player instances
36
 */
37
videojs.getAllPlayers(): Player[];
38
```
39

40
**Usage Examples:**
41

42
```javascript
43
// Basic player creation
44
const player = videojs("my-video");
45

46
// Player with options
47
const player = videojs("my-video", {
48
  controls: true,
49
  fluid: true,
50
  aspectRatio: "16:9",
51
  autoplay: false,
52
  preload: "metadata",
53
  sources: [{
54
    src: "path/to/video.mp4", 
55
    type: "video/mp4"
56
  }]
57
});
58

59
// Player with ready callback
60
const player = videojs("my-video", {}, () => {
61
  console.log("Player is ready!");
62
});
63

64
// Get existing player
65
const existingPlayer = videojs.getPlayer("my-video");
66
```
67

68
### Playback Control
69

70
Control media playback including play, pause, seeking, and speed adjustment.
71

72
```javascript { .api }
73
/**
74
 * Start playback
75
 * @returns Promise that resolves when playback starts
76
 */
77
play(): Promise<void>;
78

79
/**
80
 * Pause playback
81
 */
82
pause(): void;
83

84
/**
85
 * Check if player is paused
86
 * @returns True if paused
87
 */
88
paused(): boolean;
89

90
/**
91
 * Get current playback time in seconds
92
 * @returns Current time
93
 */
94
currentTime(): number;
95

96
/**
97
 * Set current playback time
98
 * @param seconds - Time to seek to
99
 */
100
currentTime(seconds: number): void;
101

102
/**
103
 * Get media duration in seconds
104
 * @returns Duration or NaN if unknown
105
 */
106
duration(): number;
107

108
/**
109
 * Get remaining playback time
110
 * @returns Remaining time in seconds
111
 */
112
remainingTime(): number;
113

114
/**
115
 * Get playback rate
116
 * @returns Current playback rate (1.0 = normal speed)
117
 */
118
playbackRate(): number;
119

120
/**
121
 * Set playback rate
122
 * @param rate - Playback rate (0.5 = half speed, 2.0 = double speed)
123
 */
124
playbackRate(rate: number): void;
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
// Basic playback control
131
await player.play();
132
player.pause();
133

134
// Check playback state
135
if (player.paused()) {
136
  console.log("Player is paused");
137
}
138

139
// Seeking
140
player.currentTime(30); // Seek to 30 seconds
141
console.log("Current time:", player.currentTime());
142
console.log("Duration:", player.duration());
143
console.log("Remaining:", player.remainingTime());
144

145
// Speed control
146
player.playbackRate(1.5); // Play at 1.5x speed
147
```
148

149
### Audio Control
150

151
Manage audio volume and muting functionality.
152

153
```javascript { .api }
154
/**
155
 * Get volume level
156
 * @returns Volume (0.0 to 1.0)
157
 */
158
volume(): number;
159

160
/**
161
 * Set volume level
162
 * @param level - Volume level (0.0 to 1.0)
163
 */
164
volume(level: number): void;
165

166
/**
167
 * Check if audio is muted
168
 * @returns True if muted
169
 */
170
muted(): boolean;
171

172
/**
173
 * Set muted state
174
 * @param muted - True to mute, false to unmute
175
 */
176
muted(muted: boolean): void;
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
// Volume control
183
player.volume(0.8); // Set volume to 80%
184
console.log("Volume:", player.volume());
185

186
// Muting
187
player.muted(true); // Mute audio
188
player.muted(false); // Unmute audio
189
console.log("Is muted:", player.muted());
190
```
191

192
### Source Management
193

194
Load and manage media sources with support for multiple formats and streaming.
195

196
```javascript { .api }
197
/**
198
 * Get current source(s)
199
 * @returns Array of current sources
200
 */
201
src(): Source[];
202

203
/**
204
 * Set media source(s)
205
 * @param source - Source URL, source object, or array of sources
206
 */
207
src(source: string | Source | Source[]): void;
208

209
/**
210
 * Get current source URL  
211
 * @returns Current source URL
212
 */
213
currentSrc(): string;
214

215
/**
216
 * Load new source and reset player
217
 */
218
load(): void;
219

220
/**
221
 * Reset player to initial state
222
 */
223
reset(): void;
224
```
225

226
**Usage Examples:**
227

228
```javascript
229
// Set single source
230
player.src("path/to/video.mp4");
231

232
// Set source with type
233
player.src({
234
  src: "path/to/video.mp4",
235
  type: "video/mp4"
236
});
237

238
// Set multiple sources for format fallback
239
player.src([
240
  { src: "path/to/video.webm", type: "video/webm" },
241
  { src: "path/to/video.mp4", type: "video/mp4" },
242
  { src: "path/to/video.ogv", type: "video/ogg" }
243
]);
244

245
// Get current sources
246
const sources = player.src();
247
console.log("Current source:", player.currentSrc());
248

249
// Reload with new source
250
player.load();
251
```
252

253
### Poster Management
254

255
Manage poster images displayed before playback begins.
256

257
```javascript { .api }
258
/**
259
 * Get poster image URL
260
 * @returns Poster URL
261
 */
262
poster(): string;
263

264
/**
265
 * Set poster image URL
266
 * @param src - Poster image URL
267
 */
268
poster(src: string): void;
269
```
270

271
### Dimensions and Display
272

273
Control player size, aspect ratio, and display modes.
274

275
```javascript { .api }
276
/**
277
 * Get player width
278
 * @returns Width in pixels
279
 */
280
width(): number;
281

282
/**
283
 * Set player width
284
 * @param width - Width in pixels
285
 */
286
width(width: number): void;
287

288
/**
289
 * Get player height
290
 * @returns Height in pixels
291
 */
292
height(): number;
293

294
/**
295
 * Set player height  
296
 * @param height - Height in pixels
297
 */
298
height(height: number): void;
299

300
/**
301
 * Set both width and height
302
 * @param width - Width in pixels
303
 * @param height - Height in pixels
304
 */
305
dimensions(width: number, height: number): void;
306

307
/**
308
 * Get/set responsive fluid mode
309
 * @param bool - True to enable fluid mode
310
 * @returns Current fluid state or this for chaining
311
 */
312
fluid(bool?: boolean): boolean | Player;
313

314
/**
315
 * Get/set aspect ratio
316
 * @param ratio - Aspect ratio string (e.g., "16:9")
317
 * @returns Current aspect ratio or this for chaining
318
 */
319
aspectRatio(ratio?: string): string | Player;
320
```
321

322
**Usage Examples:**
323

324
```javascript
325
// Fixed dimensions
326
player.width(800);
327
player.height(450);
328
player.dimensions(800, 450);
329

330
// Responsive/fluid sizing
331
player.fluid(true);
332
player.aspectRatio("16:9");
333

334
// Get dimensions
335
console.log("Size:", player.width(), "x", player.height());
336
```
337

338
### Fullscreen Support
339

340
Manage fullscreen display with comprehensive browser support.
341

342
```javascript { .api }
343
/**
344
 * Check if player is in fullscreen mode
345
 * @returns True if in fullscreen
346
 */
347
isFullscreen(): boolean;
348

349
/**
350
 * Request fullscreen mode
351
 * @returns Promise that resolves when fullscreen is entered
352
 */
353
requestFullscreen(): Promise<void>;
354

355
/**
356
 * Exit fullscreen mode
357
 * @returns Promise that resolves when fullscreen is exited  
358
 */
359
exitFullscreen(): Promise<void>;
360

361
/**
362
 * Check if fullscreen is supported
363
 * @returns True if fullscreen is supported
364
 */
365
supportsFullScreen(): boolean;
366
```
367

368
**Usage Examples:**
369

370
```javascript
371
// Fullscreen control
372
if (player.supportsFullScreen()) {
373
  await player.requestFullscreen();
374
  console.log("In fullscreen:", player.isFullscreen());
375
  
376
  // Exit fullscreen
377
  await player.exitFullscreen();
378
}
379
```
380

381
### Player State and Information
382

383
Access player state, buffering information, and technical details.
384

385
```javascript { .api }
386
/**
387
 * Check if player is ready
388
 * @returns True if ready
389
 */
390
readyState(): number;
391

392
/**
393
 * Get buffered time ranges
394
 * @returns TimeRanges object
395
 */
396
buffered(): TimeRanges;
397

398
/**
399
 * Get percentage of video buffered
400
 * @returns Buffered percentage (0-100)
401
 */
402
bufferedPercent(): number;
403

404
/**
405
 * Check if media is seeking
406
 * @returns True if seeking
407
 */
408
seeking(): boolean;
409

410
/**
411
 * Check if media has ended
412
 * @returns True if ended
413
 */
414
ended(): boolean;
415

416
/**
417
 * Get network state
418
 * @returns Network state constant
419
 */
420
networkState(): number;
421

422
/**
423
 * Get error object if error occurred
424
 * @returns MediaError object or null
425
 */
426
error(): MediaError | null;
427
```
428

429
### Lifecycle Management
430

431
Manage player lifecycle including initialization and cleanup.
432

433
```javascript { .api }
434
/**
435
 * Execute callback when player is ready
436
 * @param callback - Function to call when ready
437
 */
438
ready(callback: () => void): void;
439

440
/**
441
 * Dispose of player and clean up resources
442
 */
443
dispose(): void;
444

445
/**
446
 * Check if player has been disposed
447
 * @returns True if disposed
448
 */
449
isDisposed(): boolean;
450
```
451

452
**Usage Examples:**
453

454
```javascript
455
// Wait for player ready
456
player.ready(() => {
457
  console.log("Player is ready!");
458
  console.log("Duration:", player.duration());
459
});
460

461
// Clean up when done
462
player.dispose();
463
```
464

465
## Types
466

467
```javascript { .api }
468
interface VideoJsOptions {
469
  controls?: boolean;
470
  fluid?: boolean;
471
  responsive?: boolean;
472
  aspectRatio?: string;
473
  width?: number;
474
  height?: number;
475
  autoplay?: boolean | string;
476
  preload?: "none" | "metadata" | "auto";
477
  poster?: string;
478
  sources?: Source[];
479
  tracks?: TextTrackOptions[];
480
  plugins?: Record<string, any>;
481
  techOrder?: string[];
482
  html5?: Html5Options;
483
  playbackRates?: number[];
484
  language?: string;
485
  languages?: Record<string, any>;
486
  notSupportedMessage?: string;
487
  [key: string]: any;
488
}
489

490
interface Source {
491
  src: string;
492
  type: string;
493
  label?: string;
494
}
495

496
interface Html5Options {
497
  nativeTextTracks?: boolean;
498
  nativeAudioTracks?: boolean;
499
  nativeVideoTracks?: boolean;
500
  preloadTextTracks?: boolean;
501
  [key: string]: any;
502
}
503

504
interface MediaError {
505
  code: number;
506
  message: string;
507
  status?: number;
508
}
509
```