MediaFox

https://github.com/wiedymi/mediafox
Admin
MediaFox is a framework-agnostic, TypeScript-first media player library, powered by Mediabunny and...
Tokens:160,082
Snippets:652
Trust Score:8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Minimal MediaFox Player Example (HTML/JavaScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

A concise HTML example for a quick MediaFox player setup. It includes the necessary HTML structure and JavaScript to initialize the player, load a sample video, and begin playback.

```html
<!DOCTYPE html>
<html>
<head>
  <title>Quick MediaFox Player</title>
</head>
<body>
  <canvas id="player" width="1280" height="720"></canvas>

  <script type="module">
    import { MediaFox } from '@mediafox/core';

    const canvas = document.querySelector('#player');
    const player = new MediaFox({ renderTarget: canvas });

    // Load sample video
    await player.load('https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4');
    await player.play();
  </script>
</body>
</html>
```

--------------------------------

### Basic MediaFox Player Setup (HTML/JavaScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

A minimal HTML file to quickly set up and run a MediaFox player. It includes embedding a canvas element and initializing the player with a sample video URL, then starts playback.

```html
<!DOCTYPE html>
<html>
<head>
  <title>My First MediaFox Player</title>
</head>
<body>
  <canvas id="player" width="1280" height="720"></canvas>

  <script type="module">
    import { MediaFox } from '@mediafox/core';

    // Create player
    const canvas = document.querySelector('#player');
    const player = new MediaFox({
      renderTarget: canvas,
      volume: 0.8
    });

    // Load and play video
    await player.load('https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4');
    await player.play();

    console.log('Video is playing!');
  </script>
</body>
</html>
```

--------------------------------

### Initialize MediaFox Player with TypeScript

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Demonstrates how to initialize the MediaFox player using TypeScript, including setting player options and subscribing to state changes for IntelliSense and type checking.

```typescript
import { MediaFox, PlayerOptions, PlayerStateData } from '@mediafox/core';

const options: PlayerOptions = {
  renderTarget: canvas,
  volume: 0.8,
  autoplay: true
};

const player = new MediaFox(options);

player.subscribe((state: PlayerStateData) => {
  // Full IntelliSense and type checking
  console.log(state.currentTime); // number
  console.log(state.playing); // boolean
  console.log(state.volume); // number
});
```

--------------------------------

### Dispose and Destroy MediaFox Player Instance

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Illustrates how to manage MediaFox player resources by disposing of the instance to release resources or completely destroying it to prevent further use.

```typescript
// Component unmount / page unload
player.dispose(); // Releases resources but keeps instance
```

```typescript
// Or completely destroy
player.destroy(); // Cannot be used after this
```

--------------------------------

### Clone MediaFox Repository for Development

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/installation.md

Set up a development environment by cloning the MediaFox repository and installing dependencies using Bun. This allows for local development and testing.

```bash
git clone https://github.com/wiedymi/mediafox.git
cd mediafox
bun install
bun run dev
```

--------------------------------

### Install MediaFox with Bun

Source: https://github.com/wiedymi/mediafox/blob/main/docs/index.md

This command installs the core MediaFox library and Mediabunny using the Bun package manager. These are the essential dependencies to get started with MediaFox.

```bash
bun add @mediafox/core mediabunny
```

--------------------------------

### Install and Uninstall Plugins in TypeScript

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/plugins.md

Provides examples of how to install a plugin using `player.use()` and uninstall a plugin by its name using `player.unuse()`.

```typescript
// Install a plugin
await player.use(watermarkPlugin);

// Uninstall by name
await player.unuse('watermark');

```

--------------------------------

### Load Media into MediaFox Player

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Shows various methods to load media into the MediaFox player, including from a file input, a URL, a Blob object, or an ArrayBuffer. Each method requires an await call.

```typescript
// From file input
const file = fileInput.files[0];
await player.load(file);

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

// From Blob
const response = await fetch(url);
const blob = await response.blob();
await player.load(blob);

// From ArrayBuffer
const buffer = await file.arrayBuffer();
await player.load(buffer);
```

--------------------------------

### Install MediaFox Core Package

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/installation.md

Install the core MediaFox player package and its peer dependency mediabunny using various package managers. Ensure Node.js 18+ or Bun is installed.

```bash
bun add @mediafox/core mediabunny
```

```bash
npm install @mediafox/core mediabunny
```

```bash
yarn add @mediafox/core mediabunny
```

```bash
pnpm add @mediafox/core mediabunny
```

--------------------------------

### MediaFox Multi-Renderer System Initialization and Usage (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/performance.md

Demonstrates how to initialize MediaFox, check supported renderers, auto-select the best renderer, manually specify a renderer, get the current renderer type, and dynamically switch renderers. It also includes event listeners for 'rendererchange' and 'rendererfallback'.

```typescript
import { MediaFox } from '@mediafox/core';

// Check available renderers in your environment
const supported = MediaFox.getSupportedRenderers();
console.log('Supported renderers:', supported);
// Output: ['webgpu', 'webgl', 'canvas2d'] (in order of preference)

// Let MediaFox auto-select the best renderer
const player = new MediaFox({
  renderTarget: canvas
  // renderer is auto-detected
});

// Or manually specify a renderer
const webglPlayer = new MediaFox({
  renderTarget: canvas,
  renderer: 'webgl' // Force WebGL renderer
});

// Get current renderer type
console.log(`Using ${player.getRendererType()} renderer`);

// Switch renderers dynamically
async function optimizeRenderer() {
  const currentRenderer = player.getRendererType();

  // Switch based on content or performance metrics
  if (hasHighFrameRate && currentRenderer !== 'webgpu') {
    try {
      await player.switchRenderer('webgpu');
      console.log('Switched to WebGPU for better performance');
    } catch (error) {
      console.log('WebGPU unavailable, using fallback');
    }
  }
}

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

player.on('rendererfallback', ({ from, to }) => {
  console.warn(`Renderer fallback: ${from} -> ${to}`);
  // Notify user or adjust quality settings
});
```

--------------------------------

### Install and Run MediaFox Development Tasks (Bash)

Source: https://github.com/wiedymi/mediafox/blob/main/CLAUDE.md

This snippet shows essential bash commands for managing MediaFox dependencies, running the development server with watch mode, building for production, executing tests, and performing type checking. These commands are crucial for the development workflow.

```bash
# Install dependencies
bun install

# Development mode with watch
bun run dev

# Build for production
bun run build

# Run tests
bun test

# Type checking
bun run typecheck

# Linting
bun run lint
```

--------------------------------

### Handle Autoplay Restrictions in MediaFox

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Provides solutions for browser autoplay restrictions in MediaFox. It includes starting playback on user interaction and enabling muted autoplay.

```typescript
document.addEventListener('click', async () => {
  await player.play();
}, { once: true });
```

```typescript
const player = new MediaFox({
  autoplay: true,
  muted: true // Required for autoplay
});
```

--------------------------------

### Initialize MediaFox Player Instance (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Demonstrates how to initialize a MediaFox player instance in TypeScript. It requires a canvas element as the render target and allows configuration of properties like volume and autoplay.

```typescript
import { MediaFox } from '@mediafox/core';

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

--------------------------------

### Complete HTML Media Player with JavaScript

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/basic-usage.md

A fully functional HTML media player using the MediaFox library. It includes controls for play/pause, volume, file loading, and time display. This example demonstrates the basic setup, event handling, and state updates.

```html
<!DOCTYPE html>
<html>
<head>
  <style>
    .player-container {
      max-width: 800px;
      margin: 0 auto;
    }

    canvas {
      width: 100%;
      background: black;
    }

    .controls {
      display: flex;
      gap: 10px;
      padding: 10px;
      background: #333;
    }

    button {
      padding: 5px 15px;
      cursor: pointer;
    }

    .time {
      color: white;
      margin-left: auto;
    }
  </style>
</head>
<body>
  <div class="player-container">
    <canvas id="video"></canvas>

    <div class="controls">
      <button id="playPause">Play</button>
      <input type="range" id="volume" min="0" max="1" step="0.1" value="1">
      <span class="time" id="time">0:00 / 0:00</span>
    </div>

    <input type="file" id="fileInput" accept="video/*">
  </div>

  <script type="module">
    import { MediaFox, formatTime } from '@mediafox/core';

    // Initialize player
    const player = new MediaFox({
      renderTarget: document.getElementById('video')
    });

    // UI elements
    const playPauseBtn = document.getElementById('playPause');
    const volumeSlider = document.getElementById('volume');
    const timeDisplay = document.getElementById('time');
    const fileInput = document.getElementById('fileInput');

    // Load file
    fileInput.addEventListener('change', async (e) => {
      const file = e.target.files[0];
      if (file) {
        await player.load(file);
      }
    });

    // Play/pause
    playPauseBtn.addEventListener('click', async () => {
      if (player.paused) {
        await player.play();
      } else {
        player.pause();
      }
    });

    // Volume
    volumeSlider.addEventListener('input', (e) => {
      player.volume = parseFloat(e.target.value);
    });

    // Update UI on state change
    player.subscribe(state => {
      // Update button text
      playPauseBtn.textContent = state.playing ? 'Pause' : 'Play';

      // Update time
      timeDisplay.textContent = `${formatTime(state.currentTime)} / ${formatTime(state.duration)}`;
    });

    // Handle errors
    player.on('error', (error) => {
      alert(`Error: ${error.message}`);
    });
  </script>
</body>
</html>
```

--------------------------------

### Verify MediaFox Installation

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/installation.md

Verify that MediaFox has been installed correctly by importing the MediaFox class and checking its version. This confirms the core functionality is accessible.

```javascript
import { MediaFox, VERSION } from '@mediafox/core';

console.log(`MediaFox version: ${VERSION}`);

// Create a test instance
const player = new MediaFox();
console.log('Player created successfully!');
```

--------------------------------

### Use MediaFox from CDN

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/installation.md

Integrate the MediaFox core player into your project for quick prototyping using a CDN link. This method is not recommended for production environments.

```html
<script type="module">
  import { MediaFox } from 'https://unpkg.com/@mediafox/core@latest/dist/index.js';

  const player = new MediaFox({
    renderTarget: document.querySelector('canvas')
  });
</script>
```

--------------------------------

### Build Video Editor Preview with Mediafox (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/compositor.md

This TypeScript example demonstrates the complete process of creating a video editor preview. It covers initialization, media loading, timeline clip definition, preview configuration with a custom composition function, playback controls, UI updates, frame export, and resource cleanup using the Mediafox library. Ensure the Mediafox library is installed and the necessary HTML elements (canvas, buttons, slider, time display) are present in the DOM.

```typescript
import { Compositor } from '@mediafox/core';

// Setup
const canvas = document.querySelector('canvas');
const compositor = new Compositor({
  canvas,
  width: 1920,
  height: 1080
});

// Load sources
const background = await compositor.loadSource('background.mp4');
const overlay = await compositor.loadImage('logo.png');
const music = await compositor.loadAudio('soundtrack.mp3');

// Define clips on timeline
const clips = [
  { source: background, start: 0, duration: 30 },
  { source: overlay, start: 5, duration: 10, x: 50, y: 50, scale: 0.3 }
];

// Configure preview
compositor.preview({
  duration: 30,
  loop: false,
  getComposition: (time) => {
    const layers = clips
      .filter(clip => time >= clip.start && time < clip.start + clip.duration)
      .map((clip, i) => ({
        source: clip.source,
        sourceTime: time - clip.start,
        transform: {
          x: clip.x ?? 0,
          y: clip.y ?? 0,
          scaleX: clip.scale ?? 1,
          scaleY: clip.scale ?? 1,
          opacity: 1
        },
        zIndex: i
      }));

    return { time, layers };
  }
});

// Playback controls
document.querySelector('#play').onclick = () => compositor.play();
document.querySelector('#pause').onclick = () => compositor.pause();
document.querySelector('#seek').oninput = (e) => {
  compositor.seek(parseFloat(e.target.value));
};

// Update UI
compositor.on('timeupdate', ({ currentTime }) => {
  document.querySelector('#time').textContent = currentTime.toFixed(2);
  document.querySelector('#seek').value = currentTime;
});

// Export frame
document.querySelector('#export').onclick = async () => {
  const blob = await compositor.exportFrame(compositor.currentTime);
  // Download blob...
};

// Cleanup
window.addEventListener('beforeunload', () => {
  compositor.dispose();
});

```

--------------------------------

### Subscribe to MediaFox Player State Changes (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Demonstrates how to subscribe to state changes in the MediaFox player. A callback function receives the current state, and a subscription object allows for unsubscribing when no longer needed.

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

// Unsubscribe when done
subscription.unsubscribe();
```

--------------------------------

### Install MediaFox React Package

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/installation.md

Install the MediaFox React package along with the core package and mediabunny for React applications. Requires Node.js 18+ or Bun.

```bash
bun add @mediafox/react @mediafox/core mediabunny
```

```bash
npm install @mediafox/react @mediafox/core mediabunny
```

```bash
yarn add @mediafox/react @mediafox/core mediabunny
```

```bash
pnpm add @mediafox/react @mediafox/core mediabunny
```

--------------------------------

### Dynamic Renderer Selection with AdaptiveRendering

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/performance.md

Provides an example of an `AdaptiveRenderer` class that monitors performance metrics and dynamically switches MediaFox renderers to optimize playback.

```APIDOC
## Dynamic Renderer Selection with AdaptiveRendering

### Description
This section presents a conceptual `AdaptiveRenderer` class that demonstrates how to automatically adjust the MediaFox player's rendering backend based on real-time performance metrics, such as frame drops or GPU memory pressure.

### Method
N/A (This describes client-side JavaScript class implementation)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```javascript
class AdaptiveRenderer {
  constructor(player) {
    this.player = player;
    this.performanceMonitor = new PerformanceMonitor();
    this.setupAdaptiveRendering();
  }

  setupAdaptiveRendering() {
    // Monitor performance metrics
    setInterval(() => {
      this.checkAndAdaptRenderer();
    }, 10000); // Check every 10 seconds
  }

  async checkAndAdaptRenderer() {
    const metrics = this.performanceMonitor.getMetrics();
    const currentRenderer = this.player.getRendererType();

    // If experiencing frame drops with Canvas2D, try to upgrade
    if (currentRenderer === 'canvas2d' && metrics.frameDropRate > 0.1) {
      const supported = MediaFox.getSupportedRenderers();

      for (const renderer of supported) {
        if (renderer !== 'canvas2d') {
          try {
            await this.player.switchRenderer(renderer);
            console.log(`Upgraded to ${renderer} for better performance`);
            break;
          } catch (error) {
            continue; // Try next renderer
          }
        }
      }
    }

    // If GPU memory is constrained, consider downgrading
    if (currentRenderer === 'webgpu' && metrics.gpuMemoryPressure) {
      try {
        await this.player.switchRenderer('webgl');
        console.log('Switched to WebGL due to memory pressure');
      } catch (error) {
        // Fall back to canvas2d if needed
        await this.player.switchRenderer('canvas2d');
      }
    }
  }
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Install MediaFox and mediabunny

Source: https://context7.com/wiedymi/mediafox/llms.txt

Installs the core MediaFox library and its peer dependency mediabunny using npm or bun. For React applications, the React-specific package is also included.

```bash
npm install @mediafox/core mediabunny
# or
bun add @mediafox/core mediabunny
```

```bash
npm install @mediafox/react @mediafox/core mediabunny
```

--------------------------------

### Install @mediafox/react and @mediafox/core

Source: https://github.com/wiedymi/mediafox/blob/main/packages/react/README.md

Installs the necessary packages for using MediaFox React hooks. Supports npm, bun, and yarn package managers.

```bash
npm install @mediafox/react @mediafox/core
# or
bun add @mediafox/react @mediafox/core
# or
yarn add @mediafox/react @mediafox/core
```

--------------------------------

### Start Preview Playback (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/compositor.md

Starts the playback of the configured preview composition. This is an asynchronous operation and requires `preview()` to have been called first.

```typescript
await compositor.play();
```

--------------------------------

### Subscribe to All MediaFox State Changes

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/state-management.md

Demonstrates how to subscribe to all state changes emitted by the MediaFox player's store. It logs the entire state on each update and provides an example of how to unsubscribe. This is useful for general UI updates.

```typescript
import { MediaFox } from '@mediafox/core';

const player = new MediaFox({ canvas: canvasElement });

// Subscribe to all state changes
const unsubscribe = player.store.subscribe((state) => {
  console.log('State updated:', state);

  // Update UI based on state
  updatePlayButton(state.playing);
  updateTimeDisplay(state.currentTime, state.duration);
  updateVolumeControl(state.volume, state.muted);
});

// Unsubscribe when done
// unsubscribe();
```

--------------------------------

### Install MediaFox Core and Mediabunny (Bash)

Source: https://github.com/wiedymi/mediafox/blob/main/packages/mediafox/README.md

Provides commands for installing the core MediaFox library and its peer dependency, Mediabunny, using popular package managers like Bun, npm, and yarn.

```bash
bun add @mediafox/core mediabunny
# or
npm install @mediafox/core mediabunny
# or
yarn add @mediafox/core mediabunny
```

--------------------------------

### Adaptive Renderer Class for Dynamic Performance Optimization (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/performance.md

An example class demonstrating adaptive rendering. It monitors performance metrics and dynamically switches renderers (e.g., upgrading from Canvas2D to WebGPU or downgrading from WebGPU to WebGL) to maintain optimal playback performance based on system conditions.

```typescript
class AdaptiveRenderer {
  private player: MediaFox;
  private performanceMonitor: PerformanceMonitor;

  constructor(player: MediaFox) {
    this.player = player;
    this.performanceMonitor = new PerformanceMonitor();
    this.setupAdaptiveRendering();
  }

  private setupAdaptiveRendering() {
    // Monitor performance metrics
    setInterval(() => {
      this.checkAndAdaptRenderer();
    }, 10000); // Check every 10 seconds
  }

  private async checkAndAdaptRenderer() {
    const metrics = this.performanceMonitor.getMetrics();
    const currentRenderer = this.player.getRendererType();

    // If experiencing frame drops with Canvas2D, try to upgrade
    if (currentRenderer === 'canvas2d' && metrics.frameDropRate > 0.1) {
      const supported = MediaFox.getSupportedRenderers();

      for (const renderer of supported) {
        if (renderer !== 'canvas2d') {
          try {
            await this.player.switchRenderer(renderer);
            console.log(`Upgraded to ${renderer} for better performance`);
            break;
          } catch (error) {
            continue; // Try next renderer
          }
        }
      }
    }

    // If GPU memory is constrained, consider downgrading
    if (currentRenderer === 'webgpu' && metrics.gpuMemoryPressure) {
      try {
        await this.player.switchRenderer('webgl');
        console.log('Switched to WebGL due to memory pressure');
      } catch (error) {
        // Fall back to canvas2d if needed
        await this.player.switchRenderer('canvas2d');
      }
    }
  }
}
```

--------------------------------

### Install MediaFox React Package (Bash)

Source: https://github.com/wiedymi/mediafox/blob/main/packages/mediafox/README.md

Provides the command to install the dedicated MediaFox React package, along with the core library and its peer dependency, Mediabunny.

```bash
npm install @mediafox/react @mediafox/core mediabunny
```

--------------------------------

### Install MediaFox React and Core Packages

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/react.md

Installs the necessary MediaFox packages for React integration. This includes the core library and the React-specific bindings. Supports both npm and bun package managers.

```bash
npm install @mediafox/react @mediafox/core
# or
bun add @mediafox/react @mediafox/core
```

--------------------------------

### Track Discovery and Event Handling Example in TypeScript

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/track-manager.md

Demonstrates how to use the `getTracks()` method to retrieve all available media tracks and how to subscribe to `tracksChanged` events. This example shows how to log track information and update UI elements in response to track changes. It requires an instance of `TrackManager`.

```typescript
// Get all tracks
const tracks = trackManager.getTracks();
console.log('Video tracks:', tracks.video.length);
console.log('Audio tracks:', tracks.audio.length);
console.log('Subtitle tracks:', tracks.subtitle.length);

// Display track information
function displayTrackInfo(tracks: TrackList) {
  tracks.video.forEach((track, index) => {
    console.log(`Video ${index}: ${track.width}x${track.height} (${track.codec})`);
  });

  tracks.audio.forEach((track, index) => {
    console.log(`Audio ${index}: ${track.language} ${track.channels}ch (${track.codec})`);
  });

  tracks.subtitle.forEach((track, index) => {
    console.log(`Subtitle ${index}: ${track.language} (${track.format})`);
  });
}

// React to track changes
trackManager.on('tracksChanged', (tracks: TrackList) => {
  updateTrackSelectors(tracks);
  displayTrackInfo(tracks);
});
```

--------------------------------

### Initialize and Use Store (JavaScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/store.md

Demonstrates the basic usage of the MediaFox store, including initializing a new store instance, subscribing to state changes, and retrieving the current state. This example showcases how to interact with the store's core functionalities.

```javascript
const store = new Store();

// Subscribe to state changes
const unsubscribe = store.subscribe((state) => {
  console.log('State changed:', state);
});

// Get current state
const state = store.getState();
console.log(`Current time: ${state.currentTime}`); // Current time: 0
console.log(`Volume: ${state.volume}`); // Volume: 1
console.log(`Playing: ${state.playing}`); // Playing: false
```

--------------------------------

### Basic Compositor Setup with Vite Worker

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/compositor.md

Demonstrates how to import and initialize the Compositor using Vite's worker syntax. This method automatically bundles worker dependencies and provides the worker URL.

```typescript
import { Compositor } from '@mediafox/core';
import CompositorWorkerUrl from '@mediafox/core/compositor-worker?worker&url';

const compositor = new Compositor({
  canvas,
  width: 1920,
  height: 1080,
  worker: {
    enabled: true,
    url: CompositorWorkerUrl,
    type: 'module'
  }
});
```

--------------------------------

### Configure CORS for MediaFox Player

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Shows how to configure the MediaFox player to handle Cross-Origin Resource Sharing (CORS) errors when loading videos from a different domain by setting the 'crossOrigin' option.

```typescript
const player = new MediaFox({
  crossOrigin: 'anonymous' // or 'use-credentials'
});
```

--------------------------------

### MediaFox Renderer Initialization and Usage

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/performance.md

Demonstrates how to initialize MediaFox, check supported renderers, auto-select the best renderer, manually specify a renderer, and dynamically switch renderers.

```APIDOC
## MediaFox Renderer Initialization and Usage

### Description
This section covers the basic usage of the MediaFox player, including how to detect available rendering backends, initialize the player with automatic or manual renderer selection, and dynamically switch between renderers.

### Method
N/A (This describes client-side JavaScript API usage)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```javascript
import { MediaFox } from '@mediafox/core';

// Check available renderers in your environment
const supported = MediaFox.getSupportedRenderers();
console.log('Supported renderers:', supported);

// Let MediaFox auto-select the best renderer
const player = new MediaFox({
  renderTarget: canvas
  // renderer is auto-detected
});

// Or manually specify a renderer
const webglPlayer = new MediaFox({
  renderTarget: canvas,
  renderer: 'webgl' // Force WebGL renderer
});

// Get current renderer type
console.log(`Using ${player.getRendererType()} renderer`);

// Switch renderers dynamically
async function optimizeRenderer() {
  const currentRenderer = player.getRendererType();

  // Switch based on content or performance metrics
  if (hasHighFrameRate && currentRenderer !== 'webgpu') {
    try {
      await player.switchRenderer('webgpu');
      console.log('Switched to WebGPU for better performance');
    } catch (error) {
      console.log('WebGPU unavailable, using fallback');
    }
  }
}

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

player.on('rendererfallback', ({ from, to }) => {
  console.warn(`Renderer fallback: ${from} -> ${to}`);
  // Notify user or adjust quality settings
});
```

### Response
#### Success Response (200)
N/A (This describes client-side JavaScript API usage)

#### Response Example
N/A
```

--------------------------------

### Instantiate MediaFox Player with Options (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/player.md

Demonstrates how to create a new MediaFox player instance using the constructor, with examples for basic and advanced configurations. It highlights key options like renderTarget, volume, autoplay, and renderer.

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

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)
});
```

--------------------------------

### Control Media Playback with MediaFox API

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/getting-started.md

Illustrates essential playback controls for the MediaFox player, including play, pause, seeking to a specific time, volume adjustment, muting, and stopping playback.

```typescript
// Play/Pause
await player.play();
player.pause();

