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/
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 contains some basic stats about the streaming channels, is available at: https://domain:port/admin/publicstats.json
[
{
"name": "icestats",
"ns": "http://icecast.org/specs/legacystats-0.0.1"
},
{
"admin": "[email protected]",
"host": "sapircast.caster.fm",
"location": "Earth",
"server_id": "sapircast.caster.fm Streaming Server 2.5",
"server_start_iso8601": "2024-05-29T14:23:56-0400",
"modules": {},
"source": {
"/puTM7": {
"display-title": "Mil17.03.2023 Hacienda La Paz",
"genre": "Other",
"listeners": 1,
"listenurl": "http://sapircast.caster.fm:12302/puTM7",
"server_description": "Konzistencija Intenziteta",
"server_name": "Kulturica",
"stream_start_iso8601": "2024-06-01T10:10:16-0400",
"content-type": "audio/aacp",
"playlist": {
"playlist": {
"track": [
{
"title": "Cold Grits - It's Your Thing"
},
{
"title": "DOUT.D - Mathematic"
},
{
"title": "Kulturica Short"
},
{
"title": "Mil17.03.2023 Hacienda La Paz"
}
]
}
},
"metadata": {
"x_icy_title": "Mil17.03.2023 Hacienda La Paz"
}
}
}
}
]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/stats.json
the private stats endpoint will return output like the following:
[
{
"name": "icestats",
"ns": "http://icecast.org/specs/legacystats-0.0.1"
},
{
"admin": "[email protected]",
"client_connections": 9243,
"clients": 3,
"connections": 18504,
"file_connections": 0,
"host": "sapircast.caster.fm",
"instance_uuid": "7b09aa2b-3239-4d41-9fad-54f4734814f0",
"listener_connections": 12,
"listeners": 0,
"location": "Earth",
"server_id": "sapircast.caster.fm Streaming Server 2.5",
"server_start": "Sat, 01 Jun 2024 06:02:52 -0400",
"server_start_iso8601": "2024-06-01T06:02:52-0400",
"source_client_connections": 22,
"source_relay_connections": 0,
"source_total_connections": 22,
"sources": 1,
"stats": 0,
"stats_connections": 0,
"modules": {},
"authentication": [
{
"id": "2",
"type": "static",
"name": "legacy-admin",
"management-url": "/admin/manageauth.xsl?id=2",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": true
},
{
"id": "0",
"type": "anonymous",
"name": "master-all-options",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": false
},
{
"id": "1",
"type": "anonymous",
"name": "master-all-public",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": false
},
{
"id": "3",
"type": "anonymous",
"name": "anonymous",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": false
}
],
"source": {
"/6jzoV": {
"allow-direct-access": "true",
"audio_info": "ice-bitrate=96;ice-channels=2;ice-samplerate=44100",
"authenticator": true,
"bitrate": "96",
"current_bitrate": "95838.393276",
"genre": "experimental",
"instance_uuid": "63466152-abb1-49e2-8129-7e0f9999def2",
"listener_peak": 2,
"listeners": 0,
"listenurl": "http://sapircast.caster.fm:15019/6jzoV",
"max_listeners": 100,
"public": false,
"server_description": "audio of machine",
"server_name": "SoundscapeParasite",
"server_type": "audio/mpeg",
"server_url": "(null)",
"slow_listeners": 0,
"source_ip": "88.200.43.25",
"stream_start": "Sun, 02 Jun 2024 06:22:23 -0400",
"stream_start_iso8601": "2024-06-02T06:22:23-0400",
"total_bitrate": "95998",
"total_bytes_read": 47639200,
"total_bytes_sent": 5022812,
"user_agent": "butt 1.42.0",
"content-type": "audio/mpeg",
"playlist": {
"playlist": {
"track": []
}
},
"metadata": {},
"authentication": [
{
"id": "4",
"type": "anonymous",
"name": "mount-6jzoV-options-all",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": false
},
{
"id": "5",
"type": "static",
"name": "mount-6jzoV-source-client-stream",
"management-url": "/admin/manageauth.xsl?id=5",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": true
},
{
"id": "6",
"type": "static",
"name": "mount-6jzoV-source-client-get-admin",
"management-url": "/admin/manageauth.xsl?id=6",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": true
},
{
"id": "7",
"type": "static",
"name": "mount-6jzoV-global-admin-get-admin",
"management-url": "/admin/manageauth.xsl?id=7",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": true
},
{
"id": "8",
"type": "url",
"name": "mount-6jzoV-listener-stream",
"management-url": "/admin/manageauth.xsl?id=8",
"can-adduser": true,
"can-deleteuser": true,
"can-listuser": true
},
{
"id": "9",
"type": "anonymous",
"name": "mount-6jzoV-all-deny",
"can-adduser": false,
"can-deleteuser": false,
"can-listuser": false
}
]
}
}
}
]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?mount=/6jzoVNotice that in this example the mount-point name (PhBT5) is used as a parameter.
This endpoint will return output like the following:
[
{
"name": "icestats",
"ns": "http://icecast.org/specs/legacystats-0.0.1"
},
{
"modules": {},
"source": {
"/6jzoV": {
"listeners": 1,
"listener": [
{
"id": "18520",
"ip": "192.1.1.1",
"useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36 Edg/125.0.0.0",
"referer": "https://soundscape.ismyradio.com/",
"host": "sapircast.caster.fm:15019",
"connected": 15,
"role": "mount-6jzoV-listener-stream",
"acl": "mount-6jzoV-listener-stream",
"tls": "true",
"protocol": "http",
"geoip": {
"country": [
{
"iso-alpha-2": "il"
}
],
"location": [
{
"latitude": "32.012300",
"longitude": "34.770500"
}
]
}
}
],
"geoip": {
"country": [
{
"iso-alpha-2": "il",
"listeners": 1,
"tls": 1,
"ipv6": 0
}
],
"location": []
}
}
}
}
]