PHP

Hooks

Every filter and action has a page of its own, generated from the docblock above the line it fires on. All hooks, PHP and JavaScript, are searchable in one list.

Filters

Actions

Functions

The bar's controls and Now Playing's views are registered on the server, as WordPress registers blocks, so the page has every button and every view before any script runs. Register them on the riff_register action; Riff registers its own there too, and any of them can be taken away. In the browser, window.riff.view() and window.riff.control() give each what it does, by its id. How the player works has the whole of it.

add_action( 'riff_register', function () {
	riff_register_view( 'credits', array(
		'label' => __( 'Credits', 'my-plugin' ),
		'icon'  => '<svg viewBox="0 0 24 24">…</svg>',
		'order' => 32,
	) );
} );

Sources

A source answers three questions: which posts it can read, what tracks a post holds, and how those tracks render as blocks the player takes over. The library asks every source; the first that claims a post reads it.

A plugin adds its own post type or catalogue by implementing Riff\Source and registering it on init; the library, the REST routes and the player then read it like any other.

add_action( 'init', function () {
	Riff\Sources::register( new My_Catalogue_Source() );
} );

The Riff\Source interface

The track schema

One shape for a track: the REST field and routes, the block markup and the player script all use it, and WPGraphQL carries all of it. It is Riff\Tracks::schema(), version 1, and a track still matches it after the riff_track filter.

Block Bindings

riff/track (“Riff track”) is a Block Bindings source: a Heading or Paragraph bound to it shows a track's details, and an Image bound to it shows the cover, with no Riff block on the page. The binding's key picks the detail and id names the attachment; with no id, it is the post's first track. Every value is the track as the track schema has it, after riff_track, and a named track shows only where the media route would show it. In the editor the block shows that it is bound; the value is filled on the front end.

<!-- wp:heading {"metadata":{"bindings":{"content":{"source":"riff/track","args":{"key":"title","id":123}}}}} -->
<h2 class="wp-block-heading"></h2>
<!-- /wp:heading -->

<!-- wp:image {"metadata":{"bindings":{"url":{"source":"riff/track","args":{"key":"cover","id":123}}}}} -->
<figure class="wp-block-image"><img src="" alt=""/></figure>
<!-- /wp:image -->

Abilities

Through the Abilities API, AI tools and other plugins list the library and keep a listener's likes and playlists. Each ability runs its riff/v1 route as a REST request, so it answers what the route answers and is allowed what the route allows; the ones about likes, history and playlists need a signed-in user. Nothing plays through an ability: playback happens in a browser.

$albums = wp_get_ability( 'riff/albums' )->execute( array( 'search' => 'Compositions' ) );

The Listen block

riff/app: Your music library and the player, on this page. Every post with audio or video is listed, and the music keeps playing while you browse. One per page. It supports align, color, typography, spacing, __experimentalBorder, shadow.

<!-- wp:riff/app {"align":"full"} /-->

Anywhere blocks are not an option, the [riff] shortcode does the same.