// Seek to specific time
player.currentTime = 30; // Jump to 30 seconds
await player.seek(30); // Alternative method

// Volume control
player.volume = 0.5; // 50% volume
player.muted = true; // Mute

// Stop and reset
player.stop();
```

--------------------------------

### Start Media Playback (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/playback-controller.md

Demonstrates various ways to initiate media playback using the `play()` method of the PlaybackController. Includes basic usage, error handling, conditional playback, handling user interaction for autoplay policies, and integrating with analytics.

```typescript
// Basic play
await playbackController.play();

// Play with error handling
try {
  await playbackController.play();
  console.log('Playback started');
  updatePlayButton('pause');
} catch (error) {
  console.error('Failed to start playback:', error);
  showPlaybackError(error.message);
}

// Conditional play
if (!playbackController.isPlaying()) {
  await playbackController.play();
}

// Play after user interaction (for autoplay policies)
document.addEventListener('click', async () => {
  if (shouldAutoPlay) {
    await playbackController.play();
  }
}, { once: true });

// Play with analytics
async function playWithTracking() {
  const startTime = Date.now();

  await playbackController.play();

  analytics.track('video_play', {
    video_id: getCurrentVideoId(),
    start_time: playbackController.getCurrentTime(),
    timestamp: startTime
  });
}
```

--------------------------------

### Initialize MediaFox Player

Source: https://context7.com/wiedymi/mediafox/llms.txt

Creates a new MediaFox player instance. Basic setup requires a render target, while advanced configuration allows specifying audio context, volume, playback rate, and renderer backend.

```typescript
import { MediaFox } from '@mediafox/core';

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

