0
# Configuration
1

2
MediaElement.js provides extensive configuration options to customize player behavior, appearance, and functionality through the PlayerOptions interface.
3

4
## Capabilities
5

6
### Media and Poster Configuration
7

8
Options for controlling poster images and media display behavior.
9

10
```javascript { .api }
11
interface PosterOptions {
12
  /** URL to poster image */
13
  poster?: string;
14
  
15
  /** Show poster when media reaches end */
16
  showPosterWhenEnded?: boolean;
17
  
18
  /** Show poster when media is paused */
19
  showPosterWhenPaused?: boolean;
20
}
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
const player = new MediaElementPlayer('video', {
27
  poster: 'https://example.com/poster.jpg',
28
  showPosterWhenEnded: true,
29
  showPosterWhenPaused: false
30
});
31
```
32

33
### Dimension Configuration
34

35
Control player and media element sizing behavior.
36

37
```javascript { .api }
38
interface DimensionOptions {
39
  /** Default video width when not specified in HTML */
40
  defaultVideoWidth?: number; // Default: 480
41
  
42
  /** Default video height when not specified in HTML */
43
  defaultVideoHeight?: number; // Default: 270
44
  
45
  /** Default audio player width */
46
  defaultAudioWidth?: number; // Default: 400
47
  
48
  /** Default audio player height */
49
  defaultAudioHeight?: number; // Default: 40
50
  
51
  /** Override video width (ignores HTML width attribute) */
52
  videoWidth?: number; // Default: -1 (use HTML or default)
53
  
54
  /** Override video height (ignores HTML height attribute) */
55
  videoHeight?: number; // Default: -1 (use HTML or default)
56
  
57
  /** Whether to set dimensions programmatically */
58
  setDimensions?: boolean; // Default: true
59
  
60
  /** Enable automatic resizing to match media dimensions */
61
  enableAutosize?: boolean; // Default: true
62
}
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
// Fixed size video player
69
const player = new MediaElementPlayer('video', {
70
  videoWidth: 800,
71
  videoHeight: 600,
72
  enableAutosize: false
73
});
74

75
// Responsive audio player
76
const audioPlayer = new MediaElementPlayer('audio', {
77
  defaultAudioWidth: 300,
78
  defaultAudioHeight: 60,
79
  setDimensions: true
80
});
81

82
// Let media determine size
83
const adaptivePlayer = new MediaElementPlayer('video', {
84
  enableAutosize: true,
85
  setDimensions: false
86
});
87
```
88

89
### Behavior Configuration
90

91
Options controlling playback behavior and user interaction.
92

93
```javascript { .api }
94
interface BehaviorOptions {
95
  /** Enable looped playback */
96
  loop?: boolean; // Default: false
97
  
98
  /** Rewind to beginning when media ends */
99
  autoRewind?: boolean; // Default: true
100
  
101
  /** Allow click on media to play/pause */
102
  clickToPlayPause?: boolean; // Default: true
103
  
104
  /** Pause other players when this one starts */
105
  pauseOtherPlayers?: boolean; // Default: true
106
}
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
const player = new MediaElementPlayer('video', {
113
  loop: true,
114
  autoRewind: false,
115
  clickToPlayPause: true,
116
  pauseOtherPlayers: false
117
});
118
```
119

120
### Controls and UI Configuration
121

122
Comprehensive options for customizing player controls appearance and behavior.
123

124
```javascript { .api }
125
interface ControlsOptions {
126
  /** Always show controls (no auto-hide) */
127
  alwaysShowControls?: boolean; // Default: false
128
  
129
  /** Hide controls initially on video load */
130
  hideVideoControlsOnLoad?: boolean; // Default: false
131
  
132
  /** Hide controls when video is paused */
133
  hideVideoControlsOnPause?: boolean; // Default: false
134
  
135
  /** Default timeout before hiding controls (ms) */
136
  controlsTimeoutDefault?: number; // Default: 1500
137
  
138
  /** Timeout when mouse enters player (ms) */
139
  controlsTimeoutMouseEnter?: number; // Default: 2500
140
  
141
  /** Timeout when mouse leaves player (ms) */
142
  controlsTimeoutMouseLeave?: number; // Default: 1000
143
  
144
  /** List of features/controls to include */
145
  features?: string[]; // Default: ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen']
146
  
147
  /** Use the default feature set */
148
  useDefaultControls?: boolean; // Default: false
149
  
150
  /** CSS class prefix for player elements */
151
  classPrefix?: string; // Default: 'mejs__'
152
}
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Always visible controls
159
const player = new MediaElementPlayer('video', {
160
  alwaysShowControls: true,
161
  classPrefix: 'myplayer-'
162
});
163

164
// Minimal controls that hide quickly
165
const minimalPlayer = new MediaElementPlayer('video', {
166
  features: ['playpause', 'progress'],
167
  controlsTimeoutDefault: 1000,
168
  hideVideoControlsOnLoad: true
169
});
170

171
// Custom control timing
172
const customPlayer = new MediaElementPlayer('video', {
173
  controlsTimeoutDefault: 3000,
174
  controlsTimeoutMouseEnter: 5000,
175
  controlsTimeoutMouseLeave: 500
176
});
177
```
178

