1. Home
  2. Docs
  3. API Documentation
  4. Streaming Server & Broadcast status

Streaming Server & Broadcast status

Caster.fm API utilize a modified version of the Icecast 2 Streaming Server.
And so most Icecast 2 functionality should be available with our servers.

Through its web server, Icecast can serve a json based files with real-time status and statistic and a very basic internal management interface.

The base URL of your Icecast web server is constructed from the streaming server domain and streaming server port associated with your Caster.fm API account in the following way:
https://domain:port/index.html

To determinate whether the server is online simply request any of the following endpoints, if a connection error is returned it means that the server is offline.

Public Status Json

The public streams status endpoint contain some basic stats about the streaming channels, is available at: https://domain:port/status-json2.xsl and will return output like the following:

{
  "contact":"icemaster@localhost",
  "location":"Earth",
  "total_listeners":"0",
  "server_id": "sapircast.caster.fm Streaming Server 2.4",
  "mounts" : {
    "/PhBT5": {
      "server_name": "This is my server name",
      "server_description": "This is my server description",
      "server_type": "audio/mpeg",
      "stream_start": "07/Jan/2021:09:29:29 -0600",
      "bitrate": "128",
      "listeners": "0",
      "listener_peak": "4",
      "genre": "Rock",
      "mount": "/PhBT5",
      "server_url": "http://www.example.com",
      "title": "Artist - Song",
      "current_song": "Artist - Song"
    }
  }
}

Notice that every channel (mount-point) object is keyed by the mount-point rather than the channel name. If you have multiple channels, each will have its own object under the mounts property.

Private / admin STATUS JSON

The private status file will contain more detailed view of the server and stream channels stats, is located at: https://domain:port/admin/status-json2.xsl
This endpoint is private and as such will require authentication (HTTP basic auth), the username will always be admin and the password is your private token.
the private stats endpoint will return output like the following:

{
   "client_connections":"37981",
   "clients":"2",
   "connections":"55868",
   "listener_connections":"88",
   "listeners":"0",
   "outgoing_kbitrate":"1",
   "server_start":"21/Dec/2020:03:52:10 -0600",
   "source_client_connections":"10",
   "source_total_connections":"10",
   "sources":"1",
   "stream_kbytes_read":"29039155",
   "stream_kbytes_sent":"1866608",
   "mounts":{
      "/PhBT5":{
         "connected":"519780",
         "ice-bitrate":"128",
         "ice-channels":"2",
         "ice-samplerate":"44100",
         "incoming_bitrate":"128000",
         "outgoing_kbitrate":"0",
         "queue_size":"65202",
         "slow_listeners":"0",
         "source_ip":"192.114.5.10",
         "server_name":"This is my server name",
         "server_description":"This is my server description",
         "server_type":"audio/mpeg",
         "stream_start":"07/Jan/2021:09:29:29 -0600",
         "bitrate":"128",
         "listeners":"0",
         "listener_peak":"4",
         "listener_connections":"24",
         "genre":"Rock",
         "mount":"/PhBT5",
         "server_url":"http://www.altacast.com",
         "title":"Artist - Song",
         "current_song":"Artist - Song"
      }
   }
}

Notice that every channel (mount-point) object is keyed by the mount-point rather than the channel name. If you have multiple channels, each will have its own object under the mounts property.

Private / admin CURRENT Listeners JSON

Just as the previous endpoint, this endpoint has the same authentication method.
This endpoint will list all currently connected listeners to a specific channel / mount-point and is available at: https://domain:port/admin/listclients-json.xsl?mount=/PhBT5
Notice that the mount-point name is used as a parameter.
This endpoint will return output like the following:

{
   "/PhBT5":[
      {
         "ip":"192.114.5.10",
         "connected":"16",
         "lag":"0",
         "agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.141 Safari/537.36",
         "id":"55901"
      },
      ...
      ...
   ]
}

Other available stats and mangement endpoint

The streaming server provides few more helpful endpoints like metadata update, dropping specific listeners, dropping the connected source/broadcast client etc.
We encourage you to look at the WordPress Plugin source code to view how they work.