Core Media Element

/**
 * Create a new MediaElement instance
 * @param idOrNode - Element ID string or DOM node to wrap
 * @param options - Configuration options for the media element
 * @param sources - Optional array of media source objects
 */
constructor(idOrNode: string | HTMLElement, options?: MediaElementOptions, sources?: MediaSource[]);

interface MediaElementOptions {
  /** List of preferred renderers in priority order */
  renderers?: string[];
  /** HTML element type for the container */
  fakeNodeName?: string;
  /** Path to the icon sprite file */
  iconSprite?: string;
}

interface MediaSource {
  src: string;
  type?: string;
}

import { MediaElement } from 'mediaelement';

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

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

// Create with sources
const mediaElement = new MediaElement('player', {}, [
  { src: 'video.mp4', type: 'video/mp4' },
  { src: 'video.webm', type: 'video/webm' }
]);

/** Current media source URL */
src: string;

/** Current playback position in seconds */
currentTime: number;

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

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

/** Whether audio is muted */
muted: boolean;

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

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

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

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

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

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

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

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

/** Default playback rate */
defaultPlaybackRate: number;

/** Whether to automatically start playback */
autoplay: boolean;

/** Whether to loop playback */
loop: boolean;

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

/** Whether to show default controls */
controls: boolean;

/**
 * Begin playback of the media
 * @returns Promise that resolves when playback starts (modern browsers) or void
 */
play(): Promise<void> | void;

/**
 * Pause media playback
 */
pause(): void;

/**
 * Load the media resource
 */
load(): void;

/**
 * Check if the media element can play a given MIME type
 * @param type - MIME type string to check
 * @returns Support level: '' (no), 'maybe', or 'probably'
 */
canPlayType(type: string): '' | 'maybe' | 'probably';

/**
 * Switch to a different renderer
 * @param rendererName - Name of the renderer to switch to
 * @param mediaFiles - Array of media source objects
 * @returns Whether the renderer switch was successful
 */
changeRenderer(rendererName: string, mediaFiles: MediaSource[]): boolean;

/**
 * Set the dimensions of the media element
 * @param width - Width in pixels
 * @param height - Height in pixels
 */
setSize(width: number, height: number): void;

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

/**
 * Destroy the MediaElement instance and restore original element
 */
destroy(): void;

// Basic playback control
const mediaElement = new MediaElement('video');

await mediaElement.play();
mediaElement.pause();

// Set properties
mediaElement.volume = 0.5;
mediaElement.currentTime = 30;
mediaElement.muted = true;

// Check format support
const canPlay = mediaElement.canPlayType('video/mp4');
if (canPlay === 'probably') {
  mediaElement.src = 'video.mp4';
}

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

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

// Clean up
mediaElement.destroy();

// Standard HTML5 events
const mediaEvents = [
  'loadstart', 'durationchange', 'loadedmetadata', 'loadeddata',
  'progress', 'canplay', 'canplaythrough', 'suspend', 'abort',
  'error', 'emptied', 'stalled', 'play', 'playing', 'pause',
  'waiting', 'seeking', 'seeked', 'timeupdate', 'ended',
  'ratechange', 'volumechange'
];

// Custom MediaElement events
const customEvents = [
  'rendererready'  // Fired when renderer is initialized and ready
];

const mediaElement = new MediaElement('video');

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

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

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

// Listen for custom events
mediaElement.addEventListener('rendererready', () => {
  console.log('Renderer is ready');
});

interface MediaError {
  /** Error code (1-4 following HTML5 spec) */
  code: number;
  /** Human-readable error message */
  message: string;
}

// Error codes
const MEDIA_ERR_ABORTED = 1;      // Media loading aborted
const MEDIA_ERR_NETWORK = 2;      // Network error
const MEDIA_ERR_DECODE = 3;       // Media decode error
const MEDIA_ERR_SRC_NOT_SUPPORTED = 4;  // Media format not supported

mediaElement.addEventListener('error', () => {
  const error = mediaElement.error;
  switch (error.code) {
    case 1:
      console.log('Media loading was aborted');
      break;
    case 2:
      console.log('Network error occurred');
      break;
    case 3:
      console.log('Media decode error');
      break;
    case 4:
      console.log('Media format not supported');
      break;
  }
});