Hooks
Every filter and action Riff fires, in PHP and in the player. Each page is generated from the docblock above the line the hook fires on, at the commit this site was published from. A hook keeps its name and parameters within a major version.
PHP filters
- riff_abilities
Filters the abilities Riff registers, so an extension adds its own the way Riff adds its: each the REST route it runs, with what it takes and what it answers. Each is registered in Riff's category, run as a REST request to its route and allowed what the route's own permission callback allows, and offered to an MCP client only where the site turns that on.
- riff_about_sections
Filters the sections of the About panel, Riff's own included:
track, the cover, the title and the artist and album, andcredits, what the file's tags say about who made it. - riff_add_music_url
Filters where the Listen app sends someone who may upload to add music: the account menu's Add music, and Add your first album in an empty library.
- riff_app_at_root
Filters whether the site's own address opens the Listen page's app. On, a request for the home page with no other query is the Listen page in standalone mode, every link to the app and the manifest's start address are the home page, and the app/ address redirects there. The Listen page's own address and the theme's front page setting are left as they are.
- riff_app_manifest
Filters the Listen app's web app manifest, for a host that names, colours or gives icons to each site's app its own way.
- riff_app_precache
Filters what the installed Listen app's service worker keeps on the device, so it is there offline and on every launch after the first: a host's fonts that the first paint doesn't show, say. The fonts
riff_app_preload_fontsreturns are already in it. - riff_app_preload_fonts
Filters the fonts a Listen page preloads, the faces its first paint shows, so a host that draws the app in fonts of its own has them fetched with the page rather than after the stylesheet asks. The installed app's service worker keeps them on the device too.
- riff_app_views
Filters the Listen app's views: Riff's own, by slug (
home,search,albums,artists,tracks,postsandlibrary), and any a plugin adds. - riff_can_play
Filters whether the current visitor may play a track.
- riff_client_navigation
Filters whether a link on the site is followed without leaving the page, so what plays carries on. Only a block theme can: its template is the region that is swapped.
- riff_cover_accent
Filters whether the player takes its accent from the cover of the track playing: the cover's hue, muted and lightened until it reads on the player's dark surfaces, as
--riff-cover-accent, on the seek bar, the playing bars, the current Up next item and a wash behind Now Playing, and in the Listen app's own document on its links, the track playing, Liked songs and the Browse tiles. A cover that is grey, near black or near white gives none, and the accent is the site's--riff-accent, as it is everywhere with this off. - riff_enabled
Filters whether Riff's player loads on the current front-end request.
- riff_extensions
Filters the extensions Riff loads, by name: a host can leave one out, or name another plugin it has placed in Riff's extensions/ folder.
- riff_mcp
Filters whether AI assistants may use Riff's abilities over MCP. On, and with the MCP Adapter plugin active,
/wp-json/mcp/riffserves each of them as a tool to a signed-in user, and the adapter's default server lists them. Each still does only what that user may do. Off, there is no such server, and the default server does not list them. - riff_post_blocks
Filters whether a post's blocks are served as a tree at riff/v1/posts/{id}/blocks to someone who cannot edit the post.
- riff_profile_url
Filters where the Listen app's account menu sends a listener to edit their profile, for a host or a membership plugin with a profile page of its own.
- riff_protect_storage
Filters whether the storage a file is kept in elsewhere was made private, when it is protected, or public again, when it isn't. A plugin that keeps uploads in object storage or on a CDN answers for its own files: true once the copy there is private (or public again), or a WP_Error to say why it couldn't be, which the Media Library shows. Without an answer, a file only on this server is moved into the protected folder, and one kept elsewhere is not protected, as moving it would leave it public there. Riff can't send a file it doesn't have, so a plugin that protects its files signs their addresses through riff_protected_url too.
- riff_protected_path
Filters the folder protected files are kept in, so the web server never has them to send: an absolute path outside the web root, which Riff makes when it is first needed, keeping each site's files in a folder of its own inside it (the site's ID on a network). Empty, the default, keeps them in a folder under uploads, which Apache is told to refuse and Nginx needs a rule for.
- riff_protected_send
Filters how a protected file is handed over: 'php' sends it from PHP; 'x-sendfile' asks Apache's mod_xsendfile or LiteSpeed to send it; 'x-accel-redirect' asks Nginx, which then needs an internal location for the protected folder (see the readme).
- riff_protected_url
Filters the address a protected file is sent from instead of WordPress: a signed address on a CDN or in object storage, such as a CloudFront or S3 presigned URL or a Bunny or Cloudflare token, that stops working at $expires. Riff has checked that the visitor may have the file before it asks, and sends them on with a 302 nothing caches. Empty, the default, sends the file as riff_protected_send says.
- riff_sources
Filters the sources tracks are read from, keyed by id.
- riff_together_share
Filters whether a listener who hasn't chosen shares what they play with the site's other listeners. A site where listeners shouldn't see each other unless they ask, a class of children say, returns false.
- riff_track
Filters a track before the player reads it.
- riff_turntable
Filters whether Now Playing shows the record and the turntable. Off, it shows the cover on its own, and a touch screen on its side shows the cover beside the controls.
- riff_unlock_url
Filters where a locked track sends the visitor to unlock it: a sign-up, membership or checkout page.
PHP actions
- riff_before_player
Fires before the player's markup.
- riff_below_turntable
Fires in the place under the turntable, for what a plugin shows beside the record. Print one element for each thing: the place takes room only while one that isn't hidden is in it, and only where the turntable is the view. The record is out when
#riffhasdata-riff-deck="out". Script it from there;window.riff.analyser()hears the music. - riff_private_refused
Fires before a private site refuses a visitor, for a page of the site's own in place of WordPress's message.
- riff_register
Fires once a request, before the player's controls and views are first read: register them here with
riff_register_control()andriff_register_view(), or take one of Riff's own away. A plugin's keyboard shortcuts are registered here too, withriff_register_shortcut().
JavaScript filters
- riff.menu
Filters the items of the track menu, the … beside every row and every track in Up next.
- riff.queue
Filters the tracks about to become the queue.
- riff.shortcuts
Filters whether the single-key shortcuts (Space, K, J, L and plugins' keys) act on a key press.
- riff.track
Filters one track as a queue is set, after
riff.queue.
JavaScript actions
- riff.app_view
Fires when a view of the Listen app shows: the first as the app starts, then each one in-page navigation brings, and again when one is drawn again in place. A plugin that added a view with the
riff_app_viewsfilter binds its script to what it drew here, or on theriff:app_viewevent, which bubbles todocument. - riff.ended
Fires when a track plays to its end, before the next one loads.
- riff.pause
Fires when the track pauses.
- riff.play
Fires when the track starts or resumes playing.
- riff.queue
Fires when the queue changes while it plays: tracks added to play next or at the end, one moved or removed, or the queue cleared.
- riff.ready
Fires once the player is set up, its state restored and
window.riffavailable. - riff.time
Fires as the track plays, a few times a second, and again after a seek.
- riff.track
Fires when a track is loaded, before it plays.
- riff.view
Fires when a view opens or closes, Riff's own included, and again for an open view when the track changes. A view's script fills it here, or in the
renderit was given.
No hook matches.