Open-source core

Encoders and compatibility

Which sources, players, admin tools and directories Lurcast works with, and the Icecast- and SHOUTcast-compatible endpoints it serves.

Lurcast is an independent server that speaks the protocols Icecast and SHOUTcast clients use. It is compatible with Icecast and SHOUTcast tools; it is not affiliated with either project.

Icecast sources#

Icecast encoders connect to the main port (or tls_port) with HTTP PUT or the legacy SOURCE method. Chunked transfer encoding is supported. They log in with username source and source_password, or with the mount's own username and password when the mount sets them.

ffmpeg -re -i song.mp3 -c copy -content_type audio/mpeg -f mp3 \
  icecast://source:change-me-source@radio.example:8000/radio.mp3

SHOUTcast sources#

SHOUTcast encoders need their own port. Set shoutcast_port and map stream IDs to mounts:

shoutcast_port: 8001
shoutcast_mount: /shoutcast   # stream ID 1
shoutcast_mounts:
  2: /second-stream
uvox_cipher_key: foobar
  • SHOUTcast v1 sources connect to shoutcast_port and go to shoutcast_mount.
  • SHOUTcast v2 sources use encrypted Ultravox 2.1. The stream ID (SID) picks the mount from shoutcast_mounts; SID 1 falls back to shoutcast_mount. uvox_cipher_key must match the encoder's cipher key.

Both log in with a password only. Lurcast checks it against the mount's password, or source_password when the mount has none.

Formats#

Lurcast does not transcode. It passes the encoded audio through and repairs only what a late-joining listener needs.

  • MP3 (MPEG 1, 2 and 2.5, Layer I, II and III, including free-format streams).
  • AAC in ADTS and LATM/LOAS.
  • Ogg Vorbis, Opus, Theora, Speex and Skeleton, including multiplexed logical streams.
  • Other containers and codecs are relayed as they are, without format-specific repair.

Malformed MP3 and AAC source bytes are removed before they reach listeners. A listener who joins mid-stream gets a burst that starts on a verified frame boundary (MP3, AAC), or the cached headers of every logical stream followed by complete pages (Ogg).

Listener URLs#

URL For
/<mount> Icecast-style players, for example /radio.mp3.
/<mount>.m3u A playlist file pointing at the mount.
/; SHOUTcast v1 players.
/stream/<sid> SHOUTcast v2 players, by stream ID.

Lurcast answers with an HTTP response or ICY 200 OK, whichever the player expects.

ICY metadata#

Players that send Icy-MetaData: 1 get ICY metadata every metadata_interval bytes (default 8192). Metadata goes only into MP3 and AAC streams, never into Ogg.

Update the current song through the Icecast-compatible endpoint, with the source or admin account:

curl --user source:change-me-source --get \
  --data-urlencode 'mount=/radio.mp3' \
  --data-urlencode 'mode=updinfo' \
  --data-urlencode 'song=Artist - Title' \
  http://radio.example:8000/admin/metadata

SHOUTcast admin.cgi?mode=updinfo and Ultravox metadata updates also work, so encoders that send titles keep working.

Status pages#

Icecast's /status.xsl address serves Lurcast's public status page, the same as /. Icecast's XSL-based admin pages are replaced by the admin dashboard at /admin/. Scripts that call /admin without asking for HTML still get JSON.

Icecast-compatible admin endpoints#

These use basic authentication with the admin account; /admin/metadata also accepts the mount's source login. The statistics and listener endpoints answer in Icecast-style XML:

Endpoint Does
/admin/stats Server and mount statistics.
/admin/listmounts Active mounts.
/admin/listclients?mount= Listeners on a mount.
/admin/killclient?mount=&id= Disconnect one listener.
/admin/moveclients?mount=&destination= Move every listener (or one, with id) to another live mount with the same format.
/admin/metadata Update the current song (mode=updinfo).
/admin/killsource?mount= Disconnect a mount's source.
/admin/fallbacks?mount=&fallback= Change a mount's fallback at runtime. An empty fallback= removes it.
curl --user admin:change-me-admin http://radio.example:8000/admin/stats
curl --user admin:change-me-admin 'http://radio.example:8000/admin/listclients?mount=/live'
curl --user admin:change-me-admin 'http://radio.example:8000/admin/moveclients?mount=/live&destination=/backup'

Moved listeners keep their original ICY metadata interval.

Public status JSON in the Icecast format is at /status-json.xsl (also /status.json).

SHOUTcast-compatible endpoints#

Statistics are public and addressed by stream ID (sid, default 1), using shoutcast_mount and shoutcast_mounts:

Endpoint Returns
/7.html The classic one-line status.
/stats?sid= Stream statistics. XML, or JSON with json=1.
/statistics Every stream. XML, or JSON with json=1.
/currentsong?sid= The current title.
/played?sid= Song history. XML, or JSON with type=json.
/played.html?sid= Song history as a web page.
/admin.cgi?sid=&mode=&pass= Modes updinfo, viewxml, viewjson, kicksrc and kickdst.
curl http://radio.example:8000/7.html
curl 'http://radio.example:8000/stats?sid=1&json=1'
curl 'http://radio.example:8000/played?sid=1&type=json'
curl 'http://radio.example:8000/admin.cgi?sid=1&mode=viewxml&pass=change-me-admin'

kickdst takes a listener UID or IP address. /nextsong is not supported, because sources do not announce upcoming tracks.

admin.cgi takes the admin password in the query string and runs kicksrc, kickdst and updinfo on GET, because SHOUTcast tools expect that. Query strings end up in proxy and access logs. Serve admin traffic over TLS, and allow /admin.cgi and /admin/ only from trusted addresses at your proxy or firewall.

JSON API#

GET /api/v1/stations returns every active, non-hidden station: identity, current song with timestamps, listener totals, source protocol, listen URL and, for MP3, the observed technical details.

curl http://radio.example:8000/api/v1/stations

Change a live station with admin or source basic authentication. Every field is optional; an empty current_song clears it:

curl --user admin:change-me-admin --request PATCH \
  --header 'Content-Type: application/json' \
  --data '{"name":"Example Radio","genre":"Jazz","current_song":"Artist - Title"}' \
  http://radio.example:8000/api/v1/stations/radio.mp3

Relays and fallbacks#

  • Pull relays copy a stream from another server over HTTP or HTTPS and reconnect when it drops. They can connect only while someone listens (on_demand).
  • Master relays mirror every mount of an Icecast-compatible master server (master_url).
  • Fallbacks move listeners to another mount, or to a looping file in webroot, when a source ends, and back again when it returns.

See the configuration reference for the settings.

Directory listings (YP)#

Sources that send Ice-Public: 1 or icy-pub: 1 are added to the directories in yp_urls, kept fresh, and removed when they stop. See configuration.

External authentication#

With auth_url set, Lurcast asks your service before it accepts a source or listener, and tells it when listeners and mounts come and go. This follows the Icecast URL authentication callbacks (stream_auth, listener_add, listener_remove, mount_add, mount_remove). See configuration.