0
# Renderer System
1

2
MediaElement.js uses a pluggable renderer architecture that allows support for multiple media formats and streaming protocols beyond native HTML5 capabilities.
3

4
## Capabilities
5

6
### Renderer Interface
7

8
All renderers implement a standardized interface for media format support and playback.
9

10
```javascript { .api }
11
interface Renderer {
12
  /** Unique name identifying the renderer */
13
  name: string;
14
  
15
  /** Renderer-specific configuration options */
16
  options: RendererOptions;
17
  
18
  /** Check if renderer can play a specific media type */
19
  canPlayType(type: string): '' | 'maybe' | 'probably';
20
  
21
  /** Create renderer instance for media playback */
22
  create(mediaElement: MediaElement, options: any, mediaFiles: MediaFile[]): RendererInstance;
23
}
24

25
interface RendererOptions {
26
  /** Renderer priority (higher = preferred) */
27
  priority?: number;
28
  
29
  /** Additional renderer-specific options */
30
  [key: string]: any;
31
}
32

33
interface MediaFile {
34
  src: string;
35
  type?: string;
36
}
37

38
interface RendererInstance {
39
  /** Start media playback */
40
  play(): void;
41
  
42
  /** Pause media playback */  
43
  pause(): void;
44
  
45
  /** Load media source */
46
  load(): void;
47
  
48
  /** Set current playback time */
49
  setCurrentTime(time: number): void;
50
  
51
  /** Set volume level */
52
  setVolume(volume: number): void;
53
  
54
  /** Set mute state */
55
  setMuted(muted: boolean): void;
56
  
57
  /** Destroy renderer instance */
58
  destroy(): void;
59
}
60
```
61

62
### Built-in Renderers
63

64
MediaElement.js includes several built-in renderers for common media formats.
65

66
```javascript { .api }
67
/** Available built-in renderers */
68
const builtInRenderers = [
69
  'html5',        // Native HTML5 audio/video
70
  'hls',          // HTTP Live Streaming (requires hls.js)
71
  'dash',         // MPEG-DASH (requires dash.js) 
72
  'youtube',      // YouTube videos
73
  'vimeo',        // Vimeo videos
74
  'dailymotion',  // Dailymotion videos
75
  'soundcloud',   // SoundCloud audio
76
  'facebook',     // Facebook videos
77
  'twitch'        // Twitch streams
78
];
79
```
80

81
### HTML5 Renderer
82

83
The default renderer using native HTML5 audio/video elements.
84

85
```javascript { .api }
86
interface Html5Renderer extends Renderer {
87
  name: 'html5';
88
  
89
  /** Native HTML5 media types supported */
90
  supportedTypes: string[];
91
}
92

93
// Supported media types
94
const html5SupportedTypes = [
95
  'audio/mp3', 'audio/ogg', 'audio/oga', 'audio/wav', 'audio/x-wav',
96
  'audio/wave', 'audio/x-pn-wav', 'audio/mpeg', 'audio/mp4',
97
  'video/mp4', 'video/webm', 'video/ogg', 'video/ogv'
98
];
99
```
100

101
**Usage Examples:**
102

103
```javascript
104
// HTML5 renderer is used automatically for supported formats
105
const player = new MediaElementPlayer('video', {
106
  renderers: ['html5'] // Explicit HTML5 only
107
});
108

109
// Check HTML5 support
110
const canPlay = player.media.canPlayType('video/mp4');
111
console.log('MP4 support:', canPlay); // '', 'maybe', or 'probably'
112
```
113

114
### HLS Renderer
115

116
HTTP Live Streaming renderer for adaptive bitrate streaming.
117

118
```javascript { .api }
119
interface HlsRenderer extends Renderer {
120
  name: 'hls';
121
  
122
  /** HLS-specific configuration options */
123
  options: HlsOptions;
124
}
125

126
interface HlsOptions {
127
  /** Path to hls.js library */
128
  path?: string;
129
  
130
  /** HLS.js configuration object */
131
  hlsConfig?: HlsConfig;
132
  
133
  /** Enable debug logging */
134
  debug?: boolean;
135
}
136

137
interface HlsConfig {
138
  /** Maximum buffer length in seconds */
139
  maxBufferLength?: number;
140
  
141
  /** Start level (-1 for auto) */
142
  startLevel?: number;
143
  
144
  /** Enable ABR (Adaptive Bitrate) */
145
  enableWorker?: boolean;
146
  
147
  /** Additional hls.js options */
148
  [key: string]: any;
149
}
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
// Enable HLS with custom configuration
156
const player = new MediaElementPlayer('video', {
157
  renderers: ['hls', 'html5'],
158
  hls: {
159
    hlsConfig: {
160
      maxBufferLength: 30,
161
      startLevel: -1, // Auto quality
162
      enableWorker: true
163
    },
164
    debug: false
165
  }
166
});
167

168
// HLS playlist URL
169
player.media.src = 'https://example.com/stream.m3u8';
170
```
171