// Advanced configuration with all options
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' // 'webgpu' | 'webgl' | 'canvas2d'
});
```

--------------------------------

### Player Initialization and Cleanup

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/vanilla.md

Demonstrates the initialization of the `TypedVideoPlayer` and the cleanup process. The player is instantiated, and its `destroy` method is called on page unload to release resources.

```typescript
// Initialize the player
const player = new TypedVideoPlayer();

// Cleanup on page unload
window.addEventListener('beforeunload', () => {
    player.destroy();
});
```

--------------------------------

### Install MediaFox and mediabunny for Svelte

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/svelte.md

Installs the necessary MediaFox and mediabunny packages into a Svelte project using different package managers. Ensure you have Node.js and a compatible package manager (bun, npm, or yarn) installed.

```bash
bun add @mediafox/core mediabunny
```

```bash
npm install @mediafox/core mediabunny
```

```bash
yarn add @mediafox/core mediabunny
```

--------------------------------

### Create MediaFox Player Instance

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/basic-usage.md

Instantiates a MediaFox player object with provided options. Each instance manages its own media source, playback state, rendering target, and event handlers. This is the foundational step for using MediaFox.

```typescript
import { MediaFox } from '@mediafox/core';

const player = new MediaFox(options);
```

--------------------------------

### Initialize and Control MediaFox Player

Source: https://github.com/wiedymi/mediafox/blob/main/docs/index.md

Demonstrates the basic initialization of a MediaFox player, loading media from various sources (file, URL, blob), and controlling playback functions like play, pause, and seek. It also shows how to manage multi-track media by selecting different audio tracks.

```typescript
import { MediaFox } from '@mediafox/core';

