MP4EDocs
Open Studio

Getting Started

Install the MP4E Player SDK for your platform.

Requirements

PlatformRequirementsPackage
ReactReact 18+ or 19+@mp4e/react
Vanilla JS (npm)Any bundler (Vite, webpack, Rollup, esbuild)@mp4e/player
Script Tag (CDN)Any modern browser@mp4e/player via jsDelivr
iOS Coming SooniOS 14+, Swift 5.5+MP4EPlayer (SPM)
Android Coming SoonAndroid 7+, Kotlin 1.8+com.mp4e:player

Web Platforms

React

npm install @mp4e/react
App.tsx
import { MP4EPlayer } from '@mp4e/react';
import '@mp4e/react/styles.css';

function VideoPage() {
  return (
    <MP4EPlayer
      src="https://your-cdn.com/video.mp4"
      onEvent={(event, data) => {
        console.log(event, data);
      }}
    />
  );
}

The component handles everything: metadata extraction, engine initialization, overlay rendering, and plugin sandboxing. You only need the src prop.

Vanilla JS (npm)

npm install @mp4e/player

First, set up the HTML structure:

index.html
<div id="player" style="position: relative; aspect-ratio: 16/9;">
  <video id="video" playsinline crossorigin="anonymous"></video>
  <canvas id="canvas" style="position: absolute; inset: 0; pointer-events: none;"></canvas>
  <div id="overlays" style="position: absolute; inset: 0;"></div>
</div>

<script type="module" src="./player.js"></script>

Then initialize the engine:

player.js
import { MP4Engine } from '@mp4e/player';

// 1. Point the video element at your MP4E file
const video = document.getElementById('video');
video.src = 'https://your-cdn.com/video.mp4';

// 2. Create the engine with your DOM elements
const engine = new MP4Engine({
  video,
  overlayContainer: document.getElementById('overlays'),
  canvas: document.getElementById('canvas'),
});

// 3. Subscribe to events before starting
engine.onEvent('metadata:loaded', (view) => {
  console.log('Interactive video loaded', view.schemaVersion, view.layers.length, 'layers');
});

// 4. Start: reads the interactivity embedded in the MP4
await engine.init();

Framework-agnostic. You provide the DOM elements; the engine draws its controls, overlays and plugins and drives the video element. One self-contained ES module — works with any bundler (Vite, webpack, Rollup, esbuild).

Script Tag (CDN)

No build tools required. Import the same package from a CDN in any HTML page:

index.html
<div id="player" style="position: relative; aspect-ratio: 16/9;">
  <video id="video" playsinline crossorigin="anonymous"></video>
  <canvas id="canvas" style="position: absolute; inset: 0; pointer-events: none;"></canvas>
  <div id="overlays" style="position: absolute; inset: 0;"></div>
</div>

<script type="module">
  import { MP4Engine } from 'https://cdn.jsdelivr.net/npm/@mp4e/player/dist/index.js';

  const video = document.getElementById('video');
  video.src = 'https://your-cdn.com/video.mp4';

  const engine = new MP4Engine({
    video,
    overlayContainer: document.getElementById('overlays'),
    canvas: document.getElementById('canvas'),
  });
  await engine.init();
</script>

Same API as @mp4e/player — no build step, no bundler, no Node.js required. Works in any modern browser.

Automatic Metadata Extraction
Both MP4EPlayer (React) and engine.init() (vanilla JS) automatically read the embedded metadata from the MP4 file. No server-side processing needed — the extraction happens client-side using the WASM engine.

Native Platforms

Coming Soon
Native SDKs for iOS and Android are currently in development. The same engine compiles to native binaries for each platform.
🍎

iOS (Swift)

Swift Package Manager integration with native AVPlayer backend.

Coming Soon
🤖

Android (Kotlin)

Gradle/Maven integration with ExoPlayer backend.

Coming Soon

Verification

Verify your installation is working correctly:

TestPlayer.tsx
import { MP4EPlayer } from '@mp4e/react';
import '@mp4e/react/styles.css';

function TestPlayer() {
  return (
    <MP4EPlayer
      src="https://mp4e.com/samples/demo.mp4"
      debug={true}
      onEvent={(event, data) => {
        if (event === 'state:ready') console.log('Engine ready');
        if (event === 'metadata:loaded') console.log('Metadata loaded:', data);
        if (event === 'state:error') console.error('Engine error:', data);
      }}
    />
  );
}

You should see the following in your console:

Metadata loaded: 2.0
Engine ready

Next Steps

Now that the player is installed, learn how to configure it:

Props Reference →Events & Callbacks →Configuration →
Previous
Core Concepts
Next
Props Reference