0
# Media Player
1

2
The MediaElementPlayer class provides a complete media player with customizable controls, theming, and extensive configuration options. It's the main class used for most MediaElement.js implementations.
3

4
## Capabilities
5

6
### MediaElementPlayer Constructor
7

8
Creates a complete media player with controls and UI around an HTML media element.
9

10
```javascript { .api }
11
/**
12
 * Create a new MediaElementPlayer instance
13
 * @param node - Element ID string or DOM node to enhance
14
 * @param options - Player configuration options
15
 */
16
constructor(node: string | HTMLElement, options?: PlayerOptions);
17

18
interface PlayerOptions {
19
  // Media and poster configuration
20
  poster?: string;
21
  showPosterWhenEnded?: boolean;
22
  showPosterWhenPaused?: boolean;
23
  
24
  // Dimension configuration
25
  defaultVideoWidth?: number;
26
  defaultVideoHeight?: number;
27
  defaultAudioWidth?: number;
28
  defaultAudioHeight?: number;
29
  videoWidth?: number;
30
  videoHeight?: number;
31
  setDimensions?: boolean;
32
  
33
  // Behavior configuration
34
  loop?: boolean;
35
  autoRewind?: boolean;
36
  enableAutosize?: boolean;
37
  clickToPlayPause?: boolean;
38
  
39
  // Controls and UI configuration
40
  alwaysShowControls?: boolean;
41
  hideVideoControlsOnLoad?: boolean;
42
  hideVideoControlsOnPause?: boolean;
43
  controlsTimeoutDefault?: number;
44
  controlsTimeoutMouseEnter?: number;
45
  controlsTimeoutMouseLeave?: number;
46
  features?: string[];
47
  useDefaultControls?: boolean;
48
  classPrefix?: string;
49
  
50
  // Advanced configuration
51
  stretching?: 'auto' | 'fill' | 'responsive' | 'none';
52
  pauseOtherPlayers?: boolean;
53
  enableKeyboard?: boolean;
54
  keyActions?: KeyAction[];
55
  
56
  // Callbacks
57
  success?: SuccessCallback;
58
  error?: ErrorCallback;
59
}
60

61
interface SuccessCallback {
62
  (mediaElement: MediaElement, originalNode: HTMLElement, instance: MediaElementPlayer): void;
63
}
64

65
interface ErrorCallback {
66
  (mediaElement: MediaElement, originalNode: HTMLElement): void;
67
}
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
import MediaElementPlayer from 'mediaelement';
74

75
// Basic player initialization
76
const player = new MediaElementPlayer('my-video');
77

78
// Player with configuration
79
const player = new MediaElementPlayer('my-video', {
80
  stretching: 'responsive',
81
  features: ['playpause', 'progress', 'current', 'duration', 'volume', 'fullscreen'],
82
  alwaysShowControls: false,
83
  controlsTimeoutDefault: 3000,
84
  success: (mediaElement, originalNode, instance) => {
85
    console.log('Player ready');
86
  },
87
  error: (mediaElement, originalNode) => {
88
    console.error('Player initialization failed');
89
  }
90
});
91

92
// Audio player with specific dimensions
93
const audioPlayer = new MediaElementPlayer('my-audio', {
94
  defaultAudioWidth: 500,
95
  defaultAudioHeight: 50,
96
  features: ['playpause', 'progress', 'current', 'duration', 'volume']
97
});
98
```
99

100
### Player Control Methods
101

102
Methods for controlling playback and player state.
103