const player = new MediaFox({
  renderTarget: document.querySelector('#canvas'),
  volume: 0.8,
  autoplay: false
});

// Load media from various sources
await player.load(videoFile);
await player.load('https://example.com/video.mp4');
await player.load(blob);

// Control playback
await player.play();
player.pause();
await player.seek(30);

// Multi-track support
const videoTracks = player.getVideoTracks();
const audioTracks = player.getAudioTracks();
await player.selectAudioTrack(audioTracks[1].id);
```

--------------------------------

### Configure TypeScript for MediaFox

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/installation.md

Configure your tsconfig.json file to include necessary compiler options for using MediaFox with TypeScript. This ensures proper module resolution and type checking.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler"
  }
}
```

--------------------------------

### Access and Load Media Tracks with MediaFox (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/tracks.md

Demonstrates how to initialize the MediaFox player, load a video file, and access the available video and audio tracks. It also shows how to retrieve the currently active track indices.

```typescript
import { MediaFox } from '@mediafox/core';

const player = new MediaFox({ canvas: canvasElement });

// Load media and access tracks
await player.load('multi-track-video.mp4');

// Get all available tracks
const tracks = player.tracks;
console.log('Video tracks:', tracks.video);
console.log('Audio tracks:', tracks.audio);

// Access current track indices
console.log('Current video track:', player.currentVideoTrack);
console.log('Current audio track:', player.currentAudioTrack);
```

