Player reference

Taken from js/player/src/element.js, play.js and player.js, the types in js/player/types and js/react on commit 79b96c7 of the SDK repository. If a value here disagrees with the package you installed, the package wins; this page is checked against the source of the release it ships with.

How to use the player is in Embed the player. The full generated API of every module, including internals this page leaves out, is docs/api/JS-API.md in the SDK repository (generated by tools/jsapi.mjs).

There are three layers, each a thin shell over the next:

The @nearglass/react component wraps the element (React props).

The nearglass-player elementCopy Anchor Link

Load it once with import '@nearglass/player/element.js'; or a <script type="module">. Importing it defines the tag. The element needs one of: token-url, a descriptor property, or api with stream and publishable-key. With none of them the bar reads "Set token-url, or api, stream and publishable-key." and nothing starts.

AttributesCopy Anchor Link

Changing any attribute restarts the player (once per task, however many you set), except background-audio, which changes on the running player.

PropertiesCopy Anchor Link

MethodsCopy Anchor Link

EventsCopy Anchor Link

Events fire on the element and carry their data in detail.

StylingCopy Anchor Link

The shadow DOM has these parts, for ::part():

The element is display: block (and hidden by the hidden attribute), and inherits the page's font. The picture is 16:9. Nothing is drawn over it.

What the bar saysCopy Anchor Link

The mode label reads "Low latency" for moq and a "Compatibility mode" label for ll-hls. The sound button reads "Sound on" while muted and "Sound off" while playing.

play()Copy Anchor Link

import { play } from '@nearglass/player/play.js';

const p = play({ api: 'https://api.nearglass.com', stream: 'st_...', publishableKey: 'pk_...', canvas, video });
p.on('state', (state, info) => {});
p.join();
p.close();

play() returns a controller at once and starts on the next microtask, so listeners added straight after the call miss nothing.

OptionsCopy Anchor Link

Give exactly one way to be admitted: api with stream and publishableKey, or tokenUrl, or descriptor.

The controllerCopy Anchor Link

StatesCopy Anchor Link

Other eventsCopy Anchor Link

Timing constantsCopy Anchor Link

The deadlines apply to the start only. A stall after MoQ has played is the engine's to recover; it is not a reason to fall back.

A seat is kept by a heartbeat to its play_url every heartbeat_ms of the descriptor (5000 when it names none). A hidden tab says so in the heartbeat, and a tab that comes back beats at once. When the page closes, a beacon gives the seat up.

Fallback reasonsCopy Anchor Link

A permanent reason goes to LL-HLS at once and stays. For the others the player keeps trying MoQ and switches back at the first live frame. The engine itself also reports network after a stretch without frames; play() does not act on it.

Sound statesCopy Anchor Link

The audio event (and the element's audiochange) carries state:

A hidden page without backgroundAudio turns the sound off, and it stays off until the viewer taps the sound control. That tap is also the gesture iOS needs to play.

createPlayerCopy Anchor Link

createPlayer(opts) is the playback engine: one MoQ session at a time, with decode on arrival, the live-edge guard, token renewal, renditions and sound. It draws on a canvas and has no other UI. Use it when you do your own admission; play() calls it for you.

import { createPlayer } from '@nearglass/player/player.js';

createPlayer optionsCopy Anchor Link

Options that play() fills in itself (relay, relayFull, certHash, tokens, namespace, track, canvas, backgroundAudio) are listed first. Everything else can be given to play() through its player option.

Other options exist for tests and measurements (audioRenderWatchMs); they are not part of the supported surface.

Presentation modesCopy Anchor Link

Player methodsCopy Anchor Link

Player eventsCopy Anchor Link

Listeners receive one argument.

Other exportsCopy Anchor Link

The descriptorCopy Anchor Link

play() and createPlayer read the control API's descriptor JSON (the Descriptor schema). The fields the player uses:

React propsCopy Anchor Link

@nearglass/react exports NearglassPlayer, useNearglassPlayer and ELEMENT_TAG. React 18 or later is a peer dependency. NearglassPlayer renders the element and forwards a ref to it.

There is no prop for audiochange; add a listener to the element through the ref.

useNearglassPlayer(ref) follows an element and returns { state, info, mode, label, note }: state starts as idle and is the last statechange state, info is that event's detail, mode and label come from modechange (none and an empty string at first), and note is the last status text.