Skip to content
Michael Riddle edited this page Aug 26, 2026 · 8 revisions

KHost

Open-source karaoke hosting software built on .NET 10. KHost pairs a Blazor Server host console for managing singers, songs, and playback with a lightweight desktop screen app that renders karaoke video and audio to a second display — or to a Chromecast. Runs on Windows, Linux, and macOS.

KHost is a two-part application:

  1. The host console (KHost.UserInterface) — a Blazor Server web app used by the host (KJ) to queue up singers, search the song library, edit performer and venue info, and control playback in real time.
  2. The screen app (KHost.Screen2) — a Photino desktop application that renders the karaoke output. It plays an HLS stream the host transcodes, so it decodes nothing itself.

The host transcodes each song once (FFmpeg → HLS) and serves the stream, so any number of screens — and a Chromecast receiver — play the same song on a shared timeline.

Documentation

Page Contents
Getting Started Prerequisites, running from source, first-run wizard, runtime files
Configuration appsettings.json reference, settings overlay, per-venue settings, command-line flags
Users and Permissions Sign-in, permission gates, the login requirement, password recovery
Architecture Layering, runtime data flow, startup, network access policy
Projects Every project in the solution and its role
Screens and Casting Screen app, IPC protocol, shared timeline, Chromecast
Break Music and Ads Playlists, selection and weighting, ad triggers, priority, volume
Messaging The in-process message broker services and components talk through
Data and Persistence Database schema, text folding, full-text search, JSON cache, migrations
Plugins Plugin SDK, manifest format, loading, extension points, installing from the catalog
Development Contributor workflow, conventions, hot reload, SCSS
Testing Test projects, infrastructure, external-tool requirements

Features

  • Singer queue management — add, remove, and reorder singers; configurable queue-rotation strategies per venue. The name field suggests singers from the roster as it is typed, grouped by the venue each last sang at, this venue first.
  • Song / media search — SQLite FTS5 (trigram) search over the local library, forgiving about how a name is spelled: bjork finds Björk and kesha finds Ke$ha, because stored text and query are folded the same way. A plain search reads the local library only; plugin providers are searched when asked for, individually or all at once.
  • Now-playing panel — play, pause, stop (with fade), seek, and track position.
  • Second-screen output over HLS — one transcode shared by every consumer.
  • Multiple screens, one timeline — playback is anchored to a scheduled start; screens correct their playhead by seeking, never by rate-shifting, so nothing is pitch-bent to catch up.
  • Screen roles — per-screen audio/video enable, one primary screen acts as the reference clock; the Screens dialog shows live drift per screen.
  • Chromecast output — receivers discovered on demand and driven over CASTV2 (Google Default Media Receiver). One receiver at a time; a receiver is deliberately not a screen and never holds the timeline.
  • Screens survive a lost host — a screen that loses the host pauses and says so.
  • Library managers — Settings pages for media, singers, groups, venues, tips, and plugins, with a bulk media editor.
  • First-run setup wizard at /setup — security choice, admin user, first venue, initial media import.
  • User accounts and sign-in — cookie authentication with per-permission gates, named groups, Argon2id password hashing, a Lock action, and an optional single-operator mode with no login at all (Users and Permissions).
  • Tip tracking — per-singer tips with amount, payment method, and notes; stored as whole cents, entered and shown as $00.00.
  • Lyrics lookup — plain-text lyrics from LRCLIB.NET.
  • Plugin system — drop-in plugins provide media search providers, queue-rotation modes, and break-music sources, installed by hand or from a published catalog with the download checksum-verified (Plugins).
  • Themeable UI — switchable CSS themes, laid out for 1440px and usable down to about 700px.
  • An appliance, not a browser — in its own window a Release build has no page context menu outside text fields, no developer tools, and no reload or back shortcuts (Architecture).
  • Observability — Serilog and OpenTelemetry with OTLP export, custom metrics and trace activities.

Tech stack

Layer Technology
Runtime .NET 10
Host console ASP.NET Core / Blazor Server
Screen app Photino.NET (platform web view)
Host ⇄ screen IPC SignalR
Transcoding FFmpeg (one process per song, served as HLS)
Chromecast Sharpcaster (CASTV2)
Database SQLite via Entity Framework Core 10
Media metadata TagLibSharp
Password hashing Argon2id (Konscious.Security.Cryptography.Argon2)
Observability Serilog, OpenTelemetry (OTLP)
Styling Sass (SCSS), BEM naming, Bootstrap Icons

Exact package versions live in Directory.Packages.props.

License

KHost is licensed under the PolyForm Shield License 1.0.0. Self-hosting for any purpose, including commercial karaoke events, is permitted; offering KHost or a derivative as a competing product or hosted service requires a separate license. See the README for details and contact.

Clone this wiki locally