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/core
Script Tag (CDN)Any modern browsercdn.mp4e.com/mp4e.min.js
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/core

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, extractMP4EMetadata } from '@mp4e/core';

// 1. Set up DOM elements
const video = document.querySelector('video');
const overlayContainer = document.getElementById('overlays');
const canvas = document.getElementById('canvas');

// 2. Extract metadata from the MP4 file
const metadata = await extractMP4EMetadata('https://your-cdn.com/video.mp4');

// 3. Create and initialize the engine
const engine = new MP4Engine(
  { video, overlayContainer, canvas },
  { metadata }
);
await engine.init(metadata);

// 4. Handle engine events
engine.onEvent('action:play', () => video.play());
engine.onEvent('action:pause', () => video.pause());
engine.onEvent('action:seek', (data) => {
  video.currentTime = data.time;
});

Framework-agnostic. You manage the DOM and video element directly. Works with any bundler (Vite, webpack, Rollup, esbuild).

Script Tag (CDN)

No build tools required. Add a single script tag to 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, extractMP4EMetadata } from 'https://cdn.mp4e.com/mp4e.min.js';

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

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

  engine.onEvent('action:play', () => video.play());
  engine.onEvent('action:pause', () => video.pause());
  engine.onEvent('action:seek', (d) => video.currentTime = d.time);
</script>

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

Automatic Metadata Extraction
Both MP4EPlayer (React) and extractMP4EMetadata() (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