MediaFox Player API

Constructor

new MediaFox(options?)

Creates a new player instance with comprehensive media playback capabilities.

constructor(options?: PlayerOptions)

Options

Property	Type	Default	Description
renderTarget	HTMLCanvasElement | OffscreenCanvas	undefined	Canvas element for video rendering
audioContext	AudioContext	undefined	Audio context for audio playback
volume	number	1	Initial volume level (0-1)
muted	boolean	false	Initial mute state
playbackRate	number	1	Initial playback speed (0.25-4)
autoplay	boolean	false	Auto-play when media loads
preload	'none' | 'metadata' | 'auto'	'metadata'	Preloading strategy
crossOrigin	string	undefined	CORS setting for cross-origin content
maxCacheSize	number	undefined	Maximum cache size for buffering
renderer	'webgpu' | 'webgl' | 'canvas2d'	Auto-detected	Rendering backend (auto-detects best available)

Example

// Basic setup
const player = new MediaFox({
  renderTarget: document.querySelector('#video-canvas'),
  volume: 0.8,
  autoplay: true
});

// Advanced configuration
const advancedPlayer = new MediaFox({
  renderTarget: canvas,
  audioContext: new AudioContext(),
  volume: 0.7,
  muted: false,
  playbackRate: 1.0,
  autoplay: false,
  preload: 'metadata',
  crossOrigin: 'anonymous',
  maxCacheSize: 200 * 1024 * 1024, // 200MB
  renderer: 'webgpu' // Use WebGPU renderer (falls back automatically if unavailable)
});

Interactive Demo

Try the player with different configurations:

Autoplay Volume: 0.8

0:00 / 0:00

Properties

Playback Properties

Property	Type	Read/Write	Description
currentTime	number	R/W	Current playback position in seconds
duration	number	R	Total duration in seconds (from state)
paused	boolean	R	Whether playback is paused
ended	boolean	R	Whether playback has ended
seeking	boolean	R	Whether seeking is in progress

Audio Properties

Property	Type	Read/Write	Description
volume	number	R/W	Volume level (0-1)
muted	boolean	R/W	Mute state
playbackRate	number	R/W	Playback speed (0.25-4)

Interactive Property Demo

Try changing these properties in real-time:

Volume: 1.0

Playback Rate: 1.0x

Mute:

Methods

Media Loading

load(source, options?)

Loads media from various sources.

async load(
  source: MediaSource,
  options?: LoadOptions
): Promise<void>

Parameters:

• source: File, Blob, URL, ArrayBuffer, Uint8Array, or ReadableStream
• options: Optional loading configuration

Example:

// Load from file
await player.load(fileInput.files[0]);

// Load from URL
await player.load('https://example.com/video.mp4');

// Load from blob
await player.load(blob, {
  preload: 'metadata'
});

Playback Control

play()

Starts or resumes playback.

async play(): Promise<void>

Example:

await player.play();

pause()

Pauses playback.

pause(): void

Example:

player.pause();

stop()

Stops playback and resets to the beginning.

async stop(): Promise<void>

Example:

await player.stop();

seek(time, options?)

Seeks to a specific time position.

async seek(
  time: number,
  options?: SeekOptions
): Promise<void>

Parameters:

• time: Target time in seconds
• options.precise: Whether to seek to exact frame (slower but precise)
• options.keyframe: Whether to seek to keyframes only (faster but less precise)

Example:

// Quick seek
await player.seek(30);

// Precise seek to exact frame
await player.seek(30, { precise: true });

// Keyframe-only seek (fastest)
await player.seek(30, { keyframe: true });

Track Management

getVideoTracks()

Returns all available video tracks.

getVideoTracks(): VideoTrackInfo[]

Returns: Array of video track information objects

Example:

const videoTracks = player.getVideoTracks();
videoTracks.forEach(track => {
  console.log(`${track.codec} ${track.width}x${track.height}`);
});

getAudioTracks()

Returns all available audio tracks.

getAudioTracks(): AudioTrackInfo[]

Returns: Array of audio track information objects

Example:

const audioTracks = player.getAudioTracks();
audioTracks.forEach(track => {
  console.log(`${track.codec} ${track.channels}ch ${track.sampleRate}Hz`);
});

