Skip to content

Player API

Protocol

The direct API and structured message bridge use anuva/bento-player version 1.0.0. Message requests include an exact protocol version, non-empty request ID, command, and command payload. The bridge accepts only the configured origin and parent window source.

Lifecycle

The player lifecycle is:

empty -> loading -> ready
                 -> failed

load validates and materializes a presentation, emits ready, renders time zero, waits for fonts and external assets, then emits assets-ready and resolves with lifecycle ready. A failed load leaves lifecycle failed; a subsequent valid load may recover it. A newer concurrent load supersedes the older request, releases its player-local asset URLs, and returns LOAD_CANCELLED to the older caller without corrupting the winning lifecycle. Loading and failed states clear and hide the render root so stale content cannot be mistaken for capturable output.

Commands

Command Contract
load Validate and load an immutable presentation. Resolve only after player and asset readiness.
reset Rebuild the loaded surface at absolute time zero.
seek Rebuild at any non-negative absolute millisecond, including backwards.
tick Advance to a non-decreasing absolute millisecond. Backwards ticks fail.
show Set the current surface visible.
hide Set the current surface hidden.
clear Remove the current slide while retaining a loaded recoverable player.
fragment Set a stable fragment ID visible or hidden on its active slide.
diagnostics Return versions, lifecycle, state, readiness, assets, and requests without mutation.

reset, seek, and tick derive state from the immutable contract. Manual show, hide, clear, or fragment changes remain until the next absolute-state rebuild.

Events

Events include runtime, player, surface, and presentation identity plus absolute time where applicable:

  • ready;
  • assets-ready;
  • state-changed;
  • animation-complete; and
  • error.

Responses echo the request ID. Every command-originated event also carries that request ID, allowing hosts to correlate event ordering with the response. Errors return a stable code and safe message; contract errors also include structured validation issues.

Deterministic feature set

Version 1.0.0 supports:

  • none and fixed-duration fade slide transitions;
  • ordered opacity enter animations;
  • stable fragments;
  • absolute surface visibility and clear actions;
  • charts whose data is externally materialized; and
  • media paused and sought from absolute slide time.

Morph, loop, ambient, count-up, unseekable media, and other wall-clock behavior are rejected during validation or load.