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.

sh
composer require quikcast/quikcast

Connect ​

Give the client the admin address and the management token. Read the token from the environment or a secret store, never from source code.

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

CallWhat 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.

php
// 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 ​

php
// 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.

php
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 ​

php
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').

Both are held in memory on the server: they are lost on restart and not shared between replicas, so call each node.

php
$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 ​

php
$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 ​

php
$client->server()->drain(); // one way until restart; safe to repeat

Update 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.

php
$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.

php
$text = $client->metrics()->text();   // Prometheus text

$client->health()->live();   // true while serving
$client->health()->ready();  // false while draining

Errors ​

Every API error maps to its own exception. They all extend Quikcast\Exception\QuikcastException, which carries ->statusCode, ->errorCode and, for a 405, ->allow.

HTTPCodeException
401unauthorizedUnauthorizedException
400invalid_requestInvalidRequestException
400invalid_paginationInvalidPaginationException
404mount_not_foundMountNotFoundException
404listener_not_foundListenerNotFoundException
404hls_not_foundHlsNotFoundException
404relay_not_foundRelayNotFoundException
404ban_not_foundBanNotFoundException
404revocation_not_foundRevocationNotFoundException
404endpoint_not_foundEndpointNotFoundException
405method_not_allowedMethodNotAllowedException
409source_not_connectedSourceNotConnectedException
409conflictConflictException (stale generation or revision)
507ban_list_fullBanListFullException
507revocation_list_fullRevocationListFullException
503server_drainingServerDrainingException
500internal_errorInternalErrorException
php
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.