CtrlK
BlogDocsLog inGet started
Tessl Logo

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

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration.mddocs/

Configuration

MediaElement.js provides extensive configuration options to customize player behavior, appearance, and functionality through the PlayerOptions interface.

Capabilities

Media and Poster Configuration

Options for controlling poster images and media display behavior.

interface PosterOptions {
  /** URL to poster image */
  poster?: string;
  
  /** Show poster when media reaches end */
  showPosterWhenEnded?: boolean;
  
  /** Show poster when media is paused */
  showPosterWhenPaused?: boolean;
}

Usage Examples:

const player = new MediaElementPlayer('video', {
  poster: 'https://example.com/poster.jpg',
  showPosterWhenEnded: true,
  showPosterWhenPaused: false
});

Dimension Configuration

Control player and media element sizing behavior.

interface DimensionOptions {
  /** Default video width when not specified in HTML */
  defaultVideoWidth?: number; // Default: 480
  
  /** Default video height when not specified in HTML */
  defaultVideoHeight?: number; // Default: 270
  
  /** Default audio player width */
  defaultAudioWidth?: number; // Default: 400
  
  /** Default audio player height */
  defaultAudioHeight?: number; // Default: 40
  
  /** Override video width (ignores HTML width attribute) */
  videoWidth?: number; // Default: -1 (use HTML or default)
  
  /** Override video height (ignores HTML height attribute) */
  videoHeight?: number; // Default: -1 (use HTML or default)
  
  /** Whether to set dimensions programmatically */
  setDimensions?: boolean; // Default: true
  
  /** Enable automatic resizing to match media dimensions */
  enableAutosize?: boolean; // Default: true
}

Usage Examples:

// Fixed size video player
const player = new MediaElementPlayer('video', {
  videoWidth: 800,
  videoHeight: 600,
  enableAutosize: false
});

// Responsive audio player
const audioPlayer = new MediaElementPlayer('audio', {
  defaultAudioWidth: 300,
  defaultAudioHeight: 60,
  setDimensions: true
});

// Let media determine size
const adaptivePlayer = new MediaElementPlayer('video', {
  enableAutosize: true,
  setDimensions: false
});

Behavior Configuration

Options controlling playback behavior and user interaction.

interface BehaviorOptions {
  /** Enable looped playback */
  loop?: boolean; // Default: false
  
  /** Rewind to beginning when media ends */
  autoRewind?: boolean; // Default: true
  
  /** Allow click on media to play/pause */
  clickToPlayPause?: boolean; // Default: true
  
  /** Pause other players when this one starts */
  pauseOtherPlayers?: boolean; // Default: true
}

Usage Examples:

const player = new MediaElementPlayer('video', {
  loop: true,
  autoRewind: false,
  clickToPlayPause: true,
  pauseOtherPlayers: false
});

Controls and UI Configuration

Comprehensive options for customizing player controls appearance and behavior.

interface ControlsOptions {
  /** Always show controls (no auto-hide) */
  alwaysShowControls?: boolean; // Default: false
  
  /** Hide controls initially on video load */
  hideVideoControlsOnLoad?: boolean; // Default: false
  
  /** Hide controls when video is paused */
  hideVideoControlsOnPause?: boolean; // Default: false
  
  /** Default timeout before hiding controls (ms) */
  controlsTimeoutDefault?: number; // Default: 1500
  
  /** Timeout when mouse enters player (ms) */
  controlsTimeoutMouseEnter?: number; // Default: 2500
  
  /** Timeout when mouse leaves player (ms) */
  controlsTimeoutMouseLeave?: number; // Default: 1000
  
  /** List of features/controls to include */
  features?: string[]; // Default: ['playpause', 'current', 'progress', 'duration', 'tracks', 'volume', 'fullscreen']
  
  /** Use the default feature set */
  useDefaultControls?: boolean; // Default: false
  
  /** CSS class prefix for player elements */
  classPrefix?: string; // Default: 'mejs__'
}

Usage Examples:

// Always visible controls
const player = new MediaElementPlayer('video', {
  alwaysShowControls: true,
  classPrefix: 'myplayer-'
});

// Minimal controls that hide quickly
const minimalPlayer = new MediaElementPlayer('video', {
  features: ['playpause', 'progress'],
  controlsTimeoutDefault: 1000,
  hideVideoControlsOnLoad: true
});

// Custom control timing
const customPlayer = new MediaElementPlayer('video', {
  controlsTimeoutDefault: 3000,
  controlsTimeoutMouseEnter: 5000,
  controlsTimeoutMouseLeave: 500
});

Video Stretching Configuration

Control how video content is scaled and positioned within the player.

interface StretchingOptions {
  /** Video scaling mode */
  stretching?: 'auto' | 'fill' | 'responsive' | 'none'; // Default: 'auto'
}

// Stretching modes explained:
// 'auto' - Maintain aspect ratio, fit within container
// 'fill' - Stretch to fill container exactly (may distort)
// 'responsive' - Responsive scaling maintaining aspect ratio  
// 'none' - Use original video dimensions

Usage Examples:

// Responsive video that maintains aspect ratio
const responsivePlayer = new MediaElementPlayer('video', {
  stretching: 'responsive'
});

// Fill container exactly (may distort video)
const fillPlayer = new MediaElementPlayer('video', {
  stretching: 'fill'
});

// Use original video size
const originalPlayer = new MediaElementPlayer('video', {
  stretching: 'none'
});

Platform-Specific Configuration

Options for controlling behavior on specific platforms and devices.

interface PlatformOptions {
  /** Use native controls on iPad */
  iPadUseNativeControls?: boolean; // Default: false
  
  /** Use native controls on iPhone */
  iPhoneUseNativeControls?: boolean; // Default: false
  
