API

RSAS currently has three sets of HTTP APIs:

• Manage API - For managing individual mounts.
• Icecast API - An Icecast-compatible API, intended for use by streaming audio encoders.
• Legacy Icecast Stats API - Legacy Icecast-compatible statistics APIs, used by some third party listener statistics analysers.

For monitoring, see the /health endpoint documentation.

Authentication

API calls can either be authenticated as a source or the admin user. Sources use mount-specific credentials and can only operate on mounts they can authenticate with. Authentication is performed as HTTP Basic Auth.

To enable and configure the admin user, set a password in your configuration file by adding the following section:

<authentication>
    <admin-password>adminhackme</admin-password>
</authentication>

Manage API

POST /{mount}/manage

The Manage API allows you to perform various actions on an individual mount.

Two actions have been implemented, which allow you to force a source to disconnect (kick) or move listeners to a different mount.

The Manage API can be accessed by making an HTTP POST request to /{mount}/manage with the action parameter set to one of the action below.

Permissions: Depends on the action. See below.

Actions:

movelisteners

• Allows you move listeners from this mount to another mount, specified by the dest parameter.
• Additional parameters required:
  • dest - The mount that the listeners should be moved to (eg. /elevatormusic).
• Permissions:
  • Source can use movelisteners if they can authenticate against both the source and destination mounts.
• Example: curl -X POST -u admin:adminhackme http://myserver:8000/mount/manage -d action=movelisteners -d dest=/othermount

kick

• Allows you to force an existing source to disconnect from the mount.
• Permissions:
  • Sources can kick if they can authenticate on the mount.
• Example: curl -X POST -u admin:adminhackme http://myserver:8000/mount/manage -d action=kick

Icecast API

Source (Broadcasting)

PUT /{mount}

The Source API allows an encoder to connect and broadcast streaming audio on a mount. Once an encoder is connected, listeners can visit the URL at /{mount} and hear the streaming audio.

Permissions: Source or Admin

Parameters:

• Content-Type - Must be set to the MIME type of the streaming audio. Possible values include: audio/aac, audio/mpeg, application/ogg
• ice-bitrate - The bitrate in kbps of the stream. (eg. 128)
• ice-channels - Number of channels in the stream (1 or 2)
• ice-samplerate - Samplerate of the stream, per channel. (Eg. 44100)
• ice-name - A title for the stream, usually the station name.
• ice-description - A description of the audio in the stream.
• ice-url - A URL for the homepage of the stream.

We recommend using a fully featured streaming audio encoder like Rocket Broadcaster to broadcast through RSAS.

However, as a demonstration of the API, this single CURL command will broadcast a single MP3 file (once) through RSAS:

curl -u source:password http://myserver:8000/mount -H "Content-Type: audio/mpeg" --upload-file myfile.mp3 --limit-rate 16k

where myfile.mp3 is an MP3 file on disk, and 16k is the bitrate of the file divided by 8 (128 kbps / 8 = 16 kilobytes per sec). The upload rate limit makes CURL behave like a live streaming audio encoder would.

FFMPEG can also be used as a rudimentary streaming audio encoder, although the details are beyond the scope of this documentation. The simplest example of using FFMPEG to capture from a soundcard on Linux and broadcast it through RSAS is:

ffmpeg -f alsa -i hw:0,0 -acodec libmp3lame -ab 128k -ac 2 -content_type audio/mpeg -f mp3 icecast://source:password@myserver:8000/mount

Metadata Update

GET /admin/metadata?mount={mount}&mode=updinfo&song={metadata}

The metadata on an individual mount can be updated using this API.

Parameters:

• mount - The mount to set the metadata on.
• mode - Must always be updinfo
• song - The metadata to set for the stream. Must be formatted as artist - title.

Permissions: Source or Admin

Example:

$ curl -u username:password http://myserver:8000/admin/metadata -X GET -G --data-urlencode mount=/stream --data-urlencode mode=updinfo --data-urlencode song="Artist - Title"

