Package API

Table of Contents

In addition to the Track API for single tracks, the Package API allows loading complete ZIP archives (.zip, .rez), as packages, at once. An XML file (.xml, .rex) containing a single compilation is also considered a package in the context of this API.

https://web.replayer.app/#/play?
package=https://lib.replayer.app/demo/demo-compilation-featuring-lidija-roos-with-info.xml

This API allows a user to offer a complete compilation, with or without track media, 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 package 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 Package API are explained.

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.

package parameter (package=)

The URL to the package file to load. The parameter is mandatory. It must be a valid URL.

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