Track API

Table of Contents

In addition to the Package API for whole packages, Replayer provides a simple API for using single media files as a new track. It works with a specially crafted URL like in the example below:

https://web.replayer.app/#/play?
media=https://lib.replayer.app/your-light-by-lidija-roos.mp3&
title=Your+Light&
album=Not+For+Sale&
artist=Lidija+Roos&
17.5=Verse

Your Light by Lidija Roos

This API allows a user to easily share a complete track with prepared cues by just distributing an URL.

Such an URL uses only the URI fragment part for this API. The fragment part within this API however mimicks an ordinary URL query with parameters. Using only the fragment part has the benefit of processing all information locally in the browser, without sending anything to the hosting server, increasing user privacy. The referenced media itself however, is loaded from it's respective hosting server.

The query needs to be percent-encoded, to be fully compatible with the URI specification. To be working with most browsers, a total length of the resulting URL of 2000 characters should not get exceeded.

In the following, all parts of the Replayer Track API are explained. More examples are provided at the end.

URL parts

Location (https://web.replayer.app/)

Points to the location where Replayer is available.

Route (#/play)

Consists of the fragment delimiter, and the route to the desired application view. Available routes are play for the player view, and edit for the editor view.

The format of the following elements is not formally specified by an RFC, because they all fall within the fragment part. However, they voluntarily follow the specification for a URL query with parameters.

Query delimiter (?)

Separates the location from the parameters, which also called the query part in the URL specification. The parameters are split by an ampersand & character and consist of a key, the equals operator = and the value. All parameters, except media, are optional, and their order is not relevant.

media parameter (media=)

The URL to the media file to load for this track. The parameter is mandatory. It must be a valid URL, but you may also use a dummy value if you do not want to share the actual link to the media file or if the link points to a local file on your disk anyway. For playback, the recipient will then need to provide a matching URL or file by themselves,

Note that access to (media) files may be restricted due to various means like legal requirements, login requirements or insufficient CORS allowance.

title parameter (title=)

The title for this track. You can set this to whatever you find suitable.

artist parameter (artist=)

The artist performing this track. You can set this to whatever you find suitable.

album parameter (album=)

The album or place where this track can be found. You can set this to whatever you find suitable.

cue parameter(s) (nn.nn=XXX)

The cues to present, with their caption. The key is a floating point number indicating the position within the media file, in seconds from the start of the media. You may use up to two digits after the decimal point. The value is a caption (free text, can also be empty) for the cue and can have any length. You can specify any number of cues. The order of the cue keys is reflected in the player view.

API Examples

Hover or click to try these examples:

With various media

Without media

  • Media without existing URL This allows you to share just the metadata, without risk of any copyright infringements, as the recipient will need to provide their own file. A syntactically valid URL is required however.

Various