Capacity and limits ​

Quikcast refuses to start with limits that its memory budget cannot honour, so a server that boots is a server that has reserved what it promised. This page explains how the limits relate and how to size them. The individual settings are listed in the [limits] reference.

The short version ​

For most stations, change only max_listeners and listeners_per_mount to match your bandwidth, and leave the rest alone.

toml
[limits]
max_listeners = 2000
listeners_per_mount = 2000

That is enough for roughly 200 MB of reserved memory and keeps startup checks happy.

What the limits protect ​

LimitProtects against
max_connections, max_handshakesToo many sockets, and slow clients that connect but never finish asking.
max_mountsConfiguring more streams than you have memory for.
max_listeners, listeners_per_mountToo much outbound bandwidth and memory for audio listeners.
retained_audio_budgetThe total memory promised to audio buffers and listeners.
ring_bytes, ring_entries, join_bytesHow much recent audio each stream remembers.
*_timeout_msStalled clients, encoders and shutdowns.

None of them cap how long a healthy stream may run.

How the memory budget is checked ​

At startup Quikcast adds up what it must be able to hold, in the worst case, and compares it with retained_audio_budget (2 GiB by default).

text
required = 2 × mounts × generation + max_listeners × listener
  • 2 × mounts × generation: each mount can hold two source generations at once (the current one and one that listeners are still draining). A generation reserves its ring (ring_bytes plus bookkeeping for ring_entries) and fixed parser buffers. With default settings it is about 5.4 MB.
  • max_listeners × listener: every possible listener reserves pending-write space, a metadata block and a share of header storage. That is about 105 KB each.

Rules of thumb ​

You haveReserved memory is about
1 mount, 1,000 listeners115 MB
4 mounts, 2,000 listeners255 MB
10 mounts, 10,000 listeners1.16 GB
64 mounts (the default maximum), 10,000 listeners1.74 GB

The defaults (max_listeners = 10000 and a 2 GiB budget) already hold the maximum of 64 mounts, so you only meet this check after raising limits, lowering the budget, or turning on dynamic mounts. If the sum is too big you will see something like:

text
limits.retained_audio_budget: retained audio budget cannot cover admission reservations:
2 mount(s) and max_listeners = 10000 need about 1032 MiB but retained_audio_budget is 1024 MiB;
lower limits.max_listeners or raise limits.retained_audio_budget

Fix it by lowering max_listeners, or by raising retained_audio_budget. Both are restart settings.

The budget is a ceiling, not a preallocation

Quikcast does not reserve this memory up front. Real memory use follows your audio: ring buffers fill as streams run and listeners connect. If you enable dynamic mounts, the part of the budget your configured mounts and listeners do not use is what limits how many dynamic streams can exist at once.

The reservation counts what Quikcast promises, not process memory: the operating system, your proxy and the HLS store (below) are on top.

Other budgets ​

These are separate and do not borrow from retained_audio_budget:

BudgetSettingNotes
Relay workersrelay_allocation_budgetAt least 2 MiB per relay (up to 64 relays), counted even when a relay is disabled.
HLS[hls] allocation_budget, rendition_budgetIn-memory segments for all HLS streams. The per-rendition minimum is 8 × (max_segment_bytes + 128) + 4 × 262,144.

Choosing a listener limit ​

Listeners cost outbound bandwidth:

text
bandwidth ≈ listeners × bitrate

For example 1,000 listeners at 128 kbit/s is about 128 Mbit/s. Check your host's real network capacity (and your provider's fair-use limits) before setting max_listeners. It is far better to refuse listeners cleanly than to let everyone's audio stutter.

Also remember file descriptors: allow more than max_connections open files (LimitNOFILE in systemd, ulimit -n, or ulimits.nofile in Docker). Plan for max_connections + 32 (administration) + about 128 spare, so about 12,200 for the defaults and 65,536 is a comfortable value.

Quikcast raises its own soft limit up to the hard limit at startup. If the hard limit is still too low, it logs a warning and lowers public admission to fit, rather than failing later. If the system runs out of descriptors anyway, accept() errors are logged and counted in accept_errors_total, accepting pauses briefly, and existing sources and listeners keep running. quikcast --check warns when the hard limit is below what max_connections needs.

Fixed limits ​

Some limits are built in and have no setting:

WhatLimit
Request headers16 KiB and 64 fields
Configuration file128 KiB
Mountslimits.max_mounts configured (64 by default, at most 1,024), plus dynamic mounts within the memory budget
Relays64, each with up to 8 upstreams
IP rule lists10,000 distinct entries each
User-Agent rule lists256 rules of 1–256 bytes
Country lists249 codes
Signed-link HLS entries64
Console sessions128, one hour each by default (ui.session_duration)
Management request bodiesnone allowed
Country database file128 MiB, 2 million records