172
### DASH Renderer
173

174
MPEG-DASH renderer for adaptive streaming.
175

176
```javascript { .api }
177
interface DashRenderer extends Renderer {
178
  name: 'dash';
179
  
180
  /** DASH-specific configuration options */
181
  options: DashOptions;
182
}
183

184
interface DashOptions {
185
  /** Path to dash.js library */
186
  path?: string;
187
  
188
  /** DASH.js configuration object */  
189
  dashConfig?: DashConfig;
190
  
191
  /** Enable debug logging */
192
  debug?: boolean;
193
}
194

195
interface DashConfig {
196
  /** Enable debug logging in dash.js */
197
  debug?: boolean;
198
  
199
  /** Initial bitrate for video */
200
  initialBitrateFor?: {
201
    video?: number;
202
    audio?: number;
203
  };
204
  
205
  /** Additional dash.js options */
206
  [key: string]: any;
207
}
208
```
209

210
**Usage Examples:**
211

212
```javascript
213
// Enable DASH renderer
214
const player = new MediaElementPlayer('video', {
215
  renderers: ['dash', 'html5'],
216
  dash: {
217
    dashConfig: {
218
      debug: false,
219
      initialBitrateFor: {
220
        video: 1000000, // 1 Mbps
221
        audio: 128000   // 128 kbps
222
      }
223
    }
224
  }
225
});
226

227
// DASH manifest URL
228
player.media.src = 'https://example.com/stream.mpd';
229
```
230

231
### YouTube Renderer
232

233
Renderer for embedding YouTube videos.
234

235
```javascript { .api }
236
interface YouTubeRenderer extends Renderer {
237
  name: 'youtube';
238
  
239
  /** YouTube-specific options */
240
  options: YouTubeOptions;
241
}
242

243
interface YouTubeOptions {
244
  /** YouTube API key (optional) */
245
  apiKey?: string;
246
  
247
  /** YouTube player parameters */
248
  youtubeParams?: YouTubeParams;
249
}
250

251
interface YouTubeParams {
252
  /** Enable video controls */
253
  controls?: 0 | 1;
254
  
255
  /** Enable related videos */
256
  rel?: 0 | 1;
257
  
258
  /** Video quality preference */
259
  vq?: 'small' | 'medium' | 'large' | 'hd720' | 'hd1080';
260
  
261
  /** Additional YouTube parameters */
262
  [key: string]: any;
263
}
264
```
265

266
**Usage Examples:**
267

268
```javascript
269
// YouTube video player
270
const player = new MediaElementPlayer('video', {
271
  renderers: ['youtube', 'html5'],
272
  youtube: {
273
    youtubeParams: {
274
      controls: 0,  // Hide YouTube controls
275
      rel: 0,       // Disable related videos
276
      vq: 'hd720'   // Prefer 720p quality
277
    }
278
  }
279
});
280

281
// YouTube video URL
282
player.media.src = 'https://www.youtube.com/watch?v=VIDEO_ID';
283
```
284

285
### Vimeo Renderer
286

287
Renderer for embedding Vimeo videos.
288

289
```javascript { .api }
290
interface VimeoRenderer extends Renderer {
291
  name: 'vimeo';
292
  
293
  /** Vimeo-specific options */
294
  options: VimeoOptions;
295
}
296

297
interface VimeoOptions {
298
  /** Vimeo player parameters */
299
  vimeoParams?: VimeoParams;
300
}
301

302
interface VimeoParams {
303
  /** Video portrait display */
304
  portrait?: 0 | 1;
305
  
306
  /** Video title display */
307
  title?: 0 | 1;
308
  
309
  /** Video byline display */
310
  byline?: 0 | 1;
311
  
312
  /** Player color theme */
313
  color?: string;
314
  
315
  /** Additional Vimeo parameters */
316
  [key: string]: any;
317
}
318
```
319

320
**Usage Examples:**
321

322
```javascript
323
// Vimeo video player
324
const player = new MediaElementPlayer('video', {
325
  renderers: ['vimeo', 'html5'],
326
  vimeo: {
327
    vimeoParams: {
328
      portrait: 0,
329
      title: 0,
330
      byline: 0,
331
      color: 'ff0000' // Red theme
332
    }
333
  }
334
});
335

336
// Vimeo video URL
337
player.media.src = 'https://vimeo.com/VIDEO_ID';
338
```
339