selectVideoTrack(trackId)

Selects a specific video track.

async selectVideoTrack(trackId: string | null): Promise<void>

Parameters:

• trackId: ID of the video track to select (or null to disable video)

Example:

const tracks = player.getVideoTracks();
await player.selectVideoTrack(tracks[0].id);

selectAudioTrack(trackId)

Selects a specific audio track.

async selectAudioTrack(trackId: string | null): Promise<void>

Parameters:

• trackId: ID of the audio track to select (or null to disable audio)

Example:

const tracks = player.getAudioTracks();
await player.selectAudioTrack(tracks[1].id);

getSubtitleTracks()

Returns all available subtitle tracks.

getSubtitleTracks(): SubtitleTrackInfo[]

Returns: Array of subtitle track information objects

Example:

const subtitleTracks = player.getSubtitleTracks();
subtitleTracks.forEach(track => {
  console.log(`${track.language}: ${track.name || 'Subtitle'}`);
});

selectSubtitleTrack(trackId)

Selects a specific subtitle track.

selectSubtitleTrack(trackId: string | null): void

Parameters:

• trackId: ID of the subtitle track to select (or null to disable subtitles)

Example:

const tracks = player.getSubtitleTracks();
player.selectSubtitleTrack(tracks[0].id);

// Disable subtitles
player.selectSubtitleTrack(null);

registerSubtitleTracks(sourceId, registrations)

Registers external subtitle tracks.

registerSubtitleTracks(
  sourceId: string,
  registrations: SubtitleTrackRegistration[]
): void

Parameters:

• sourceId: Unique identifier for this subtitle source
• registrations: Array of subtitle track registrations

Example:

player.registerSubtitleTracks('external-subs', [
  {
    info: {
      id: 'en-subs',
      codec: null,
      language: 'en',
      name: 'English Subtitles',
      selected: false
    },
    resolver: async () => ({
      format: 'srt',
      content: await fetch('/subtitles/en.srt').then(r => r.text())
    })
  }
]);

unregisterSubtitleTracks(sourceId)

Removes previously registered subtitle tracks.

unregisterSubtitleTracks(sourceId: string): void

Parameters:

• sourceId: ID of the subtitle source to remove

Example:

player.unregisterSubtitleTracks('external-subs');

getSubtitleTrackResource(trackId)

Gets the resource data for a subtitle track.

async getSubtitleTrackResource(
  trackId: string | null
): Promise<SubtitleTrackResource | null>

Parameters:

• trackId: ID of the subtitle track

Returns: Subtitle resource data or null

Example:

const resource = await player.getSubtitleTrackResource('en-subs');
if (resource) {
  console.log('Format:', resource.format);
  if (resource.content) {
    console.log('Content loaded');
  } else if (resource.url) {
    console.log('URL:', resource.url);
  }
}

Playlist Management

loadPlaylist(items, options?)

Loads a playlist of media items.

async loadPlaylist(
  items: Array<MediaSource | { mediaSource: MediaSource; title?: string; poster?: string }>,
  options?: { autoplay?: boolean; startTime?: number }
): Promise<void>

Parameters:

• items: Array of media sources or playlist item configurations
• options.autoplay: Whether to start playing immediately (default: false)
• options.startTime: Start time in seconds for the first item (default: 0)

Example:

// Basic playlist
await player.loadPlaylist([
  { mediaSource: 'video1.mp4', title: 'First Video' },
  { mediaSource: 'video2.mp4', title: 'Second Video' },
  'video3.mp4' // Simple URL also works
]);

// With autoplay and start time
await player.loadPlaylist(
  [{ mediaSource: 'video.mp4', title: 'My Video' }],
  { autoplay: true, startTime: 30 }
);

addToPlaylist(item, index?)

Adds an item to the playlist.

addToPlaylist(
  item: MediaSource | { mediaSource: MediaSource; title?: string; poster?: string },
  index?: number
): void

Parameters:

• item: Media source or playlist item configuration
• index: Position to insert at (optional, defaults to end)

Example:

// Add to end
player.addToPlaylist({ mediaSource: 'new.mp4', title: 'New Video' });