  /** Use native controls on Android */
  AndroidUseNativeControls?: boolean; // Default: false
}

Usage Examples:

// Use native controls on mobile devices
const mobilePlayer = new MediaElementPlayer('video', {
  iPadUseNativeControls: true,
  iPhoneUseNativeControls: true,
  AndroidUseNativeControls: true
});

Keyboard and Accessibility Configuration

Options for keyboard controls and accessibility features.

interface AccessibilityOptions {
  /** Enable keyboard shortcuts */
  enableKeyboard?: boolean; // Default: true
  
  /** Custom keyboard action definitions */
  keyActions?: KeyAction[];
  
  /** Hide screen reader title text */
  hideScreenReaderTitle?: boolean; // Default: false
}

interface KeyAction {
  /** Array of key codes that trigger this action */
  keys: number[];
  /** Function to execute when key is pressed */
  action: (player: MediaElementPlayer, media: MediaElement, event: KeyboardEvent) => void;
}

Usage Examples:

// Custom keyboard shortcuts
const player = new MediaElementPlayer('video', {
  enableKeyboard: true,
  keyActions: [
    {
      keys: [32], // Spacebar
      action: (player, media) => {
        if (media.paused) {
          player.play();
        } else {
          player.pause();
        }
      }
    },
    {
      keys: [27], // Escape
      action: (player) => {
        if (player.isFullScreen) {
          player.exitFullScreen();
        }
      }
    }
  ]
});

// Disable keyboard controls
const noKeyboardPlayer = new MediaElementPlayer('video', {
  enableKeyboard: false
});

Advanced Configuration

Advanced options for specialized use cases.

interface AdvancedOptions {
  /** Custom error handler */
  customError?: string | ((media: MediaElement, originalNode: HTMLElement) => void);
  
  /** Function to calculate backward seek interval */
  defaultSeekBackwardInterval?: (media: MediaElement) => number;
  
  /** Function to calculate forward seek interval */
  defaultSeekForwardInterval?: (media: MediaElement) => number;
  
  /** Renderer priority order */
  renderers?: string[];
  
  /** Icon sprite file path */
  iconSprite?: string;
}

Usage Examples:

// Custom seek intervals
const player = new MediaElementPlayer('video', {
  defaultSeekBackwardInterval: (media) => Math.min(media.duration * 0.1, 10), // Max 10 seconds
  defaultSeekForwardInterval: (media) => Math.min(media.duration * 0.1, 30), // Max 30 seconds
  
  // Custom error handling
  customError: (media, originalNode) => {
    console.error('Player error occurred:', media.error);
    // Show custom error UI
  },
  
  // Renderer preferences
  renderers: ['html5', 'hls', 'dash'],
  
  // Custom icon sprite
  iconSprite: '/assets/custom-icons.svg'
});

Time Format Configuration

Options for controlling time display format.

interface TimeFormatOptions {
  /** Time display format */
  timeFormat?: string; // Default: ''
  
  /** Always show hours even for short media */
  alwaysShowHours?: boolean; // Default: false
  
  /** Show frame count in timecode */
  showTimecodeFrameCount?: boolean; // Default: false
  
  /** Frames per second for frame counting */
  framesPerSecond?: number; // Default: 25
}

Usage Examples:

// Force hour display
const player = new MediaElementPlayer('video', {
  alwaysShowHours: true,
  timeFormat: 'hh:mm:ss'
});

// Show frame count for video editing
const framePlayer = new MediaElementPlayer('video', {
  showTimecodeFrameCount: true,
  framesPerSecond: 30
});

Callback Configuration

Success and error callbacks for player initialization.

interface CallbackOptions {
  /** Called when player initializes successfully */
  success?: (mediaElement: MediaElement, originalNode: HTMLElement, instance: MediaElementPlayer) => void;
  
  /** Called when player initialization fails */
  error?: (mediaElement: MediaElement, originalNode: HTMLElement) => void;
}

Usage Examples:

const player = new MediaElementPlayer('video', {
  success: (mediaElement, originalNode, instance) => {
    console.log('Player ready:', instance.id);
    
    // Set up event listeners
    mediaElement.addEventListener('play', () => {
      console.log('Playback started');
    });
    
    // Configure additional options
    instance.setVolume(0.8);
  },
  
  error: (mediaElement, originalNode) => {
    console.error('Failed to initialize player');
    // Show fallback content or error message
  }
});

Complete Configuration Example

const player = new MediaElementPlayer('my-video', {
  // Media configuration
  poster: '/posters/video-poster.jpg',
  showPosterWhenEnded: true,
  showPosterWhenPaused: false,
  
  // Dimensions
  defaultVideoWidth: 854,
  defaultVideoHeight: 480,
  enableAutosize: true,
  stretching: 'responsive',
  
  // Behavior
  loop: false,
  autoRewind: true,
  clickToPlayPause: true,
  pauseOtherPlayers: true,
  
  // Controls
  features: ['playpause', 'current', 'progress', 'duration', 'volume', 'fullscreen'],
  alwaysShowControls: false,
  controlsTimeoutDefault: 2000,
  classPrefix: 'mejs__',
  
  // Keyboard
  enableKeyboard: true,
  
  // Platform
  iPadUseNativeControls: false,
  iPhoneUseNativeControls: false,
  AndroidUseNativeControls: false,
  
  // Advanced
  renderers: ['html5', 'hls'],
  iconSprite: '/assets/mejs-controls.svg',
  
  // Callbacks
  success: (mediaElement, originalNode, instance) => {
    console.log('Player initialized successfully');
  },
  
  error: (mediaElement, originalNode) => {
    console.error('Player initialization failed');
  }
});

docs

configuration.md

core-media-element.md

feature-system.md

index.md

media-player.md

renderer-system.md

utility-functions.md

tile.json