Menu
ContentsCapabilities

  1. API

    1. Using the API
    2. API reference
    3. Emby-compatible API

  2. Plugin SDK

    1. Plugins and built-in features
    2. Capabilities
    3. Quick start
    4. Package, sign and publish

Capabilities

A plugin lists the capabilities it provides in its manifest. The server only calls a plugin for what it declares; a call to an undeclared capability is not forwarded. The admin console sorts plugins into categories from their capabilities, so a plugin does not pick its own category.

On this page
  1. Conventions
  2. Errors
  3. Tasks
  4. Checks
  5. Settings fields
  6. Permissions
  7. Host features
Capability What it means
metadata.movie Search for and fetch movie metadata
metadata.series Series, seasons and episodes
metadata.person Person details
metadata.person.search Find a person from a name and the titles they appear in, when no provider ID is known
metadata.collection Collection details
metadata.trailers Return trailers with the item
metadata.search.hints Receive the recognition hints (titles, year, language, shape) in a search
metadata.series.absolute Accept an absolute episode number
images.movie, images.series Posters, backdrops and logos by provider ID
images.person Person photos, by provider ID, name and aliases
subtitles.search Search and download subtitles
media.recognize Work out a title from a path or file name, without reading the file or using the network
segments.provider, segments.submit Community intro and outro data: read and contribute
danmaku.provider Timed comments for a video
usersync.link, usersync.scrobble, usersync.watched.pull, usersync.watched.push Link an account and sync watch state with an outside service
people.aliasmap A map of alternative names for people
cast.target Find devices on the local network and play on them. Needs the network.lan permission and a declared cast protocol
plugin.tasks Maintenance tasks the plugin lists in its manifest, run on a schedule or on demand (see Tasks below)
plugin.checks Buttons on the settings page that test the settings, such as an API key (see Checks below)

Name recognition, subtitle search and download and community segments are paid capabilities (danmaku is free): the server does not use them without the matching plan, whoever provides them. The plugin itself still installs and runs.

Conventions#

  • Requests carry a language (BCP 47) and fallback languages. Return text in the requested language when you can.
  • Provider ID keys are lowercase (tmdb, imdb, tvdb). Dates are YYYY-MM-DD.
  • Image addresses should be HTTPS; plain HTTP is accepted. The server downloads and caches the images; a plugin writes no image files. Images on a private network address (for example a NAS) need the host listed in the manifest's image fetch rules and the network.lan permission, which the administrator must turn on for the plugin.
  • A plugin can tell the user what happened at each source (sign-in needed, blocked, timed out) with notices, and can mark a slow result as incomplete so the server asks again later. A plugin that combines several sources can name the source of each field and image. The SDK has this field, but the current server version ignores it and shows nothing.
  • Item stills (scene images) have their own image type. A person's gallery photos have another.
  • Searching with no results returns an empty list, not an error.

Errors#

Return a standard gRPC code, and the server reacts to it:

Code Use it for What the server does
NOT_FOUND The item does not exist Treats it as no result
INVALID_ARGUMENT A bad request Reports it
FAILED_PRECONDITION The plugin needs configuration Takes it out of use until Configure passes
RESOURCE_EXHAUSTED The service rate-limits you; add a retry-after-seconds trailer Pauses calls to the plugin (default 60 seconds, at most one hour)
UNAUTHENTICATED The member's credential is no longer valid Asks the member to link again
UNAVAILABLE, deadline errors Temporary trouble Retries later

Tasks#

A plugin that declares plugin.tasks lists maintenance tasks in its manifest, for example refreshing a downloaded index or clearing a cache. Each has a name (never renamed after release), a title, a description and an optional default schedule: every 5 to 44640 minutes, or a five-field cron expression in the server's time zone. They show in the task center and under Scheduled tasks on the plugin's page, where administrators can change the schedule, pause it or press Run now. A task runs only when its schedule is due or an administrator starts it, never because the plugin was enabled, configured or restarted. A run may last up to 30 minutes, and the same task never runs twice at once. Tasks are free on every plan. Do not use a task for work the server already schedules for a capability, such as scraping.

Checks#

A plugin that declares plugin.checks lists up to 16 checks, such as "test the API key" or "show the remaining quota". Each is a button on the plugin's settings page. A check runs only when an administrator presses it, with the settings as currently filled in, even if they are not saved. It returns lines marked OK, warning or failed. The server only shows them: it stores nothing and a result never decides whether settings can be saved. A check has a 30-second limit, only one check of a plugin runs at a time, and the same check cannot run again within 10 seconds. A check must not download data in bulk, write files or start other work. In a group of similar entries a check can belong to one entry, shown inside it as "Test this source", and the server can also run it for every entry in turn.

Settings fields#

A manifest lists the fields of the settings form. Each has a key (lowercase letters, digits and underscores, never renamed after release), a label, an optional description, a link with a label (HTTPS, for example where to get an API key), and a type:

Type Stored as
string The text as typed
secret Stored encrypted by the server. The console only shows whether it is set and never shows the value; give it no default
bool "true" or "false"
int A decimal number, with optional min and max
select The value of one option
multiselect A JSON array of option values, for example ["en","ja"]
text A multi-line text box, at most 64 KiB
string_list A JSON array of strings; the user adds, removes and reorders entries
ordered_multiselect A JSON array of the chosen option values, highest priority first

Fields can be grouped. A group can be collapsed by default as advanced, carry an icon, or be a list of similar entries (for example one per data source) with the same settings, which the console shows as a searchable list. A field can be shown only while another field has certain values. The limits are 1000 fields, 50 groups, 200 options per field and 100 entries per group. A required field without a value shows the plugin as needing configuration. Configure receives the complete saved settings; answer with an error and per-field errors to reject them, and keep the previous settings when you do. Translations are optional: an English-only plugin is complete, and other languages fall back to English.

Permissions#

A manifest can declare llm (use the AI assistance the administrator has set up; the administrator must allow it for your plugin, and it is off by default) and network.lan (reach devices on the local network, and load images from private network hosts). For network.lan the administrator turns on Local network access on the plugin's page, and the server tells the plugin whether it is on at startup and restarts it when the setting changes. The server ignores unknown permissions. Permissions are disclosure, not a sandbox.

Host features#

The server tells a plugin at startup which compatible additions it keeps (for example tasks, checks and image crop), so a plugin can fall back on an older server. The full list is in PROTOCOL.md.