tessl/npm-mediaelement

HTML5 video and audio player with unified cross-browser interface and extensive customization options

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Media Player

Name: tessl/npm-mediaelement
Author: tessl

The MediaElementPlayer class provides a complete media player with customizable controls, theming, and extensive configuration options. It's the main class used for most MediaElement.js implementations.

Capabilities

MediaElementPlayer Constructor

Creates a complete media player with controls and UI around an HTML media element.

/**
 * Create a new MediaElementPlayer instance
 * @param node - Element ID string or DOM node to enhance
 * @param options - Player configuration options
 */
constructor(node: string | HTMLElement, options?: PlayerOptions);

interface PlayerOptions {
  // Media and poster configuration
  poster?: string;
  showPosterWhenEnded?: boolean;
  showPosterWhenPaused?: boolean;
  
  // Dimension configuration
  defaultVideoWidth?: number;
  defaultVideoHeight?: number;
  defaultAudioWidth?: number;
  defaultAudioHeight?: number;
  videoWidth?: number;
  videoHeight?: number;
  setDimensions?: boolean;
  
  // Behavior configuration
  loop?: boolean;
  autoRewind?: boolean;
  enableAutosize?: boolean;
  clickToPlayPause?: boolean;
  
  // Controls and UI configuration
  alwaysShowControls?: boolean;
  hideVideoControlsOnLoad?: boolean;
  hideVideoControlsOnPause?: boolean;
  controlsTimeoutDefault?: number;
  controlsTimeoutMouseEnter?: number;
  controlsTimeoutMouseLeave?: number;
  features?: string[];
  useDefaultControls?: boolean;
  classPrefix?: string;
  
  // Advanced configuration
  stretching?: 'auto' | 'fill' | 'responsive' | 'none';
  pauseOtherPlayers?: boolean;
  enableKeyboard?: boolean;
  keyActions?: KeyAction[];
  
  // Callbacks
  success?: SuccessCallback;
  error?: ErrorCallback;
}

interface SuccessCallback {
  (mediaElement: MediaElement, originalNode: HTMLElement, instance: MediaElementPlayer): void;
}

interface ErrorCallback {
  (mediaElement: MediaElement, originalNode: HTMLElement): void;
}

Usage Examples:

import MediaElementPlayer from 'mediaelement';

// Basic player initialization
const player = new MediaElementPlayer('my-video');

// Player with configuration
const player = new MediaElementPlayer('my-video', {
  stretching: 'responsive',
  features: ['playpause', 'progress', 'current', 'duration', 'volume', 'fullscreen'],
  alwaysShowControls: false,
  controlsTimeoutDefault: 3000,
  success: (mediaElement, originalNode, instance) => {
    console.log('Player ready');
  },
  error: (mediaElement, originalNode) => {
    console.error('Player initialization failed');
  }
});

// Audio player with specific dimensions
const audioPlayer = new MediaElementPlayer('my-audio', {
  defaultAudioWidth: 500,
  defaultAudioHeight: 50,
  features: ['playpause', 'progress', 'current', 'duration', 'volume']
});

Player Control Methods

Methods for controlling playback and player state.

/**
 * Start media playback
 */
play(): void;

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

/**
 * Stop playback and reset to beginning
 */
stop(): void;

/**
 * Set current playback position
 * @param time - Time in seconds
 */
setCurrentTime(time: number): void;

/**
 * Set volume level
 * @param volume - Volume between 0.0 and 1.0
 */
setVolume(volume: number): void;

/**
 * Set mute state
 * @param muted - Whether to mute audio
 */
setMuted(muted: boolean): void;

/**
 * Enter fullscreen mode
 */
enterFullScreen(): void;

/**
 * Exit fullscreen mode
 */
exitFullScreen(): void;

/**
 * Remove player and restore original element
 */
remove(): void;

/**
 * Destroy player instance completely
 */
destroy(): void;

Usage Examples:

const player = new MediaElementPlayer('video');

// Playback control
player.play();
player.pause();
player.stop();

// Seek to specific time
player.setCurrentTime(120); // 2 minutes

// Volume control
player.setVolume(0.8);
player.setMuted(true);

// Fullscreen
player.enterFullScreen();
player.exitFullScreen();

// Cleanup
player.destroy();

Player Properties

Access to underlying media element and player components.

/** The underlying MediaElement instance */
media: MediaElement;

/** Player configuration options */
options: PlayerOptions;

/** Container element wrapping the entire player */
container: HTMLElement;

/** Controls container element */
controls: HTMLElement;

/** Layers container for overlays */
layers: HTMLElement;

/** Original media element node */
node: HTMLElement;

/** Whether player is currently in fullscreen */
isFullScreen: boolean;

/** Whether player has been built and initialized */
built: boolean;

