Quick start

This builds the smallest working plugin in Go: a movie metadata provider that knows one title. You need Go and an installed Kryspal Media server to try it on.

1. Create the module#

mkdir minimal && cd minimal
go mod init example.com/minimal
go get github.com/kryspal/plugin-sdk@latest

The SDK is released under the Apache License 2.0. While it is at version 0.x, helper functions may change, but the protocol on the wire does not.

2. Write the plugin#

The SDK repository contains this as examples/minimal. The shape is:

• A type that embeds the unimplemented server types and implements Describe, Configure and the services you declare.
• Describe returns the manifest: an ID (lowercase letters, digits and hyphens), a name, a version (MAJOR.MINOR.PATCH), the protocol version and the capabilities.
• main calls sdk.Main with the services you implement. The SDK handles the handshake, health checks, shutdown and logging.

type provider struct {
    pluginv1.UnimplementedPluginServer
    pluginv1.UnimplementedMetadataProviderServer
}

func main() {
    p := &provider{}
    sdk.Main(sdk.Config{Plugin: p, MetadataProvider: p})
}

Return helpers such as sdk.NotFound, sdk.RateLimited and sdk.NeedsConfiguration map to the right error codes. A panic in a handler becomes an internal error and the plugin keeps running. Write logs to standard error; standard output belongs to the handshake.

3. Build#

Build a static binary:

CGO_ENABLED=0 go build -trimpath -buildvcs=false -ldflags "-s -w" -o minimal .

You cannot run it by hand. A plugin exits right away unless the server starts it with the right environment.

4. Test with the test kit#

The SDK ships a conformance test. It starts your plugin the way the server does and checks the handshake, health, Describe, Configure and a clean shutdown, and, if you give it a case, a search followed by a fetch:

func TestPlugin(t *testing.T) {
    plugintest.Run(t, "./minimal", plugintest.Options{
        Metadata: &plugintest.MetadataCase{Type: pluginv1.ItemType_ITEM_TYPE_MOVIE, Name: "Big Buck Bunny", Year: 2008},
    })
}

It also checks the manifest's settings, groups, tasks and other declarations, and can run your tasks. It does not cover subtitles, account sync, segments, danmaku, alias maps or casting, so test those yourself. You can start the plugin with your own fake upstream servers through the options for environment and setup.

5. Testing a plugin on your own server#

The quickest way is developer mode. The server loads plugins from a folder on its own machine. They need no signature and no catalog.

1. Put your build in <dir>/<id>/<version>/<id>, where <id> is the plugin ID and the last one is the executable. For example dev-plugins/hello/0.1.0/hello.

2. Mount the folder into the container and set MEDIASERVER_DEV_PLUGINS to its path inside the container:

   services:
     server:
       environment:
         MEDIASERVER_DEV_PLUGINS: /dev-plugins
       volumes:
         - /path/to/dev-plugins:/dev-plugins:ro
   

3. Restart the server. The plugin appears in the plugin center, marked "In development" and turned off. Fill in any required settings and press Enable.

4. After you rebuild, click Reload developer plugins at the top of the plugin center. You do not need to restart. A banner there reminds you that developer mode is on.

Good to know:

• A SHA256SUMS file next to the executable is optional. If it is there, the server checks it and skips a version that does not match.
• With several versions in a folder, the highest one is used.
• Developer plugins are never updated from a catalog. Uninstalling one removes only its settings, not your files.
• Official plugin IDs are skipped. A plugin from the folder is used instead of an installed plugin with the same ID, and its settings are kept.
• Paid capabilities still follow your license.
• Plugins run without a sandbox, so use developer mode only for plugins you wrote or trust.
• Remove the setting when you are done testing.

To test the whole install path, host a catalog over HTTPS and add it in the admin console: see Package, sign and publish. The server refuses catalog addresses on your own network, so that needs a public HTTPS host.

Reading more#

The protocol, with every service, timeout and error rule, is PROTOCOL.md in the plugin SDK repository. The examples/static example there uses every service and shows how to test translations. Read the licence notes in the SDK README before you pick a licence for your plugin.