Repository navigation
Development
Everything in Getting Started — the .NET 10 SDK, Node.js 18+ with npm, and FFmpeg on PATH — plus:
- (Optional) Docker Desktop — for the Aspire dashboard's local telemetry when running via
KHost.AppHost. - (Optional) ffprobe — ships with FFmpeg; the transcode tests use it to assert a segment really carries audio.
- (Optional) Chromecast-Emulator listening on
127.0.0.1:8009— the Cast tests skip without it.
# With the Aspire dashboard (telemetry, resource view)
dotnet run --project src/KHost.AppHost
# The Blazor UI directly
dotnet run --project src/KHost.UserInterface
# Headless (no native window; serve the console to a browser)
dotnet run --project src/KHost.UserInterface -- --headlessScreens are normally launched from the host's Screens dialog, which injects the host's live listening address as --server-uri. To run one by hand:
# --screen-id defaults to the machine name
dotnet run --project src/KHost.Screen2 -- --server-uri http://localhost:5251/ipc/screen --screen-id main
# --log-level debug adds the state the page reports each tick (position, expected
# position, readyState) — how to tell a screen that is behind from one that never started
dotnet run --project src/KHost.Screen2 -- --server-uri http://localhost:5251/ipc/screen --log-level debugScreen logs land in logs/ beside the screen executable, one file per screen id per day.
The repository carries a project skill at .claude/skills/run-khost/SKILL.md — the verified recipe for launching KHost and driving its native window (readiness checks, GUI automation via cliclick, a full playback pass with the log lines that prove each step, shutdown expectations). Agent sessions load it automatically when asked to run the app; it reads as a checklist for humans too.
Its most important rule applies to anyone testing by hand: every graceful exit clears the singer queue and queued performances (the venue's ClearQueueOnClose defaults on and runs on shutdown — window close, Ctrl+C, and SIGTERM alike). Back up src/KHost.UserInterface/bin/Debug/net10.0/cache/ before a test run that will stop the app, and restore it after, or the run eats the local queue.
cd src/KHost.UserInterface
npm run dev # runs dotnet watchRedirect the output so the IDE's bin/ isn't locked:
dotnet build KHost.slnx "-p:BaseOutputPath=./obj/_build"SCSS compiles inside dotnet build (AspNetCore.SassCompiler) — there is no separate sass step. The build needs node_modules (npm install in src/KHost.UserInterface/) for copy:vendors.
- Component styles live beside their component (
Foo.razor.scss→ scopedFoo.razor.css; the generated.cssis gitignored — never edit or commit it). - Shared blocks live under
wwwroot/scssand are pulled in viaapp.scss. Onlyapp.scssandthemes/*should lack a_prefix — any other file without one compiles to its own stylesheet. - Top-level class names are prefixed
kh-, with BEM naming. No inlinestyleattributes, no<style>blocks. Bootstrap Icons only — no Bootstrap CSS/JS; its utility classes resolve to nothing.
The console is laid out for roughly 1440px and holds together down to about 700px. Two different widths decide what shrinks, and picking the wrong one is the usual mistake:
-
Panels answer to
@container.panel-resize.jswrites a pixel width onto the queue column, so a panel can be 180px wide in a 1440px window. Anything inside a panel keys off a named container (kh-queue,kh-singer-info,kh-media-search), never the viewport. -
The header answers to
@media. It spans the window, with no splitter between it and the viewport, so window width is the only width it has.
Set thresholds against a panel's measured width at 1440, not a round number — the queue column is about 283px there, so a 300px threshold would put a full-screen console into narrow mode.
For a control to shrink at all it usually needs min-width: 0 as well as white-space: nowrap:
without it a flex item cannot go below its longest word, so it pushes its neighbours off the row
instead of truncating.
A scoped rule only matches elements the component itself renders. A class handed to another
component — <Icon Class="…" />, <InputNumber class="…" />, anything inside a RenderFragment
passed as a parameter — lands on markup that carries a different scope id or none at all, and the
rule silently matches nothing. Reach it with ::deep from an ancestor the component does render:
.kh-thing__row {
::deep .kh-thing__field { width: 120px; }
}Never lead with ::deep &__x — the & expands to the parent and swallows it, leaving a selector
the browser drops.
.kh-card__body pads a direct <form> child and nothing else, so a card body without a form needs
its own padding.
- Interfaces live in
KHost.Abstractions, concrete types in their implementation project, registered in that project'sProjectExtensions(AddDomain()/AddDataAccess()/ …); UI-only services inProgram.cs. - Domain services are singletons — guard mutable state with
SemaphoreSlim. - Services announce changes on
IMessageBrokerrather than raising events — there is noStateChangedand noIKHostService. A service that has something to report takesIMessageBrokerin its own constructor and callsBroker.Announce(new ThingChanged()); components subscribe inOnInitialized, hold the subscriptions in aSubscriptionSet, and dispose it inDispose. See Messaging. - Services that expose configuration use the nested
ServiceOptionsclass pattern withBindConfiguration(ServiceOptions.SectionName)andIOptionsMonitor<>for live reload. - Every
Task/ValueTask-returning method ends inAsync— enforced by reflection inAsyncNamingConventionTests. - Component logic lives in a code-behind partial (
Foo.razor.cs), never an inline@codeblock. - Member order: fields → events → properties → public → protected → private → nested types.
- Method names that cross a string boundary (
[JSInvokable]called from JS, SignalR hub methods invoked by name) are passed asnameof(...)from C# and taken as a parameter on the JS side, so a rename cannot break silently.
The full conventions, including agent-facing gotchas, live in AGENTS.md in the repository.
Venue.Settings is a JSON column — adding or removing properties on VenueSettings is not a schema change and needs no migration at all. But EF reads keys missing from stored rows as default, ignoring property initializers, so a new setting that must default to true needs a data-only json_set backfill migration.
For a real schema change (any DbSet<T> model), add a migration:
dotnet ef migrations add <Name> --project src/KHost.DataAccessAdditive changes such as an index apply in place and leave both the runtime database and the hand-written AddMediaFts migration alone.
Regenerating the chain from scratch is a separate, deliberate act rather than a step in adding a column. It destroys the local library, users and queue, and it drops the FTS5 setup on the floor:
- Delete
src/KHost.DataAccess/Migrations/and the runtime database. dotnet ef migrations add InitialSchema --project src/KHost.DataAccess- Recreate
AddMediaFtsby hand — the FTS5 table and its triggers are raw SQL EF will not regenerate, and search throwsno such table: media_ftswithout it. Copy theUp/DownSQL from a priorAddMediaFts.cs.
See CONTRIBUTING.md for the contribution workflow, license grant, and DCO sign-off requirements.
Starting points for the technologies KHost uses:
- .NET / C# — .NET docs, C# guide
- .NET Aspire — overview, AppHost
- Blazor Server — docs, component lifecycle, render modes
- Photino — docs, Photino.NET; HLS spec (RFC 8216)
- EF Core + SQLite — EF Core docs, SQLite provider, SQLite docs
- Media — FFmpeg docs, FFMpegCore, TagLib#
- Observability — Serilog, OpenTelemetry for .NET, HTTP resilience
- Testing — xUnit, NSubstitute, coverlet
- Styling — Sass guide, BEM, Bootstrap Icons
KHost
Architecture
- Architecture
- Projects
- Screens and Casting
- Break Music and Ads
- Messaging
- Data and Persistence
- Plugins
Contributing