MP4EDocs
Open Studio

Player Methods

Imperative methods available via the player ref.

Overview

While most interactions are handled through props and callbacks, you can also control the player imperatively using a ref. This is useful for building custom controls, triggering actions from external UI, and advanced integrations.

Current Status

Imperative Ref API
The player exposes a comprehensive imperative API via a React ref covering playback, variables, actions, scenes, objects, and viewer preferences.

The player currently supports:

  • Props: Configure via src, metadata, objectGroups, etc.
  • Callbacks: React to events via onEngineReady, onSceneChange, onPlaybackRestricted
  • Actions: The engine executes actions defined in rules and plugin event handlers

See the Props Reference for currently available options.

Ref API

Access player methods through a React ref:

Using the Ref

Player ref usage
1import { useRef } from 'react';
2import { MP4EPlayer, type MP4EPlayerRef } from '@mp4e/react';
3import '@mp4e/react/styles.css';
4
5function App() {
6  const playerRef = useRef<MP4EPlayerRef>(null);
7
8  const handlePlayPause = () => {
9    if (playerRef.current?.isPaused()) {
10      playerRef.current.play();
11    } else {
12      playerRef.current?.pause();
13    }
14  };
15
16  const handleSeekTo10Seconds = () => {
17    playerRef.current?.seek(10);
18  };
19
20  const handleLogState = () => {
21    console.log('t=', playerRef.current?.getCurrentTime());
22    console.log('frame=', playerRef.current?.getCurrentFrame());
23  };
24
25  return (
26    <div>
27      <MP4EPlayer
28        ref={playerRef}
29        src="/video.mp4"
30        onEvent={(event) => { if (event === 'state:ready') console.log('Ready!'); }}
31      />
32
33      <div className="controls">
34        <button onClick={handlePlayPause}>Play/Pause</button>
35        <button onClick={handleSeekTo10Seconds}>Seek to 10s</button>
36        <button onClick={handleLogState}>Log state</button>
37      </div>
38    </div>
39  );
40}

Playback Methods

Control video playback programmatically.

play()async

Starts or resumes video playback.

Returns: Promise<void>

await playerRef.current?.play();
pause()

Pauses video playback.

Returns: void

playerRef.current?.pause();
seek(time)(time: number)

Seeks to the specified time in seconds.

Returns: void

playerRef.current?.seek(30.5);
seekToFrame(frame)(frame: number)

Seeks to the specified frame number.

Returns: void

playerRef.current?.seekToFrame(750);
seekSilently(timeSeconds)(timeSeconds: number)

Seeks without triggering engine seeked rules (prevents loops).

Returns: void

playerRef.current?.seekSilently(12.0);
setPlaybackRate(rate)(rate: number)

Sets the playback speed. Range: 0.25 to 4.0.

Returns: void

playerRef.current?.setPlaybackRate(1.5);
setVolume(volume)(volume: number)

Sets the volume level. Range: 0.0 to 1.0.

Returns: void

playerRef.current?.setVolume(0.8);
mute()

Mutes audio.

Returns: void

playerRef.current?.mute();
unmute()

Unmutes audio.

Returns: void

playerRef.current?.unmute();

State Methods

Query current player state.

getCurrentTime()

Returns the current playback time in seconds.

Returns: number

const time = playerRef.current?.getCurrentTime(); // 30.5
getCurrentFrame()

Returns the current frame number.

Returns: number

const frame = playerRef.current?.getCurrentFrame(); // 763
getDuration()

Returns the total video duration in seconds.

Returns: number

const duration = playerRef.current?.getDuration(); // 120
isPaused()

Returns whether the video is paused.

Returns: boolean

const paused = playerRef.current?.isPaused(); // false
isMuted()

Returns whether the audio is muted.

Returns: boolean

const muted = playerRef.current?.isMuted(); // false
getVolume()

Returns the current volume level (0-1).

Returns: number

const volume = playerRef.current?.getVolume(); // 0.8
getPlaybackRate()

Returns the current playback rate.

Returns: number

const rate = playerRef.current?.getPlaybackRate(); // 1.0
isFullscreen()

Returns whether the player is in fullscreen mode.

Returns: boolean

const fs = playerRef.current?.isFullscreen(); // false

Metadata & State

Access and reload metadata, check a document for problems before applying it, and query playback loop boundaries.

reloadMetadata(newMetadata?)(newMetadata?: MP4EMetadata | null)

