0
# MediaElement.js
1

2
MediaElement.js is a comprehensive HTML5 video and audio player library that provides a unified interface across different browsers and devices. It offers both a core media wrapper and a complete player with customizable controls, supporting IE11+, MS Edge, Chrome, Firefox, Safari, iOS 8+ and Android 4.0+.
3

4
## Package Information
5

6
- **Package Name**: mediaelement
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mediaelement`
10

11
## Core Imports
12

13
```javascript
14
import MediaElementPlayer from 'mediaelement';
15

16
// Or import specific components
17
import { MediaElement, MediaElementPlayer } from 'mediaelement';
18
```
19

20
For CommonJS:
21

22
```javascript
23
const MediaElementPlayer = require('mediaelement');
24

25
// Or destructure
26
const { MediaElement, MediaElementPlayer } = require('mediaelement');
27
```
28

29
For CDN/Browser:
30

31
```html
32
<script src="https://cdn.jsdelivr.net/npm/mediaelement@7.0.7/build/mediaelement-and-player.min.js"></script>
33
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mediaelement@7.0.7/build/mediaelementplayer.min.css">
34
```
35

36
## Basic Usage
37

38
```javascript
39
import MediaElementPlayer from 'mediaelement';
40

41
// Initialize player on an existing video/audio element
42
const player = new MediaElementPlayer('my-video', {
43
  // Configuration options
44
  stretching: 'responsive',
45
  features: ['playpause', 'progress', 'current', 'duration', 'volume', 'fullscreen'],
46
  success: (mediaElement, originalNode, instance) => {
47
    console.log('Player initialized successfully');
48
  }
49
});
50

51
// Basic playback control
52
player.play();
53
player.pause();
54
player.setCurrentTime(30);
55
player.setVolume(0.8);
56
```
57

58
## Architecture
59

60
MediaElement.js is built around several key components:
61

62
- **MediaElement**: Core media wrapper that provides HTML5-compatible API for various media formats
63
- **MediaElementPlayer**: Complete player with controls, theming, and advanced features
64
- **Renderer System**: Pluggable architecture supporting HTML5, HLS, DASH, YouTube, Vimeo, and more
65
- **Feature System**: Modular controls system allowing custom player features
66
- **Configuration System**: Extensive options for customizing player behavior and appearance
67
- **Utility Functions**: Helper methods for DOM manipulation, media detection, and time formatting
68

69
## Capabilities
70

71
### Core Media Element
72

73
Low-level media element wrapper providing HTML5-compatible API with renderer switching capabilities. Essential for custom player implementations.
74

75
```javascript { .api }
76
class MediaElement {
77
  constructor(idOrNode, options, sources);
78
  
79
  // HTML5 MediaElement compatible properties
80
  src: string;
81
  currentTime: number;
82
  duration: number;
83
  volume: number;
84
  muted: boolean;
85
  paused: boolean;
86
  ended: boolean;
87
  
88
  // HTML5 MediaElement compatible methods
89
  play(): Promise<void> | void;
90
  pause(): void;
91
  load(): void;
92
  canPlayType(type: string): string;
93
}
94
```
95

96
[Core Media Element](./core-media-element.md)
97

98
### Media Player
99

100
Complete media player with controls, theming, and extensive configuration options. Main class for most use cases.
101

102
```javascript { .api }
103
class MediaElementPlayer {
104
  constructor(node, options);
105
  
106
  // Player control methods
107
  play(): void;
108
  pause(): void;
109
  stop(): void;
110
  setCurrentTime(time: number): void;
111
  setVolume(volume: number): void;
112
  setMuted(muted: boolean): void;
113
  enterFullScreen(): void;
114
  exitFullScreen(): void;
115
  
116
  // Properties
117
  media: MediaElement;
118
  options: PlayerOptions;
119
  controls: HTMLElement;
120
  container: HTMLElement;
121
}
122
```
123

124
[Media Player](./media-player.md)
125

126
### Configuration System
127

128
Comprehensive configuration options for customizing player behavior, appearance, and features.
129

130
```javascript { .api }
131
interface PlayerOptions {
132
  // Media and poster
133
  poster?: string;
134
  showPosterWhenEnded?: boolean;
135
  showPosterWhenPaused?: boolean;
136
  
137
  // Dimensions
138
  defaultVideoWidth?: number;
139
  defaultVideoHeight?: number;
140
  videoWidth?: number;
141
  videoHeight?: number;
142
  
143
  // Features and controls
144
  features?: string[];
145
  alwaysShowControls?: boolean;
146
  hideVideoControlsOnLoad?: boolean;
147
  
148
  // Advanced options
149
  stretching?: 'auto' | 'fill' | 'responsive' | 'none';
150
  enableKeyboard?: boolean;
151
  pauseOtherPlayers?: boolean;
152
}
153
```
154

155
[Configuration](./configuration.md)
156

157
### Renderer System
158

159
Pluggable renderer architecture supporting multiple media formats and streaming protocols.
160

161
```javascript { .api }
162
interface Renderer {
163
  name: string;
164
  options: RendererOptions;
165
  canPlayType(type: string): '' | 'maybe' | 'probably';
166
  create(mediaElement: MediaElement, options: any, mediaFiles: any[]): any;
167
}
168

169
// Available renderers
170
const renderers = ['html5', 'hls', 'dash', 'youtube', 'vimeo', 'dailymotion', 'soundcloud'];
171
```
172

173
[Renderer System](./renderer-system.md)
174

175
### Utility Functions
176

177
Helper functions for DOM manipulation, media type detection, time formatting, and browser feature detection.
178

179
```javascript { .api }
180
// DOM utilities
181
function hasClass(el: HTMLElement, className: string): boolean;
182
function addClass(el: HTMLElement, className: string): void;
183
function removeClass(el: HTMLElement, className: string): void;
184

185
// Media utilities
186
function getTypeFromFile(url: string): string;
187
function formatType(url: string, type: string): string;
188

189
// Time utilities
190
function secondsToTimeCode(time: number, forceHours: boolean, showFrameCount: boolean, fps: number): string;
191
```
192

193
[Utility Functions](./utility-functions.md)
194

195
### Feature System
196

197
Modular system for adding custom controls and player features with standardized lifecycle methods.
198

199
```javascript { .api }
200
// Feature interface pattern
201
interface Feature {
202
  build(player: MediaElementPlayer, controls: HTMLElement, layers: HTMLElement, media: MediaElement): void;
203
  clean?(player: MediaElementPlayer, layers: HTMLElement, controls: HTMLElement, media: MediaElement): void;
204
}
205

206
// Built-in features
207
const features = ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen'];
208
```
209

210
[Feature System](./feature-system.md)
211

212
## Global Namespace
213

214
```javascript { .api }
215
// Global mejs namespace
216
interface MejsGlobal {
217
  version: string;
218
  MediaElement: typeof MediaElement;
219
  MediaElementPlayer: typeof MediaElementPlayer;
220
  html5media: Html5MediaConfig;
221
  Features: FeatureDetection;
222
  Utils: UtilityFunctions;
223
  i18n: Internationalization;
224
  Renderers: RendererManager;
225
}
226

227
// Available as window.mejs
228
declare global {
229
  interface Window {
230
    mejs: MejsGlobal;
231
    MediaElement: typeof MediaElement;
232
    MediaElementPlayer: typeof MediaElementPlayer;
233
  }
234
}
235
```