--------------------------------

### Define TimeRanges Interface (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/types.md

Represents a collection of time ranges, typically used for buffered media. It provides methods to get the number of ranges and the start and end times for each range.

```typescript
interface TimeRanges {
  readonly length: number;
  start(index: number): number;
  end(index: number): number;
}
```

--------------------------------

### Set Up Real-time Preview Playback

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/compositor.md

Configures the compositor for real-time preview playback, including duration, FPS, looping, and a callback function to define the composition at any given time. It also shows basic playback controls.

```typescript
compositor.preview({
  duration: 60, // Total duration in seconds
  fps: 30,
  loop: true,
  getComposition: (time) => {
    // Return composition for any given time
    return {
      time,
      layers: [
        {
          source: video,
          sourceTime: time,
          transform: { opacity: 1 }
        },
        // Show logo only between 5-15 seconds
        ...(time >= 5 && time < 15 ? [{
          source: logo,
          transform: { x: 50, y: 50, opacity: 1 },
          zIndex: 1
        }] : [])
      ]
    };
  }
});

// Control playback
await compositor.play();
compositor.pause();
await compositor.seek(30); // Seek to 30 seconds
```

--------------------------------

### Get Full MediaFox Player State Object

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/state-management.md

Demonstrates how to retrieve the entire current state object from the MediaFox player's store using `getState()`. This is useful for inspecting all state values at once or checking complex conditions, such as player readiness.