340
### Renderer Management
341

342
The renderer system provides methods for managing and selecting renderers.
343

344
```javascript { .api }
345
interface RendererManager {
346
  /** Register a new renderer */
347
  add(renderer: Renderer): void;
348
  
349
  /** Select best renderer for media files */
350
  select(mediaFiles: MediaFile[], renderers?: string[]): Renderer | null;
351
  
352
  /** Get all registered renderers */
353
  getRenderers(): { [name: string]: Renderer };
354
  
355
  /** Set renderer priority order */
356
  order: string[];
357
}
358

359
// Access renderer manager
360
const rendererManager = window.mejs.Renderers;
361
```
362

363
**Usage Examples:**
364

365
```javascript
366
// Check available renderers
367
const renderers = window.mejs.Renderers.getRenderers();
368
console.log('Available renderers:', Object.keys(renderers));
369

370
// Set renderer priority
371
window.mejs.Renderers.order = ['hls', 'dash', 'html5', 'youtube'];
372

373
// Select renderer for specific media
374
const mediaFiles = [
375
  { src: 'video.m3u8', type: 'application/vnd.apple.mpegurl' },
376
  { src: 'video.mp4', type: 'video/mp4' }
377
];
378
const selectedRenderer = window.mejs.Renderers.select(mediaFiles);
379
console.log('Selected renderer:', selectedRenderer?.name);
380
```
381

382
### Custom Renderer Development
383

384
Create custom renderers for specialized media formats or services.
385

386
```javascript { .api }
387
/**
388
 * Custom renderer implementation example
389
 */
390
const CustomRenderer = {
391
  name: 'custom',
392
  
393
  options: {
394
    priority: 10
395
  },
396
  
397
  /**
398
   * Check if renderer supports media type
399
   */
400
  canPlayType(type) {
401
    return type === 'custom/format' ? 'probably' : '';
402
  },
403
  
404
  /**
405
   * Create renderer instance
406
   */
407
  create(mediaElement, options, mediaFiles) {
408
    const customInstance = {
409
      // Implement required methods
410
      play() {
411
        console.log('Custom renderer: play');
412
      },
413
      
414
      pause() {
415
        console.log('Custom renderer: pause');
416
      },
417
      
418
      load() {
419
        console.log('Custom renderer: load');
420
      },
421
      
422
      setCurrentTime(time) {
423
        console.log('Custom renderer: setCurrentTime', time);
424
      },
425
      
426
      setVolume(volume) {
427
        console.log('Custom renderer: setVolume', volume);
428
      },
429
      
430
      setMuted(muted) {
431
        console.log('Custom renderer: setMuted', muted);
432
      },
433
      
434
      destroy() {
435
        console.log('Custom renderer: destroy');
436
      }
437
    };
438
    
439
    return customInstance;
440
  }
441
};
442

443
// Register custom renderer
444
window.mejs.Renderers.add(CustomRenderer);
445
```
446

447
### Renderer Configuration
448

449
Configure renderers globally or per-player instance.
450

451
```javascript { .api }
452
// Global renderer configuration
453
window.mejs.HlsRenderer = {
454
  options: {
455
    hlsConfig: {
456
      maxBufferLength: 60,
457
      enableWorker: true
458
    }
459
  }
460
};
461

462
// Per-instance renderer configuration
463
const player = new MediaElementPlayer('video', {
464
  renderers: ['hls', 'html5'],
465
  hls: {
466
    hlsConfig: {
467
      startLevel: 2, // Start at specific quality level
468
      maxBufferLength: 30
469
    },
470
    debug: true
471
  }
472
});
473
```
474

475
### Renderer Events
476

477
Renderers can dispatch custom events for advanced integration.
478

479
```javascript { .api }
480
// Listen for renderer-specific events
481
const player = new MediaElementPlayer('video', {
482
  success: (mediaElement) => {
483
    // HLS-specific events (when using HLS renderer)
484
    mediaElement.addEventListener('hlsManifestParsed', (e) => {
485
      console.log('HLS manifest loaded');
486
    });
487
    
488
    mediaElement.addEventListener('hlsLevelSwitched', (e) => {
489
      console.log('Quality level changed');
490
    });
491
    
492
    // DASH-specific events (when using DASH renderer)
493
    mediaElement.addEventListener('dashQualityChanged', (e) => {
494
      console.log('DASH quality changed');
495
    });
496
  }
497
});
498
```