Configuration

Configuration

TinyIce keeps all state in a single JSON file, tinyice.json (override the path with -config). The setup wizard writes a minimal working file on first run; most settings are also editable from the admin UI, which writes back to the same file.

• Atomic writes. Saves go to tinyice.json.tmp then rename(2) into place, serialised by a process-wide lock so concurrent admin/API/background writes can't shred the file.
• Hot reload. ./tinyice reload (or kill -HUP <pid>) re-reads the file without dropping listeners — mounts, passwords, relays, and UI settings are re-synced. See Command Line and Signals.
• Secrets are hashed. Admin, source, and mount passwords are stored as bcrypt hashes (cost 12). You cannot read a password back out of the file.

Inspect the effective config any time with ./tinyice dump-config.

Minimal example

{
    "bind_host": "0.0.0.0",
    "port": "8000",
    "base_url": "https://radio.example.com",
    "page_title": "My Radio",
    "page_subtitle": "Broadcasting 24/7",
    "accent_color": "#ff6600",
    "max_listeners": 100,
    "directory_listing": true,
    "ingest": { "rtmp_enabled": true, "rtmp_port": "1935" },
    "trusted_proxies": ["127.0.0.1", "10.0.0.0/8"],
    "autodjs": [
        {
            "name": "24/7 Chill", "mount": "/chill",
            "music_dir": "/music/chill", "format": "mp3", "bitrate": 128,
            "enabled": true, "loop": true, "inject_metadata": true
        }
    ]
}

Server and networking

Key	Type	Default	Notes
bind_host	string	0.0.0.0	Interface to bind (IPv4 + IPv6).
port	string	8000	HTTP / Icecast port.
https_port	string	443	HTTPS port (when use_https).
base_url	string	—	Public URL, e.g. https://radio.example.com. Used to build player/listen URLs in Webhooks and the API.
hostname	string	—	Advertised host name.
max_listeners	int	100	Hard cap across all mounts. New listeners over the cap get 503.
low_latency_mode	bool	false	Disables HTTP-level buffering (X-Accel-Buffering) and shrinks per-mount burst buffers. Toggle in the admin UI too.
trusted_proxies	[]string	—	Reverse-proxy IPs/CIDRs whose X-Forwarded-For/X-Real-IP are honoured. See Security.

HTTPS / ACME

Key	Type	Notes
use_https	bool	Serve TLS.
auto_https	bool	Obtain/renew certificates automatically via ACME (Let's Encrypt).
domains	[]string	Domains for the ACME certificate.
acme_email	string	Contact address for the CA.
acme_directory_url	string	Custom ACME CA (Step-CA, ZeroSSL, …). Empty = Let's Encrypt.
cert_file / key_file	string	Manual certificate pair (when not using ACME).

{
    "use_https": true, "auto_https": true,
    "port": "80", "https_port": "443",
    "domains": ["radio.example.com"], "acme_email": "admin@example.com"
}

Ports 80/443 must be reachable for ACME challenges. Web browsers are redirected to HTTPS; plain-HTTP encoders (most hardware) keep working on the HTTP port. See Deployment.

Mounts

Mounts can be created implicitly by a source connecting, or pre-declared. Three maps cover the common per-mount toggles, plus an advanced settings map:

Key	Type	Notes
default_source_password	string	Fallback source password for any mount without its own. Hashed.
mounts	map[mount]password	Legacy global mount → password map.
advanced_mounts	map[mount]→MountSettings	Per-mount password, burst_size, and name_override.
disabled_mounts	map[mount]bool	Disabled mounts refuse new SOURCE connections.
visible_mounts	map[mount]bool	Whether a mount appears in public listings.
fallback_mounts	map[source]→fallback	Mount to redirect listeners to when the source is down.

MountSettings.name_override, when set, replaces the source's Ice-Name on metadata update — rebrand a station server-side without touching the encoder. Default burst size is 512 KB (the "instant start" buffer); raising it lowers startup latency at a small memory cost.

Ingest (RTMP and SRT)

"ingest": {
    "rtmp_enabled": true, "rtmp_port": "1935",
    "srt_enabled": true, "srt_port": "9000", "srt_latency": 120
}

Key	Default	Notes
rtmp_enabled / rtmp_port	off / 1935	H.264 + AAC/MP3 from OBS, ffmpeg.
srt_enabled / srt_port	off / 9000	MPEG-TS over SRT (audio + video).
srt_latency	120	SRT receiver latency in ms.

Both are off by default. Icecast SOURCE/PUT and WebRTC ingest need no ingest config. Details in Streaming Sources.

AutoDJ

autodjs is a list of independent file-based stations. Full reference in AutoDJ.

Key	Notes
name, mount, music_dir	Identity and source directory.
format (mp3/opus), bitrate	Output encoding.
enabled, loop, inject_metadata, visible	Behaviour toggles.
playlist, last_playlist	Ordered file list / last saved playlist name.
mpd_enabled, mpd_port, mpd_password	Per-instance MPD control protocol.
song_command (+ song_command_timeout)	External next-track selector.
on_play_command (+ on_play_command_timeout)	Shell hook at track start.

song_command / on_play_command run via sh -c as the service user. Creating or editing an AutoDJ requires the superadmin role for exactly this reason — see Security.

Transcoders, relays, webhooks

Key	Points to	Page
transcoders	TranscoderConfig list (MP3/Opus re-encode, per-output visibility, Opus tuning)	Transcoding
auto_transcode_mp3_bitrates	[]int — spawn ephemeral MP3 transcoders for any non-MP3 source on connect	Transcoding
relays	RelayConfig list (pull from upstream Icecast)	Streaming Sources
webhooks	WebhookConfig list (templated outbound HTTP)	Webhooks
variant_groups	map[primary]→ordered member mounts (ABR/simulcast)	Playback and Output

Authentication & users

Key	Notes
admin_user / admin_password	Bootstrap super-admin (migrated into users on load).
users	map[username]→User with role (superadmin/admin/dj), per-mount grants, passkeys, linked emails.
api_tokens	Bearer tokens (hashed) with role, expiry, last-used tracking.
oidc_providers	OIDC/OAuth2 login providers.
pending_users	OIDC sign-ups awaiting approval.
webauthn	Passkey relying-party config (rp_id, rp_name, rp_origins).
smtp	Outbound email for notifications.
setup_complete	Set once onboarding finishes.

Full model and flows in Authentication and Users.

Security & access control

Key	Notes
banned_ips	IPs/CIDRs dropped at accept time.
whitelisted_ips	IPs/CIDRs that bypass scan/ban checks.
trusted_proxies	See above / Security.
audit_enabled	Enable the audit log.

Branding & UI

Key	Default	Notes
page_title	TinyIce	Site name.
page_subtitle	Live Streaming Server powered by Go	Tagline.
accent_color	#ff6600	UI accent (hex).
logo_path	—	Logo file, served at /branding/logo.
landing_markdown	—	GFM landing copy, sanitised with DOMPurify before render.

Directory listing (YP)

Key	Default	Notes
directory_listing	—	Report public mounts to a YP directory.
directory_server	http://dir.xiph.org/cgi-bin/yp-cgi	YP endpoint. Proper add/touch/remove lifecycle.

Multi-tenant

multi_tenant (enabled, default_tenant, tenant_store) is present in the schema for hosting multiple logical stations. It is early-stage; single-tenant is the supported path today.

---

Most keys have a CLI shortcut: ./tinyice get <key> and ./tinyice set <key> <value>. See Command Line and Signals.