```typescript
// Get the current complete state
const currentState = player.store.getState();
console.log(currentState);

// Check if player is ready to play
if (currentState.readyState >= 3) {
  console.log('Player can start playback');
}
```

--------------------------------

### MediaFox Constructor

Source: https://context7.com/wiedymi/mediafox/llms.txt

Initializes a new MediaFox player instance. You can configure various options such as the rendering target, audio context, volume, playback rate, and preferred renderer backend.

```APIDOC
## MediaFox Constructor

Creates a new MediaFox player instance with configurable options for rendering target, audio context, volume, playback rate, and renderer backend selection.

### Method

`new MediaFox(options)`

### Parameters

#### Request Body

- **renderTarget** (HTMLElement | string) - Required - The DOM element or a selector for the element where the media will be rendered.
- **audioContext** (AudioContext) - Optional - An existing AudioContext to use for audio processing.
- **volume** (number) - Optional - The initial volume level, ranging from 0.0 to 1.0. Defaults to 1.0.
- **muted** (boolean) - Optional - Whether the player should start muted. Defaults to false.
- **playbackRate** (number) - Optional - The initial playback rate. Defaults to 1.0.
- **autoplay** (boolean) - Optional - Whether the media should autoplay. Defaults to false.
- **preload** (string) - Optional - The preload attribute for the media. Options: 'none', 'metadata', 'auto'. Defaults to 'auto'.
- **crossOrigin** (string) - Optional - The cross-origin attribute for the media. Options: 'anonymous', 'use-credentials'. Defaults to undefined.
- **maxCacheSize** (number) - Optional - The maximum cache size in bytes. Defaults to 100MB.
- **renderer** (string) - Optional - The preferred rendering backend. Options: 'webgpu', 'webgl', 'canvas2d'. Defaults to 'webgpu' with fallback.

### Request Example

```typescript
import { MediaFox } from '@mediafox/core';

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