Legacy Icecast Stats APIs

Before using these APIs, you must enable the Icecast-compatible emulated status page in your config file.

Admin Stats

GET /admin/stats

Returns statistics about the server itself.

Only the fields necessary to integrate with third party listener statistics services are implemented. Other fields may return stub data or be estimates only.

Permissions: Admin only

Example response:

<?xml version="1.0"?>
<icestats>
    <admin></admin>
    <banned_IPs>0</banned_IPs>
    <build>20210203133533</build>
    <client_connections>6</client_connections>
    <clients>2</clients>
    <connections>7</connections>
    <file_connections>0</file_connections>
    <host>localhost</host>
    <listener_connections>2</listener_connections>
    <listeners>1</listeners>
    <location>Earth</location>
    <outgoing_kbitrate>128</outgoing_kbitrate>
    <server_id>rocketstreamingserver</server_id>
    <server_start>16/Aug/2022:10:30:37 -0400</server_start>
    <source_client_connections>1</source_client_connections>
    <source_relay_connections>0</source_relay_connections>
    <source_total_connections>1</source_total_connections>
    <sources>1</sources>
    <stats>0</stats>
    <stats_connections>0</stats_connections>
    <stream_kbytes_read>146</stream_kbytes_read>
    <stream_kbytes_sent>147</stream_kbytes_sent>
    <source mount="/radio">
      <audio_codecid>10</audio_codecid>
      <audio_info>ice-samplerate=44100;ice-bitrate=64;ice-channels=2</audio_info>
      <bitrate>64</bitrate>
      <connected>20</connected>
      <genre>various</genre>
      <ice-bitrate>64</ice-bitrate>
      <ice-channels>2</ice-channels>
      <ice-samplerate>44100</ice-samplerate>
      <incoming_bitrate>67328</incoming_bitrate>
      <listener_connections>2</listener_connections>
      <listener_peak>1</listener_peak>
      <listeners>1</listeners>
      <listenurl>http://localhost:8000/radio</listenurl>
      <max_listeners>unlimited</max_listeners>
      <metadata_updated>16/Aug/2022:10:32:04 -0400</metadata_updated>
      <mpeg_channels>2</mpeg_channels>
      <mpeg_samplerate>44100</mpeg_samplerate>
      <outgoing_kbitrate>256</outgoing_kbitrate>
      <public>0</public>
      <queue_size>91022</queue_size>
      <server_name>New Stream</server_name>
      <server_type>audio/aac</server_type>
      <slow_listeners>0</slow_listeners>
      <source_ip>127.0.0.1</source_ip>
      <stream_start>16/Aug/2022:10:32:01 -0400</stream_start>
      <title>artist - title</title>
      <total_bytes_read>151488</total_bytes_read>
      <total_bytes_sent>150651</total_bytes_sent>
      <total_mbytes_sent>0</total_mbytes_sent>
      <user_agent>Rocket Broadcaster 1.0.0</user_agent>
    </source>
</icestats>

List Clients

GET /admin/listclients?mount={mount}

Parameters

• mount - The mount to retrieve the listeners on.

Permissions: Source or Admin

Example response:

<icestats>
    <source mount="/radio">
        <Listeners>1</Listeners>
        <listener>
            <IP>127.0.0.1</IP>
            <UserAgent>VLC/3.0.16 LibVLC/3.0.16</UserAgent>
            <Connected>13</Connected>
            <ID>16</ID>
        </listener>
    </source>
</icestats>

List Mounts

GET /admin/listmounts

Retrieve an XML list of mounts active on the server. (Offline mounts are not returned.)

Permissions: Admin only

Example response:

<?xml version="1.0"?>
<icestats>
  <source mount="/radio">
    <listeners>1</listeners>
    <Listeners>1</Listeners>
    <connected>38</connected>
    <content-type>audio/aac</content-type>
  </source>
</icestats>