REST API | Riff Developer

Everything here describes itself: send OPTIONS to a route for its arguments and schema. The tables below come from the same registration code.

The track on media is public and keeps its shape within a major version. The riff/v1 routes are the player's own, there for the player and the Listen block to call, and may change in any release.

The track on media

Every audio and video item in wp/v2/media carries riff_track: The file as a track the player reads; null for files that are not audio or video. It is read only, and null for any other file. Its shape is the track schema.

GET /wp-json/wp/v2/media/123?_fields=id,riff_track

Routes

GET /riff/v1/library

riff-library

Arguments

Name	Type	Description
`page`	integer	Page of the library. Default `1`.

Response

Property	Type	Description
`items`	array
`items[].id`	integer	Post ID.
`items[].title`	string	Post title.
`items[].url`	string	Permalink.
`items[].artist`	string	The artist every track shares, or empty.
`items[].art`	array	Artwork, smallest first.
`items[].art[].src`	string
`items[].art[].sizes`	string
`items[].count`	integer	Number of tracks.
`items[].meta`	string	A one-line byline for the post, written by a feature that knows how to say it in the language.
`items[].duration`	number	Total length in seconds, 0 when unknown.
`page`	integer
`pages`	integer
`total`	integer

GET /riff/v1/library/{id}

riff-library-post

Arguments

Name	Type	Description
`id`	integer Required	Post ID.

Response

Property	Type	Description
`id`	integer	Post ID.
`title`	string	Post title.
`url`	string	Permalink.
`artist`	string	The artist every track shares, or empty.
`art`	array	Artwork, smallest first.
`art[].src`	string
`art[].sizes`	string
`count`	integer	Number of tracks.
`meta`	string	A one-line byline for the post, written by a feature that knows how to say it in the language.
`duration`	number	Total length in seconds, 0 when unknown.
`tracks`	array	The tracks, in order, as the player reads them.
`html`	string	The media blocks rendered as the post renders them.

GET /riff/v1/tracks

Tracks from the Media Library, by title, or one album in its order, or one artist; searchable by title, artist and album. A visitor sees every track except those uploaded to an unpublished or password-protected post; someone who can upload files sees them all.

Arguments

Name	Type	Description
`search`	string	Words to look for, at least two characters: a track matches on its title, artist or album; an album or artist on its name. Default `""`.
`album`	integer	Only the tracks on this album, by term ID, in album order. Default `0`.
`artist`	integer	Only the tracks by this artist, by term ID. Default `0`.
`include`	array	Only these, by ID; what the requester cannot see is still left out. Default `[]`.
`orderby`	string	By title, the most recently added first, in the order include names them, or shuffled by seed. An album is in album order unless shuffled. Default `"title"`.
`seed`	integer	With orderby random, the shuffle: the same seed deals the same order, so its pages follow on without a track twice. Default `0`.
`page`	integer	Page of results. Default `1`.
`after`	string	Where the last page ended, as its next said: the page after it, which stays fast however deep into the library it is. By title or newest first, and not with album or include. Default `""`.
`per_page`	integer	Tracks per page. Default `50`.

Response