const advancedPlayer = new MediaFox({
  renderTarget: '#video-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' // 'webgpu' | 'webgl' | 'canvas2d'
});
```

### Response

#### Success Response (200)

- **player** (MediaFox) - The newly created MediaFox player instance.

#### Response Example

```json
{
  "message": "MediaFox player initialized successfully"
}
```
```

--------------------------------

### Integrate MediaFox with React and Vue

Source: https://github.com/wiedymi/mediafox/blob/main/docs/index.md

Provides example code snippets for integrating the MediaFox player into popular JavaScript frameworks like React and Vue. It covers basic setup, state subscription, and player disposal within component lifecycles.

```typescript
// Framework integration examples

// React
function VideoPlayer({ src }) {
  const playerRef = useRef();
  const [state, setState] = useState(null);

  useEffect(() => {
    const player = new MediaFox({ renderTarget: canvasRef.current });
    const { unsubscribe } = player.subscribe(setState);

    playerRef.current = player;
    return () => { unsubscribe(); player.dispose(); };
  }, []);

  return <canvas ref={canvasRef} onClick={() => player.play()} />;
}

// Vue
const player = new MediaFox({ renderTarget: canvasRef.value });
const state = ref(null);

```

--------------------------------

### Get Event Names with Listeners (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/docs/api/event-emitter.md

Retrieves an array of all event names that currently have registered listeners. This is useful for auditing or managing active event subscriptions. The provided examples demonstrate basic retrieval, cleanup of unused listeners, and a comprehensive event audit.

```typescript
// Get all events with listeners
const events = player.eventNames();
console.log('Events with listeners:', events);

// Cleanup utility
function cleanupUnusedListeners(emitter: EventEmitter) {
  const events = emitter.eventNames();

  events.forEach(event => {
    const count = emitter.listenerCount(event);
    if (count === 0) {
      // Event has no listeners, could clean up related resources
      console.log(`Event ${String(event)} has no listeners`);
    }
  });
}

// Event audit
function auditEventListeners(emitter: EventEmitter) {
  const events = emitter.eventNames();
  const report = events.map(event => ({
    event: String(event),
    listenerCount: emitter.listenerCount(event)
  }));

  console.table(report);
  return report;
}
```

--------------------------------

### Handle MediaFox-Specific Events in TypeScript

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/events.md

