Skip to content

API Reference

Jump to bottom
Ken Ellorando edited this page Aug 23, 2023 · 27 revisions

This page is the official API Reference for a Cadence 5.x API.

  • Examples on this page target the demo deployment, https://cadenceradio.com. Remember to replace this as necessary with your server's IP address or your DNS.
  • All requests, responses, and messages shall be transmitted as raw body JSON.
  • To report errata, create an issue on the Cadence repository.

Radio Features

Search for Music

POST /api/search

Search the server's music library.

Cadence searches by both "title" and "artist" metadata. Returns a list of results ordered by relevance.

Request

{ 
	"Search": "zutomayo" 
}

Examples

  • curl

    curl -XPOST \
	-H 'Content-Type: application/json' \
	-d '{ "Search": "zutomayo" }' \
	'https://cadenceradio.com/api/search'

Response

  • 200 OK
[
	{
		"ID": 1,
		"Artist": "ZUTOMAYO",
		"Title": "勘ぐれい (Hunch Gray)",
		"Album": "ぐされ (Gusare)",
		"Genre": "J-POP",
		"Year": 2021
	},
	{
		"ID": 2,
		"Artist": "ZUTOMAYO",
		"Title": "秒針を噛む (Bite the Second Hand)",
		"Album": "潜潜話 (Hisohiso Banashi)",
		"Genre": "Rock",
		"Year": 2019
	}
]
  • 400 Bad Request

Request a Song by ID

POST /api/request/id

Submit a request for a specific song to be played.

This accepts a song’s ID. ID is an arbitrary label Cadence internally applies to track songs and is not an inherent attribute of the audio file itself. In practice, you should execute a search for an ID first.

Alternatively, consider using /api/request/bestmatch to automatically request the number one search result immediately.

Request

{ 
	"ID": "2" 
}

Examples

  • curl

    curl -XPOST \
	-H 'Content-Type: application/json' \
	-d '{ "ID": "2" }' \
	'https://cadenceradio.com/api/request/id'

Response

  • 202 Accepted
  • 400 Bad Request
  • 429 Too Many Requests
    • Cadence’s request rate limiter found your request was submitted too soon after another one. This timeout is configurable by the radio administrator.

Request a Song by Best Match

POST /api/request/bestmatch

Executes a search, selects the number one result if available (i.e. the most relevant result to the search), and executes a request for it.

This is Cadence's equivalent to Google's "I'm Feeling Lucky".

Alternatively, to submit requests for specific songs, use /api/search to discover a song ID then /api/request/id to submit a request for it.

Request

{ 
	"Search": "zutomayo" 
}

Examples

  • curl

    curl -XPOST \
	-H 'Content-Type: application/json' \
	-d '{ "Search": "zutomayo" }' \
	'https://cadenceradio.com/api/request/bestmatch'

Response

  • 202 Accepted
  • 400 Bad Request
  • 429 Too Many Requests
    • Cadence’s request rate limiter found your request was submitted too soon after another one. This timeout is configurable by the radio administrator.

Get Now Playing Text Metadata

GET /api/nowplaying/metadata

Gets all text metadata (title, artist, album, genre, year) on the song currently playing.

If there are multiple audio files on the server which share the exact same title and artist, Cadence will return the first result only.

Note that this does not return album art. To fetch album art, use /api/nowplaying/albumart

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/nowplaying/metadata'

Response

  • 200 OK
{ 
	"ID": "1", 
	"Artist": "fripSide",
	"Title": "only my railgun", 
	"Album": "only my railgun - Single",
	"Genre": "J-Pop", 
	"Year": 2009
}
  • 404 Not Found
    • No song is currently playing, or the song is not in Cadence's internal database.

Get Now Playing Album Art

GET /api/nowplaying/albumart

Gets the base64-encoded album art of the currently playing song.

