PHP client
quikcast/quikcast is a PHP library for the management API. It returns typed read-only objects, maps every API error code to its own exception and builds on ElliePHP HttpClient (Symfony HttpClient).
Source and issues: github.com/RadioPlatform/quikcastphp.
Install
It needs PHP 8.4 or newer.
composer require quikcast/quikcastConnect
Give the client the admin address and the management token. Read the token from the environment or a secret store, never from source code.
use Quikcast\QuikcastClient;
$client = QuikcastClient::create('http://127.0.0.1:9090', getenv('QUIKCAST_TOKEN'));
$server = $client->server()->get();
echo $server->state->value; // accepting | draining | shutting_down
$stats = $client->stats()->get();
printf("listeners=%d sources=%d\n", $stats->activeListeners, $stats->activeSources);
foreach ($client->mounts()->list() as $mount) {
echo $mount->path.' '.($mount->source?->track->title ?? '(no source)').PHP_EOL;
}The management API is on admin_listen, which is loopback by default. See client libraries for how to reach it from another host.
Resources
One method group per part of the API:
| Call | What it does |
|---|---|
server() | Server info, capabilities, limits, drain() |
stats() | Counters |
mounts() | List and inspect mounts |
sources() | Inspect or disconnect a mount's source |
listeners() | Page, iterate, get or disconnect listeners |
relays() | List, inspect, restart, stop |
hls() | Streams, renditions and directory-stream sessions |
bans() | List, create and lift bans |
revocations() | List, revoke and restore signed links |
history() | Listener history |
metadata() | Update the track title (source credentials) |
metrics() | Prometheus text |
health() | Liveness and readiness probes |
Listeners
Listener lists are paged. Use one page, walk every page lazily, or collect them all.
// One page.
$page = $client->listeners()->page('/radio.mp3', limit: 100);
// Every page, one at a time.
foreach ($client->listeners()->paginate('/radio.mp3') as $page) {
foreach ($page->items as $listener) {
echo $listener->id.PHP_EOL;
}
}
// Everything at once. Mount registries are bounded, so this is fine for admin tools.
$all = $client->listeners()->all('/radio.mp3');
// Disconnect one listener.
$client->listeners()->disconnect('0123456789abcdef0123456789abcdef');Sources
// Null when the mount exists but nothing is connected.
$source = $client->sources()->get('/radio.mp3');
// Pass the generation so you never disconnect a newer source by mistake.
if ($source !== null) {
$client->sources()->disconnect('/radio.mp3', $source->generation);
}Relays
Restart and stop return a snapshot straight away (HTTP 202). Pass the revision you read, and poll get() until the state settles.
foreach ($client->relays()->list() as $relay) {
$updated = $client->relays()->restart($relay->mount, $relay->revision);
echo $updated->state->value.PHP_EOL;
// $client->relays()->stop($relay->mount, $relay->revision);
}HLS
foreach ($client->hls()->listStreams() as $stream) {
foreach ($client->hls()->listRenditions($stream->name) as $rendition) {
echo $rendition->name.' '.$rendition->format.PHP_EOL;
}
}A stream served from a directory has $stream->isDirectory() set, plus listener and request counters. List its sessions with $client->hls()->listeners('radio').
Bans and link revocation
Both are held in memory on the server: they are lost on restart and not shared between replicas, so call each node.
$result = $client->bans()->create('203.0.113.0/24', ttlSeconds: 86400, reason: 'scraper', kick: true);
echo $result->kickedListeners;
foreach ($client->bans()->list() as $ban) {
echo $ban->ip.' '.$ban->expiresInSeconds.PHP_EOL;
}
$client->bans()->lift('203.0.113.0/24'); // the same text it was created with
// Stop one signed link before it expires. The sig and expires come from the link itself.
$client->revocations()->revoke($sig, $expires);
$client->revocations()->restore($sig);See signed links.
Listener history
$history = $client->history()->get(); // whole server, last 60 minutes
$history = $client->history()->get('/radio.mp3', minutes: 180); // one mount, 1 to 1440 minutes
echo $history->peakListeners24h;
echo $history->uniqueListenersEstimate24h; // an estimate, about 3% error
foreach ($history->minutes as $m) {
echo $m->startMs.' '.$m->peakListeners.PHP_EOL;
}History is kept in memory and resets on restart.
Policies and counters
MountInfo and ServerInfo expose the access rules in effect (access, sourceAccess, listenerAuth, hlsListenerAuth), the fallback target, listener capacity, disconnect counters and an embedded relay snapshot. Rule contents and secret paths are never included. ServerInfo::hasCapability() checks the list of features the server advertises.
Drain
$client->server()->drain(); // one way until restart; safe to repeatUpdate the track title
This is not a management call. It runs on the streaming port with the mount's encoder username and password. Pass the listen address, not the admin address.
$client->metadata()->updateSong(
'http://127.0.0.1:8000', // listen address
'/radio.mp3',
'source', // the mount's encoder username
$sourceSecret, // the mount's encoder password
'Artist - Title',
);
// Or artist and title separately:
$client->metadata()->updateTrack('http://127.0.0.1:8000', '/radio.mp3', 'source', $sourceSecret, 'Title', 'Artist');Metrics and health
Both are on the admin address and need no token.
$text = $client->metrics()->text(); // Prometheus text
$client->health()->live(); // true while serving
$client->health()->ready(); // false while drainingErrors
Every API error maps to its own exception. They all extend Quikcast\Exception\QuikcastException, which carries ->statusCode, ->errorCode and, for a 405, ->allow.
| HTTP | Code | Exception |
|---|---|---|
| 401 | unauthorized | UnauthorizedException |
| 400 | invalid_request | InvalidRequestException |
| 400 | invalid_pagination | InvalidPaginationException |
| 404 | mount_not_found | MountNotFoundException |
| 404 | listener_not_found | ListenerNotFoundException |
| 404 | hls_not_found | HlsNotFoundException |
| 404 | relay_not_found | RelayNotFoundException |
| 404 | ban_not_found | BanNotFoundException |
| 404 | revocation_not_found | RevocationNotFoundException |
| 404 | endpoint_not_found | EndpointNotFoundException |
| 405 | method_not_allowed | MethodNotAllowedException |
| 409 | source_not_connected | SourceNotConnectedException |
| 409 | conflict | ConflictException (stale generation or revision) |
| 507 | ban_list_full | BanListFullException |
| 507 | revocation_list_full | RevocationListFullException |
| 503 | server_draining | ServerDrainingException |
| 500 | internal_error | InternalErrorException |
use Quikcast\Exception\ConflictException;
use Quikcast\Exception\MountNotFoundException;
try {
$client->sources()->disconnect('/radio.mp3', $generation);
} catch (ConflictException $e) {
// The source changed. Read it again and retry.
} catch (MountNotFoundException $e) {
// Unknown mount.
}Network failures, timeouts and malformed JSON throw TransportException. Bad arguments (a limit outside 1 to 200, a malformed listener ID, an empty mount) throw InvalidArgumentException before anything is sent.
Mount paths
Pass /radio.mp3 or radio.mp3 or nested/radio.mp3. The client adds the leading slash and encodes each segment, so nested mounts never collide with reserved paths.