@radiolise/api

Express API server that powers Radiolise and its metadata retrieval.
Provides clients with title information from ICY radio streams.

Setup

Before setting up your own instance, check out https://gitlab.com/radiolise/radiolise.gitlab.io/-/blob/master/setup.md. The preferred method is to use Docker with Compose.

Usage

Official client library

It's recommended to use the official JavaScript wrapper if your code has access to browser APIs. See @radiolise/metadata-client.

Manual WebSocket interaction

If your code doesn't belong to a web app, you may want to establish a WebSocket connection manually. The steps described below are language-agnostic.

In your app, connect to the official backend or provide your own instance URL:

wss://backend.radiolise.com/api/data-service

Send a JSON payload with the URL of the station you want to subscribe to:

{
  "action": "subscribe",
  "data": {
    "url": "https://liveradio.swr.de/sw282p3/swr3/play.mp3"
  }
}

You should get a message like this on each title update:

{
  "action": "setTitle",
  "data": {
    "title": "Always look on the bright side of life / Monty Python"
  }
}

Parse the message as JSON and the title can be extracted (e.g. .data.title).

To unsubscribe, just send:

{
  "action": "unsubscribe"
}

Whenever the server encounters an error, it's reported like this:

{
  "action": "reportError",
  "data": {
    "type": "malformedPayload",
    "detail": "<optional detail message, omitted for most errors>"
  }
}

See the source code for details on error types: https://gitlab.com/radiolise/radiolise.gitlab.io/-/blob/master/packages/common/index.ts

HTTP interaction

Mainly implemented for backward compatibility with the deprecated PHP service (https://gitlab.com/radiolise/deprecated-service). Prefer WebSockets where possible as they allow quick, bidirectional and – in this case – more private communication.

Official URL of the HTTPS endpoint:

https://backend.radiolise.com/api/v1/metadata

Getting metadata using JSON requests:

POST /api/v1/metadata HTTP/1.1
Host: backend.radiolise.com
Content-Type: application/json

{"url":"https://liveradio.swr.de/sw282p3/swr3/play.mp3"}

Using query parameters:

Warning: Query parameters are often persisted in server logs, and with the client periodically sending a stream URL, the server owner could find out about when users are listening to which stations without using any further tools.

GET /api/v1/metadata?url=https://liveradio.swr.de/sw282p3/swr3/play.mp3 HTTP/1.1
Host: backend.radiolise.com

A typical response:

{
  "content-type": "audio/mpeg",
  "description": "SWR3",
  "genre": "Pop Music",
  "name": "SWR3 MP3 128",
  "title": "Always look on the bright side of life / Monty Python",
  "url": "https://www.swr3.de/"
}

License

MIT

Copyright (c) 2023-present Marco Bauer