104
```javascript { .api }
105
/**
106
 * Start media playback
107
 */
108
play(): void;
109

110
/**
111
 * Pause media playback
112
 */
113
pause(): void;
114

115
/**
116
 * Stop playback and reset to beginning
117
 */
118
stop(): void;
119

120
/**
121
 * Set current playback position
122
 * @param time - Time in seconds
123
 */
124
setCurrentTime(time: number): void;
125

126
/**
127
 * Set volume level
128
 * @param volume - Volume between 0.0 and 1.0
129
 */
130
setVolume(volume: number): void;
131

132
/**
133
 * Set mute state
134
 * @param muted - Whether to mute audio
135
 */
136
setMuted(muted: boolean): void;
137

138
/**
139
 * Enter fullscreen mode
140
 */
141
enterFullScreen(): void;
142

143
/**
144
 * Exit fullscreen mode
145
 */
146
exitFullScreen(): void;
147

148
/**
149
 * Remove player and restore original element
150
 */
151
remove(): void;
152

153
/**
154
 * Destroy player instance completely
155
 */
156
destroy(): void;
157
```
158

159
**Usage Examples:**
160

161
```javascript
162
const player = new MediaElementPlayer('video');
163

164
// Playback control
165
player.play();
166
player.pause();
167
player.stop();
168

169
// Seek to specific time
170
player.setCurrentTime(120); // 2 minutes
171

172
// Volume control
173
player.setVolume(0.8);
174
player.setMuted(true);
175

176
// Fullscreen
177
player.enterFullScreen();
178
player.exitFullScreen();
179

180
// Cleanup
181
player.destroy();
182
```
183

184
### Player Properties
185

186
Access to underlying media element and player components.
187

188
```javascript { .api }
189
/** The underlying MediaElement instance */
190
media: MediaElement;
191

192
/** Player configuration options */
193
options: PlayerOptions;
194

195
/** Container element wrapping the entire player */
196
container: HTMLElement;
197

198
/** Controls container element */
199
controls: HTMLElement;
200

201
/** Layers container for overlays */
202
layers: HTMLElement;
203

204
/** Original media element node */
205
node: HTMLElement;
206

207
/** Whether player is currently in fullscreen */
208
isFullScreen: boolean;
209

210
/** Whether player has been built and initialized */
211
built: boolean;
212

213
/** Unique player ID */
214
id: string;
215
```
216

217
**Usage Examples:**
218

219
```javascript
220
const player = new MediaElementPlayer('video');
221

222
// Access underlying MediaElement
223
console.log('Duration:', player.media.duration);
224
console.log('Current time:', player.media.currentTime);
225

226
// Access DOM elements
227
player.container.style.border = '2px solid red';
228
player.controls.style.backgroundColor = 'rgba(0,0,0,0.8)';
229

230
// Check player state
231
if (player.isFullScreen) {
232
  console.log('Player is in fullscreen mode');
233
}
234
```
235

236
### Control Features
237

238
Built-in control features that can be enabled/disabled through configuration.
239

240
```javascript { .api }
241
interface ControlFeatures {
242
  /** Play/pause toggle button */
243
  playpause: Feature;
244
  /** Current time display */
245
  current: Feature;
246
  /** Progress bar with scrubbing */
247
  progress: Feature;
248
  /** Total duration display */
249
  duration: Feature;
250
  /** Volume control with slider */
251
  volume: Feature;
252
  /** Fullscreen toggle button */
253
  fullscreen: Feature;
254
  /** Track/subtitle controls */
255
  tracks: Feature;
256
}
257

258
// Default feature set
259
const defaultFeatures = ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen'];
260
```
261

262
**Feature Configuration Examples:**
263

264
```javascript
265
// Minimal controls
266
const player = new MediaElementPlayer('video', {
267
  features: ['playpause', 'progress']
268
});
269

270
// Full feature set
271
const player = new MediaElementPlayer('video', {
272
  features: ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen']
273
});
274

275
// Custom feature order
276
const player = new MediaElementPlayer('video', {
277
  features: ['playpause', 'volume', 'progress', 'fullscreen']
278
});
279
```
280

281
### Keyboard Controls
282

283
Built-in keyboard shortcuts for player control.
284