179
### Video Stretching Configuration
180

181
Control how video content is scaled and positioned within the player.
182

183
```javascript { .api }
184
interface StretchingOptions {
185
  /** Video scaling mode */
186
  stretching?: 'auto' | 'fill' | 'responsive' | 'none'; // Default: 'auto'
187
}
188

189
// Stretching modes explained:
190
// 'auto' - Maintain aspect ratio, fit within container
191
// 'fill' - Stretch to fill container exactly (may distort)
192
// 'responsive' - Responsive scaling maintaining aspect ratio  
193
// 'none' - Use original video dimensions
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
// Responsive video that maintains aspect ratio
200
const responsivePlayer = new MediaElementPlayer('video', {
201
  stretching: 'responsive'
202
});
203

204
// Fill container exactly (may distort video)
205
const fillPlayer = new MediaElementPlayer('video', {
206
  stretching: 'fill'
207
});
208

209
// Use original video size
210
const originalPlayer = new MediaElementPlayer('video', {
211
  stretching: 'none'
212
});
213
```
214

215
### Platform-Specific Configuration
216

217
Options for controlling behavior on specific platforms and devices.
218

219
```javascript { .api }
220
interface PlatformOptions {
221
  /** Use native controls on iPad */
222
  iPadUseNativeControls?: boolean; // Default: false
223
  
224
  /** Use native controls on iPhone */
225
  iPhoneUseNativeControls?: boolean; // Default: false
226
  
227
  /** Use native controls on Android */
228
  AndroidUseNativeControls?: boolean; // Default: false
229
}
230
```
231

232
**Usage Examples:**
233

234
```javascript
235
// Use native controls on mobile devices
236
const mobilePlayer = new MediaElementPlayer('video', {
237
  iPadUseNativeControls: true,
238
  iPhoneUseNativeControls: true,
239
  AndroidUseNativeControls: true
240
});
241
```
242

243
### Keyboard and Accessibility Configuration
244

245
Options for keyboard controls and accessibility features.
246

247
```javascript { .api }
248
interface AccessibilityOptions {
249
  /** Enable keyboard shortcuts */
250
  enableKeyboard?: boolean; // Default: true
251
  
252
  /** Custom keyboard action definitions */
253
  keyActions?: KeyAction[];
254
  
255
  /** Hide screen reader title text */
256
  hideScreenReaderTitle?: boolean; // Default: false
257
}
258

259
interface KeyAction {
260
  /** Array of key codes that trigger this action */
261
  keys: number[];
262
  /** Function to execute when key is pressed */
263
  action: (player: MediaElementPlayer, media: MediaElement, event: KeyboardEvent) => void;
264
}
265
```
266

267
**Usage Examples:**
268

269
```javascript
270
// Custom keyboard shortcuts
271
const player = new MediaElementPlayer('video', {
272
  enableKeyboard: true,
273
  keyActions: [
274
    {
275
      keys: [32], // Spacebar
276
      action: (player, media) => {
277
        if (media.paused) {
278
          player.play();
279
        } else {
280
          player.pause();
281
        }
282
      }
283
    },
284
    {
285
      keys: [27], // Escape
286
      action: (player) => {
287
        if (player.isFullScreen) {
288
          player.exitFullScreen();
289
        }
290
      }
291
    }
292
  ]
293
});
294

295
// Disable keyboard controls
296
const noKeyboardPlayer = new MediaElementPlayer('video', {
297
  enableKeyboard: false
298
});
299
```
300

301
### Advanced Configuration
302

303
Advanced options for specialized use cases.
304

305
```javascript { .api }
306
interface AdvancedOptions {
307
  /** Custom error handler */
308
  customError?: string | ((media: MediaElement, originalNode: HTMLElement) => void);
309
  
310
  /** Function to calculate backward seek interval */
311
  defaultSeekBackwardInterval?: (media: MediaElement) => number;
312
  
313
  /** Function to calculate forward seek interval */
314
  defaultSeekForwardInterval?: (media: MediaElement) => number;
315
  
316
  /** Renderer priority order */
317
  renderers?: string[];
318
  
319
  /** Icon sprite file path */
320
  iconSprite?: string;
321
}
322
```
323