// Add at specific position
player.addToPlaylist('video.mp4', 0); // Add at start

removeFromPlaylist(index)

Removes an item from the playlist.

async removeFromPlaylist(index: number): Promise<void>

Parameters:

• index: Index of item to remove

Example:

await player.removeFromPlaylist(2); // Remove third item

clearPlaylist()

Clears the entire playlist.

clearPlaylist(): void

Example:

player.clearPlaylist();

next()

Advances to the next playlist item.

async next(): Promise<void>

Example:

await player.next();

prev()

Goes to the previous playlist item.

async prev(): Promise<void>

Example:

await player.prev();

jumpTo(index)

Jumps to a specific playlist item.

async jumpTo(index: number): Promise<void>

Parameters:

• index: Index of item to jump to

Example:

await player.jumpTo(2); // Jump to third item

Playlist Properties

Property	Type	Read/Write	Description
playlist	PlaylistItem[]	R	Current playlist items
playlistIndex	number | null	R	Index of currently playing item
nowPlaying	PlaylistItem | null	R	Currently playing item
playlistMode	PlaylistMode	R/W	Playlist playback mode

Playlist Modes

type PlaylistMode = 'sequential' | 'manual' | 'repeat' | 'repeat-one' | null;

• null (default): No playlist behavior (single source)
• 'manual': Navigation via next()/prev()/jumpTo() only
• 'sequential': Auto-advance to next item on end
• 'repeat': Loop entire playlist
• 'repeat-one': Repeat current item continuously

Example:

// Set playlist mode
player.playlistMode = 'sequential';

// Access playlist data
console.log(player.playlist);       // Array of items
console.log(player.playlistIndex);  // Current index
console.log(player.nowPlaying);     // Current item

Playlist Events

Event	Data Type	Description
playlistchange	{ playlist: Playlist }	Playlist was loaded or cleared
playlistitemchange	{ index: number, item: PlaylistItem, previousIndex?: number }	Current item changed
playlistend	void	End of playlist reached (sequential/manual)
playlistadd	{ item: PlaylistItem, index: number }	Item added to playlist
playlistremove	{ index: number }	Item removed from playlist
playlistitemerror	{ index: number, error: Error }	Failed to load playlist item

Example:

player.on('playlistitemchange', ({ index, item, previousIndex }) => {
  console.log(`Now playing: ${item.title} (${index + 1}/${player.playlist.length})`);
});

player.on('playlistend', () => {
  console.log('Playlist finished');
});

Advanced Features

screenshot(options?)

Takes a screenshot of the current video frame.

async screenshot(options?: ScreenshotOptions): Promise<Blob | null>

Parameters:

• options.format: Image format ('png', 'jpeg', 'webp')
• options.quality: JPEG/WebP quality (0-1)

Returns: Blob containing the image data

Example:

// PNG screenshot
const blob = await player.screenshot();

// JPEG with quality
const jpegBlob = await player.screenshot({
  format: 'jpeg',
  quality: 0.9
});

// Download screenshot
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'screenshot.png';
a.click();
URL.revokeObjectURL(url);

setRenderTarget(target)

Changes the rendering target canvas.

setRenderTarget(target: HTMLCanvasElement | OffscreenCanvas | null): void

Parameters:

• target: New canvas element or null to disable rendering

Example:

// Change canvas
const newCanvas = document.querySelector('#new-canvas');
player.setRenderTarget(newCanvas);

// Use OffscreenCanvas for worker rendering
const offscreen = canvas.transferControlToOffscreen();
player.setRenderTarget(offscreen);

getRendererType()

Gets the current renderer type being used.

getRendererType(): RendererType

Returns: Current renderer type ('webgpu', 'webgl', or 'canvas2d')

Example:

const renderer = player.getRendererType();
console.log(`Using ${renderer} renderer`);

switchRenderer(type)

Switches to a different renderer backend with automatic fallback.

async switchRenderer(type: RendererType): Promise<void>

Parameters:

• type: Target renderer type ('webgpu', 'webgl', or 'canvas2d')

Example:

// Switch to WebGL renderer
await player.switchRenderer('webgl');

