MP4E Studio - Interactive Video Editor

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`	-	Override the embedded metadata. Usually not needed - the player automatically extracts metadata from the MP4 file.
`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). Applied once per src (uses a silent seek to avoid rule loops on load).

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`	Enable/disable all mouse interaction with objects.
`controls`	`boolean`	`true`	Show built-in playback controls (play/pause, seek, volume, fullscreen).

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>`	-	Deep-merge partial metadata into the video at runtime. Injects host layers, plugins, variables, and settings without modifying the .mp4 file. See Overrides page.
`config`	`MP4EConfig`	-	Host behavior configuration — sandbox rules, action gating, plugin security, disabled content. See Configuration page.
`trustContent`	`boolean`	`false`	Trust all plugin content. Sets sandbox to allow-same-origin for all plugins. Use 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. Useful for analytics or logging.
`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.
`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' \| 'none'`	`'none'`	Visualize object tracking data. Useful for debugging detection quality.

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