Configuration

Almost everything is set in the interface, under Settings. The configuration file and environment variables are only needed for installation (port, database location) and special cases. This page covers both.

Settings

The Settings tabs, in order. Some only show at the Advanced or Expert interface level (account menu › Interface).

Tab	Main content
General	Playback (loop, shuffle, volume in Audiophile mode), Interface (theme, language, startup view, default zone, volume display, sidebar order), Profiles
Audio	Local Audio Outputs (audio backend, WASAPI mode, ReplayGain, background analysis speed), network devices, Squeezebox / Lyrion, HQPlayer, DSD playback to network renderers, audio diagnostic, Wi-Fi network
Library	Scan the library, Locations (folders and SMB shares), scan options, automatic analysis, metadata, enrichment, adding content
Zones	Automatic zone creation, "Follow me"
Devices	Per-zone settings (DSD, max rate, fixed volume, bit-perfect strict, mono output…), settings backup
Display	Track list columns, collection cover mosaic, Stop button, sources in the sidebar
Extensions (Expert)	Installed extensions and catalogue
Access and tokens (Advanced)	Streaming services, service keys (Last.fm, etc.)
System	About and Updates, Server Health (log level, cleanup), Database (backup / restore, migration to PostgreSQL), data location, import from another player (Roon, Plex), CSV export
Acoustic analysis (Expert)	Acoustic analysis of the library
Tune Premium License	Activate or release a licence

To find a setting quickly, use Search a setting… in the account menu.

Updates

When a new version is available, Tune announces it in the sidebar ("Update available"). To check yourself, use Check for updates in Settings › System › About › Updates. On Windows, macOS, the .deb package and Tune OS, the update installs from within Tune; any running scan is stopped first. With Homebrew, Tune runs brew upgrade or tells you to. With Docker, pull the new image yourself.

Note for the .deb: an update installed from Tune replaces the files in /opt/tune without going through apt. Reinstalling an older .deb afterwards brings back that package's version.

Backup

Settings › System › Database › Backup / Restore makes a copy of the database. Copies are stored in a backups folder next to the database, and Tune keeps the five most recent. This is not available with PostgreSQL: use pg_dump instead. Settings › Devices › Settings backup saves your zone settings to a file. Volume, queue and groups are not included. Load the file again with Open a backup….

The `tune.toml` configuration file

Tune needs no file to start. If you create one, Tune uses the first tune.toml it finds, in this order:

Windows: %APPDATA%\Tune\tune.toml
the folder Tune is started from: ./tune.toml
/etc/tune/tune.toml
macOS: ~/.config/tune/tune.toml

port = 8888
db_path = "tune.db"
auto_scan = false
log_level = "info"
music_dirs = ["/srv/music"]
# local_audio_backend = "asio"     # Windows: auto, wasapi or asio
# dlna_play_delay_ms = 0

Careful: a malformed file is skipped without any error message, and Tune moves on to the next one or to the defaults.

Environment variables

Environment variables take precedence over tune.toml. Tune also reads a .env file in the folder it is started from (and on Windows, in %LOCALAPPDATA%\TuneServer\ or next to tune-server.exe). With the .deb package, put them in /etc/default/tune-server (one per line, no quotes), then run sudo systemctl restart tune-server.

Variable	Default	Purpose
`TUNE_PORT`	8888	Port of the web interface and API
`TUNE_DB_PATH`	see below	SQLite database file
`TUNE_MUSIC_DIRS`	none	Music folders, comma-separated or as a JSON array. Read on first start only (see below).
`TUNE_AUTO_SCAN`	false	Scan the library at startup (`true` to enable)
`TUNE_LOG_LEVEL`	info	Log level: error, warn, info, debug, trace
`TUNE_LOG_FILE`	per platform	Log file path
`TUNE_ARTWORK_DIR`	per platform	Cover art cache folder
`TUNE_ADVERTISED_IP`	detected	IP address Tune announces to renderers. Useful when the machine has several network interfaces.
`TUNE_DATABASE_URL`	none	A `postgres://…` URL to use PostgreSQL
`TUNE_LOCAL_AUDIO_BACKEND`	auto	Windows: `auto` (WASAPI), `wasapi` or `asio`. The choice made in Settings › Audio takes precedence.
`TUNE_LOCAL_EXCLUSIVE_MODE`	false	Exclusive mode for local outputs
`TUNE_TIDAL_QUALITY`	HI_RES_LOSSLESS	Requested TIDAL quality
`TUNE_SLIMPROTO_PORT`	3483	Squeezebox (SlimProto) server port
`TUNE_CLI_PORT`	9090	LMS-compatible command port
`TUNE_SCAN_IO_CONCURRENCY`	auto	Number of files read in parallel during a scan (4 on a hard disk, 32 otherwise)
`TUNE_DISCOGS_TOKEN`	none	Discogs personal token
`TUNE_LASTFM_API_KEY`, `TUNE_LASTFM_API_SECRET`	none	Last.fm keys, copied once into the settings
`TUNE_TELEMETRY`	on	Set to `false` to turn telemetry off (also available in Settings › System)
`RUST_LOG`	none	Advanced log filter; takes precedence over `TUNE_LOG_LEVEL`

