JavaScript, RiffPress

How a script talks to the player. window.riff is set before the riff.ready action fires. Everything here is public and keeps working within a major version.

`window.riff`

Properties

Name	Description
version	The version of this api: 1.
strings	The player's strings, after the `riff_strings` filter.

Methods

Name	Description
play()	Makes `tracks` the queue and plays the one at `index`.
toggle()	Plays or pauses.
next()	Skips to the next track.
prev()	Goes back a track, or to the start of this one.
seek()	Moves the current track to a time.
open()	Opens Now Playing.
close()	Closes Now Playing.
mount()	Reads every `figure[data-riff-track]` on the page again, after content was swapped in.
current()	The track playing.
queue()	The queue in play order.
playing()	Whether something is playing.
on()	Listens to one of the player's actions, without `wp-hooks`.

window.riff.version

The version of this api: 1.

Type: number

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.strings

The player's strings, after the riff_strings filter.

Type: Object<string, string>

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.play( tracks, index = 0, options )

Makes tracks the queue and plays the one at index.

The tracks go through the riff.queue and riff.track filters first.

Parameters

tracksObject[]Required

Tracks, in the shape Tracks::schema() describes.

indexnumberOptional

The one to play first. Default 0.

optionsObjectOptional

Options.

shuffleboolean
true or false sets shuffle before playing.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.toggle()

Plays or pauses.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.next()

Skips to the next track.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.prev()

Goes back a track, or to the start of this one.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.seek( seconds )

Moves the current track to a time.

Parameters

secondsnumberRequired: From the start of the track.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.open()

Opens Now Playing.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.close()

Closes Now Playing.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.mount()

Reads every figure[data-riff-track] on the page again, after content was swapped in.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.current()

The track playing.

Return

Object|null The track, or null.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.queue()

The queue in play order.

Return

Object[] Tracks.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.playing()

Whether something is playing.

Return

boolean True while a track plays.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

window.riff.on( name, fn )

Listens to one of the player's actions, without wp-hooks.

Parameters

namestringRequired: The action without its prefix: track, play, pause and the rest.
fn(detail: Object, api: Object) => voidRequired: Called with the detail and the api.

Return

() => void Stops listening.

Since 4.0.0plugins/riff/assets/riff.jsView on GitHub

Each change of state is announced twice with the same detail: through wp.hooks as riff.<name>, for scripts that depend on wp-hooks, and as a riff:<name> CustomEvent on #riff that bubbles, for everything else. The filters run only through wp.hooks.

Name	Description
riff.queue`filter`	Filters the tracks about to become the queue.
riff.shortcuts`filter`	Filters whether the single-key shortcuts (Space, K, J, L) act on a key press.
riff.track`filter`	Filters one track as a queue is set, after `riff.queue`.
riff.action`action`	Fires when a control an extension added through `riff_chips` or `riff_bar_controls` is pressed.
riff.close`action`	Fires when Now Playing closes.
riff.ended`action`	Fires when a track plays to its end, before the next one loads.
riff.open`action`	Fires when Now Playing opens.
riff.pause`action`	Fires when the track pauses.
riff.play`action`	Fires when the track starts or resumes playing.
riff.ready`action`	Fires once the player is set up, its state restored and `window.riff` available.
riff.track`action`	Fires when a track is loaded, before it plays.

wp.hooks.addAction( 'riff.track', 'my-plugin', ( detail, riff ) => {
	console.log( detail.track.title );
} );

window.riff.on( 'play', ( detail ) => {} );
document.getElementById( 'riff' ).addEventListener( 'riff:pause', ( e ) => e.detail );

A track

Every track the player takes or hands back is the shape Tracks::schema() describes in PHP; the PHP reference lists every property. The REST API returns the same shape.

Controls

Add a chip under Now Playing or a control at the end of the bar from PHP, with the riff_chips or riff_bar_controls filter, then handle the press with the riff.action action.

add_filter( 'riff_chips', function ( array $chips ): array {
	$chips['lyrics'] = array(
		'label'  => __( 'Lyrics', 'my-plugin' ),
		'action' => 'my-plugin-lyrics',
		'svg'    => '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="…"/></svg>',
	);
	return $chips;
} );

wp.hooks.addAction( 'riff.action', 'my-plugin', ( { action, track } ) => {
	if ( action === 'my-plugin-lyrics' ) {
		showLyrics( track );
	}
} );

Loading your script

The player is an ES module with no dependencies. A script that uses wp.hooks depends on wp-hooks; one that only uses window.riff or the events can load however it likes, and should wait for riff.ready (or check window.riff) before calling anything.