[5.4.2+] As of version 5.4.2, Cadence hard rate-limits each client IP to a maximum of 16 requests to this API per song. Since album art data size is relatively large, this limit is meant to put some reasonable maximum cap on data transfer. This count resets to 0 for all clients when the song changes. If a client, for whatever reason, makes more than 16 requests to this API over the duration of one song, Cadence will respond with a 304 Not Modified status until the song changes. (See https://github.com/kenellorando/cadence/pull/249)

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/nowplaying/albumart'

Response

  • 200 OK
{ 
	"Picture": "(base64 encoding of album art)" 
}
  • 204 No Content
    • The song playing does not have any artwork metadata.
  • 304 Not Modified [5.4.2+]
    • The client has requested album art more than 16 times during the duration of the same song, Cadence will stop re-transmitting new data until the song changes.
  • 404 Not Found
    • No song is currently playing.

Get Current Listener Count

GET /api/listeners

Returns an integer number of connected listeners.

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/listeners'

Response

  • 200 OK
{ 
	"Listeners": 11 
}

Get Current Listen URL

GET /api/listenurl

Returns the direct audio listen URL.

This is useful for programmatically setting an audio source.

Note that the return URL does not contain a protocol. You should decide whether to prepend http:// or https://, depending on your setup.

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/listenurl'

Response

  • 200 OK
{ 
	"ListenURL": "stream.cadenceradio.com/cadence1" 
}

Get Current Server Version

GET /api/version

Returns the Cadence API Server version.

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/version'

Response

  • 200 OK
{ 
	"Version": "5.1.0" 
}

Get Stream Bitrate [5.1+]

GET /api/bitrate

Returns the Cadence Icecast stream bitrate as an integer representing kilobits per second.

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/bitrate'

Response

  • 200 OK
{ 
	"Bitrate": "192" 
}

Get History [5.1+]

GET /api/history

Returns a list of up to the last ten songs played and their ending times.

Note that if the same song repeats each play will not appear as an individual entry. For example, if the same song plays twice in a row, it will only appear in history once.

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/history'

Response

  • 200 OK
[
    {
        "Title":"秒針を噛む",
        "Artist":"ZUTOMAYO",
        "Ended":"2023-02-12T06:21:48.193544277Z"
    }
]

Server-Sent Events (SSE)

Real-Time Radio Information

GET /api/radiodata/sse

Clients that connect to this endpoint will receive server-pushed data as it changes live on the back-end. This eliminates the need for clients to poll for certain data that is likely to change during radio play. This event source monitors and notifies real-time changes.

  • JavaScript

    Creating an EventSource

    let eventSource = new EventSource("/api/radiodata/sse");

    title

    eventSource.addEventListener("title", function(event) {
    console.log(event.data);    // "only my railgun"
});

    artist

    eventSource.addEventListener("artist", function(event) {
    console.log(event.data);    // "fripSide"
});

    listenurl

    eventSource.addEventListener("listenurl", function(event) {
    console.log(event.data);    // "stream.cadenceradio.com/cadence1"
});

    listeners

    eventSource.addEventListener("listeners", function(event) {
    console.log(event.data);    // 14
});

    history [5.1+]

    history does not return data, but its triggering serves as signal that a song change was detected. This is a more concise and accurate way to detect for song changes versus checking for differences in title and artist client-side.

    After detecting a change using history, it is a good idea to run /api/history to refresh play history, check /api/nowplaying/albumart to fetch new art, and possibly check /api/nowplaying/metadata to fetch now playing data (if not already received by the title and artist SSE endpoints.

    eventSource.addEventListener("history", function() {
    // no data returned, only signals that a song change was detected
});

Server Administrator Utilities

Health Check / Heartbeat

GET /ready

Returns an OK response with no body. Use this endpoint to monitor Cadence API health.

Response

  • 200 OK

Development Mode

This section requires provides optionally-enabled API endpoints that provide extra utility that may be helpful for developers testing their radio station.

To enable this mode, set CSERVER_DEVMODE in cadence.env set to 1. Don't run a production server with this enabled.

Skip Track [5.1+]

GET /api/dev/skip

Skip the currently playing track.

Examples

  • curl

    curl -XGET \
	-H 'Content-Type: application/json' \
	'https://cadenceradio.com/api/dev/skip'

Response

  • 200 OK
Clone this wiki locally