Property	Type	Description
`items`	array	Tracks, in the shape of the track schema.
`items[].id`	string	The attachment ID, or "url:" and a hash for a file outside the Media Library.
`items[].src`	string
`items[].type`	string	One of `audio`, `video`.
`items[].title`	string
`items[].artist`	string
`items[].album`	string
`items[].year`	integer	The year from the file's tags, or 0.
`items[].disc`	integer	Which disc of a set the track is on, from the file's disc number tag (1 for "1/2"), or 0 when the tags do not say.
`items[].duration`	number	Seconds, 0 when unknown.
`items[].lang`	string	The language of the title and artist, as a lang attribute takes it, from the file's tags; empty when the file does not say.
`items[].format`	string	The container, lower case, as WordPress read it from the file: mp3, flac, m4a. Empty when unknown.
`items[].bitrate`	integer	Kilobits per second, 0 when unknown.
`items[].lossless`	boolean	Whether the encoding is lossless.
`items[].bits`	integer	Bits per sample, as WordPress read it from the file; 0 when the format does not say, as MP3 does not.
`items[].rate`	integer	Samples per second, 0 when unknown.
`items[].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.
`items[].art`	array	Artwork, smallest first.
`items[].art[].src`	string
`items[].art[].sizes`	string
`items[].art[].alt`	string	What the picture shows, for a screen reader: the image's alt text, or the album and artist a drawn cover names.
`items[].captions`	array	Text tracks for a video: the WebVTT file its Captions field names, or the tracks its video block carries.
`items[].captions[].src`	string
`items[].captions[].label`	string
`items[].captions[].srclang`	string
`items[].captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`items[].video`	object \| null
`items[].video.src`	string
`items[].video.poster`	string
`items[].video.captions`	array
`items[].video.captions[].src`	string
`items[].video.captions[].label`	string
`items[].video.captions[].srclang`	string
`items[].video.captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`items[].post`	object \| null
`items[].post.id`	integer
`items[].post.title`	string
`items[].post.url`	string
`items[].locked`	boolean	Whether the current visitor may not play the track, as riff_can_play decided. A locked track has no src.
`items[].unlock`	string	Where a locked track sends the visitor to unlock it, from riff_unlock_url. Empty otherwise.
`page`	integer
`pages`	integer
`total`	integer
`next`	string	Where this page ended, to pass as after for the next; empty when this is the last, or for an album or include.

GET /riff/v1/albums

Albums with at least one track the requester can see, by name, each with its artist, artwork and track count.

Arguments

Name	Type	Description
`search`	string	Words to look for, at least two characters: a track matches on its title, artist or album; an album or artist on its name. Default `""`.
`artist`	integer	Only the albums with a track by this artist, by term ID. Default `0`.
`include`	array	Only these, by ID; what the requester cannot see is still left out. Default `[]`.
`orderby`	string	By name, or the most recently added first. Default `"name"`.
`page`	integer	Page of results. Default `1`.

Response

Property	Type	Description
`items`	array
`items[].id`	integer	Term ID.
`items[].name`	string
`items[].count`	integer	Tracks the requester can see.
`items[].artist`	string	The album's artist, or empty.
`items[].art`	array	The album's first track's artwork as the player shows it, as { src, sizes }.
`page`	integer
`pages`	integer
`total`	integer

GET /riff/v1/artists

Artists with at least one track the requester can see, by name, each with a track count.

Arguments

Name	Type	Description
`search`	string	Words to look for, at least two characters: a track matches on its title, artist or album; an album or artist on its name. Default `""`.
`include`	array	Only these, by ID; what the requester cannot see is still left out. Default `[]`.
`page`	integer	Page of results. Default `1`.

Response

Property	Type	Description
`items`	array
`items[].id`	integer	Term ID.
`items[].name`	string
`items[].count`	integer	Tracks the requester can see.
`page`	integer
`pages`	integer
`total`	integer

GET, POST /riff/v1/users/{user}/likes

The signed-in user's likes, newest first. Kept as the riff_likes user option, one list per site.

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`items`	array Required	Likes to add: a kind and an ID each, and when it was liked.

Response

Property	Type	Description
`items`	array
`items[].kind`	string	One of `track`, `album`, `artist`.
`items[].id`	integer
`items[].at`	integer	When it was liked, in milliseconds since the epoch.

DELETE /riff/v1/users/{user}/likes/{kind}/{id}

The signed-in user's likes, newest first. Kept as the riff_likes user option, one list per site.

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`kind`	string	What was liked: track, album or artist.
`id`	integer	Its ID.

Response

Property	Type	Description
`items`	array
`items[].kind`	string	One of `track`, `album`, `artist`.
`items[].id`	integer
`items[].at`	integer	When it was liked, in milliseconds since the epoch.

GET, POST, DELETE /riff/v1/users/{user}/history

The tracks the signed-in user played, newest first, at most 30. Kept as the riff_history user option, one list per site.

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`items`	array Required	Plays to add: a track's ID each, and when it was played.

Response

Property	Type	Description
`items`	array
`items[].id`	string	The attachment ID, or "url:" and a hash for a file outside the Media Library.
`items[].src`	string
`items[].type`	string	One of `audio`, `video`.
`items[].title`	string
`items[].artist`	string
`items[].album`	string
`items[].year`	integer	The year from the file's tags, or 0.
`items[].disc`	integer	Which disc of a set the track is on, from the file's disc number tag (1 for "1/2"), or 0 when the tags do not say.
`items[].duration`	number	Seconds, 0 when unknown.
`items[].lang`	string	The language of the title and artist, as a lang attribute takes it, from the file's tags; empty when the file does not say.
`items[].format`	string	The container, lower case, as WordPress read it from the file: mp3, flac, m4a. Empty when unknown.
`items[].bitrate`	integer	Kilobits per second, 0 when unknown.
`items[].lossless`	boolean	Whether the encoding is lossless.
`items[].bits`	integer	Bits per sample, as WordPress read it from the file; 0 when the format does not say, as MP3 does not.
`items[].rate`	integer	Samples per second, 0 when unknown.
`items[].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.
`items[].art`	array	Artwork, smallest first.
`items[].art[].src`	string
`items[].art[].sizes`	string
`items[].art[].alt`	string	What the picture shows, for a screen reader: the image's alt text, or the album and artist a drawn cover names.
`items[].captions`	array	Text tracks for a video: the WebVTT file its Captions field names, or the tracks its video block carries.
`items[].captions[].src`	string
`items[].captions[].label`	string
`items[].captions[].srclang`	string
`items[].captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`items[].video`	object \| null
`items[].video.src`	string
`items[].video.poster`	string
`items[].video.captions`	array
`items[].video.captions[].src`	string
`items[].video.captions[].label`	string
`items[].video.captions[].srclang`	string
`items[].video.captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`items[].post`	object \| null
`items[].post.id`	integer
`items[].post.title`	string
`items[].post.url`	string
`items[].locked`	boolean	Whether the current visitor may not play the track, as riff_can_play decided. A locked track has no src.
`items[].unlock`	string	Where a locked track sends the visitor to unlock it, from riff_unlock_url. Empty otherwise.
`items[].played`	integer	When it was played, in milliseconds since the epoch.