Reload metadata without full destroy/reinit. When the engine is already initialized, this performs a soft reload that preserves DOM (no iframe recreation or visible flash) and carries playback position, variable values, running timers, counters, and the current scene through the swap for ids that still exist in the new document. On a file that streams its object tracking, the tracking already loaded is kept too when the new document's tracking is unchanged (as on every overrides change), so nothing is fetched again. If newMetadata is omitted, the current metadata prop is re-applied. The returned promise resolves once the new document has been applied and rendered — await it when you need to know the swap has landed, or ignore it for fire-and-forget calls.

Returns: Promise<void>

// Soft reload with updated metadata await playerRef.current?.reloadMetadata(updatedMetadata); // Re-apply current metadata prop playerRef.current?.reloadMetadata();
getEffectiveMetadata()

Returns the view of the loaded document, with your overrides already merged in — the same value the metadata:loaded event carries. The view holds schemaVersion, videoDetails (fps, width, height, durationSeconds), layers (id, name, order and their overlays — each overlay with id, layerId, type, name, overlayCategory, position, size, config, opacity, zIndex), audioTracks, media, thumbnails, objectCount and timeline.mode ('chunked' when the file streams its object tracking, else 'full'). It does not include objects, variables, rules, scenes or plugins — read variables with getVariable() / getVariables(). Returns null until a document has been loaded.

Returns: MetadataView | null

const view = playerRef.current?.getEffectiveMetadata(); if (view) { console.log('Frame rate:', view.videoDetails.fps); console.log('Layers:', view.layers.map((layer) => layer.name)); console.log('Overlays:', view.layers.flatMap((layer) => layer.overlays).map((o) => o.id)); console.log('Tracked objects:', view.objectCount); }
diagnose(metadata)(metadata: MP4EMetadata)async

Runs the engine's diagnostics over a metadata document and returns every problem it would hit or silently skip when running it — dangling references, unparseable conditions or variables, unknown types, impossible frame ranges, structural shapes the engine drops, plugin config that contradicts the plugin's schema, and templates that resolve to nothing. The document is checked in isolation: nothing is loaded and player state is untouched, so this is safe to call on a candidate document before applying it. An empty array means the document is clean. Each finding carries a severity (error / warning / info), a stable namespaced code and dotted path, a human-readable message, the owning entity, and — where one exists — suggested replacements. The findings from the document the player actually loaded arrive on their own via the metadata:diagnostics event.

Returns: Promise<DiagnosticFinding[]>

const findings = (await playerRef.current?.diagnose(candidateMetadata)) ?? []; const blocking = findings.filter(f => f.severity === 'error'); if (blocking.length) { console.table(blocking.map(f => ({ code: f.code, path: f.path, hint: f.suggestions?.[0] }))); }
getPlaybackStart()

Returns the playback loop start time in seconds. This is the time the video will seek to when looping or when setPlaybackStart has been applied via rules.

Returns: number

const loopStart = playerRef.current?.getPlaybackStart(); // 0
getPlaybackEnd()

Returns the playback loop end time in seconds. Returns -1 if no end boundary is set (plays to the end of the video).

Returns: number

const loopEnd = playerRef.current?.getPlaybackEnd(); // -1 (no limit)

Variable Methods

Read and modify engine variables. The setVariable method triggers the engine's rules pipeline, so any rules listening for variable changes will fire.

setVariable(variableId, value)(variableId: string, value: any)

Sets a variable value at runtime. This goes through the engine, so any rules with variable-change conditions will trigger. Plugins listening via onVariableChange will also be notified.

Returns: void

// Set a simple variable playerRef.current?.setVariable('cartCount', 5); // Set an object variable playerRef.current?.setVariable('selectedProduct', { id: 'prod_123', name: 'Blue T-Shirt', price: 29.99, });
getVariable(variableId)(variableId: string)

Returns the current value of a variable. Returns undefined if the variable doesn't exist.

Returns: any

const score = playerRef.current?.getVariable('score'); // 42 const name = playerRef.current?.getVariable('userName'); // 'Alice'
getVariables()

Returns a snapshot of all variables as a plain object. Keys are variable IDs, values are current values.

Returns: Record<string, any>

const vars = playerRef.current?.getVariables(); console.log(vars); // { score: 42, userName: 'Alice', cartCount: 3 }

Action Methods

Execute actions and send events programmatically from host code.

executeAction(action)(action: any)