// Try WebGPU with automatic fallback if unavailable
try {
  await player.switchRenderer('webgpu');
} catch (error) {
  console.log('Renderer switch failed, using fallback');
}

getSupportedRenderers() (Static)

Gets list of supported renderers in the current environment.

static getSupportedRenderers(): RendererType[]

Returns: Array of supported renderer types in preference order

Example:

const supported = MediaFox.getSupportedRenderers();
console.log('Supported renderers:', supported);
// Output: ['webgpu', 'webgl', 'canvas2d'] or ['webgl', 'canvas2d'] etc.

// Use best available renderer
const player = new MediaFox({
  renderTarget: canvas,
  renderer: supported[0] // Use best available
});

State Management

subscribe(listener)

Subscribes to all state changes.

subscribe(listener: (state: PlayerStateData) => void): Subscription

Parameters:

• listener: Callback function that receives state updates

Returns: Subscription object with unsubscribe() method

Example:

const subscription = player.subscribe(state => {
  console.log(`Time: ${state.currentTime}/${state.duration}`);
  console.log(`Playing: ${state.playing}`);
  console.log(`Volume: ${state.volume}`);
});

// Later, unsubscribe
subscription.unsubscribe();

getState()

Gets the current player state.

getState(): PlayerStateData

Returns: Current state object

Example:

const state = player.getState();
console.log(`Current time: ${state.currentTime}`);
console.log(`Duration: ${state.duration}`);
console.log(`Playing: ${state.playing}`);
console.log(`Volume: ${state.volume}`);

Event Handling

on(event, listener)

Adds an event listener.

on<K extends keyof PlayerEventMap>(
  event: K,
  listener: (data: PlayerEventMap[K]) => void
): UnsubscribeFn

Parameters:

• event: Event name
• listener: Event handler function

Returns: Function to remove the listener

Example:

const unsubscribe = player.on('play', () => {
  console.log('Playback started');
});

player.on('error', (error) => {
  console.error('Player error:', error);
});

// Remove listener
unsubscribe();

once(event, listener)

Adds a one-time event listener.

once<K extends keyof PlayerEventMap>(
  event: K,
  listener: (data: PlayerEventMap[K]) => void
): UnsubscribeFn

Parameters:

• event: Event name
• listener: Event handler function

Returns: Function to remove the listener

Example:

player.once('loadedmetadata', (info) => {
  console.log('Media loaded:', info);
});

off(event, listener?)

Removes event listener(s).

off<K extends keyof PlayerEventMap>(
  event: K,
  listener?: (data: PlayerEventMap[K]) => void
): void

Parameters:

• event: Event name
• listener: Specific listener to remove (optional)

Example:

// Remove specific listener
player.off('play', playHandler);

// Remove all listeners for an event
player.off('play');

Cleanup

dispose()

Releases resources but keeps the instance usable.

dispose(): void

Example:

player.dispose();
// Player can still be used after loading new media

destroy()

Completely destroys the player instance.

destroy(): void

Example:

player.destroy();
// Player instance should not be used after this

Events

MediaFox emits various events during playback. All events are strongly typed.

Media Events

Event	Data Type	Description
loadstart	void	Loading has started
loadedmetadata	MediaInfo	Metadata has been loaded
loadeddata	void	First frame is available
canplay	void	Playback can start
canplaythrough	void	Playback can continue without buffering

Playback Events

Event	Data Type	Description
play	void	Playback has started
pause	void	Playback has been paused
playing	void	Playback has resumed
ended	void	Playback has ended
seeking	{ currentTime: number }	Seeking has started
seeked	{ currentTime: number }	Seeking has completed
waiting	void	Waiting for data

State Change Events

Event	Data Type	Description
timeupdate	{ currentTime: number }	Playback position has changed
durationchange	{ duration: number }	Duration has changed
volumechange	{ volume: number, muted: boolean }	Volume or mute state has changed
ratechange	{ playbackRate: number }	Playback rate has changed
progress	{ buffered: TimeRange[] }	Download progress

Track Events

Event	Data Type	Description
trackchange	{ type: 'video' | 'audio' | 'subtitle', trackId: string | null }	Track selection has changed
resize	{ width: number, height: number }	Video dimensions have changed

Warning Events

