Skip to content

Plugins

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

Plugins

KHost loads drop-in plugins at startup. A plugin is a folder containing a manifest.json and a .NET assembly compiled against KHost.Plugins.Sdk (which has no other project references — plugin authors compile against that assembly alone).

Location and lifecycle

  • Load path: plugins/<plugin-folder>/ next to the host binary (AppContext.BaseDirectory/plugins). It is not part of the source tree — it is created wherever a plugin is installed, so a fresh build has no such folder. A plugin installed from the catalog lands in a folder named for its id; one dropped in by hand can be named anything, since ids are read from the manifest inside.
  • Discovery and loading happen once, in AddPlugins() before the DI container is built. Each enabled plugin gets its own non-collectible AssemblyLoadContext with SDK/host assemblies resolved from the default context to preserve type identity. Enabling, disabling, or changing a plugin therefore requires an app restart (PluginsService tracks RestartRequired).
  • Enable/disable state and per-plugin settings persist in the JSON cache (cache/plugins.json, key Plugins).
  • Per-plugin failures never crash startup: a plugin ends up Disabled, Enabled, Loaded, Incompatible (API version mismatch), or Errored, shown in the Plugins manager at /settings/plugins-manager.

Manifest

manifest.json, validated against the SDK's manifest.schema.json (draft-07, additionalProperties: false):

Field Required Notes
id yes GUID; must be unique across installed plugins.
name, version yes
entryAssembly yes Must end in .dll and exist in the plugin folder.
apiVersion yes Must equal PluginApi.CurrentVersion (currently 1; bumped only on breaking SDK changes).
author, description no
settings[] no Each: key, type (string/int/bool), label, optional secret, default. Rendered in the Plugins manager; values reach the plugin via IPlugin.GetSetting<T>() / BindSettings<TSettings>() and are fixed for the process lifetime.

Extension points

The loader registers exported types implementing:

  • IMediaProvider — an external media search source (SearchAsync returning MediaSearchEntity results with MediaProviderActions). The host's own library search is the built-in LocalMediaProvider. Every registered provider appears automatically in the media search split button. The main button searches the local library only — remote providers cost a round trip each to a metered or rate-limited service, so reaching them is always explicit: the dropdown lists each provider by DisplayName for a search scoped to that source (IMediaSearchService.SearchAsync(query, source)), plus an All providers entry (SearchAllAsync) once more than one is registered. A provider that throws is logged and skipped, never fatal to the search.
  • IQueueRotationMode — a queue-rotation strategy with Id/Name/Description, selectable per venue. Ids already taken by the host or an earlier-loaded plugin win.
  • IBreakMusicProvider — a source of between-singer music, selectable per venue. The built-in LibraryBreakMusicProvider plays from the local library; a plugin can drive an external player instead. See Break Music and Ads.

Built-in queue rotation

QueueRotationStrategyFactory resolves a venue's QueueRotationConfig (strategy id, drop-position mode, VIP group, first-time boost, cool-down, weights) to a strategy. Built-in modes: FIFO (default), Round Robin, Reverse, Longest Wait First, Fewest Songs First, Weighted Fair, Weighted Lottery, Pure Lottery, Shuffle Bucket — plus modifiers (cool-down, VIP tier, first-time boost) applied via the config.

Installing from the catalog

The Plugins manager has two tabs. Installed lists what is on disk; Available browses a published catalog and installs from it.

The catalog is fetched only when the Available tab is opened — never at startup, because a console runs on whatever wifi the room has. A failed fetch keeps the last copy and shows the error beside it, so a dead network costs a stale list rather than no list.

What the host checks before installing

A plugin runs in-process with the host's own access, so the catalog is the trust root and a release is only offered when it is served over https and carries a sha256. On install the host:

  1. downloads the asset with no credentials, hashing it as it streams;
  2. refuses it unless the hash matches the one the catalog published;
  3. checks every zip entry for a path escaping the destination before writing any of them, and caps the expanded size;
  4. reads the manifest.json inside and requires its id to match the catalog entry and its apiVersion to equal this host's;
  5. requires entryAssembly to resolve inside the plugin folder — the loader hands that name straight to LoadFromAssemblyPath.

Any failure leaves the installed plugin untouched.

Staging and the restart

Nothing installs into a running host: plugins load at startup, and on Windows a loaded assembly is locked by the process. A verified payload is parked in plugins-staging/ — a sibling of plugins/, since the loader treats every subdirectory of plugins/ as a plugin — and applied on the next start, before discovery. Until then the row reads Restart to install, with an Undo that drops the payload.

Removing a plugin works the same way: it is marked, and the folder is deleted on the next start. Its settings are kept, so reinstalling restores them.

When a plugin cannot be installed

Row reads Meaning
Not compatible Nothing listed will run here — either no release targets this host's plugin API, or none is built for this platform. The tooltip says which.
Not verifiable A release targets this host, but is published without an https URL and a checksum, so the host cannot know it got what the catalog described. Only the publisher can fix it.
Installed The newest release the host can use is already installed.

Publishing a plugin

A release is a zip holding manifest.json at its root (or inside a single wrapping folder), the entry assembly, and its .deps.json — AssemblyDependencyResolver reads that to find plugin-private dependencies.

Do not ship .pdb files, and do not ship a copy of KHost.Plugins.Sdk.dll: each plugin's load context resolves anything the host has already loaded from the default context, so a plugin-local SDK copy is never loaded and only adds weight.

Adding it to the catalog

plugin-catalog.json lives at the root of the KHost repo. Add a release with the tool rather than by hand:

dotnet run --project tools/KHost.CatalogSync -- <owner/repo> [--tag v1.2.0] [--rid win] [--capabilities "Media provider"]

It reads the GitHub release, downloads the asset unauthenticated, hashes what it actually received, unpacks it through the host's own validation, and writes the entry from the manifest inside. Review the diff and commit it — that commit is what a host trusts.

Two reasons it works this way:

  • Unauthenticated on purpose. The host sends no credentials, so a release on a private repository reads as 404 to it. Checking with gh, or any authenticated client, passes happily while every host gets nothing.
  • GitHub's digest is cross-checked, never copied. GitHub recomputes an asset's sha256 from whatever was uploaded, so it attests to transport and not to what anyone reviewed. The hash that reaches the catalog is the one the sync run computed, and a mismatch aborts.

Platform-specific builds

A release may name the platform it was built for with rid: win, osx, linux, optionally with an architecture (win-x64). Leave it blank for a build that runs anywhere — that is what a plugin should aim for, and blank is the common case.

Name a platform only where an OS API forces a separate build. Selection takes version first and platform second: a newer neutral build beats an older one built for this OS, and at the same version the platform build wins.

Clone this wiki locally