Executes a single action programmatically. Convenience wrapper around executeActions.

Returns: void

playerRef.current?.executeAction({ type: 'pause' }); playerRef.current?.executeAction({ type: 'showOverlay', overlayId: 'promo-banner' });
executeActions(actions)(actions: any[])

Executes an array of actions programmatically. Actions are processed through the engine's action executor, so all engine-side effects (variable changes, rule triggers, playback events) apply as if the actions were triggered by a rule.

Returns: void

playerRef.current?.executeActions([ { type: 'pause' }, { type: 'showOverlay', overlayId: 'promo-banner' }, { type: 'setVariable', variableId: 'promoShown', value: true }, ]);
notify(event, data?)(event: string, data?: any)

Sends an event into the engine. This is the universal event entry point — any rules listening for the specified event will fire. Useful for custom host-originated events that drive rule logic.

Returns: void

// Notify the engine of a custom event playerRef.current?.notify('custom:purchase', { productId: 'abc', amount: 29.99, }); // Notify of a standard event playerRef.current?.notify('overlay:click', { overlayId: 'cta-button', });

Scene Methods

Navigate between scenes and query scene state.

goToScene(sceneId)(sceneId: string)

Navigates to the specified scene. The engine resolves the scene's start time and seeks the video accordingly. Any scene exit/enter rules will fire.

Returns: void

playerRef.current?.goToScene('chapter-2'); playerRef.current?.goToScene('quiz-scene');
setPlaybackPath(groupId)(groupId: string) => Promise<PlaybackPathResult>

Plays only the scenes of one scene group. The progress bar shows the path's duration, every seek stays inside the path, gaps between scenes are skipped, and playback pauses at the end of the last scene. Authored rules keep seeing media time; controls see presentation time.

Returns: Promise<{ ok: true, state } | { ok: false, error: { code, message, groupId } }>

const res = await playerRef.current?.setPlaybackPath('scenegroup_short'); if (!res?.ok) console.warn(res?.error.code); // playbackPath.invalidGroup | playbackPath.locked | playbackPath.emptyAfterBounds
clearPlaybackPath()() => Promise<PlaybackPathResult>

Returns to the full timeline. The playhead is not moved.

Returns: Promise<PlaybackPathResult>

await playerRef.current?.clearPlaybackPath();
getPlaybackPath()() => Promise<PlaybackPathState | null>

Current playback path: group id, revision, presentation duration and time, current scene, completed and locked flags, initiator, ranges and scenes.

Returns: Promise<PlaybackPathState | null>

const path = await playerRef.current?.getPlaybackPath(); console.log(path?.time, '/', path?.duration);
getSceneGroups()() => Promise<SceneGroupSnapshot[]>

