Configuration reference
Every setting Quikcast accepts, in the order you will meet them in a real file. Each entry tells you what the setting does, its type, its default, the values it accepts, and whether a SIGHUP reload applies it or it needs a restart.
Prefer a form to a text editor? The config generator builds a file for the common setups.
New to Quikcast? Start with the quickstart for a working local setup, then come back here when you need to know exactly what a line does. A copy-ready file with every option commented lives at config/quikcast.reference.toml in the repository; config/quikcast.example.toml is the short starting point.
How to read this page
Each setting is introduced like this:
Type
integer· Default4096· Range1–65,536· Applies restart
| Field | Meaning |
|---|---|
| Type | The TOML type: string, integer, boolean, array of strings, table, or array of tables. |
| Default | The value used when the key is omitted. "none" means the feature is off or the key is required. |
| Range / Values | What is accepted. Anything else stops startup with a diagnostic that names the key. |
| Applies | reload means kill -HUP applies it to new work without dropping connections. restart means the process must be restarted. |
Rules that apply to the whole file
- Unknown keys are rejected. A typo such as
listner_limitstops startup instead of being ignored. [[mount]]and[[relay]]also work.[[mounts]]and[[relays]]are lists, one block per entry, so the guides use the plural. If the singular reads better to you,[[mount]]and[[relay]]are accepted too, along with their sub-tables ([mount.access],[mount.listener_auth]). Use one spelling per file: mixing[[mount]]with[[mounts]]stops startup withduplicate field mounts(and likewise for relays).- Root keys come first.
listen,admin_listenandlog_filtermust appear before the first[table]header, or TOML assigns them to that table. - Paths are relative to the config file. A
*_filevalue such assecrets/radio-sourceresolves beside the configuration file, not the working directory. Absolute paths stay absolute.~and$VARIABLESare not expanded. - Size limit. The configuration file itself may be at most 128 KiB.
- A failed reload changes nothing. If SIGHUP finds any error, the running configuration stays active and the error is logged.
TIP
Validate any change before applying it:
quikcast --config quikcast.toml --check--check runs the complete startup validation, including reading every secret, list, certificate and database, and then exits without binding a port. Exit code 0 means the file is good.
Secret values
Secrets are never defaults, so you must supply them. Where a setting offers both an inline value and a _file form, prefer the file.
| Kind | Length | Characters | Used by |
|---|---|---|---|
| Mount / HLS password | 16–512 bytes | any bytes; a password may contain : | secret, secret_file on mounts, [sources], [hls] |
| Usernames | 1–64 bytes | ASCII graphic, no whitespace, no : | every username |
| Management token | 32–512 bytes | ASCII graphic, no whitespace | [management] |
| Upstream relay password | 1–512 bytes | ASCII graphic, no whitespace | [[relays]] |
| Signed-URL key | 32–4,096 bytes | any bytes | listener_auth |
| UI password | at least 15 characters, at most 512 bytes | UTF-8 | [ui] |
A secret file contains only the secret. One trailing newline is removed; nothing else is trimmed. Do not wrap the value in quotes or write password=.... Files are read at startup and on SIGHUP, so editing a file takes effect only after a successful reload or restart.
Generate a good value with:
openssl rand -hex 32 > secrets/radio-sourceRoot settings
These keys sit at the top of the file, above every table.
listen
Type
string(host:port) · Default"127.0.0.1:8000"· Applies restart
The address of the public listener. Players, encoders, HLS clients and the operator console all connect here.
The default only accepts connections from the same machine, which is right for local testing or when a reverse proxy runs beside Quikcast. To accept outside connections, bind a public address such as "0.0.0.0:8000". Inside Docker you must use 0.0.0.0, otherwise the published port has nothing to reach.
listen = "0.0.0.0:8000"Use port 0 only in automated tests; the operating system then picks a free port.
admin_listen
Type
string(host:port) · Default"127.0.0.1:9090"· Applies restart
The address of the private listener. It serves /health/live, /health/ready, /metrics and the native /api management routes.
This address must be a loopback address (127.0.0.1 or ::1) unless you opt in with management.allow_remote. Without that switch Quikcast refuses to start with a non-loopback admin address, because these routes can disconnect listeners and drain the server. Reach it from outside through an SSH tunnel or an internal-only proxy, or read remote management before opting in.
log_filter
Type
string· Default"quikcast=info"· Applies restart
A tracing filter that decides how much is logged. Examples: "quikcast=debug" for connection-level detail, "quikcast=warn" for problems only.
The QUIKCAST_LOG environment variable overrides this value when set. Logs go to standard output through a bounded, non-blocking writer, so the output must be a terminal or a pipe that something is reading. Redirecting straight to a regular file is rejected. Logging currently requires a Unix system.
[tls]
Serve HTTPS directly from Quikcast. Omit the table to serve plain HTTP, which is the right choice when a proxy such as Traefik, nginx or Cloudflare already terminates TLS.
[tls]
cert_file = "secrets/tls/fullchain.pem"
key_file = "secrets/tls/privkey.pem"TLS applies to the public listener only, unless you set management.tls for a remotely exposed admin listener. Otherwise the admin listener stays plain. Quikcast offers TLS 1.2 and 1.3 with ALPN http/1.1. A plain HTTP request sent to a TLS port is closed without a response, and the TLS handshake counts against header_timeout_ms and max_handshakes.
INFO
Enabling or disabling [tls] needs a restart. Renewing a certificate does not: replace the files and send SIGHUP. New connections use the new certificate, existing listeners are not interrupted, and a bad file leaves the old certificate in place.
cert_file
Type
string(path) · Default none (required inside[tls]) · Max size 256 KiB · Applies reload
A PEM file containing the certificate chain, leaf certificate first, with one to eight certificates. A Let's Encrypt fullchain.pem is exactly the right file.
key_file
Type
string(path) · Default none (required inside[tls]) · Max size 64 KiB · Applies reload
A PEM file with the matching private key (PKCS#8, PKCS#1 or SEC1). A key that does not match the certificate stops startup or the reload with an error.
[trusted_proxies]
Tells Quikcast which network peers are your own proxies, so it can report real listener addresses instead of the proxy's address. The real address feeds IP rules, country rules, listener statistics and logs. By default no proxy is trusted and Quikcast uses the connecting address as is.
[trusted_proxies]
ips = ["127.0.0.1", "10.0.0.0/8"]
providers = ["cloudflare"]
proxy_protocol = falseWARNING
Only list infrastructure you control. Anyone you trust here can claim any client address, which weakens every IP and country rule.
ips
Type
array of strings· Default[]· Max 64 entries · Applies reload
IP addresses or CIDR networks (IPv4 or IPv6) of your proxies. When a connection comes from one of these, Quikcast reads the X-Forwarded-For header and walks it right to left, stopping at the first address that is not itself trusted. Bare addresses mean a single host (/32 or /128). Hostnames and ports are rejected. Errors name the entry, for example trusted_proxies.ips[1].
The same trust decision applies to X-Forwarded-Prefix, which lets the operator console work behind a proxy that mounts it under a path prefix.
providers
Type
array of strings· Default[]· Values"cloudflare"· Applies reload
Adds the built-in list of Cloudflare's published address ranges. A connection that comes directly from Cloudflare may then supply the client address in CF-Connecting-IP. The ranges ship inside Quikcast and are never fetched at runtime; they are refreshed by upgrading Quikcast.
proxy_protocol
Type
boolean· Defaultfalse· Applies reload (new connections)
Use this behind a layer-4 load balancer (HAProxy in TCP mode, nginx stream, a cloud network load balancer) that cannot add HTTP headers. When true, every public connection must begin with a PROXY protocol v1 or v2 header, sent before TLS and HTTP.
- It needs
ipsorproviders. Only peers that match them may send the header; a connection from anyone else is closed without a reply. - The client address in the header replaces the connecting address for all access rules and statistics.
- A header marked
LOCALorUNKNOWN, which is what health checks send, keeps the connecting address. - A missing or malformed header closes the connection.
- The admin listener never uses PROXY protocol.
[trusted_proxies]
ips = ["10.0.0.0/8"]
proxy_protocol = trueWARNING
Turning this on means every public connection, including your own health checks and direct curl tests, has to arrive through the proxy.
[management]
Enables the native management API on the admin listener (/api/server, /api/stats, /api/mounts, /api/listeners, /api/history, and others).
The API is fail-closed: without this table every /api request is rejected. Mount and HLS passwords do not unlock it.
[management]
token_file = "secrets/management-token"Call it by sending the token as a Bearer credential to the admin address:
curl -H "Authorization: Bearer $(cat secrets/management-token)" \
http://127.0.0.1:9090/api/servertoken_file
Type
string(path) · Default none · Applies reload
Path to a file holding the token, 32–512 ASCII graphic characters. Set exactly one of token_file and token. Editing the file rotates the token after the next successful reload.
token
Type
string· Default none · Applies reload
The token written directly in the config. It works, but keeps a secret in a file you may commit or share. Prefer token_file.
allow_remote
Type
bool· Defaultfalse· Applies restart
Permits admin_listen to bind a non-loopback address such as 0.0.0.0:8001, so a remote management client (for example a hosting control panel) can read /api/stats, /api/mounts, /api/listeners and call DELETE /api/listeners/{id}. With false (the default) a non-loopback admin_listen stops startup with an error that names this switch.
When it is true, validation (quikcast --check included) also requires a [management] token and applies the protections described under remote management.
allowed_ips
Type
array of strings· Default[]· Applies reload
Only with allow_remote = true. IP addresses or CIDR ranges (same syntax as [trusted_proxies], at most 64 entries) allowed to connect to the admin listener. Other peers are dropped before any bytes are read. Empty means any peer that holds the token. The check uses the TCP peer address, never X-Forwarded-For. Setting it without allow_remote is a configuration error.
tls
Type
bool· Defaultfalse· Applies reload
Only with allow_remote = true, and only when a top-level [tls] certificate and key are configured. Serves the admin listener over TLS with the same certificate as the public listener (TLS 1.2/1.3, ALPN http/1.1); health and metrics on that port then also require HTTPS. Enabling or disabling [tls] itself still needs a restart. Setting tls = true without allow_remote or without [tls] is a configuration error.
Remote management
admin_listen = "0.0.0.0:8001"
[management]
token_file = "secrets/management-token" # openssl rand -hex 32
allow_remote = true
allowed_ips = ["203.0.113.10"] # the management client
tls = true # needs [tls]What Quikcast enforces once allow_remote = true:
- A token of at least 32 bytes, compared in constant time (padded fixed-size comparison). There are no accounts and no lockout of the token itself.
- Per-client failed-authentication throttling: after 10 failed attempts within 60 seconds, a client receives
429 too_many_failureswithRetry-After(even for a correct token) until the window ends. IPv6 clients share one budget per /64. The table holds 4096 clients; if it is full of active entries, new clients are not tracked. A successful call clears the client's counter. Withoutallow_remote, nothing is throttled, as before. - Optional peer allow-list (
allowed_ips) and optional TLS (tls). - A startup warning in the log that the API is reachable beyond loopback.
What it does not do:
- Without
tls = truethe bearer token and all responses travel in clear text. Put the port behind a TLS-terminating proxy, a VPN or a private network, and firewall it to the management client. /health/live,/health/readyand/metricsshare this listener and stay unauthenticated, so they are reachable too, and so are the HLS ingest routes (/internal/..., protected by the HLS producer credential). Useallowed_ipsor a firewall to keep them private.- Throttling is per client IP behind your firewall's view; a distributed attacker is not stopped, and an attacker who can spoof a trusted client address can lock that address out. A token is only as strong as its entropy.
- The token grants every management action (drain, disconnect, source control). There are no read-only tokens.
[icecast_admin]
Serves Icecast's admin API on the public listener, so Icecast control panels and monitoring tools can use Quikcast as a remote Icecast server. It is off unless this table exists. See Icecast-compatible admin API.
[icecast_admin]
username = "admin"
password_file = "secrets/icecast-admin"| Path | Returns |
|---|---|
/admin/stats | Server totals and one <source> per live mount: listeners, artist, title, content type, bitrate, listen URL |
/admin/listmounts | Live mounts with their listener counts |
/admin/listclients?mount=/radio.mp3 | One <listener> per client with IP, UserAgent, Connected (seconds) and ID |
/admin/killclient?mount=/radio.mp3&id=… | Disconnects that listener |
/status-json.xsl | Public JSON status with no login, as Icecast serves it. ?mount= narrows it, and a mount with hide_listener_count reports 0 listeners |
A .xsl or .xml suffix is accepted on each /admin name. A title written "Artist - Title" is reported as separate artist and title. The same credential may also call /admin/metadata. Wrong or missing credentials get 401 with a Basic challenge, and repeated failures from one address are throttled with 429.
username
Type
string· Default"admin"· Applies reload
The Basic-auth user name.
password_file
Type
string(path) · Default none · Applies reload
Path to a file holding the password, 16–512 bytes. Set exactly one of password_file and password.
password
Type
string· Default none · Applies reload
The password written directly in the config. Prefer password_file.
[ui]
The embedded operator console, served at /console on both listeners, and an optional public status page at /. The table can also be written as [console]; use one spelling per file. It is compiled into the binary, so there is nothing else to install. It is off by default.
[ui]
enabled = true
mode = "private"
username = "admin"
password_file = "secrets/ui-password"Behind a reverse proxy that serves the console under a path prefix and strips it (for example /28000/console forwarded as /console), the proxy can send X-Forwarded-Prefix: /28000. Quikcast then prefixes the console's asset, script and link URLs, its API calls, its redirects and the session cookie Path (/28000/console). The header is honoured only from peers listed in [trusted_proxies]. A value must start with /, have no trailing /, // or .., use only letters, digits and . _ ~ - /, and be at most 128 characters; anything else, or a repeated header, is ignored. Stream URLs in the console use [ui] public_url when set; otherwise same-origin links carry the prefix too.
The console has one operator identity, separate from source, HLS and management credentials. Any change to the effective UI settings, including a password change, signs out existing sessions after the next reload.
enabled
Type
boolean· Defaultfalse· Applies reload
When false, every /console and /ui URL, the status page at / and the assets all return 404.
mode
Type
string· Default"private"· Values"private","public","both"· Applies reload
"private" shows a login form and, after sign-in, the full console at /console. "public" shows only a small sanitized status page at / and offers no login or controls. "both" runs the two at once: the status page at / and the console at /console, which still needs its sign-in. /console/status is readable without signing in in every mode where the UI is enabled. The console used to live at /ui; requests to /ui and below redirect to /console.
username
Type
string· Default""· Range 1–64 ASCII graphic bytes · Applies reload
The operator login name. Required in private mode.
password_file
Type
string(path) · Default none · Applies reload
Path to a file holding the password: at least 15 characters excluding surrounding whitespace, at most 512 bytes. Obvious values (a single repeated character, common passwords) are rejected. Required in private mode. The file is re-read on every reload.
secure_cookie
Type
boolean· Defaulttrue· Applies reload
Marks the session cookie Secure, so browsers only send it over HTTPS. Leave it on in production, including when a proxy terminates TLS. Set it to false only for throwaway testing over plain HTTP.
session_duration
Type
integer(seconds) · Default3600· Range 60–2,592,000 (30 days) · Applies reload
How long a console sign-in stays valid. The clock starts at login and is not extended by activity, so the operator signs in again once it runs out. The same value sets the cookie's Max-Age. Sessions are held in memory, so a restart still signs everyone out, and so does any change to the console settings, including this one.
[ui]
session_duration = 28800 # stay signed in for 8 hourspublic_url
Type
string· Default none · Applies reload
The address listeners use to reach your streams, for example "https://radio.example.com". The console uses it for the Copy URL buttons and the built-in test player. Without it, the console guesses: it reuses the address of the page you are on and the public port from listen. That guess is right for a direct setup and wrong behind a proxy, a CDN or a different domain, so set it in those cases.
It must be an http:// or https:// origin: no path, query, fragment or user name. A trailing slash is removed. Changing it signs out console sessions on the next reload, like any other console setting.
[ui]
enabled = true
username = "admin"
password_file = "secrets/ui-password"
public_url = "https://radio.example.com"public_mounts
Type
array of strings· Default every mount whenmodeis"public"or"both", none when"private"· Applies reload
The mounts the public status page may show, and the ones /console/status reports without a sign-in. It takes one of three forms:
- Omitted: with
mode = "public"or"both", every mount is shown, including mounts that encoders create on the fly (seeallow_dynamic_mounts). Withmode = "private", none are. ["*"]: every mount, whatever the mode. It must be the only entry.- A list of paths such as
["/radio.mp3"]: only those. Each entry must be a configured mount, so an encoder-created mount can never be named here. An empty list[]discloses nothing.
Showing a mount publishes its availability, codec, content type and listener count (unless the mount sets hide_listener_count). It does not give anyone access to play it.
[limits]
Capacity and timing controls that protect the server. Every value has a sensible default, so most stations never need this table. All of [limits] needs a restart.
[limits]
max_listeners = 2000
listeners_per_mount = 2000Startup checks that the memory you reserve fits retained_audio_budget. If it does not, you get retained audio budget cannot cover admission reservations; lower max_listeners or raise the budget.
| Setting | Default | Range |
|---|---|---|
ring_bytes | 4194304 | positive |
ring_entries | 4096 | 1–65,536 |
join_bytes | 65536 | 0 to ring_bytes |
max_connections | 12000 | 1–100,000 |
max_handshakes | 128 | 1 to max_connections |
max_mounts | 64 | 1–1,024 |
max_listeners | 10000 | 1 to max_connections |
listeners_per_mount | 10000 | 0 to max_listeners |
retained_audio_budget | 2147483648 | enough for the reservation formula |
relay_allocation_budget | 33554432 | at least 2 MiB per relay |
header_timeout_ms | 5000 | 1–3,600,000 |
source_timeout_ms | 10000 | 1–3,600,000 |
write_timeout_ms | 10000 | 1–3,600,000 |
shutdown_timeout_ms | 10000 | 1–3,600,000 |
flac_initialization_bytes | 65536 | 42–262,144 |
flac_frame_bytes | 1048576 | 16–4,194,304 |
ring_bytes
The most encoded audio kept in memory for each live stream, in bytes. It is the catch-up buffer new listeners join from, and the line a slow listener must stay inside: a listener who falls further behind than the ring is disconnected, so one slow client never holds back everyone else. Default 4 MiB.
ring_entries
The most separate chunks of audio the ring can hold at once. Whichever of ring_bytes and ring_entries fills first decides when the oldest audio is dropped. A chunk is a block of published data, not one second or one codec frame.
join_bytes
How much recent audio a new listener may start from, in bytes (not milliseconds). Codec rules still decide the exact safe starting point. 0 means "start at the live edge".
max_connections
The most simultaneous TCP connections on the public listener, counting encoders, players, the console and HLS downloads. The admin listener has its own fixed reserve of 32 connections, so a flood of public clients can never lock you out of health checks or management. Connections beyond the limit are refused, not queued.
max_handshakes
The most connections that may be waiting to send their request headers (or finish a TLS handshake) at one time. This is the main defence against slow-connection attacks. The admin listener has a separate reserve of 16.
max_mounts
The most static [[mounts]] you may configure. The default is 64 and the ceiling is 1,024. Idle mounts are cheap, but every mount reserves audio memory (about 5.4 MB with default ring settings), so startup checks the total against retained_audio_budget and refuses to start if it does not fit. Raise the budget when you raise this. Changing it needs a restart. Mounts that encoders create on demand through [sources] are not counted here.
max_listeners
The most simultaneous audio listeners across all mounts. HLS downloads are ordinary requests and do not count here. This value also sizes the memory reservation, even when individual mounts are capped lower.
listeners_per_mount
The default listener cap for each mount. 0 means no per-mount cap beyond max_listeners. A mount's own listener_limit replaces this value rather than being combined with it.
retained_audio_budget
The total memory, in bytes, Quikcast promises it can use for audio rings, parser buffers and listener references. Startup calculates what your mounts and max_listeners require and refuses to start if that exceeds the budget. Default 2 GiB, enough for the default maximum of 64 mounts with default listener limits. If you raise max_mounts, raise this budget with it. It is a ceiling for these checks, not memory Quikcast allocates up front. The exact formula is in Capacity and limits.
relay_allocation_budget
Memory set aside for relay workers, at least 2 MiB per configured relay (up to 64). Disabled relays still count. Default 32 MiB.
header_timeout_ms
How long a client may take to send its request headers before the connection is dropped. Also bounds the TLS handshake.
source_timeout_ms
How long an encoder may send nothing before it is disconnected. A healthy stream can run forever; this only catches stalls.
write_timeout_ms
How long a listener's socket may refuse data before the listener is disconnected as a slow consumer. A quiet stream with nothing to send is not a violation.
shutdown_timeout_ms
How long a graceful shutdown waits for connections to finish after you stop the server. Anything still running afterwards is aborted.
flac_initialization_bytes
The most data Quikcast accepts for the start of a native FLAC stream: the fLaC marker plus every metadata block, including cover art. Raise it if your encoder embeds large artwork.
flac_frame_bytes
The most bytes allowed for a single unfinished native FLAC frame. This is a size limit in bytes, not a sample or block-size setting.
[[mounts]]
A mount is one stream path, such as /radio.mp3, that an encoder feeds and listeners play. Every [[mounts]] header starts a new mount; the settings under it, and its sub-tables, belong to it. You can also write [[mount]] (and [mount.access] and so on) if you prefer the singular; use one spelling per file.
Configure 1 to limits.max_mounts mounts (64 by default). Zero mounts is allowed only if you enable [hls] or [sources].
[[mounts]]
path = "/radio.mp3"
username = "source"
secret_file = "secrets/radio-source"Only one encoder can own a mount at a time. A second one is refused with 409 Source already connected; there is no takeover or priority. When the encoder disconnects, its listeners disconnect too, and players reconnect to the next encoder session.
path
Type
string· Default none (required) · Applies reload
The URL path listeners use. It must start with /, be at most 2,048 bytes, and use only ASCII letters, digits and / . _ - ~. Names are case-sensitive, and nested names such as /stations/jazz are fine.
Not allowed: / alone, a trailing /, //, . or .. parts, spaces, Unicode, or any path under the reserved roots /api, /admin, /internal, /health, /metrics and /hls.
The extension does not choose the codec. /radio.mp3 can carry any supported format; the encoder's content type decides.
Adding, removing and renaming mounts on reload is described in Streams and mounts; a rename is a removal plus an addition. A reload that adds a path is refused, and the running configuration is kept, if an encoder-created mount is already using that path, if the mount count or the limits.retained_audio_budget arithmetic no longer fits, or if the encoder-created mounts already live would no longer fit in the remaining budget.
username
Type
string· Default"source"· Applies reload
The username the encoder uses for HTTP Basic authentication (and for metadata updates).
secret_file
Type
string(path) · Default none · Applies reload
Path to the encoder password file. Set exactly one of secret_file and secret. If you set neither, the mount inherits the whole global [sources] credential.
secret
Type
string· Default none · Applies reload
The encoder password written directly in the config. Prefer secret_file.
fallback
Type
string· Default none · Applies reload
Another configured mount to serve when this one has no source. The listener keeps its original URL; Quikcast attaches it internally, with no redirect. Chains may be up to eight mounts long including the first. Unknown targets, a mount pointing at itself, loops and chains that are too long stop startup. Compatible MP3 and AAC listeners return to the original mount automatically when its source comes back. See Fallback mounts.
[[mounts]]
path = "/live.mp3"
fallback = "/automation.mp3"
secret_file = "secrets/live-source"
[[mounts]]
path = "/automation.mp3"
secret_file = "secrets/automation-source"fallback_when_full
Type
boolean· Defaultfalse· Applies reload · Requiresfallback
When this mount has reached its listener_limit, serve new listeners from its fallback instead of refusing them. See overflow when a mount is full. Each mount in a chain decides for itself. If every mount is full the listener is refused. Server-wide limits.max_listeners is not affected.
hide_listener_count
Type
boolean· Defaultfalse· Applies reload
Keep this mount's listener count off the public status page and /console/status. The mount is still listed, with its availability, codec and bitrate, just without a number. Because the page's server-wide total would reveal the hidden count, the total is left out as soon as any mount sets this. It changes only what the public sees: the signed-in console, /api, /metrics and listener limits are unaffected.
listener_limit
Type
integer· Default inheritlimits.listeners_per_mount· Range 0 tomax_listeners· Applies restart
The most listeners this mount allows. 0 removes the per-mount cap (the global limits still apply). A listener served through fallback counts against the mount that actually serves it.
charset
Type
string· Default UTF-8 · Applies reload
The character set of title text sent to the metadata endpoint for this mount, for encoders that cannot send UTF-8. Quikcast converts it to UTF-8 before listeners see it. Use a standard name such as ISO-8859-1 or windows-1252 (ISO-8859-1 is treated as windows-1252). A charset= field on a metadata request overrides this value. Text that is not valid in the chosen set is rejected rather than garbled. UTF-16 and other non-ASCII-compatible sets are not supported.
max_listener_duration
Type
integer· Default0(unlimited) · Range 0–31,536,000 seconds · Applies reload
The longest a single listener may stay connected to this mount. When the time is up, Quikcast closes that connection and most players reconnect on their own. It is counted from when the listener connected, and applies to listeners who asked for this mount, including those served through its fallback. Disconnects are counted under the duration_limit reason. Use it to stop forgotten browser tabs and idle players holding connections open for days.
intro
Type
string(file path) · Default none · Applies reload
An audio file played to every new listener before the live stream starts, such as a station ID or a short jingle. Paths are relative to the config file. The file must be MP3 or AAC (ADTS) and at most 8 MiB. Quikcast never converts audio, so the clip must match the live stream's format, sample rate and channel count; bitrate may differ. Quikcast compares it with the stream's first frame, and if anything differs (an AAC intro on an MP3 mount, 48 kHz against 44.1 kHz, mono against stereo) the listener gets no intro and a warning naming both formats is logged once. ID3 tags are stripped. Ogg and FLAC mounts do not support intros, and the intro starts once the encoder is sending audio.
[[mounts]]
path = "/radio.mp3"
secret_file = "secrets/radio-source"
intro = "audio/station-id.mp3"
max_listener_duration = 14400 # 4 hours
charset = "ISO-8859-1"[mounts.listener_auth]
Protect this mount with signed, expiring URLs created by your own application. Omit the table, or use type = "none", to keep the mount public. Quikcast only verifies; it has no accounts or sessions. See Signed URLs for the exact signing recipe.
[mounts.listener_auth]
type = "signed_url"
secret_file = "secrets/radio-signing-key"
max_ttl_seconds = 86400
clock_skew_seconds = 0
previous_secret_files = []
bind_ip = false| Key | Default | Range | Meaning |
|---|---|---|---|
type | "none" | "none", "signed_url" | "none" leaves the mount public. |
secret_file | none | 32–4,096 bytes | HMAC key shared with your application. Required for signed_url. |
max_ttl_seconds | 86400 | 1–604,800 | The furthest in the future a link may expire. Longer links are refused. |
clock_skew_seconds | 0 | 0–60 | Extra time after expiry a link is still accepted, to tolerate clock drift. |
previous_secret_files | [] | up to 4 files | Older keys that still verify links, so you can rotate the key without breaking links already issued. Same size rules as secret_file; each key must be different. |
bind_ip | false | true, false | Also sign the listener's IP address, so a link only works from the address it was made for. See Bind links to an IP. |
[mounts.access]
Restrictions on who may listen. They are added to the global [access] rules: a listener must pass both. The fields are identical to [access] except that geoip_database and asn_database are only allowed in the global table.
[mounts.access]
countries_allow = ["GH", "NG"]
ip_deny_file = "lists/blocked.txt"[mounts.source_access]
Restrictions on which IP addresses may connect an encoder to this mount. Credentials are still required. There is no global version, and no User-Agent or country rules here.
[mounts.source_access]
ip_allow = ["203.0.113.10", "2001:db8::/48"]| Key | Type | Meaning |
|---|---|---|
ip_allow | array of strings | Only these IPs or CIDRs may connect. Empty means no restriction. |
ip_allow_file | path | A list file merged with ip_allow. It must contain at least one rule. |
ip_deny | array of strings | These IPs or CIDRs are always refused. |
ip_deny_file | path | A list file merged with ip_deny. An empty file is fine. |
Up to 10,000 distinct rules per list, counting inline and file entries together. Changes apply on reload.
[access]
Global restrictions on who may listen, applied to every mount, in addition to each mount's own [mounts.access]. Omit it for open playback.
A listener is allowed only if it passes every category you configure: IP, User-Agent, country and network (ASN). A deny rule always wins over an allow rule in the same category. Everything here applies on reload.
[access]
ip_deny_file = "lists/blocked.txt"
user_agent_deny = ["exact:bad-monitor"]
countries_allow = ["GH", "NG"]ip_allow and ip_deny
Type
array of strings· Default[]· Limit 10,000 distinct rules together with the file
IPv4 or IPv6 addresses or CIDR networks, for example "203.0.113.9" or "198.51.100.0/24". With a non-empty ip_allow, only matching listeners are admitted. ip_deny always refuses matches. Equivalent entries are merged; overlapping networks are kept as written. IPv4-mapped IPv6 addresses (::ffff:192.0.2.1) match their IPv4 form.
ip_allow_file and ip_deny_file
Type
string(path) · Default none · Max size 1 MiB
A text file of rules, one IP or CIDR per line. Blank lines and lines starting with # are ignored, and a leading UTF-8 byte-order mark is tolerated. The file is merged with the inline list and re-read on every reload, so you can update a blocklist without restarting.
# blocked.txt
203.0.113.0/24
198.51.100.7
2001:db8:bad::/48Errors name the file and line, such as ip_deny_file: lists/blocked.txt:2: invalid IP/CIDR "not-an-ip".
WARNING
An ip_allow_file with no rules is rejected, because an empty allow list would mean "allow everyone". An empty ip_deny_file is fine.
user_agent_allow and user_agent_deny
Type
array of strings· Default[]· Limit 256 rules · Rule length 1–256 bytes
Match the player's User-Agent header. Each rule is mode:text, where the mode is one of:
| Mode | Matches when the User-Agent... |
|---|---|
exact: | equals the text exactly. |
prefix: | starts with the text. |
substring: | contains the text. |
Matching is case-sensitive. A rule without a mode, or with an unknown mode such as regex:, stops startup.
user_agent_allow = ["prefix:RadioPlayer/"]
user_agent_deny = ["substring:unsupported-build"]INFO
User-Agent is chosen by the client and trivially faked. Use it for compatibility and convenience, not security.
countries_allow and countries_deny
Type
array of strings· Default[]· Limit 249 codes
Two-letter ISO 3166-1 country codes (and XK for Kosovo). Lowercase is accepted and normalised. countries_deny refuses listeners in those countries; countries_allow, when non-empty, admits only those countries. Addresses whose country cannot be determined, such as local ones, pass a deny-only policy but fail an allow list.
geoip_database
Type
string(path) · Default the built-in database · Max size 128 MiB
Country lookups use a database embedded in Quikcast, so country rules work with no setup. Set this to use your own MaxMind-format country database instead, for example "/etc/quikcast/GeoLite2-Country.mmdb". If you set it, it is opened and validated at startup even when no country rules are active, and re-opened on every reload. Quikcast never downloads or updates databases.
asns_allow and asns_deny
Type
array of integers· Default[]· Limit 256 each · Uses the bundled ASN database orasn_database
Autonomous system numbers, which identify the network an address belongs to. Use asns_deny to refuse hosting providers, proxies and scrapers by network instead of listing every range. asns_deny refuses listeners in those networks; asns_allow, when non-empty, admits only those. An address the database does not know, or a private one, passes a deny-only policy but fails an allow list. A damaged database refuses every listener rather than silently lifting the rule. With no asn_database, a geoip_database that also holds ASN records serves both; otherwise the bundled database is used. 0 is reserved and rejected.
[access]
asn_database = "/etc/quikcast/GeoLite2-ASN.mmdb" # optional; the bundled database is used if omitted
asns_deny = [16509, 14061]asn_database
Type
string(path) · Default bundled database · Max size 128 MiB · Global table only
A MaxMind-format ASN database, such as GeoLite2-ASN, with autonomous_system_number records. When omitted, Quikcast uses the ip-location-db origin-asn snapshot (PDDL 1.0) embedded in the binary, which covers IPv4 and IPv6 and is refreshed with each release. A file you set is opened and validated at startup and re-opened on every reload.
listeners_per_ip
Type
integer· Default0(no limit) · Range 0–1,000,000
The most simultaneous listeners one address may hold. Set in [access], it counts across all mounts; set in [mounts.access], it counts on that mount only, and both apply. A listener over the limit gets 429 Too Many Requests and the listener_per_ip_rejected_total counter rises. IPv6 listeners share one budget per /64. The count follows the real listener address, so set trusted_proxies behind a proxy or every listener will look like one address. The limit applies to continuous streams; HLS listeners are estimated, not connected, so it does not apply to them.
[access]
listeners_per_ip = 4
[[mounts]]
path = "/members.mp3"
secret_file = "secrets/members-source"
[mounts.access]
listeners_per_ip = 1[sources]
Lets encoders connect to paths you did not list under [[mounts]]. The mount is created when the encoder connects and disappears when its last listener leaves. Nothing is saved to the config. Listed mounts always win over dynamic ones.
[sources]
allow_dynamic_mounts = true
username = "source"
secret_file = "secrets/dynamic-source"
[sources.defaults]
name = "Quikcast Stream"
genre = "Various"
public = falseEven with allow_dynamic_mounts = false, setting credentials here makes every [[mounts]] that omits its own secret inherit them. A server with global credentials may have no [[mounts]] at all.
allow_dynamic_mounts
Type
boolean· Defaultfalse· Applies reload
When true, a correctly authenticated encoder may create a new mount just by connecting to a free path. It requires the credentials below, and the retained-audio budget must have room for at least one more stream.
username and secret_file / secret
Type
string· Default username"source"· Applies reload
The shared encoder credential for dynamic mounts and for configured mounts that have none of their own. Set exactly one of secret_file or secret.
[sources.defaults]
Descriptive station metadata used when an encoder sends none. An encoder's own ice-name, ice-description, ice-genre, ice-url and ice-public headers always win. These fields describe the station only; they cannot change limits, security or routing.
| Key | Type | Meaning |
|---|---|---|
name | string | The station name shown to players. |
description | string | A short description. |
genre | string | The genre. |
url | string | The station's website. |
public | boolean | Whether the stream may be listed publicly. |
[[relays]]
A relay pulls an existing internet stream and republishes it on one of your mounts. Use it to rebroadcast another station, build an edge server, or run a backup feed.
You can also write [[relay]]; use one spelling per file. The target mount must exist under [[mounts]]. Once a mount has a relay, the relay owns it: an encoder cannot connect there, even while the relay is stopped. You can have up to 64 relays, one per mount. Relay settings apply on reload; changing any of them restarts that relay.
[[mounts]]
path = "/remote.mp3"
secret_file = "secrets/remote-local"
[[relays]]
mount = "/remote.mp3"
upstreams = [
{ url = "https://primary.example/live" },
{ url = "https://backup.example/live" },
]mount
Type
string· Default none (required)
The local mount the relay feeds. It is the path your listeners use, not part of the upstream URL.
url, urls and upstreams
Type
string,array of strings, orarray of tables· Default none · Choose exactly one
Where to pull audio from. Use one of the three forms:
url = "https://origin.example/live"is a single upstream.urls = ["https://a.example/live", "https://b.example/live"]lists 1–8 upstreams that share the relay's credentials.upstreams = [{ url = "..." }, ...]lists 1–8 upstreams where each may have its own credentials.
All forms need absolute http:// or https:// URLs of at most 2,048 bytes. Queries are fine. Fragments, user:pass@ in the URL, whitespace and other schemes are rejected. Pointing a relay at this same server is rejected. Duplicates are rejected.
The upstream may be a plain stream (MP3, AAC, Ogg, FLAC), an old SHOUTcast server, or an audio-only HLS playlist (experimental and not reliable; see Relay another station).
The first entry is the primary. If it fails, Quikcast tries the next entry immediately. After the last entry fails, it waits for the backoff delay and starts again at the primary. A working backup stays selected until it fails: there is no automatic return to the primary.
TIP
New configurations should prefer upstreams, since it can express everything url and urls can. The older forms still work.
upstreams = [
{ url = "https://primary.example/live", username = "primary-user", secret_file = "secrets/primary-password" },
{ url = "https://backup.example/live" },
]username and secret_file
Type
string· Default none (anonymous) · Password 1–512 ASCII graphic bytes
Basic-auth credentials sent to the upstream. Set both or neither. There is no inline secret field for relays. With upstreams, these act as the default for entries that set neither of their own fields; an entry with its own username and secret_file overrides them.
enabled
Type
boolean· Defaulttrue
Whether the relay starts with the server. false starts it stopped (the mount still stays reserved); you can start it later through the management API.
charset
Type
string· Default UTF-8 · Applies reload (restarts the relay)
The character set of the titles in the upstream's in-stream metadata. Many older stations send Latin-1 (ISO-8859-1) or windows-1252 titles. With the default, a title that is not valid UTF-8 is rejected and counted under metadata_rejections_total; with charset set, it is converted to UTF-8 so listeners see the right accented characters. See charset on mounts for supported names. It does not affect audio.
on_demand
Type
boolean· Defaultfalse
Connect to the upstream only while someone is listening. The relay starts idle, the first listener wakes it (waiting up to wake_wait_ms), and it disconnects after idle_timeout_ms with no listeners. While idle it reports state stopped with stopped_reason idle. How it behaves, including fallback and the management API, is in on-demand relays.
idle_timeout_ms
Type
integer· Default30000· Range 1–3,600,000 · Applieson_demandonly
How long an on-demand relay stays connected with no listeners before it disconnects. It must not be shorter than wake_wait_ms.
wake_wait_ms
Type
integer· Default8000· Range 0–60,000 · Applieson_demandonly
How long the first listener waits for the relay to connect and deliver audio. If the origin is not ready in time, the listener gets the usual "not found" response and can retry.
max_redirects
Type
integer· Default0· Range 0–8
How many upstream redirects (301, 302, 303, 307, 308) to follow per attempt. 0 treats any redirect as a failure. Credentials are never sent to a different host than the one you configured: they are dropped at the first change of scheme, host or port.
hls_variant
Type
string· Default"highest"· Values"highest","lowest"· Applies reload (restarts the relay)
When a relay's upstream is an HLS master playlist offering several bitrates, this chooses which audio-only variant to follow. "highest" gives the best quality; "lowest" uses the least bandwidth. Variants that contain video are never chosen. It has no effect on non-HLS upstreams. HLS relaying is experimental; see the warning.
[[relays]]
mount = "/hls-station.aac"
url = "https://stream.example/live/master.m3u8"
hls_variant = "lowest"
max_redirects = 3Timeouts and retry
All values are milliseconds from 1 to 3,600,000 unless stated.
| Key | Default | Meaning |
|---|---|---|
connect_timeout_ms | 10000 | One overall deadline for DNS, TCP connect and TLS. |
header_timeout_ms | 5000 | How long the upstream may take to send response headers. |
audio_timeout_ms | 10000 | How long without new audio before the attempt is abandoned. For HLS upstreams the limit is the longer of this and three segment lengths, and it also bounds each playlist or segment download. |
initial_backoff_ms | 1000 | First wait after every upstream failed. Must not exceed max_backoff_ms. |
max_backoff_ms | 60000 | Longest wait between retry cycles. |
stable_connection_ms | 30000 | A connection that lasts this long resets the backoff. |
jitter_percent | 20 | Random variation applied to waits, 0 to 50. |
Network safety
These rules have no settings. The guide explains them under Safety rules.
- Redirects and HLS references from a public upstream may only lead to other public addresses. Targets on loopback, private, link-local or reserved ranges, and
0.0.0.0/::, are refused (destination_not_allowed). Upstreams you configure on a private address are trusted, and so is anything they redirect to. - Outbound HTTPS is always verified against the bundled public certificate roots. There is no option to disable verification, add a private CA or use client certificates.
[primary]
Share the list of this server's streams with replica servers. Omit the table to keep the endpoint off.
[primary]
username = "replica"
secret_file = "secrets/replica-password"
share = ["/radio.mp3"]
redirect_after = 200username and secret / secret_file
Type
string· Default username"replica"· Password 16–512 bytes · Applies reload
The login a replica must present to read the stream list at GET /api/streams on the public listener. Configure exactly one of secret or secret_file (prefer the file). Use a password that is different from every encoder, management and console password.
share
Type
array of strings· Default every public mount · Applies reload
Only list these mounts. Mounts protected by signed links, and mounts that are copies made by a replica, are never listed.
redirect_after
Type
integer· Default none (never redirect) · Applies reload
Send new listeners to replicas once a mount already has this many. 0 redirects every listener. A listener the primary has no room for is redirected whatever the number. Nothing is redirected until a replica has announced itself with public_url.
[replica]
Copy the streams of another Quikcast server. See Primary and replica. A server with a [replica] section may have no [[mounts]] of its own, and it must be started from a config file, because it applies stream changes by reloading it.
[replica]
primary = "https://radio.example.com"
username = "replica"
secret_file = "secrets/primary-password"
refresh_secs = 30
on_demand = true
max_streams = 16
only = ["/radio.mp3"]
public_url = "https://eu.example.com"primary
Type
string· Required · Applies reload
The primary server's address, such as https://radio.example.com or http://10.0.0.5:8000. It must have no path. Streams are relayed from the same address at their original paths.
username and secret / secret_file
Type
string· Default username"replica"· Applies reload
The login for the primary's [primary] section. Configure exactly one of secret or secret_file. 1–512 printable bytes, no spaces.
refresh_secs
Type
integer· Default30· Range 5–3600 · Applies reload
How often the primary's stream list is checked. A failed check keeps the current streams.
on_demand
Type
boolean· Defaulttrue· Applies reload
Whether replicated relays connect to the primary only while someone is listening. See on_demand on relays.
max_streams
Type
integer· Default16· Range 1–48 · Applies reload
The most streams to copy, before the global limits of limits.max_mounts mounts and 64 relays and limits.relay_allocation_budget. Streams beyond the limit are skipped with a warning, in alphabetical order.
only
Type
array of strings· Default all listed streams · Applies reload
Copy only these paths.
public_url
Type
string· Default none · Applies reload
This replica's own public address, such as https://eu.example.com, with no path. When set, the replica tells the primary its address and the streams it carries, so the primary can redirect listeners to it. Listeners must be able to reach this address.
[hls]
A separate subsystem that serves HLS (.m3u8 playlists with segment files) to browsers and mobile players. Quikcast does not encode: your own tool, such as FFmpeg, pushes finished, correctly packaged segments to the private ingest API, and Quikcast stores and serves them from memory. HLS is not derived from your normal mounts.
Ingested content is held in memory and lost on restart. Alternatively, directory serves HLS files that another program writes to disk. See What can be reloaded for what applies on reload.
[hls]
username = "hls"
secret_file = "secrets/hls-ingest"
cors_origin = "https://player.example.com"See HLS ingest API for the ingest API and supported formats.
username
Type
string· Default"hls"
The ingest username (Basic authentication).
secret_file / secret
Type
string· Default none · Password 16–512 bytes
The ingest password. Set exactly one. It must differ from every mount password. When directory is set, both may be left out; the ingest API is then disabled.
directory
Type
string· Default none · Applies restart
A directory whose subdirectories are served as HLS streams at /hls/<subdirectory>/.... A relative path is relative to the configuration file. The directory must exist and be readable at startup (--check verifies it). Names must be 1–64 letters, digits, _ or -.
Only regular files ending in .m3u8, .ts, .m4s, .mp4, .aac or .mp3 are served, up to 16 MiB each, at most four levels below the stream. Everything else returns 404. Which files are served, caching, naming and precedence over ingested streams are explained in Serve HLS from a directory.
[hls]
directory = "/var/lib/radio/hls"directory_listener_window_secs
Type
integer· Default60· Range 5–3600 · Applies restart
Only used with directory. A client IP counts as an active listener of a directory stream if it fetched a playlist or segment within this many seconds. See Counting listeners.
directory_session_timeout_secs
Type
integer· Default30· Range 5–3600 · Applies restart
Only used with directory. A listener session of a directory stream is active if its client requested a playlist or segment within this many seconds. Session fields and limits are in GET /api/hls/{stream}/listeners.
cors_origin
Type
string· Default none (CORS off) · Max length 256 bytes
The website allowed to play your HLS from a browser. Use "*" or exactly one origin such as "https://player.example.com" (no path, no trailing slash, no list). Without it, browsers on other sites cannot fetch your playlists, although non-browser players are unaffected. Preflight requests allow Range, If-None-Match and If-Range.
Capacity settings
| Key | Default | Range | Meaning |
|---|---|---|---|
max_streams | 16 | 1–64 | Most HLS streams. |
renditions_per_stream | 8 | 1–16 | Most quality levels per stream. |
max_renditions | 64 | 1–128 | Most quality levels overall. |
max_segment_bytes | 2097152 | 188–16,777,216 | Largest single uploaded segment. A safety ceiling, not a target size. |
max_segments | 1024 | 16–4,096 | Segment slots per rendition. |
max_uploads | 4 | 1–16 | Uploads accepted at the same time. |
rendition_budget | 134217728 | up to allocation_budget | Memory reserved per rendition. |
allocation_budget | 536870912 | up to 4 GiB | Total memory for HLS. |
[hls.listener_auth."/hls/NAME"]
Protect one HLS stream with signed URLs. The key is the stream's public path, /hls/ followed by 1–64 letters, digits, _ or -. A stream with no entry is public; up to 64 entries are allowed. One signature covers the playlists and every segment of that stream. The fields are the same as [mounts.listener_auth].
[hls.listener_auth."/hls/private"]
type = "signed_url"
secret_file = "secrets/hls-private-key"Putting it together
A small station with HTTPS, a private console, a country allow list and a backup feed:
listen = "0.0.0.0:8443"
admin_listen = "127.0.0.1:9090"
[tls]
cert_file = "secrets/tls/fullchain.pem"
key_file = "secrets/tls/privkey.pem"
[management]
token_file = "secrets/management-token"
[ui]
enabled = true
username = "admin"
password_file = "secrets/ui-password"
[access]
countries_allow = ["GH", "NG"]
ip_deny_file = "lists/blocked.txt"
[[mounts]]
path = "/radio.mp3"
fallback = "/backup.mp3"
secret_file = "secrets/radio-source"
[[mounts]]
path = "/backup.mp3"
secret_file = "secrets/backup-local"
[[relays]]
mount = "/backup.mp3"
upstreams = [{ url = "https://backup.example/live" }]What can be reloaded
Send SIGHUP to apply changes without dropping connected listeners or encoders:
kill -HUP "$(pidof quikcast)"| Applies on reload | Needs a restart |
|---|---|
[tls] certificate and key files | listen, admin_listen, log_filter |
[trusted_proxies] (all keys) | Enabling or disabling [tls] |
[management] (except allow_remote), [ui] | management.allow_remote, every [limits] setting |
[access] and every list file | listener_limit of an existing mount |
Mount credentials, fallback, listener_auth, access, source_access | HLS capacity settings and directory (while [hls] is on) |
[sources] (credentials, dynamic mounts, defaults) | |
[[relays]] (a changed relay restarts) | |
[hls] credentials, cors_origin, listener_auth | |
Adding or removing the [hls] table (removing it drops ingested HLS streams from memory) | |
Adding or removing a [[mounts]] entry (removal disconnects its encoder and listeners) |
A reload is all or nothing. Existing listeners and encoders stay connected, and rotated credentials affect new connections and updates. For the full behaviour, see Operations: reload, drain and troubleshooting.