324
**Usage Examples:**
325

326
```javascript
327
// Custom seek intervals
328
const player = new MediaElementPlayer('video', {
329
  defaultSeekBackwardInterval: (media) => Math.min(media.duration * 0.1, 10), // Max 10 seconds
330
  defaultSeekForwardInterval: (media) => Math.min(media.duration * 0.1, 30), // Max 30 seconds
331
  
332
  // Custom error handling
333
  customError: (media, originalNode) => {
334
    console.error('Player error occurred:', media.error);
335
    // Show custom error UI
336
  },
337
  
338
  // Renderer preferences
339
  renderers: ['html5', 'hls', 'dash'],
340
  
341
  // Custom icon sprite
342
  iconSprite: '/assets/custom-icons.svg'
343
});
344
```
345

346
### Time Format Configuration
347

348
Options for controlling time display format.
349

350
```javascript { .api }
351
interface TimeFormatOptions {
352
  /** Time display format */
353
  timeFormat?: string; // Default: ''
354
  
355
  /** Always show hours even for short media */
356
  alwaysShowHours?: boolean; // Default: false
357
  
358
  /** Show frame count in timecode */
359
  showTimecodeFrameCount?: boolean; // Default: false
360
  
361
  /** Frames per second for frame counting */
362
  framesPerSecond?: number; // Default: 25
363
}
364
```
365

366
**Usage Examples:**
367

368
```javascript
369
// Force hour display
370
const player = new MediaElementPlayer('video', {
371
  alwaysShowHours: true,
372
  timeFormat: 'hh:mm:ss'
373
});
374

375
// Show frame count for video editing
376
const framePlayer = new MediaElementPlayer('video', {
377
  showTimecodeFrameCount: true,
378
  framesPerSecond: 30
379
});
380
```
381

382
### Callback Configuration
383

384
Success and error callbacks for player initialization.
385

386
```javascript { .api }
387
interface CallbackOptions {
388
  /** Called when player initializes successfully */
389
  success?: (mediaElement: MediaElement, originalNode: HTMLElement, instance: MediaElementPlayer) => void;
390
  
391
  /** Called when player initialization fails */
392
  error?: (mediaElement: MediaElement, originalNode: HTMLElement) => void;
393
}
394
```
395

396
**Usage Examples:**
397

398
```javascript
399
const player = new MediaElementPlayer('video', {
400
  success: (mediaElement, originalNode, instance) => {
401
    console.log('Player ready:', instance.id);
402
    
403
    // Set up event listeners
404
    mediaElement.addEventListener('play', () => {
405
      console.log('Playback started');
406
    });
407
    
408
    // Configure additional options
409
    instance.setVolume(0.8);
410
  },
411
  
412
  error: (mediaElement, originalNode) => {
413
    console.error('Failed to initialize player');
414
    // Show fallback content or error message
415
  }
416
});
417
```
418

419
## Complete Configuration Example
420

421
```javascript
422
const player = new MediaElementPlayer('my-video', {
423
  // Media configuration
424
  poster: '/posters/video-poster.jpg',
425
  showPosterWhenEnded: true,
426
  showPosterWhenPaused: false,
427
  
428
  // Dimensions
429
  defaultVideoWidth: 854,
430
  defaultVideoHeight: 480,
431
  enableAutosize: true,
432
  stretching: 'responsive',
433
  
434
  // Behavior
435
  loop: false,
436
  autoRewind: true,
437
  clickToPlayPause: true,
438
  pauseOtherPlayers: true,
439
  
440
  // Controls
441
  features: ['playpause', 'current', 'progress', 'duration', 'volume', 'fullscreen'],
442
  alwaysShowControls: false,
443
  controlsTimeoutDefault: 2000,
444
  classPrefix: 'mejs__',
445
  
446
  // Keyboard
447
  enableKeyboard: true,
448
  
449
  // Platform
450
  iPadUseNativeControls: false,
451
  iPhoneUseNativeControls: false,
452
  AndroidUseNativeControls: false,
453
  
454
  // Advanced
455
  renderers: ['html5', 'hls'],
456
  iconSprite: '/assets/mejs-controls.svg',
457
  
458
  // Callbacks
459
  success: (mediaElement, originalNode, instance) => {
460
    console.log('Player initialized successfully');
461
  },
462
  
463
  error: (mediaElement, originalNode) => {
464
    console.error('Player initialization failed');
465
  }
466
});
467
```