GET, POST /riff/v1/users/{user}/playlists

A user's playlists, the most recently changed first. Each is a private riff_playlist post holding a core Playlist block.

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`title`	string Required	The playlist's name.
`tracks`	array	Tracks, by their audio attachments' IDs, in order.

Response

Property	Type	Description
`items`	array
`items[].id`	integer
`items[].title`	string
`items[].count`	integer	How many tracks it holds.
`items[].covers`	array	Up to four covers from its first tracks, for a mosaic.
`items[].modified`	string	When it last changed.

GET, POST, DELETE /riff/v1/users/{user}/playlists/{id}

riff-playlist

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`id`	integer	The playlist's post ID.
`title`	string	The playlist's name.
`tracks`	array	Tracks, by their audio attachments' IDs, in order.

Response

Property	Type	Description
`id`	integer
`title`	string
`count`	integer	How many tracks it holds.
`covers`	array	Up to four covers from its first tracks, for a mosaic.
`modified`	string	When it last changed.
`ids`	array	Every track's ID, in order, including any the requester cannot see.
`tracks`	array	The tracks the requester can see, in the track shape, in order.
`tracks[].id`	string	The attachment ID, or "url:" and a hash for a file outside the Media Library.
`tracks[].src`	string
`tracks[].type`	string	One of `audio`, `video`.
`tracks[].title`	string
`tracks[].artist`	string
`tracks[].album`	string
`tracks[].year`	integer	The year from the file's tags, or 0.
`tracks[].disc`	integer	Which disc of a set the track is on, from the file's disc number tag (1 for "1/2"), or 0 when the tags do not say.
`tracks[].duration`	number	Seconds, 0 when unknown.
`tracks[].lang`	string	The language of the title and artist, as a lang attribute takes it, from the file's tags; empty when the file does not say.
`tracks[].format`	string	The container, lower case, as WordPress read it from the file: mp3, flac, m4a. Empty when unknown.
`tracks[].bitrate`	integer	Kilobits per second, 0 when unknown.
`tracks[].lossless`	boolean	Whether the encoding is lossless.
`tracks[].bits`	integer	Bits per sample, as WordPress read it from the file; 0 when the format does not say, as MP3 does not.
`tracks[].rate`	integer	Samples per second, 0 when unknown.
`tracks[].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.
`tracks[].art`	array	Artwork, smallest first.
`tracks[].art[].src`	string
`tracks[].art[].sizes`	string
`tracks[].art[].alt`	string	What the picture shows, for a screen reader: the image's alt text, or the album and artist a drawn cover names.
`tracks[].captions`	array	Text tracks for a video: the WebVTT file its Captions field names, or the tracks its video block carries.
`tracks[].captions[].src`	string
`tracks[].captions[].label`	string
`tracks[].captions[].srclang`	string
`tracks[].captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`tracks[].video`	object \| null
`tracks[].video.src`	string
`tracks[].video.poster`	string
`tracks[].video.captions`	array
`tracks[].video.captions[].src`	string
`tracks[].video.captions[].label`	string
`tracks[].video.captions[].srclang`	string
`tracks[].video.captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`tracks[].post`	object \| null
`tracks[].post.id`	integer
`tracks[].post.title`	string
`tracks[].post.url`	string
`tracks[].locked`	boolean	Whether the current visitor may not play the track, as riff_can_play decided. A locked track has no src.
`tracks[].unlock`	string	Where a locked track sends the visitor to unlock it, from riff_unlock_url. Empty otherwise.
`tracks[].index`	integer	The track's place in the playlist, from 0.

POST /riff/v1/users/{user}/playlists/{id}/tracks

riff-playlist

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`id`	integer	The playlist's post ID.
`tracks`	array Required	Tracks, by their audio attachments' IDs, in order.

Response

Property	Type	Description
`id`	integer
`title`	string
`count`	integer	How many tracks it holds.
`covers`	array	Up to four covers from its first tracks, for a mosaic.
`modified`	string	When it last changed.
`ids`	array	Every track's ID, in order, including any the requester cannot see.
`tracks`	array	The tracks the requester can see, in the track shape, in order.
`tracks[].id`	string	The attachment ID, or "url:" and a hash for a file outside the Media Library.
`tracks[].src`	string
`tracks[].type`	string	One of `audio`, `video`.
`tracks[].title`	string
`tracks[].artist`	string
`tracks[].album`	string
`tracks[].year`	integer	The year from the file's tags, or 0.
`tracks[].disc`	integer	Which disc of a set the track is on, from the file's disc number tag (1 for "1/2"), or 0 when the tags do not say.
`tracks[].duration`	number	Seconds, 0 when unknown.
`tracks[].lang`	string	The language of the title and artist, as a lang attribute takes it, from the file's tags; empty when the file does not say.
`tracks[].format`	string	The container, lower case, as WordPress read it from the file: mp3, flac, m4a. Empty when unknown.
`tracks[].bitrate`	integer	Kilobits per second, 0 when unknown.
`tracks[].lossless`	boolean	Whether the encoding is lossless.
`tracks[].bits`	integer	Bits per sample, as WordPress read it from the file; 0 when the format does not say, as MP3 does not.
`tracks[].rate`	integer	Samples per second, 0 when unknown.
`tracks[].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.
`tracks[].art`	array	Artwork, smallest first.
`tracks[].art[].src`	string
`tracks[].art[].sizes`	string
`tracks[].art[].alt`	string	What the picture shows, for a screen reader: the image's alt text, or the album and artist a drawn cover names.
`tracks[].captions`	array	Text tracks for a video: the WebVTT file its Captions field names, or the tracks its video block carries.
`tracks[].captions[].src`	string
`tracks[].captions[].label`	string
`tracks[].captions[].srclang`	string
`tracks[].captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`tracks[].video`	object \| null
`tracks[].video.src`	string
`tracks[].video.poster`	string
`tracks[].video.captions`	array
`tracks[].video.captions[].src`	string
`tracks[].video.captions[].label`	string
`tracks[].video.captions[].srclang`	string
`tracks[].video.captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`tracks[].post`	object \| null
`tracks[].post.id`	integer
`tracks[].post.title`	string
`tracks[].post.url`	string
`tracks[].locked`	boolean	Whether the current visitor may not play the track, as riff_can_play decided. A locked track has no src.
`tracks[].unlock`	string	Where a locked track sends the visitor to unlock it, from riff_unlock_url. Empty otherwise.
`tracks[].index`	integer	The track's place in the playlist, from 0.

