Skip to content

Configuration

Michael Riddle edited this page Aug 26, 2026 · 6 revisions

Configuration

src/KHost.UserInterface/appsettings.json is the host's configuration file. Environment-specific overrides live in appsettings.Development.json, and machine-level changes made from the UI land in the settings overlay. Options-pattern sections bind whether or not they appear in the file; absent keys use the defaults below.

Host settings

Section / key Default Purpose
Logging — Standard Microsoft.Extensions.Logging levels. Serilog is layered on top in Program.cs.
AllowedHosts * ASP.NET Core host filter.
Auth.RequireLogin true Whether the console asks for credentials. When off, every session runs as the console admin — see Users and Permissions.
Urls http://0.0.0.0:5251 Where Kestrel listens (semicolon-separated). Binds every interface so Cast receivers and off-machine screens can reach the stream; only /media and /ipc/screen are answered off-box (see Architecture).
FFmpegPath null Path to the FFmpeg binary directory when it is not on PATH.
Playback.StopFadeDuration 5 s Audio fade applied on stop.
Playback.SyncStartLead 400 ms How far in the future the shared-timeline start is scheduled, so every screen starts on the same instant.
LocalScreen.ExePath KHost.Screen2 next to the host binary Override for the screen executable path.
LocalScreen.ServerUri host's live listening address SignalR hub URI passed to launched screen processes. The host injects the address it is actually bound on; set only to force a specific URI.
MediaStream.BaseAddress host's live listening address Base URL embedded in HLS playlist URLs handed to screens and Cast receivers.
MediaStream.WorkingDirectory %TEMP%/khost-streams Where per-session HLS output (stream.m3u8 + segments) is written.
MediaStream.SegmentSeconds 2 HLS segment length.
PluginCatalog.Url https://raw.githubusercontent.com/riddlemd/KHost/master/plugin-catalog.json Where the Plugins page reads its list of installable plugins. Blank disables browsing, leaving manual installs only. See Plugins.
PluginCatalog.CacheLifetime 06:00:00 How long a fetched catalog is reused before the Available tab checks again. The cached copy is kept and shown when a fetch fails.
MediaFileParsingService.* — Filename-to-metadata parsing: Format (ArtistFirst/TitleFirst), Separators, PrefixStripPatterns, TitleNoisePatterns, FeaturingPattern, FeaturingHandling, FallbackArtistName.

Cast discovery is not configured here: it sweeps the whole network, so it is off at startup and enabled from the Screens dialog only while the dialog is open.

The settings overlay (cache/settings.json)

The App Settings page (admin-only) edits a handful of machine-level settings from the UI. It does not rewrite appsettings.json — that stays a read-only deployment default — but writes a config-shaped overlay to cache/settings.json, registered as the last configuration source with reload-on-change:

  • Applied live (on the next read of the value): Auth:RequireLogin, Playback:StopFadeDuration, Playback:SyncStartLead, MediaStream:SegmentSeconds.
  • Needs a restart: FFmpegPath — the page flags this after saving.

Turning the login requirement on is refused while no admin-group user has a password; see Users and Permissions.

Per-venue settings

These are stored on the venue (Venue.Settings, a JSON column) and edited in the venue editor, not in appsettings.json:

Setting Default Purpose
DefaultVolume 100 Playback volume (0–100) sent to the audible screen. Applies immediately when the venue is selected or its settings change.
OnScreenDisconnect ResumeOnReconnect What playback does when the last screen disconnects.
ShowEstimatedWaitTime true Show estimated wait per queued singer.
TippingEnabled true Enable tip recording.
WarnOnDuplicateSong false Prompt when a song was already sung recently.
DuplicateSongWindowHours 4 Window for the duplicate-song warning.
PromptBeforeRemovingSinger true Confirmation prompt when removing a singer.
PromptBeforeRemovingPerformance true Confirmation prompt when removing a queued performance.
ClearQueueOnClose true Clear the queue on any graceful shutdown — closing the window, Ctrl+C, SIGTERM. A force kill leaves the queue in place.
QueueRotation FIFO Queue-rotation strategy and its parameters (see Plugins for the built-in modes).

Command-line flags

Host (KHost.UserInterface):

Flag Effect
--headless No native Photino window; the console is served to a browser.
--start-page <route> One-time redirect to the given route on first load.
--reset-password <username> Resets the user's password to a generated one, prints it, and exits. Run while the host is stopped (Users and Permissions).

Screen (KHost.Screen2):

Flag Default Effect
--server-uri http://localhost:5000/ipc/screen SignalR hub to connect to. Screens launched from the Screens dialog get the host's live address injected.
--screen-id machine name Identity reported to the host; also names the screen's log files.
--log-level Information debug additionally logs the state the page reports each tick (position, expected position, readyState).

Runtime files

See Getting Started for the on-disk layout (cache/, logs/, the SQLite file).

Clone this wiki locally