/** Unique player ID */
id: string;

Usage Examples:

const player = new MediaElementPlayer('video');

// Access underlying MediaElement
console.log('Duration:', player.media.duration);
console.log('Current time:', player.media.currentTime);

// Access DOM elements
player.container.style.border = '2px solid red';
player.controls.style.backgroundColor = 'rgba(0,0,0,0.8)';

// Check player state
if (player.isFullScreen) {
  console.log('Player is in fullscreen mode');
}

Control Features

Built-in control features that can be enabled/disabled through configuration.

interface ControlFeatures {
  /** Play/pause toggle button */
  playpause: Feature;
  /** Current time display */
  current: Feature;
  /** Progress bar with scrubbing */
  progress: Feature;
  /** Total duration display */
  duration: Feature;
  /** Volume control with slider */
  volume: Feature;
  /** Fullscreen toggle button */
  fullscreen: Feature;
  /** Track/subtitle controls */
  tracks: Feature;
}

// Default feature set
const defaultFeatures = ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen'];

Feature Configuration Examples:

// Minimal controls
const player = new MediaElementPlayer('video', {
  features: ['playpause', 'progress']
});

// Full feature set
const player = new MediaElementPlayer('video', {
  features: ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen']
});

// Custom feature order
const player = new MediaElementPlayer('video', {
  features: ['playpause', 'volume', 'progress', 'fullscreen']
});

Keyboard Controls

Built-in keyboard shortcuts for player control.

interface KeyAction {
  /** Key codes that trigger this action */
  keys: number[];
  /** Action to perform */
  action: (player: MediaElementPlayer, media: MediaElement) => void;
}

// Default keyboard shortcuts
const defaultKeyActions = [
  { keys: [32], action: 'play_pause' },     // Spacebar
  { keys: [38], action: 'volume_up' },      // Up arrow
  { keys: [40], action: 'volume_down' },    // Down arrow
  { keys: [37], action: 'seek_backward' },  // Left arrow
  { keys: [39], action: 'seek_forward' },   // Right arrow
  { keys: [70], action: 'fullscreen' },     // F key
  { keys: [77], action: 'mute' }            // M key
];

Custom Keyboard Actions:

const player = new MediaElementPlayer('video', {
  enableKeyboard: true,
  keyActions: [
    {
      keys: [32], // Spacebar
      action: (player, media) => {
        if (media.paused) {
          player.play();
        } else {
          player.pause();
        }
      }
    },
    {
      keys: [82], // R key
      action: (player, media) => {
        media.currentTime = 0; // Restart
      }
    }
  ]
});

Events

Player-specific events in addition to standard media events.

// Player lifecycle events
const playerEvents = [
  'controlsready',    // Controls have been built
  'controlsshown',    // Controls became visible
  'controlshidden',   // Controls were hidden
  'resize'            // Player was resized
];

Event Handling Examples:

const player = new MediaElementPlayer('video', {
  success: (mediaElement, originalNode, instance) => {
    // Listen for player events
    instance.addEventListener('controlsready', () => {
      console.log('Controls are ready');
    });
    
    instance.addEventListener('controlsshown', () => {
      console.log('Controls shown');
    });
    
    instance.addEventListener('controlshidden', () => {
      console.log('Controls hidden');
    });
    
    // Listen for media events through the media element
    mediaElement.addEventListener('play', () => {
      console.log('Playback started');
    });
    
    mediaElement.addEventListener('ended', () => {
      console.log('Playback finished');
    });
  }
});

Styling and Theming

MediaElement.js uses CSS classes with configurable prefixes for complete visual customization.

// Default CSS class structure (with 'mejs__' prefix)
interface CSSClasses {
  container: 'mejs__container';
  inner: 'mejs__inner'; 
  mediaelement: 'mejs__mediaelement';
  layers: 'mejs__layers';
  controls: 'mejs__controls';
  button: 'mejs__button';
  playpauseButton: 'mejs__playpause-button';
  timeRail: 'mejs__time-rail';
  volumeButton: 'mejs__volume-button';
  fullscreenButton: 'mejs__fullscreen-button';
}

Custom Styling Example:

// Use custom CSS prefix
const player = new MediaElementPlayer('video', {
  classPrefix: 'myplayer-',
  features: ['playpause', 'progress', 'volume']
});

// Results in classes like:
// .myplayer-container
// .myplayer-controls  
// .myplayer-button
// etc.

/* Custom player styling */
.mejs__container {
  background: #000;
  border-radius: 8px;
}

.mejs__controls {
  background: linear-gradient(transparent, rgba(0,0,0,0.8));
  padding: 10px;
}

.mejs__button {
  color: #fff;
  border: none;
  padding: 8px;
}

.mejs__button:hover {
  background: rgba(255,255,255,0.2);
}