Snapshot of every scene group in metadata order, disabled ones included. Each group carries its scenes (start time, exclusive end time, duration, and, when the video has been analysed, the summary of the chapter that overlaps it most — with the creator's corrections, and none from a chapter the creator hid or kept private), the duration of the group's combined scene ranges, and the scene currently active in that group (null for disabled groups).

Returns: Promise<SceneGroupSnapshot[]>

const groups = await playerRef.current?.getSceneGroups(); for (const g of groups ?? []) console.log(g.name, g.duration, g.activeSceneId);
getCurrentScene()

Returns the ID of the currently active scene, or null if no scene is active.

Returns: string | null

const sceneId = playerRef.current?.getCurrentScene(); console.log('Current scene:', sceneId); // 'chapter-1'

Viewer Preferences

Control privacy and accessibility preferences for the current viewer. These preferences are passed to the engine and affect how plugins behave (e.g., respecting do-not-track, reduced motion, high contrast).

setViewerPreferences(prefs)(prefs: Record<string, any>)

Sets privacy and accessibility preferences for the viewer. Supported keys include doNotTrack, doNotShareIdentity, limitStorage (privacy) and reducedMotion, highContrast (accessibility). Preferences are sent to the engine and made available to plugins.

Returns: void

playerRef.current?.setViewerPreferences({ doNotTrack: true, doNotShareIdentity: false, limitStorage: true, reducedMotion: true, highContrast: false, });
getViewerPreferences()

Returns the current viewer preferences object. Returns an empty object if no preferences have been set.

Returns: Record<string, any>

const prefs = playerRef.current?.getViewerPreferences(); console.log('Do Not Track:', prefs.doNotTrack); // true console.log('Reduced Motion:', prefs.reducedMotion); // true

Display ControlComing Soon

Programmatically show and hide object and overlay display popups. These methods are available on the underlying engine but not yet exposed on the player ref.

showObjectDisplay(objectId?, eventType?, bbox?)(objectId?: string, eventType?: string, bbox?: number[])

Programmatically show an object's display overlay (e.g., tooltip, product card). The eventType determines which display plugin to use (e.g., 'hovered', 'clicked'). The bbox is an optional bounding box [x, y, w, h] in video coordinates for positioning. Showing a display that is already open shows it again.

Returns: void

// Show the hover display for a specific object playerRef.current?.showObjectDisplay('obj_chair_1', 'hovered', [100, 200, 50, 50]); // Show the click display playerRef.current?.showObjectDisplay('obj_chair_1', 'clicked');
hideObjectDisplay(objectId?)(objectId?: string)

Hide an object's display overlay. If objectId is omitted, hides all object displays. A display that opens by itself while its object is on screen (a 'visible' binding) stays closed after this until its object leaves the screen and comes back.

Returns: void

playerRef.current?.hideObjectDisplay('obj_chair_1');
showOverlayDisplay(overlayId?, eventType?, boundObjectId?, bbox?)(overlayId?: string, eventType?: string, boundObjectId?: string | null, bbox?: number[])

Show an overlay's display popup. For group-bound overlays, provide the boundObjectId to target a specific instance. The bbox provides positioning context in video coordinates.

Returns: void

// Show a display for a specific overlay playerRef.current?.showOverlayDisplay('hotspot-1', 'clicked'); // Show for a group-bound overlay instance playerRef.current?.showOverlayDisplay('hotspot-1', 'clicked', 'obj_lamp_3', [300, 150, 80, 60]);
hideOverlayDisplay(overlayId?, boundObjectId?, eventType?)(overlayId?: string, boundObjectId?: string | null, eventType?: string)

Hide an overlay's display popup. For group-bound overlays, provide the boundObjectId to target a specific instance.

Returns: void

playerRef.current?.hideOverlayDisplay('hotspot-1', null, 'clicked');

Layout & Positioning

Inspect and modify overlay layout, coordinate transforms, and container elements.

updateOverlayStyle(overlayId, styles)(overlayId: string, styles: { x?: number; y?: number; width?: number; height?: number })

Dynamically update an overlay's position and/or size at runtime. Values are in the overlay's coordinate units. Only the provided properties are updated; omitted properties remain unchanged.

Returns: void

// Move an overlay playerRef.current?.updateOverlayStyle('cta-button', { x: 200, y: 100 }); // Resize an overlay playerRef.current?.updateOverlayStyle('sidebar', { width: 300, height: 400 }); // Move and resize simultaneously playerRef.current?.updateOverlayStyle('panel', { x: 50, y: 50, width: 250, height: 150 });
getOverlayPositions()

Returns all computed overlay positions as a Map. Each entry maps an overlay ID to its rendered position data including screen coordinates, dimensions, and visibility state.

Returns: Map<string, RenderedOverlayPosition>

const positions = playerRef.current?.getOverlayPositions(); if (positions) { for (const [id, pos] of positions) { console.log(id, pos); } }
getVideoDisplayTransform()

Returns the current video-to-screen coordinate transform. This describes how video-native pixel coordinates map to screen coordinates, accounting for letterboxing, scaling, and aspect ratio. Returns null if the video element is not yet ready.

Returns: VideoDisplayTransform | null

const transform = playerRef.current?.getVideoDisplayTransform(); if (transform) { console.log('Scale:', transform.scaleX, transform.scaleY); console.log('Offset:', transform.offsetX, transform.offsetY); }
getOverlayContainerRef()

Returns the overlay container DOM element. This is the div that contains all overlay iframes and positioned elements. Useful for advanced integrations that need to inject custom DOM alongside overlays.

Returns: HTMLDivElement | null

const container = playerRef.current?.getOverlayContainerRef(); if (container) { console.log('Overlay container dimensions:', container.offsetWidth, container.offsetHeight); }

Object Methods

Query tracked objects and their data.

getVisibleObjects()

Returns objects visible in the current frame, including their bounding boxes, polygons, custom data, and group memberships.

Returns: Array<{ id: string; bbox: number[]; polygon?: number[][]; data?: any; groupIds?: string[] }>

const objects = playerRef.current?.getVisibleObjects(); for (const obj of objects) { console.log(obj.id, obj.bbox, obj.data?.title); }
getObject(objectId)(objectId: string)

Returns object data from the registry by ID. This includes custom data fields defined in the object's group data schema. Returns null if the object doesn't exist.

Returns: any | null

const chair = playerRef.current?.getObject('obj_chair_1'); if (chair) { console.log(chair.label, chair.data?.price); }

Utility Methods

Fullscreen, metadata, and cleanup.

enterFullscreen()async

Enters fullscreen mode.

Returns: Promise<void>

await playerRef.current?.enterFullscreen();
exitFullscreen()async

Exits fullscreen mode.

Returns: Promise<void>

await playerRef.current?.exitFullscreen();
toggleFullscreen()async

Toggles fullscreen mode.

Returns: Promise<void>

await playerRef.current?.toggleFullscreen();
getVideoElement()

Returns the underlying HTMLVideoElement (advanced use only).

Returns: HTMLVideoElement | null

const el = playerRef.current?.getVideoElement();
getCanvasElement()

Returns the overlay canvas element (advanced use only).

Returns: HTMLCanvasElement | null

const el = playerRef.current?.getCanvasElement();

Complete Example

All methods reference
1const playerRef = useRef<MP4EPlayerRef>(null);
2
3// Playback control
4await playerRef.current?.play();
5playerRef.current?.pause();
6playerRef.current?.seek(30);
7playerRef.current?.seekToFrame(750);
8playerRef.current?.setPlaybackRate(1.5);
9playerRef.current?.setVolume(0.8);
10playerRef.current?.mute();
11playerRef.current?.unmute();
12playerRef.current?.seekSilently(12.0);
13
14// Get state
15const time = playerRef.current?.getCurrentTime();     // 30.5
16const frame = playerRef.current?.getCurrentFrame();   // 763
17const duration = playerRef.current?.getDuration();    // 120
18const paused = playerRef.current?.isPaused();         // false
19const muted = playerRef.current?.isMuted();           // false
20const volume = playerRef.current?.getVolume();        // 0.8
21const rate = playerRef.current?.getPlaybackRate();    // 1.5
22const fullscreen = playerRef.current?.isFullscreen(); // false
23
24// Metadata & state
25const view = playerRef.current?.getEffectiveMetadata(); // the loaded document's view
26playerRef.current?.reloadMetadata(updatedMetadata);
27const loopStart = playerRef.current?.getPlaybackStart();
28const loopEnd = playerRef.current?.getPlaybackEnd();
29
30// Variables
31playerRef.current?.setVariable('cartCount', 5);
32const score = playerRef.current?.getVariable('score');       // 42
33const allVars = playerRef.current?.getVariables();           // { score: 42, ... }
34
35// Actions
36playerRef.current?.executeAction({ type: 'pause' });
37playerRef.current?.executeActions([
38  { type: 'showOverlay', overlayId: 'promo-banner' },
39  { type: 'setVariable', variableId: 'promoShown', value: true },
40]);
41playerRef.current?.notify('custom:purchase', { productId: 'abc' });
42
43// Scenes
44playerRef.current?.goToScene('chapter-2');
45const scene = playerRef.current?.getCurrentScene();          // 'chapter-1'
46
47// Objects
48const visible = playerRef.current?.getVisibleObjects();      // [{ id, bbox, ... }]
49const chair = playerRef.current?.getObject('obj_chair_1');   // { label, data, ... }
50
51// Viewer preferences
52playerRef.current?.setViewerPreferences({
53  doNotTrack: true,
54  reducedMotion: true,
55});
56const prefs = playerRef.current?.getViewerPreferences();
57
58// Layout & positioning
59const transform = playerRef.current?.getVideoDisplayTransform();
60const positions = playerRef.current?.getOverlayPositions();
61playerRef.current?.updateOverlayStyle('overlay-1', { x: 100, y: 200 });
62const container = playerRef.current?.getOverlayContainerRef();
63
64// Fullscreen
65await playerRef.current?.enterFullscreen();
66await playerRef.current?.exitFullscreen();
67await playerRef.current?.toggleFullscreen();
68
69// Elements (advanced)
70const videoEl = playerRef.current?.getVideoElement();
71const canvasEl = playerRef.current?.getCanvasElement();

Related

Events ReferenceProps ReferenceActions Reference
Previous
Events & Callbacks
Next
Styling & Themes