Configuration Reference

All config.json fields with types, defaults, and descriptions. All fields are optional.

Lookup order: CLI overrides config file, config file overrides defaults. See Configuration Sources.

Top-level fields

Key	Type	Default	Description
`schema_version`	int	`4`	Configuration format version; normally managed by automatic migration.
`alias`	string	`""`	Device alias shown on the idle screen.
`autorun_preset`	string	—	Removed. Ignored on load and erased on save. Startup playback must be explicit.

`network`

{ "network": { "base_port": 18290, "enable_osc": true, "listen_address": "0.0.0.0", "advertise_address": "auto", "controller_ip_whitelist": [] } }

Key	Type	Default	Description
`base_port`	int	`18290`	Base port for HTTP and OSC/UDP.
`enable_osc`	bool	`true`	Enable the OSC UDP socket. Same source policy as other control transports.
`listen_address`	string	`"0.0.0.0"`	Address used by HTTP, OSC/UDP, and Maintenance Remote Debug. Explicit values are respected.
`advertise_address`	string	`"auto"`	Address shown in the QR code and local status views. Display-only; does not affect binding or authorization.
`controller_ip_whitelist`	string[]	`[]`	Optional exact source IPs shared by HTTP, OSC, Maintenance, and Remote Debug. Empty adds no player-level source restriction.

`window`

{ "window": { "fullscreen": { "enabled": true, "mode": "borderless", "width": 0, "height": 0 }, "screen_index": 0, "always_on_top": true } }

Key	Type	Default	Description
`fullscreen.enabled`	bool	`true`	Start in fullscreen. `false` = windowed.
`fullscreen.mode`	string	`"borderless"`	`"borderless"` (exhibition default) or `"exclusive"` (performance / KMS). Neither mode can block OS-level prompts.
`screen_index`	int	`0`	Target display. `0` = primary.
`fullscreen.width`	int	`0`	Exclusive-fullscreen target width. `0` keeps the desktop mode.
`fullscreen.height`	int	`0`	Exclusive-fullscreen target height. `0` keeps the desktop mode. Refresh rate always follows the display's current desktop mode.
`always_on_top`	bool	`true`	Keep window above ordinary windows (applied when not in exclusive fullscreen).
`inhibit_screensaver`	bool	—	Removed. Ignored on load and erased on save. The player always inhibits the screensaver, display sleep, DPMS, and console blanking.
`fullscreen_refresh_rate`	float	—	Removed. Ignored on load and erased on save. Exclusive fullscreen follows the display's current refresh rate.

`control`

{ "control": { "media_root": "./assets", "load_timeout_sec": 30 } }

media_root is the directory used to resolve relative play_media / load sources. Putting files there does not start playback.

Key	Type	Default	Description
`media_root`	string	`"./assets"`	Base directory for relative v1 playback sources. CLI: `--media-root`.
`load_timeout_sec`	int	`30`	Seconds before an accepted load fails with `LOAD_TIMEOUT`. CLI: `--load-timeout`.
`freeze_exit_sec`	int	—	Removed. Ignored on load and erased on save. The player does not self-exit because a frame is stale.

`decode`

{ "decode": { "hwdec_mode": "auto" } }

Hardware decode backend only. This is not a playlist and does not choose which file to play. Old playlist.hwdec_mode is copied here once, then the playlist object is erased.

Key	Type	Default	Description
`hwdec_mode`	string	`"auto"`	`"auto"`, `"auto-copy"`, `"no"`, or `"v4l2m2m"` (Raspberry Pi). CLI: `--hwdec-mode`.

`idle_screen`

{ "idle_screen": { "image_path": "", "fill_mode": "fill" } }

Idle appearance follows RuntimeMode. Formal entry with an empty image_path is a black screen. Maintenance entry shows the local guide.

Key	Type	Default	Description
`image_path`	string	`""`	Background image for Normal idle. Empty means black. CLI: `--idle-image`.
`fill_mode`	string	`"fill"`	`"fill"` (cover), `"fit"` (contain), or `"stretch"`. Only used when `image_path` is set. CLI: `--idle-fill-mode`.

`audio`

{ "audio": { "output_device": "auto" } }

Key	Type	Default	Description
`output_device`	string	`"auto"`	libmpv audio-device ID. `"auto"` follows the system default. CLI: `--audio-output-device`.

`projection.mask`

{ "projection": { "mask": { "enabled": false, "invert": false, "feather_px": 0.0, "points_norm": [] } } }

Machine geometry, applied at every start. Same class of setting as window.*.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the mask. CLI: `--mask-enabled`.
`invert`	bool	`false`	Invert mask area. CLI: `--mask-invert`.
`feather_px`	float	`0.0`	Edge feather in pixels. CLI: `--mask-feather`.
`points_norm`	float[][]	`[]`	Polygon vertices `[[x, y], ...]`. Each value 0.0–1.0.

Overlays are not configuration. They are session content controlled by overlay_set, overlay_remove, and overlay_clear; list them with GET /api/extensions/overlays. They are cleared when the process exits and are not restored at startup.

Configuration Reference

On this page