PHP, RiffPress

Riff is built the way a feature plugin is: one track shape everywhere, read through WordPress's own APIs. Everything here is public and keeps working within a major version; anything that has to go is deprecated for a release first.

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

Filter	Description
riff_accent	Filters the player's accent colour, after the theme's own setting.
riff_art_layouts	Filters the layouts a drawn cover picks from: where the record sits. The plugin knows `corner`, `centre` and `horizon`; a layout it does not know draws as `corner`.
riff_art_palettes	Filters the palettes a drawn cover picks from: lists of background, accent and ink.
riff_art_svg	Filters a drawn cover.
riff_bar_controls	Filters the controls at the end of the bar on a wide screen.
riff_chips	Filters the chips under Now Playing's controls.
riff_enabled	Filters whether Riff's player loads on the current front-end request.
riff_library_item	Filters a post as the library lists it.
riff_library_query	Filters the query behind the library: which posts the app lists.
riff_player_data	Filters the data handed to the player script: strings, and the addresses of scripts a feature wants loaded, such as the Listen feature's app on the page that holds its block.
riff_sources	Filters the sources tracks are read from, keyed by id.
riff_strings	Filters the strings the player shows.
riff_track	Filters a track before the player reads it.

Actions

Action	Description
riff_after_player	Fires after the player's markup.
riff_before_player	Fires before the player's markup.

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

public function id(): string

A short id, such as "blocks".

Return

string

Since 4.0.0plugins/riff/src/interface-source.phpView on GitHub

public function supports( WP_Post $post ): bool

Whether this source can read the post.

Parameters

$postWP_Post: Post.

Return

bool

Since 4.0.0plugins/riff/src/interface-source.phpView on GitHub

public function tracks( WP_Post $post ): array

The tracks in the post, in order, in the shape Tracks::schema() describes.

Parameters

$postWP_Post: Post.

Return

array[]

Since 4.0.0plugins/riff/src/interface-source.phpView on GitHub

public function html( WP_Post $post ): string

The tracks rendered as figures carrying data-riff-track, which riff.js turns into rows.

Parameters

$postWP_Post: Post.

Return

string

Since 4.0.0plugins/riff/src/interface-source.phpView on GitHub

public function where(): string

A WHERE clause fragment (without a leading AND) matching posts this source can read, or an empty string when the source cannot say from SQL alone.

Return

string

Since 4.0.0plugins/riff/src/interface-source.phpView on GitHub

Riff\Sources::register( Source $source ): void

Registers a source. The core blocks source registers itself at boot; a plugin registers its own on init.

Parameters

$sourceSource: Source.

Since 4.0.0plugins/riff/src/class-sources.phpView on GitHub

Riff\Sources::unregister( string $id ): void

Removes a source.

Parameters

$idstring: Source id.

Since 4.0.0plugins/riff/src/class-sources.phpView on GitHub

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.

Property	Type	Description
`id`	string	The attachment ID, or "url:" and a hash for a file outside the Media Library.
`src`	string
`type`	string (audio, video)
`title`	string
`artist`	string
`album`	string
`duration`	number	Seconds, 0 when unknown.
`format`	string	The container, lower case, as WordPress read it from the file: mp3, flac, m4a. Empty when unknown.
`bitrate`	integer	Kilobits per second, 0 when unknown.
`lossless`	boolean	Whether the encoding is lossless.
`bits`	integer	Bits per sample, as WordPress read it from the file; 0 when the format does not say, as MP3 does not.
`rate`	integer	Samples per second, 0 when unknown.
`levels`	string	The track's loudness over time as digits 0 to 9, one per sample, when something has measured it; the drawn cover puts it in the groove. Empty otherwise.
`art`	array	Artwork, smallest first.
`art[].src`	string
`art[].sizes`	string
`video`	object \| null
`video.src`	string
`video.poster`	string
`post`	object \| null
`post.id`	integer
`post.title`	string
`post.url`	string

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.

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

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

[riff]

[riff], the same as the block.

Return

string

Since 4.0.0plugins/riff/features/listen/class-app.phpView on GitHub