Plugins and built-in features
Kryspal Media can be extended in two ways. Only one of them is open to you as a developer: plugins. This page explains the difference, how a plugin runs, and where the SDK lives.
On this page
Plugins and built-in features#
| Plugin | Built-in feature | |
|---|---|---|
| What it is | A separate program the server starts as a child process | Code inside the server itself |
| Versions | Has its own version and is released through a plugin catalog; the admin console can update it on its own | Ships with the server version and updates with it |
| Uninstall | Yes. Plugins that ship with the server can be uninstalled and installed again from the catalog | No. It can only be enabled, disabled and configured |
| Plan | A plugin is never locked. Paid capabilities it provides are simply not used without the plan | The whole feature is locked by the plan |
| Open to developers | Yes, through the plugin SDK | No |
In the admin console both appear on the Plugins page, in two groups. Built-in features include StrmTool, intro and outro detection, the media info archive, episode numbering fix, metadata care, poster language ranking and subtitle auto-fill. They are not extension points for outside code.
How a plugin runs#
- The server starts your executable as a child process and talks to it over gRPC on a Unix socket. Any language that can serve gRPC will do; the SDK for Go does the plumbing for you.
- The server starts it with a clean environment, waits for a one-line handshake on standard output, then calls
Describe(what the plugin is and what settings it has) andConfigure(the saved settings). Only after the settings pass is the plugin used. - The server checks health every 30 seconds and restarts a plugin that stops answering. A plugin that crashes five times in ten minutes is disabled until an administrator enables it again.
- The protocol is versioned. Version 1 only gets compatible additions; a breaking change would be a new major version, and the server can support several at once. A plugin built for an older protocol is shown as needing an update.
- There is no sandbox. A plugin runs as the server's user and can reach the network and the server's data folder. Installing a plugin means trusting its author. The server only isolates environment variables.
- A plugin keeps no state of its own that the server depends on: settings and credentials are passed on each call. Its working folder (also
HOME) is its own data folder, which survives upgrades and is deleted when you uninstall it. A plugin writes cache files only there.
What a plugin provides#
A plugin declares capabilities, such as movie metadata, images, subtitles or a casting target, and implements the matching services. The capabilities page lists them. A plugin also declares its settings form (text, secret, switch, number, choice, lists and groups), which the admin console draws for it, and optional attribution text for the data source. It can also list maintenance tasks, which run on a schedule, and checks, which are buttons that test the settings. It may ask for permissions, such as AI assistance or access to the local network.
Where to get the SDK#
The Go SDK (current version v0.3.1) is open source under the Apache License 2.0:
- github.com/kryspal/plugin-sdk holds the protocol definition (
PROTOCOL.md), the Go SDK, a test kit, examples and a changelog. - The official plugins that are open source are public too, and make good examples of real plugins. The list is under Official open-source plugins below.
Next: Capabilities, Quick start, Package, sign and publish. If you only want to install or manage plugins, read the Plugin center and Third-party plugins in the user guide.
Official open-source plugins#
These are the plugins Kryspal publishes as open source. Read them as examples of a complete plugin for each kind of capability: