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
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.
https://web.replayer.app/
)Points to the location where Replayer is available.
#/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.
?
)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=
)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=
)The title for this track. You can set this to whatever you find suitable.
artist=
)The artist performing this track. You can set this to whatever you find suitable.
album=
)The album or place where this track can be found. You can set this to whatever you find suitable.
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.
Hover or click to try these examples: