Configuration
File: /etc/freedome/mediaserver.toml (Windows %ProgramData%\Freedome\mediaserver.toml, macOS
/Library/Application Support/Freedome/mediaserver.toml). The annotated reference with every key and its default
is config/mediaserver.example.toml; the JSON Schema is
config/mediaserver.schema.json. Smaller starting points:
config/minimal.toml (single node), config/demo.toml, config/cluster.toml (several render nodes, Redis broker).
freedome-mediaserver --check-config --config /etc/freedome/mediaserver.tomlfreedome-mediaserver --print-config-schema- Unknown keys are errors; the error names the dotted key (
http.listne). Config errors exit with code 78. - Paths are absolute;
${data_dir}expands todata_dir. - No inline secrets: keys such as
password,token,secret,api_keyare refused — use<name>_filepointing to a file readable by the service. - Environment overrides:
FREEDOME_MS__SECTION__KEY=value(value parsed as TOML, e.g.FREEDOME_MS__HTTP__LISTEN='["0.0.0.0:8080"]'). GET /api/v1/system/configreturns the effective configuration with secrets redacted ("***").
Reload
Section titled “Reload”systemctl reload freedome-mediaserver (SIGHUP) re-reads the file. Reloadable keys apply at once (log level, CORS
origins, allow-lists, limits, system.host_power, …). Keys that need a restart (listen addresses, nodes, storage)
are listed in /health as the degraded check config: restart required: <keys>; the server stays ready.
Sections
Section titled “Sections”| Section | What |
|---|---|
[log] |
level, json / text |
[http] |
listen addresses, base_path (behind a reverse proxy; X-Forwarded-Prefix honoured), CORS origins, Swagger UI, GraphiQL (off / admin / all) |
[osc] |
UDP / TCP listen (7000), reply_port (7001), allow-list (CIDR), listener role, admin_allow |
[grpc] |
Unix socket, optional TCP (50062), TLS / mTLS, admin_group |
[mdns] |
_freedome._tcp / _osc._udp announce, instance name |
[auth] |
admin key file, pairing TTL, sessions, cloud JWKS URL + cache age, rate limits, legacy_guest |
[broker] |
inproc (default), redis (default for clusters), nats; prefix |
[storage], [uploads] |
data dir, blob GC grace, tus chunk / expiry limits, work folders (read-only roots) |
[probe] |
ffprobe / ffmpeg binaries, timeouts |
[[nodes]], [engine] |
render nodes (topology is not in .dome) and their engine endpoints (unix://, http(s):// + mTLS), RPC timeouts |
[sync] |
clock source (ptp via linuxptp pmc, ntp, local), thresholds, optional manage_linuxptp |
[sources] |
external source re-probe interval (RTSP / SRT / HLS / RTMP / NDI) |
[scenarios] |
scenario host (enabled scenarios) |
[devices.*] |
projector-line agents (visual), PJLink, Art-Net / sACN, serial ports — all off until configured |
[gateways.*], [[drivers.*]] |
compatibility emulators / outbound drivers (phase 5) |
[limits] |
per-client queues, body sizes |
[system] |
host_power (opt-in) |
[ws], [events] |
WebSocket heartbeat / message size; event ring buffer for resume |
[legacy] |
legacy compatibility profile, listen_3000 |
[cues], [triggers] |
outbound allow-list for cue actions (OSC / HTTP); time-zone offset for time triggers; MIDI input |