DELETE /riff/v1/users/{user}/playlists/{id}/tracks/{index}

riff-playlist

Arguments

Name	Type	Description
`user`	string	Whose: me for the signed-in user, or a user ID, for someone who may edit that user.
`id`	integer	The playlist's post ID.
`index`	integer	The track's place in the playlist, from 0.

Response

Property	Type	Description
`id`	integer
`title`	string
`count`	integer	How many tracks it holds.
`covers`	array	Up to four covers from its first tracks, for a mosaic.
`modified`	string	When it last changed.
`ids`	array	Every track's ID, in order, including any the requester cannot see.
`tracks`	array	The tracks the requester can see, in the track shape, in order.
`tracks[].id`	string	The attachment ID, or "url:" and a hash for a file outside the Media Library.
`tracks[].src`	string
`tracks[].type`	string	One of `audio`, `video`.
`tracks[].title`	string
`tracks[].artist`	string
`tracks[].album`	string
`tracks[].year`	integer	The year from the file's tags, or 0.
`tracks[].disc`	integer	Which disc of a set the track is on, from the file's disc number tag (1 for "1/2"), or 0 when the tags do not say.
`tracks[].duration`	number	Seconds, 0 when unknown.
`tracks[].lang`	string	The language of the title and artist, as a lang attribute takes it, from the file's tags; empty when the file does not say.
`tracks[].format`	string	The container, lower case, as WordPress read it from the file: mp3, flac, m4a. Empty when unknown.
`tracks[].bitrate`	integer	Kilobits per second, 0 when unknown.
`tracks[].lossless`	boolean	Whether the encoding is lossless.
`tracks[].bits`	integer	Bits per sample, as WordPress read it from the file; 0 when the format does not say, as MP3 does not.
`tracks[].rate`	integer	Samples per second, 0 when unknown.
`tracks[].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.
`tracks[].art`	array	Artwork, smallest first.
`tracks[].art[].src`	string
`tracks[].art[].sizes`	string
`tracks[].art[].alt`	string	What the picture shows, for a screen reader: the image's alt text, or the album and artist a drawn cover names.
`tracks[].captions`	array	Text tracks for a video: the WebVTT file its Captions field names, or the tracks its video block carries.
`tracks[].captions[].src`	string
`tracks[].captions[].label`	string
`tracks[].captions[].srclang`	string
`tracks[].captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`tracks[].video`	object \| null
`tracks[].video.src`	string
`tracks[].video.poster`	string
`tracks[].video.captions`	array
`tracks[].video.captions[].src`	string
`tracks[].video.captions[].label`	string
`tracks[].video.captions[].srclang`	string
`tracks[].video.captions[].kind`	string	One of `captions`, `subtitles`, `descriptions`.
`tracks[].post`	object \| null
`tracks[].post.id`	integer
`tracks[].post.title`	string
`tracks[].post.url`	string
`tracks[].locked`	boolean	Whether the current visitor may not play the track, as riff_can_play decided. A locked track has no src.
`tracks[].unlock`	string	Where a locked track sends the visitor to unlock it, from riff_unlock_url. Empty otherwise.
`tracks[].index`	integer	The track's place in the playlist, from 0.

WPGraphQL

When WPGraphQL is active, Riff adds these fields and types.

Field	Description
`MediaItem.riffTrack`RiffTrack	The file as a track, for audio and video.
`Post.riffTracks`[RiffTrack]	The tracks in the post, in order.

`RiffArt`

One size of a track's artwork.

Field	Type
`src`	String
`sizes`	String
`alt`	String

`RiffCaptions`

Field	Type
`src`	String
`label`	String
`srclang`	String
`kind`	String

`RiffVideo`

The video version of an audio track.

Field	Type
`src`	String
`poster`	String
`captions`	[RiffCaptions]

`RiffPost`

The post a track appears in.

Field	Type
`id`	Int
`title`	String
`url`	String

`RiffTrack`

A file as a track the Riff player reads.

Field	Type
`id`	String
`src`	String
`type`	String
`title`	String
`artist`	String
`album`	String
`year`	Int
`disc`	Int
`duration`	Float
`lang`	String
`format`	String
`bitrate`	Int
`lossless`	Boolean
`bits`	Int
`rate`	Int
`levels`	String
`art`	[RiffArt]
`captions`	[RiffCaptions]
`video`	RiffVideo
`post`	RiffPost
`locked`	Boolean
`unlock`	String