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/

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
and will return output like the following:

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
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:

JSON
[
    {
        "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=/6jzoV
Notice that in this example the mount-point name (PhBT5) is used as a parameter.
This endpoint will return output like the following:

JSON
[
    {
        "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": []
                }
            }
        }
    }
]
Updated on June 2, 2024
Was this article helpful?

Related Articles