285
```javascript { .api }
286
interface KeyAction {
287
  /** Key codes that trigger this action */
288
  keys: number[];
289
  /** Action to perform */
290
  action: (player: MediaElementPlayer, media: MediaElement) => void;
291
}
292

293
// Default keyboard shortcuts
294
const defaultKeyActions = [
295
  { keys: [32], action: 'play_pause' },     // Spacebar
296
  { keys: [38], action: 'volume_up' },      // Up arrow
297
  { keys: [40], action: 'volume_down' },    // Down arrow
298
  { keys: [37], action: 'seek_backward' },  // Left arrow
299
  { keys: [39], action: 'seek_forward' },   // Right arrow
300
  { keys: [70], action: 'fullscreen' },     // F key
301
  { keys: [77], action: 'mute' }            // M key
302
];
303
```
304

305
**Custom Keyboard Actions:**
306

307
```javascript
308
const player = new MediaElementPlayer('video', {
309
  enableKeyboard: true,
310
  keyActions: [
311
    {
312
      keys: [32], // Spacebar
313
      action: (player, media) => {
314
        if (media.paused) {
315
          player.play();
316
        } else {
317
          player.pause();
318
        }
319
      }
320
    },
321
    {
322
      keys: [82], // R key
323
      action: (player, media) => {
324
        media.currentTime = 0; // Restart
325
      }
326
    }
327
  ]
328
});
329
```
330

331
### Events
332

333
Player-specific events in addition to standard media events.
334

335
```javascript { .api }
336
// Player lifecycle events
337
const playerEvents = [
338
  'controlsready',    // Controls have been built
339
  'controlsshown',    // Controls became visible
340
  'controlshidden',   // Controls were hidden
341
  'resize'            // Player was resized
342
];
343
```
344

345
**Event Handling Examples:**
346

347
```javascript
348
const player = new MediaElementPlayer('video', {
349
  success: (mediaElement, originalNode, instance) => {
350
    // Listen for player events
351
    instance.addEventListener('controlsready', () => {
352
      console.log('Controls are ready');
353
    });
354
    
355
    instance.addEventListener('controlsshown', () => {
356
      console.log('Controls shown');
357
    });
358
    
359
    instance.addEventListener('controlshidden', () => {
360
      console.log('Controls hidden');
361
    });
362
    
363
    // Listen for media events through the media element
364
    mediaElement.addEventListener('play', () => {
365
      console.log('Playback started');
366
    });
367
    
368
    mediaElement.addEventListener('ended', () => {
369
      console.log('Playback finished');
370
    });
371
  }
372
});
373
```
374

375
## Styling and Theming
376

377
MediaElement.js uses CSS classes with configurable prefixes for complete visual customization.
378

379
```javascript { .api }
380
// Default CSS class structure (with 'mejs__' prefix)
381
interface CSSClasses {
382
  container: 'mejs__container';
383
  inner: 'mejs__inner'; 
384
  mediaelement: 'mejs__mediaelement';
385
  layers: 'mejs__layers';
386
  controls: 'mejs__controls';
387
  button: 'mejs__button';
388
  playpauseButton: 'mejs__playpause-button';
389
  timeRail: 'mejs__time-rail';
390
  volumeButton: 'mejs__volume-button';
391
  fullscreenButton: 'mejs__fullscreen-button';
392
}
393
```
394

395
**Custom Styling Example:**
396

397
```javascript
398
// Use custom CSS prefix
399
const player = new MediaElementPlayer('video', {
400
  classPrefix: 'myplayer-',
401
  features: ['playpause', 'progress', 'volume']
402
});
403

404
// Results in classes like:
405
// .myplayer-container
406
// .myplayer-controls  
407
// .myplayer-button
408
// etc.
409
```
410

411
```css
412
/* Custom player styling */
413
.mejs__container {
414
  background: #000;
415
  border-radius: 8px;
416
}
417

418
.mejs__controls {
419
  background: linear-gradient(transparent, rgba(0,0,0,0.8));
420
  padding: 10px;
421
}
422

423
.mejs__button {
424
  color: #fff;
425
  border: none;
426
  padding: 8px;
427
}
428

429
.mejs__button:hover {
430
  background: rgba(255,255,255,0.2);
431
}
432
```