Repository navigation
Home
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:
-
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. -
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.
| 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 |
- 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:
bjorkfinds Björk andkeshafinds 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.
| 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.
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.
KHost
Architecture
- Architecture
- Projects
- Screens and Casting
- Break Music and Ads
- Messaging
- Data and Persistence
- Plugins
Contributing