Overview

Seeking methods let consumers position playback at a specific time. Every seek dispatches beforeSeek first, and listeners may preventDefault() to cancel. seekPrevented fires instead of seek/seeked when a seek is cancelled.

time(t?, opts?)

Get or seek to a playback position in seconds.

Read: time() returns the current position as a number.

Write: time(t, opts?) dispatches beforeSeek; if not prevented, runs a seeking phase round-trip, updates position, emits seek then seeked, and forwards to the backend. Negative values are clamped to 0.

Returns: number (read) or Promise<void> (write)

Events emitted: beforeSeek → seek → seeked (or seekPrevented)

// read
const pos = player.time(); // seconds

// seek to 2:30
await player.time(150);

// seek attributed to a remote sync command
await player.time(150, { source: 'remote' });

seekByPercentage(pct, opts?)

Seek to a position expressed as a percentage (0–100) of the total duration.

pct is clamped to [0, 100]. No-op when duration is zero or non-finite (metadata not yet loaded). Delegates to time() so beforeSeek fires and the full seek cycle applies.

// seek to the halfway point
player.seekByPercentage(50);

// build a progress bar scrubber
seekBar.addEventListener('input', (event) => {
  const pct = Number((event.target as HTMLInputElement).value);
  player.seekByPercentage(pct);
});

rewind(seconds?, opts?)

Seek backwards by seconds (default 5). Clamps the result to 0, so rewinding past the start lands at the start.

Events emitted: beforeSeek (with negative delta time) → seek → seeked

forward(seconds?, opts?)

Seek forwards by seconds (default 5). No upper clamp.

See also

• Time, duration, buffered, timeData
• Transport, restart, rewind, forward
• Events Reference, beforeSeek, seek, seeked, seekPrevented