0
# Core Media Element
1

2
The MediaElement class is the foundation of MediaElement.js, providing a low-level wrapper that mimics the HTML5 MediaElement API while supporting multiple renderers and media formats.
3

4
## Capabilities
5

6
### MediaElement Constructor
7

8
Creates a new MediaElement instance that wraps an existing HTML media element or creates a new one.
9

10
```javascript { .api }
11
/**
12
 * Create a new MediaElement instance
13
 * @param idOrNode - Element ID string or DOM node to wrap
14
 * @param options - Configuration options for the media element
15
 * @param sources - Optional array of media source objects
16
 */
17
constructor(idOrNode: string | HTMLElement, options?: MediaElementOptions, sources?: MediaSource[]);
18

19
interface MediaElementOptions {
20
  /** List of preferred renderers in priority order */
21
  renderers?: string[];
22
  /** HTML element type for the container */
23
  fakeNodeName?: string;
24
  /** Path to the icon sprite file */
25
  iconSprite?: string;
26
}
27

28
interface MediaSource {
29
  src: string;
30
  type?: string;
31
}
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
import { MediaElement } from 'mediaelement';
38

39
// Wrap existing video element
40
const mediaElement = new MediaElement('my-video');
41

42
// Create with options
43
const mediaElement = new MediaElement('my-audio', {
44
  renderers: ['html5', 'hls'],
45
  iconSprite: 'assets/icons.svg'
46
});
47

48
// Create with sources
49
const mediaElement = new MediaElement('player', {}, [
50
  { src: 'video.mp4', type: 'video/mp4' },
51
  { src: 'video.webm', type: 'video/webm' }
52
]);
53
```
54

55
### HTML5 MediaElement Properties
56

57
All standard HTML5 MediaElement properties are supported with cross-renderer compatibility.
58

59
```javascript { .api }
60
/** Current media source URL */
61
src: string;
62

63
/** Current playback position in seconds */
64
currentTime: number;
65

66
/** Total duration of media in seconds (read-only) */
67
readonly duration: number;
68

69
/** Volume level between 0.0 and 1.0 */
70
volume: number;
71

72
/** Whether audio is muted */
73
muted: boolean;
74

75
/** Whether media is currently paused (read-only) */
76
readonly paused: boolean;
77

78
/** Whether media has finished playing (read-only) */
79
readonly ended: boolean;
80

81
/** Current ready state of the media (read-only) */
82
readonly readyState: number;
83

84
/** Current network state (read-only) */
85
readonly networkState: number;
86

87
/** Whether media is currently seeking (read-only) */
88
readonly seeking: boolean;
89

90
/** TimeRanges object representing buffered portions (read-only) */
91
readonly buffered: TimeRanges;
92

93
/** TimeRanges object representing seekable portions (read-only) */
94
readonly seekable: TimeRanges;
95

96
/** Current playback rate (1.0 = normal speed) */
97
playbackRate: number;
98

99
/** Default playback rate */
100
defaultPlaybackRate: number;
101

102
/** Whether to automatically start playback */
103
autoplay: boolean;
104

105
/** Whether to loop playback */
106
loop: boolean;
107

108
/** Preload behavior ('none', 'metadata', 'auto') */
109
preload: string;
110

111
/** Whether to show default controls */
112
controls: boolean;
113
```
114

115
### HTML5 MediaElement Methods
116

117
Standard HTML5 MediaElement methods with renderer abstraction.
118

119
```javascript { .api }
120
/**
121
 * Begin playback of the media
122
 * @returns Promise that resolves when playback starts (modern browsers) or void
123
 */
124
play(): Promise<void> | void;
125

126
/**
127
 * Pause media playback
128
 */
129
pause(): void;
130

131
/**
132
 * Load the media resource
133
 */
134
load(): void;
135

136
/**
137
 * Check if the media element can play a given MIME type
138
 * @param type - MIME type string to check
139
 * @returns Support level: '' (no), 'maybe', or 'probably'
140
 */
141
canPlayType(type: string): '' | 'maybe' | 'probably';
142
```
143

144
### MediaElement-Specific Methods
145

146
Additional methods specific to MediaElement.js functionality.
147

