Lyrical Systems API

Lyrical Systems provides an open REST API so that web and mobile apps can integrate with the fun functionality of its karaoke systems. This is the guts behind the mobile apps that we support for companies like Voicebox at vbsongs.com, and how websites can display the current popular songs.

We encourage experimentation and development of features which integrate with social networking sites and other online music systems.

Please be considerate of others, and of the fact that hundreds of paying customers use our system every day. Abuse will not be tolerated.

Packages

The Lyrical Systems API is broken into separate packages:

See the Lyrical Systems site for information about available packages.
Please contact us if you have further interest in using this API.

API Overview

The following features are common to the entire API, regardless of which package, resource, or feature is used.

Versioning
Result Formats
JSONP
Error Handling
Pagination
Sessions
Login
Organizations
Ping

Versioning

Each URL contains a version, which is something like v1, so the actual URL would be /api/v1/songs

Current Version: v1

Result Formats

The URLs also contain an optional format, which can be one of: .json, .txt, or .html

If the format is unspecified, it uses the Accept header in the HTTP request. Browsers will typically use Accept: text/html, so you will get back an HTML result, which is not JSON. Though this makes for convenient testing from a browser, you should use .json in your production system.

json should be used by production systems
txt is more human-readable json
html is a formatted response

JSONP

The Lyrical Systems API optionally supports JSONP responses, by supplying an additional ‘callback=myFunctionName’ parameter on any of the resources below. Note that this only works with the .json format. This will cause the response to be returned as:

myFunctionName({ ... })

Error handling in JSONP is notoriously bad. See this discussion for an overview of the problem. If there is an error, the script tag will simply not be loaded by the browser, and the AJAX call will stall. To get around this, the Lyrical API will respond with an HTTP status code of 200 even if an error occurs, and the response body will be something like:

myFunctionName({"error":"Description of the error","status":400})

The status provided is the HTTP status code that would have been received, were it not a JSONP request.

Error Handling

The HTTP responses use standard HTTP status codes.

Successful responses will be 200 OK, or 201 Created.

Error responses will contain a result like:

{"error":"Description of the error","status":400}

The status code will indicate the type of error:

400 Bad Request - there is missing or invalid data in the request
401 Unauthorized - the room_code or api_key provided is incorrect
403 Forbidden - the action is not allowed right now, e.g. the queue is limited, or requires a logged-in session
404 Not Found - the URL does not correspond to a valid resource, e.g. the song_id does not exist
500 Internal Server Error - something went wrong on our end. We’ll log it and fix it
504 Gateway Timeout - the Internet is unavailable between our server and the brick-and-mortar location

Pagination

Because there are so many songs available (over 60000 and growing), there is no single request to get all of the song data. Instead, we provide resources to browse the song database much as one would browse a song book, by artist or by title.

Large resources, like the songs resources, return only a limited set of results, and have a page parameter to control which page is returned.

There is also a per_page parameter, which can adjust how many results come back per page, though most resources will have a maximum.

Sessions

Each API call may provide a session parameter, which should be a valid UUID, in the 8-4-4-4-12 hexadecimal format. This session is used to identify activity from a single user, for keeping track of play history, storing a user’s favorite songs, and other features as we grow. This parameter is usually optional, but some features require a session, such as getting your play history.

Clients may generate a session UUID themselves, and they do not need to actually call the Lyrical API in order to get a session. This session UUID should be stored client-side and sent with every request.

For testing, please use session 12345678-1234-1234-1234-123456abcdef

In addition to sessions, the Lyrical API supports login to a user profile, by supplying an email address. This finds an existing profile, or creates a new profile, which allows features such as play history to persist across sessions, or to be viewed from another device. Some features require a login, such as viewing a user’s favorite songs, and more to come.

Organizations

The Lyrical API supports many brick-and-mortar locations. It was originally developed to support Voicebox Karaoke in Portland OR, but it also supports several other partner organizations across the country such as Punchbowl Social. Each API resource accepts an additional parameter, called organization, which should be set to the organization key that we have provided. This is how Lyrical supports each independent mobile app such as vbsongs.com for Voicebox, and pbs-karaoke.com for Punchbowl Social.

For testing, please use organization 00000000000000000000000000000000 and room_code CQFW
If you were previously able to use the API to implicitly access Voicebox, note that the organization parameter is now required

GET /api/version/ping.format

Returns a result from the API, to ensure connectivity.

Parameters

None

Examples

To ping the API

GET /api/v1/ping

Or via curl

curl https://app.lyricalsystems.com/api/v1/ping

Example Response

{ 
  "ok": true,
  "now": "2016-10-25T09:55:20.190Z"
}