Skip to main content

window.benecasterFrontend.seek()

Utilities Free 
window.benecasterFrontend.seek( episodeId: number | null, seconds: number, options?: { play?: boolean } ): boolean

A JavaScript function, not a PHP one. Moves an episode’s player on the page to a moment and, by default, starts it playing. It is what an interactive transcript calls when a listener clicks a line, and what [benecaster_timestamp] is built on. It works with whichever of Benecaster’s player surfaces rendered the episode — [benecaster_player], [benecaster_episodes], the episode page or an archive card — including a theme override that renamed the classes, and with audio and video alike. An embedded player (an iframe from YouTube, Spotify and the like) cannot be moved from the page and is never chosen.

It is strict about the episode. An episodeId whose player is not on the page answers false and moves nothing; it never falls back to another episode’s player. A caller that wants that fallback calls seek( null, … ) itself.

Following along: the benecaster:timeupdate event. Benecaster fires this DOM event on its own players’ media elements whenever the browser fires timeupdate (several times a second while playing) and after every seek, so a highlight follows the scrubber while paused too. It bubbles, so listen on document or any container. event.detail carries episodeId (a number; 0 when the player’s markup carries no episode ID), currentTime and duration in seconds (duration is NaN until the file’s metadata has loaded), paused, and media — the element itself. Any other <audio> or <video> on the page fires nothing, and players added after the page loaded are covered.

Parameters

Name Type Default Required Description
episodeId number|null — Yes The episode whose player to move. null (or 0) means the first Benecaster player on the page, in document order.
seconds number — Yes Where to move to, in seconds — a finite number of zero or more.
options { play?: boolean } { play: true } No play defaults to true; pass { play: false } to move without starting playback.

Return Value

Type: boolean

true when a player was found and moved. false when that episode has no player on the page, seconds is not a finite number of zero or more, or the browser refused the seek.

Example

// Jump episode 42's player to 1:23 and play.
window.benecasterFrontend?.seek( 42, 83 );

// Move it without starting playback.
window.benecasterFrontend?.seek( 42, 83, { play: false } );

// Follow the player: fires during playback and after every seek.
document.addEventListener( 'benecaster:timeupdate', ( event ) => {
    const { episodeId, currentTime } = event.detail;
    if ( 42 === episodeId ) {
        highlightLineAt( currentTime );
    }
} );

Notes

It changes where a player is, never what it plays. A visitor without access hears only what Benecaster already gave their player — the preview clip, if there is one.

A browser that blocks autoplay rejects the play quietly; the seek itself still lands. It works before the file has loaded: the browser starts from that point when it does.

Needs the benecaster-frontend script on the page. [benecaster_player] loads it; the episode page and the archive do not on their own, so list benecaster-frontend as a dependency of your own script. The handle is registered on every front-end request. Worked example: the recipe Follow along with an episode as it plays.

Need this built rather than just documented? See our services →