Event	Data Type	Description
warning	{ type: string, message: string, error?: Error }	Non-fatal warning occurred

Renderer Events

Event	Data Type	Description
rendererchange	RendererType	Renderer backend has changed
rendererfallback	{ from: RendererType, to: RendererType }	Renderer has fallen back to a different backend

Error Events

Event	Data Type	Description
error	MediaFoxError	An error has occurred

Event Example

// Listen to all major events
player.on('loadstart', () => {
  console.log('Loading started');
});

player.on('loadedmetadata', (info) => {
  console.log(`Duration: ${info.duration}s`);
  console.log(`Has video: ${info.hasVideo}`);
  console.log(`Has audio: ${info.hasAudio}`);
});

player.on('play', () => {
  console.log('Playback started');
});

player.on('timeupdate', ({ currentTime }) => {
  updateProgressBar(currentTime);
});

player.on('error', (error) => {
  console.error(`Error ${error.code}: ${error.message}`);
});

// Listen to renderer events
player.on('rendererchange', (type) => {
  console.log(`Renderer changed to: ${type}`);
});

player.on('rendererfallback', ({ from, to }) => {
  console.warn(`Renderer fallback: ${from} -> ${to}`);
});

Type Definitions

PlayerStateData

Complete player state object returned by subscribe() and getState().

interface PlayerStateData {
  // Playback state
  state: PlayerState;
  playing: boolean;
  paused: boolean;
  ended: boolean;
  seeking: boolean;

  // Time
  currentTime: number;
  duration: number;
  buffered: TimeRange[];

  // Audio
  volume: number;
  muted: boolean;
  playbackRate: number;

  // Media info
  mediaInfo: MediaInfo | null;
  videoTracks: VideoTrackInfo[];
  audioTracks: AudioTrackInfo[];
  subtitleTracks: SubtitleTrackInfo[];
  selectedVideoTrack: string | null;
  selectedAudioTrack: string | null;
  selectedSubtitleTrack: string | null;
  canPlay: boolean;
  canPlayThrough: boolean;
  isLive: boolean;

  // Renderer
  rendererType: RendererType;

  // Error state
  error: Error | null;
}

MediaInfo

Information about loaded media.

interface MediaInfo {
  duration: number;
  format: string;
  mimeType: string;
  metadata: MetadataTags;
  hasVideo: boolean;
  hasAudio: boolean;
  hasSubtitles: boolean;
}

VideoTrackInfo

Video track information.

interface VideoTrackInfo {
  id: string;
  codec: VideoCodec | null;
  language: string;
  name: string | null;
  width: number;
  height: number;
  frameRate: number;
  bitrate: number;
  rotation: 0 | 90 | 180 | 270;
  selected: boolean;
  decodable: boolean;
  converted?: boolean;
}

AudioTrackInfo

Audio track information.

interface AudioTrackInfo {
  id: string;
  codec: AudioCodec | null;
  language: string;
  name: string | null;
  channels: number;
  sampleRate: number;
  bitrate: number;
  selected: boolean;
  decodable: boolean;
  converted?: boolean;
}

RendererType

Supported rendering backends for video playback.

type RendererType = 'webgpu' | 'webgl' | 'canvas2d';

• webgpu: Modern GPU-accelerated rendering using WebGPU API (best performance)
• webgl: Hardware-accelerated rendering using WebGL (broad compatibility)
• canvas2d: Software rendering using Canvas 2D API (universal fallback)

PlaylistItem

Information about a playlist item.

interface PlaylistItem {
  id: string;                      // Unique identifier
  mediaSource: MediaSource;        // The media source
  title?: string;                  // Display title
  poster?: string;                 // Poster/thumbnail URL
  savedPosition: number | null;    // Saved playback position
  duration: number | null;         // Duration (populated after loading)
}

PlaylistMode

Playlist playback behavior.

type PlaylistMode = 'sequential' | 'manual' | 'repeat' | 'repeat-one' | null;

• null: No playlist behavior (default)
• 'sequential': Auto-advance to next item when current ends
• 'manual': Only advance via explicit next()/prev()/jumpTo() calls
• 'repeat': Loop entire playlist (after last item, go to first)
• 'repeat-one': Repeat current item continuously