This TypeScript example demonstrates handling custom MediaFox-specific events, including 'tracksChanged' for available track information, 'trackChanged' for selected track updates, 'sourceChanged' for media source updates, and lifecycle events like 'ready' and 'destroy'.

```typescript
player.on('tracksChanged', (tracks) => {
  console.log('Available tracks:', tracks);
  console.log(`Video tracks: ${tracks.video.length}`);
  console.log(`Audio tracks: ${tracks.audio.length}`);
});

player.on('trackChanged', (type: 'video' | 'audio', trackIndex: number) => {
  console.log(`${type} track changed to index: ${trackIndex}`);
});

player.on('sourceChanged', (newSource: string) => {
  console.log('Media source changed to:', newSource);
});

player.on('ready', () => {
  console.log('Player is ready for playback');
});

player.on('destroy', () => {
  console.log('Player has been destroyed');
});
```

--------------------------------

### Initialize Compositor with Canvas

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/compositor.md

Sets up the Compositor instance, requiring a canvas element and specifying dimensions and background color. This is the foundational step for any compositing operation.

```typescript
import { Compositor } from '@mediafox/core';

// Create compositor with a canvas
const canvas = document.querySelector('canvas');
const compositor = new Compositor({
  canvas,
  width: 1920,
  height: 1080,
  backgroundColor: '#000000'
});
```

--------------------------------

### Svelte Action for MediaFox Player Events

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/events.md

A Svelte action `playerEvents` to attach and manage event listeners to a MediaFox player instance associated with an HTML element. It handles setup, updates, and cleanup of event listeners. Requires Svelte and the MediaFox core library.

```typescript
// playerEvents.ts
export function playerEvents(
  node: HTMLElement,
  { player, events }: { player: MediaFox, events: Record<string, Function> }
) {
  const eventHandlers = new Map();

  function setupEvents() {
    Object.entries(events).forEach(([event, handler]) => {
      player.on(event as any, handler);
      eventHandlers.set(event, handler);
    });
  }

  function cleanupEvents() {
    eventHandlers.forEach((handler, event) => {
      player.off(event, handler);
    });
    eventHandlers.clear();
  }

  setupEvents();

  return {
    update({ player: newPlayer, events: newEvents }) {
      cleanupEvents();
      Object.entries(newEvents).forEach(([event, handler]) => {
        newPlayer.on(event as any, handler);
        eventHandlers.set(event, handler);
      });
    },
    destroy: cleanupEvents
  };
}

// Usage in Svelte component
// <div use:playerEvents={{ player, events: {
//   play: () => isPlaying = true,
//   pause: () => isPlaying = false,
//   timeupdate: (time) => currentTime = time
// } }}>
//   <!-- Player UI -->
// </div>
```

--------------------------------

### Building a Timeline-Based Editor with Compositor

Source: https://github.com/wiedymi/mediafox/blob/main/docs/guide/compositor.md

Provides a code example for constructing a timeline-based video editor using the Compositor, including defining clips, adding them to the timeline, and configuring preview playback.

```typescript
// Define clips on timeline
interface Clip {
  id: string;
  source: CompositorSource;
  track: number;
  startTime: number;
  duration: number;
  sourceOffset: number;
  transform: LayerTransform;
}

const clips: Clip[] = [];

// Add a clip
async function addClip(file: File, track: number, startTime: number) {
  const source = await compositor.loadSource(file);
  clips.push({
    id: crypto.randomUUID(),
    source,
    track,
    startTime,
    duration: Math.min(source.duration, 10),
    sourceOffset: 0,
    transform: { opacity: 1, scaleX: 1, scaleY: 1 }
  });
  updatePreview();
}

// Configure preview
function updatePreview() {
  const duration = Math.max(...clips.map(c => c.startTime + c.duration), 10);

  compositor.preview({
    duration,
    fps: 30,
    loop: true,
    getComposition: (time) => {
      const visibleClips = clips
        .filter(c => time >= c.startTime && time < c.startTime + c.duration)
        .sort((a, b) => a.track - b.track);

      const layers = visibleClips.map((clip, i) => ({
        source: clip.source,
        sourceTime: time - clip.startTime + clip.sourceOffset,
        transform: clip.transform,
        zIndex: i
      }));

      return { time, layers };
    }
  });
}

// Playback controls
document.querySelector('#play').onclick = () => compositor.play();
document.querySelector('#pause').onclick = () => compositor.pause();
```

--------------------------------

### Initialize and Play Media with MediaFox (TypeScript)

Source: https://github.com/wiedymi/mediafox/blob/main/packages/mediafox/README.md

Demonstrates the basic initialization of a MediaFox player instance, loading a media file, and starting playback. It requires a canvas element as a render target.

```typescript
import { MediaFox } from '@mediafox/core';

// Create player instance
const player = new MediaFox({
  renderTarget: document.querySelector('canvas'),
  volume: 0.8
});

// Load media
await player.load(videoFile); // File, Blob, URL, or ArrayBuffer

// Control playback
await player.play();
player.pause();
player.currentTime = 30; // Seek to 30 seconds
player.volume = 0.5;
```
Tokens:
Raw