SttPlayer

SttPlayer is the HTMLMediaElement-shaped facade over the TimeController and the PlaybackGovernor — the recommended single entry point for playback. Underneath sit a dumb rAF clock, a buffering state machine, and the BufferSource oracle; the facade owns the choreography of coordinating them:

• One driver. Play/pause/seek/scrub all route through the governor's gates; speed routes through the controller — and you never have to remember which is which (or that calling controller.play()/setTime() directly bypasses the gates).
• The baseRate × playbackRate speed model. Video's literal 1× is meaningless for sim time; the data-player convention is a per-dataset base rate ("the dataset plays in its target duration") with a user-facing multiplier on top. The facade owns that split.
• A throttled timeupdate. Media elements fire timeupdate at ~4 Hz; the facade does the same (configurable), with an immediate emit whenever the clock freezes or a seek lands — so UIs never rest on a stale frame, and React consumers don't re-render at 60 Hz. The internal clock still advances every animation frame; layers read it directly.

The wrapped pieces stay exposed (player.timeController for layer wiring, player.governor for advanced use), so nothing the lower-level APIs can do is lost.

Installation#

import { SttPlayer } from '@poopdeck.gl/playback';

Quick start#

const player = new SttPlayer({
  timeRange: { start, end },
  baseRate: (end - start) / 60_000, // dataset plays in ~60 s at 1×
  loop: true,
});

new AnimatedTripsLayer({
  data: manifestUrl,
  // Layers READ the clock; the player drives it.
  timeController: player.timeController,
  // The tileset is the governor's BufferSource — hand it over when it arrives:
  onTilesetReady: (tileset) => player.setSource(tileset),
  // Buffer events re-evaluate gates immediately (vs the 250 ms poll):
  onBufferChange: (runway) => player.notifyBufferChange(runway),
});

playButton.onclick = () => (player.paused ? player.play() : player.pause());

// Scrubbing: preview is free, release commits a seek.
slider.onpointerdown = () => player.beginScrub();
slider.oninput = (e) => player.scrubTo(+e.target.value);
slider.onpointerup = (e) => player.endScrub(+e.target.value);

// UI feedback — media-element shaped:
player.on('timeupdate', (t) => updateSlider(t)); // ~4 Hz + final snap
player.on('play', () => setGlyph('pause'));
player.on('pause', () => setGlyph('play'));
player.on('waiting', ({ etaMs }) => showSpinner(etaMs));
player.on('ready', () => hideSpinner());
player.on('ended', () => showReplayAffordance());

HTMLMediaElement mapping#

Constructor#

new SttPlayer(options: SttPlayerOptions)

Methods and properties#

Playback#

Everything in the mapping table above, plus:

Scrubbing#

beginScrub() / scrubTo(time) / endScrub(time) — preview-vs-commit passthroughs to the governor (grab freezes the clock; previews render resident tiles with no fetch churn; release commits a real seek). The readonly seekSettleMs field is the shared settle-debounce knob for UIs that commit a rested thumb mid-drag. The isScrubbing getter is true while the thumb is held (beginScrub … endScrub) — a passthrough to governor.isScrubbing.

Plumbing and queries#

Events#

const unsubscribe = player.on('timeupdate', (time) => {});
player.on('play', () => {}); // intent became "playing" (incl. adopted external play)
player.on('pause', () => {}); // intent became "paused" (incl. external pause / range-end clamp)
player.on('statechange', (state) => {});
player.on('waiting', ({ state, etaMs }) => {});
player.on('ready', ({ degraded }) => {});
player.on('progress', (runway) => {});
player.on('ended', (time) => {});
player.on('ratechange', (rate) => {});
player.on('scrubstart', (time) => {}); // scrubber grabbed (payload: playhead at the grab)
player.on('scrubend', (time) => {}); // scrubber released (payload: committed position)

on() returns an unsubscribe function; off(event, callback) also works. At a non-looping range end, 'pause' fires before 'ended' (media-element ordering). 'scrubstart' / 'scrubend' re-emit the governor's scrub bracket (see PlaybackGovernor events).

Speed model#

effective clock speed (sim-ms per wall-ms) = baseRate × playbackRate

Pick baseRate so the dataset plays in a target wall duration (span / targetMs); expose playbackRate to the user as the 0.25×–10× control. For Auto speed, feed getAutoSpeedMultiplierSuggestion() through decideAutoSpeedMultiplier on a cadence + on 'waiting' — see the governor docs for the asymmetric policy.

Source#

packages/playback/src/stt-player.ts · underlying pieces: TimeController, PlaybackGovernor