MP4E — Interactive video that travels in the file

TypeScript Support

All props are fully typed. Import MP4EPlayerProps for the complete interface.

Source Props

Configure the video source. The player automatically extracts embedded metadata from the MP4 file - you typically only need to provide the src prop.

Prop	Type	Default	Description
`src`*	`string`	-	URL or path to the MP4 video file. Can be absolute URL, relative path, or blob URL. Metadata is automatically extracted from the MP4 atom.
`metadata`	`MP4EMetadata \| null`	-	The base metadata document. Neither this nor overrides is required — an ordinary MP4 with no embedded metadata still becomes fully interactive (the player generates a minimal base at runtime from the video's own dimensions and duration). When provided, this replaces the extracted/generated base; usually not needed, since the player auto-extracts metadata from the MP4 file. If the engine cannot load the document you pass, the player stays a plain video without interactivity or controls until you pass a document it can load.
`runtimeFlags`	`MP4ERuntimeFlags`	-	Optional runtime feature flags. Defaults to metadata.settings.runtimeFlags; this prop overrides metadata when provided.
`objectGroups`	`ObjectGroup[]`	-	Object groups with display settings for controlling how objects are rendered and interact.
`defaultDisplaySettings`	`ObjectDisplaySettings`	-	Default display settings applied to objects without group-specific settings.

Playback Props

Control video playback behavior.

Prop	Type	Default	Description
`autoplay`	`boolean`	`false`	Automatically start playing when the video is ready. Note: most browsers require muted=true for autoplay.
`muted`	`boolean`	`false`	Start with audio muted. Required for autoplay in most browsers.
`loop`	`boolean`	`false`	Restart video from beginning when it ends.
`initialTime`	`number`	-	Start playback from this time (in seconds), e.g. a link to a moment. Applied once per src, as soon as the video's interactivity has loaded. With @mp4e/player, pass it as initialTime in the MP4Engine config. Plugins see it as getVideoState().startTime, so they can skip start-of-video prompts.

Display Props

Control debug and canvas rendering options.

Prop	Type	Default	Description
`showBboxes`	`boolean`	`false`	Show bounding boxes/polygons on canvas.
`showCanvasLabels`	`boolean`	`true`	Show canvas labels on hover. Disable when using display plugins.
`showObjectDisplays`	`boolean`	`true`	Show object displays (tooltips, product cards) on hover/click.
`interactive`	`boolean`	`true`	Opt OUT of the engine entirely when false — renders a plain, non-interactive <video> element with no WASM engine, no render loop, no overlays/controls/menu, and no metadata bootstrap (host-supplied or generated). An explicit escape hatch for a bare video, not a lightweight mode that can gain interactivity later without a full remount.
`controls`	`boolean`	`true`	Show built-in playback controls (play/pause, seek, volume, fullscreen).
`loadingIndicator`	`boolean`	`true`	Show a small centered spinner over the frame area while the video has no decoded frame yet. The player holds overlays back over that same window, so the video and its interactive layer appear together instead of plugins painting over a black frame. Controls stay visible throughout. The engine renders the indicator itself (via MP4EngineConfig.loadingIndicator), so vanilla @mp4e/player hosts get the same affordance without writing one. On a source that never decodes a frame and never errors, the indicator stays up until the viewer starts playback. Setting this to false only hides the spinner — it does not change when overlays are revealed. Read at init: toggling it on a mounted player takes effect when src or interactive next changes. The ring stops animating for viewers who ask for reduced motion.

Callback Props

Event handlers for player lifecycle and interactions.

Prop	Type	Default	Description
`onEvent`	`(event: string, data: any) => void`	-	Single event channel for ALL engine events (playback, objects, overlays, scenes, variables, errors). See Events Reference for all event names.
`onFrameChange`	`(frame: number) => void`	-	Called on each frame change. Used for Studio timeline sync (high-frequency).
`onVideoDuration`	`(duration: number) => void`	-	Called when video duration becomes available.

Host Configuration Props

Configure host-level behavior including metadata overrides, sandbox policies, and content trust. These props control how the player integrates with your host application.

Prop	Type	Default	Description
`overrides`	`Record<string, any>`	-	A replaceable injection layer deep-merged on top of metadata (or the generated base, when metadata is omitted) at runtime. Neither this nor metadata is required for an ordinary video. Re-rendering with a new value REPLACES the current override layer outright (not a merge queue); {}, null, or undefined clears it and restores the base. Changing this prop does not reconstruct the engine or reload src, and playback position, variable values, running timers, counters, and the current scene all carry through the swap for ids that still exist. See Overrides page.
`config`	`MP4EConfig`	-	Host behavior configuration — sandbox rules, action gating, plugin security, disabled content. See Configuration page.
`trustContent`	`boolean`	`false`	Explicit opt-in to the trusted sandbox level: every plugin gets allow-same-origin. Plugins are isolated from the host page by default; set this only for self-hosted deployments.

See Configuration for the full MP4EConfig reference, Overrides for deep-merge examples, and Viewer Preferences for the runtime viewer preference system.

Security & Gating Callbacks

Callbacks for approving or denying gated actions and network requests. These give the host application full control over what plugins and actions are allowed to do at runtime.

Prop	Type	Default	Description
`onActionGate`	`(action: any, resolve: (approved: boolean) => void) => void`	-	Called when a gated action is triggered. Show approval UI, then call resolve(true) to allow or resolve(false) to deny. See Configuration page.
`onActionComplete`	`(actionType: string, data: any) => void`	-	Called after an action finishes executing — including viewer play/pause via the player controls. The data object is the fully resolved action and carries an initiator ({type, id?, event?, via?}) describing what caused it: the viewer, a rule (with its id), a plugin, or your application. See Player Events › Event Provenance.
`onNetworkGate`	`(request: { pluginId: string; url: string; method: string }, resolve: (approved: boolean) => void) => void`	-	Called when a plugin makes a network request. Approve or deny based on URL/domain. See Configuration page.
`onSecurityViolation`	`(violation: { pluginId: string; blockedURI: string; violatedDirective: string }) => void`	-	Called when a plugin triggers a Content Security Policy violation.

Action Gating

Action gating uses an intersection model — each layer restricts, never expands. See Configuration for how to define gated actions and timeout policies.

Performance Props

Optimize video loading and seeking performance. Blob caching downloads the full file in the background for instant seeking after the initial load.

Prop	Type	Default	Description
`enableBlobCache`	`boolean`	`false`	Download the full video file in the background, then swap to a blob URL for instant seeking with zero network round-trips. The download starts once the video element has decoded its first frame, so it never delays initial playback.
`blobCacheMaxBytes`	`number`	`1610612736`	Maximum file size in bytes for blob caching (default ~1.5 GB). Files exceeding this are skipped.

Advanced Props

Low-level props for customizing the player engine, controls, and debugging behavior. Most applications will not need to change these from their defaults.

Prop	Type	Default	Description
`pluginOverrides`	`Record<string, { pluginId: string; config?: Record<string, any> }>`	-	Override the built-in UI plugins for controls, subtitles, or menu with your own plugin implementations.
`nativeControls`	`boolean`	`false`	Use native browser video controls instead of MP4E's custom controls.
`useWorker`	`boolean`	`true`	Run the WASM engine in a Web Worker. Reduces main thread load but adds ~15-20ms latency. Set to false for frame-perfect polygon rendering.
`debugViewMode`	`'bboxes' \| 'polygons' \| 'amodal' \| 'corners' \| 'mesh' \| 'zones' \| 'none'`	`'none'`	Visualize object tracking data. 'zones' outlines the resolved replacement-zone geometry (polygon, corners, mesh points) exactly as rendered.

Example

Example using currently implemented props:

InteractiveVideo.tsx

1import { MP4EPlayer } from '@mp4e/react';
2import '@mp4e/react/styles.css';
3
4function InteractiveVideo() {
5  return (
6    <MP4EPlayer
7      // Source (required) - metadata is auto-extracted from the MP4 file
8      src="https://cdn.example.com/video.mp4"
9
10      // Object display settings (optional)
11      objectGroups={[
12        {
13          id: 'products',
14          objectIds: ['obj_1', 'obj_2'],
15          displaySettings: { /* ... */ }
16        }
17      ]}
18
19      // Debug options
20      showBboxes={false}
21      showCanvasLabels={false}
22
23      // Single event handler
24      onEvent={(event, data) => {
25        if (event === 'state:ready') console.log('Engine ready!');
26        if (event === 'metadata:loaded') console.log('Loaded:', data.schemaVersion);
27        if (event === 'scene:enter') console.log('Scene changed:', data);
28      }}
29    />
30  );
31}

Events Reference Player Methods Styling Guide

Props Reference