Music folders. TUNE_MUSIC_DIRS (or music_dirs) is copied into the settings on first start only. After that, the list in Settings › Library › Locations is what counts, and changing the variable has no effect. A missing or empty folder is not copied.

Removed variables. The old variables PORT, HOST, MUSIC_DIRS, DB_DRIVER, API_KEY, AUDIO_DEVICE, DSD_MODE, WRITE_TAGS, WATCH_FILESYSTEM and similar ones are no longer read. Several variables in .env.tune.example also have no effect: TUNE_TIDAL_ENABLED, TUNE_QOBUZ_ENABLED, TUNE_DEEZER_ENABLED, TUNE_SPOTIFY_ENABLED, TUNE_YOUTUBE_ENABLED, TUNE_DEFAULT_OUTPUT_FORMAT. Services are turned on in the interface.

Where data lives

Installation	Database	Log
Windows	`%LOCALAPPDATA%\TuneServer\tune.db`	`%LOCALAPPDATA%\TuneServer\tune-server.log`
macOS	`~/Library/Application Support/Tune/tune.db`	`~/Library/Logs/tune-server.log`
.deb package	`/var/lib/tune/tune.db`	`journalctl -u tune-server`
Linux archive	`./tune.db` (start folder)	`~/.local/state/tune/tune-server.log`
Docker	`/data/tune.db`	container output (`docker logs tune`)
Tune OS	`/opt/tune/data/tune.db`	`journalctl -u tune`

The cover art cache sits alongside: %LOCALAPPDATA%\TuneServer\artwork_cache on Windows, ~/Library/Application Support/Tune/artwork_cache on macOS, /data/artwork_cache on Docker, /opt/tune/data/artwork_cache on Tune OS. The log file is capped at 10 MiB, with one backup copy (.1). On Tune OS, a device installed before 1.0 keeps its original cache, /opt/tune/artwork_cache.

Database: SQLite or PostgreSQL

Tune uses SQLite by default, with no setup. PostgreSQL is supported by the published Windows, macOS and Linux (x86-64 and aarch64) builds. It is not supported by the Docker image or the Linux aarch64-musl build. Two ways to turn it on:

in the interface: Settings › System › Database › Migrate to PostgreSQL (Expert level);
at startup: TUNE_DATABASE_URL=postgres://user:password@host:5432/tune, or TUNE_DB_ENGINE=postgres together with TUNE_DB_HOST, TUNE_DB_PORT, TUNE_DB_NAME, TUNE_DB_USER and TUNE_DB_PASS.

Network ports

Port	Purpose
TCP 8888	Web interface, API, WebSocket and audio streams sent to renderers
UDP 1900	SSDP discovery (DLNA/UPnP)
UDP 5353	mDNS discovery (AirPlay, Chromecast…)
TCP/UDP 3483	Squeezebox (SlimProto) server. It clashes with an LMS running on the same machine.
TCP 9090	LMS-compatible command port. If 9090 is taken, Tune tries 9091 to 9098.
TCP 8890	UPnP/OpenHome event listener (another port is picked if it is taken)

Tune listens on all network interfaces; the listening address cannot be changed. On Tune OS, port 80 forwards to 8888.

Security

By default Tune has no password and no HTTPS: anyone with access to your local network can open the interface. Do not expose port 8888 to the Internet. Account and token authentication exists in the API (see the Technical Guide) but cannot be set from the interface.