148
```javascript { .api }
149
/**
150
 * Switch to a different renderer
151
 * @param rendererName - Name of the renderer to switch to
152
 * @param mediaFiles - Array of media source objects
153
 * @returns Whether the renderer switch was successful
154
 */
155
changeRenderer(rendererName: string, mediaFiles: MediaSource[]): boolean;
156

157
/**
158
 * Set the dimensions of the media element
159
 * @param width - Width in pixels
160
 * @param height - Height in pixels
161
 */
162
setSize(width: number, height: number): void;
163

164
/**
165
 * Generate and dispatch an error event
166
 * @param message - Error message
167
 * @param urlList - List of URLs that failed to load
168
 */
169
generateError(message: string, urlList: string[]): void;
170

171
/**
172
 * Destroy the MediaElement instance and restore original element
173
 */
174
destroy(): void;
175
```
176

177
**Usage Examples:**
178

179
```javascript
180
// Basic playback control
181
const mediaElement = new MediaElement('video');
182

183
await mediaElement.play();
184
mediaElement.pause();
185

186
// Set properties
187
mediaElement.volume = 0.5;
188
mediaElement.currentTime = 30;
189
mediaElement.muted = true;
190

191
// Check format support
192
const canPlay = mediaElement.canPlayType('video/mp4');
193
if (canPlay === 'probably') {
194
  mediaElement.src = 'video.mp4';
195
}
196

197
// Switch renderer for streaming content
198
const switched = mediaElement.changeRenderer('hls', [
199
  { src: 'stream.m3u8', type: 'application/vnd.apple.mpegurl' }
200
]);
201

202
// Resize element
203
mediaElement.setSize(640, 360);
204

205
// Clean up
206
mediaElement.destroy();
207
```
208

209
### Events
210

211
MediaElement supports all standard HTML5 media events plus custom events.
212

213
```javascript { .api }
214
// Standard HTML5 events
215
const mediaEvents = [
216
  'loadstart', 'durationchange', 'loadedmetadata', 'loadeddata',
217
  'progress', 'canplay', 'canplaythrough', 'suspend', 'abort',
218
  'error', 'emptied', 'stalled', 'play', 'playing', 'pause',
219
  'waiting', 'seeking', 'seeked', 'timeupdate', 'ended',
220
  'ratechange', 'volumechange'
221
];
222

223
// Custom MediaElement events
224
const customEvents = [
225
  'rendererready'  // Fired when renderer is initialized and ready
226
];
227
```
228

229
**Event Handling Examples:**
230

231
```javascript
232
const mediaElement = new MediaElement('video');
233

234
// Listen for standard events
235
mediaElement.addEventListener('play', () => {
236
  console.log('Playback started');
237
});
238

239
mediaElement.addEventListener('timeupdate', () => {
240
  console.log(`Current time: ${mediaElement.currentTime}`);
241
});
242

243
mediaElement.addEventListener('error', (e) => {
244
  console.error('Media error:', e);
245
});
246

247
// Listen for custom events
248
mediaElement.addEventListener('rendererready', () => {
249
  console.log('Renderer is ready');
250
});
251
```
252

253
## Error Handling
254

255
MediaElement provides comprehensive error handling with detailed error information.
256

257
```javascript { .api }
258
interface MediaError {
259
  /** Error code (1-4 following HTML5 spec) */
260
  code: number;
261
  /** Human-readable error message */
262
  message: string;
263
}
264

265
// Error codes
266
const MEDIA_ERR_ABORTED = 1;      // Media loading aborted
267
const MEDIA_ERR_NETWORK = 2;      // Network error
268
const MEDIA_ERR_DECODE = 3;       // Media decode error
269
const MEDIA_ERR_SRC_NOT_SUPPORTED = 4;  // Media format not supported
270
```
271

272
**Error Handling Example:**
273

274
```javascript
275
mediaElement.addEventListener('error', () => {
276
  const error = mediaElement.error;
277
  switch (error.code) {
278
    case 1:
279
      console.log('Media loading was aborted');
280
      break;
281
    case 2:
282
      console.log('Network error occurred');
283
      break;
284
    case 3:
285
      console.log('Media decode error');
286
      break;
287
    case 4:
288
      console.log('Media format not supported');
289
      break;
290
  }
291
});
292
```