Plugins

UI extensions

Every ui.contributions and ui.configPages field, the closed predicate and actionId vocabularies, and how each slot actually renders in the client.

The rule#

A plugin ships no Angular. It declares data in its manifest's ui.* block; core renders it with its own, existing components. If a settings page needs something none of the three page kinds below can express, it isn't a plugin page, the answer is a core change adding a new kind, not a plugin shipping code. This is deliberately restrictive: it's what lets every plugin's admin surface look and behave consistently, and what lets core keep rendering an old plugin's declared UI correctly across a client release.

ui.contributions[]#

One entry per nav item, menu row, or settings-sidebar link.

Field Type Required Notes
id string yes Unique within your manifest.
slot one of seven, below yes
weight number yes Sort order within the slot, ascending, then by id.
labelKey string yes An i18n key from your own i18n block.
shortLabelKey string no A shorter label for compact surfaces (the phone dock); falls back to labelKey.
icon string no Name from a closed icon set the surface understands; an unrecognised name renders a plain circle rather than nothing.
tone 'default' | 'danger' no
badge string no A counter key read from the counts endpoint; the badge only shows when its value is > 0.
confirmKey string no Accepted, but no slot's renderer reads it today, so a contribution never asks for confirmation. Confirmation dialogs come from the separate confirmKey on a table or providers page action (below).
when array of predicates no See below.
action {kind:'route', path} | {kind:'action', actionId} | {kind:'submenu'} yes A submenu only opens its children; an older client that doesn't know this kind drops the row rather than showing a parent that does nothing.
children UiContribution[] no Only meaningful under action.kind: 'submenu'.

The seven slots#

Slot Where it renders Core has entries here too?
nav.main The main sidebar/nav bar (desktop), the TV tab row, or the phone "more" sheet, depending on client. Yes, home/search/profile/live TV/playlists/downloads/history.
nav.acquisition The requests area's own nav. Yes, requests and calendar.
settings.page The admin settings sidebar. Each plugin gets its own section named after it, it never joins a core section. Yes, 8 core sections; plugin sections come after them, ordered by plugin id.
media.actions The whole work. The card context menu and the detail page's ⋯ menu, both built from one merged list. Yes, core's own actions.
card.actions Same merged list as media.actions. Same list.
media.group.actions Extra buttons in the action row of a group: a season, a volume or a disc. No, this slot is plugin-only.
media.item.actions Extra buttons in the action row of an item: an episode, an issue or a track. No, this slot is plugin-only.

A route contribution opening one of your own views must be exactly /plugins/<your-id>/<pageId> or /admin/settings/plugins/<your-id>/<pageId>, where <pageId> is a page you declare in ui.configPages; anything else fails registration (invalid-ui-contribution). Declaring a page does not link to it: only a settings.page contribution actually puts it in the sidebar.

The when predicate vocabulary#

Evaluated with .every(), entirely client-side, from state the client already has, nothing is re-fetched to answer a when. A leading ! negates. An unrecognised predicate always evaluates false, negated or not, so a client that doesn't understand a rule hides the row instead of guessing.

Predicate True when
isAdmin The signed-in user is an admin.
hasPermission:<policy> The signed-in user's ability grants that policy.
mediaType:movie / mediaType:series The surface has a media item of that kind in context.
hasFiles The item has at least one file on disk.
isMonitored The item is monitored.
hasQualityProfile The target has at least one want with a quality profile, whatever its kind.
level:work / level:group / level:item The level the menu is built for: the whole work, a group (season, volume, disc) or an item (episode, issue, track).
isEpisode Core's own gate on its title-level rows: true on a series item. A manifest should use level:* instead.
identified The item has at least one metadata-provider id (defaults true when the surface doesn't supply this fact).
isTv Running on a TV form factor.
isTouch Running on a touch device.
liveTv The signed-in user has at least one Live TV channel available.
server:<version> The connected server is at least that release, for example server:5.1.0. A row that needs a newer server hides itself against an older one.
surface:card / surface:detail Which menu is being built; a "Play" row makes no sense on the page you're already on.

None of this is a trust boundary: whatever a when hides, the route behind it is still checked server-side with the same CASL policy as ever. A plugin row that reuses a core actionId inherits that core action's own guards too, a plugin can narrow a core action, never widen it.

actionId, per slot: also a closed vocabulary#

An action.kind: 'action' row names an id core implements; an id core doesn't recognise, or that the current surface has no handler for, makes the row disappear rather than render inert.

Slot Closed set
media.actions / card.actions media.recommend, media.toggle-series-watched, media.open-tracking, media.request, media.grab-best, media.search-releases, media.edit-profiles, media.edit-library, media.edit-subtitles, media.refresh-metadata, media.analyze, media.toggle-monitored, media.delete, media.toggle-like, media.download, media.download-series, media.auto-download-0, -3, -5 and -10, media.play, media.open, media.add-to-playlist, media.watch-together, media.toggle-watched, media.remove, media.identify, media.request-deletion. Each surface serves only a subset; "Play" and "Open", for instance, exist only on the card.
media.group.actions group.search-releases, group.grab-best. Plugin-only, core declares no entries here.
media.item.actions item.search-releases, item.grab-best. Plugin-only, core declares no entries here.
nav.main nav.my-profile only, and only for core's own row.
A form page's actions[] events.test-delivery only, today.
A table page's row actionId table.open-media only: needs the row's mediaId and mediaType columns (and optionally episodeId); missing either means no button renders at all.

ui.configPages[]#

One entry per settings page, discriminated on kind. Missing kind means form.

Field (every kind) Type Notes
id string Matched by a settings.page contribution's route.
labelKey string Page title, and the admin sidebar link text.
icon string Same closed icon set as contributions.
subtitleKey string, optional One explanatory line under the title.

form (the default, and the only kind that works with the process stopped)#

Rendered by a generic schema-form component. fields is an ordered array of items:

Item kind Fields Renders as
(absent) or 'field' key, type, labelKey, hint?, placeholder?, required?, secret?, default?, options? (required for multiselect), topLevel?, min?/max?/minLength?/maxLength? One input, by type: text/email/password/url/number as a text-style input, toggle as a switch, select as a dropdown from options, multiselect as a multi-value picker.
'caption' textKey A line of static text, no input, no stored value.
'group' labelKey, fields (plain fields only, one level deep) A labelled, bordered section. Nesting a group inside a group is refused at install, not merely ignored.
'status' labelKey, settingKey A read-only line showing whatever the plugin last wrote to plugin.<id>.<settingKey> via config.set. No route behind it, so it still renders with the process stopped, it is not a live check.

min/max (numbers) and minLength/maxLength (everything else) are the only validation a field may declare, enforced by the renderer before it saves. There's deliberately no author-supplied regular expression: a pattern from an untrusted manifest, or from a providers page's fields arriving over HTTP at render time, has no syntactic check that separates a safe expression from one that hangs the tab. A blank required field is shown as a hint but never blocks saving, clearing a value is how an operator unsets it.

Secrets. secret: true on a field means: stripped from every read response, and only written back when the incoming value is non-empty. A resource that honours this lists which of its secret keys currently hold a value under the response key secretsSet (SECRETS_SET_KEY in the contract); the editor then shows those masked, with an option to erase (write null) rather than ask the operator to retype a credential it never received. A blank field on save means "leave it alone", not "clear it", clearing needs the explicit erase.

actions[] on a form page ({ id, labelKey, actionId }) renders outline buttons beside Save, restricted to the closed actionId set above, today just events.test-delivery.

providers#

A CRUD list of instances (indexers, download clients, notification targets) over the plugin's own routes. Needs the process running.

Field Notes
list, implementations Routes: the current rows, and the driver list ({implementation, labelKey, fields} per driver).
testConnection.route Tests the unsaved draft: POST {implementation, settings, id?} before anything is saved.
showPriority, defaultPriority, reorderable A priority column and drag-to-reorder, when the resource has a meaningful priority concept.
bulkSelect Adds a selection column plus bulk enable/disable/delete and one bulk field edit.
labels Overrides generic wording ("New provider") with domain terms ("New indexer").
actions[] { id, labelKey, method: GET|POST|DELETE, route, scope: 'row'|'list', confirmKey?, slot?, result?, successKey?, afterSave? }. A GET row action needs a declared result: { kind: 'table', columns, emptyKey } or it renders no button at all, core has no domain view to fall back on. slot: 'cooldown-reset' is the one recognised placement, next to a row's own reported cooldown rather than as its own button. successKey is toasted after a successful mutation, interpolated with the fields of what it answered. afterSave also runs a scope: 'row' action, unconfirmed, on the row the editor just saved when that row is enabled.

table#

A read-only list over one route, with declared columns and row/list actions. Needs the process running.

Field Notes
list The route. With paged: true it answers {data, total, page, pageSize} instead of a bare array; pageSize sets how many rows a page asks for.
columns[] key, labelKey, format? (date/bytes/percent/speed, or peers: key as seeders and leechersKey as leechers, shown as a green ▲ and an orange ▼ pair, empty when key is not a number), labelKeys? (enum-to-label map), badges? (value-to-tone map, * covers everything else; the tones are neutral, primary, secondary, accent, info, success, warning, error and ghost, and an unknown name falls back to ghost), nowrap?, truncate?, subValues? (a second line under the cell, each with its own format, labelKeys and badges), detailField?+detailTitleKey? (turns the cell into a button opening a dialog), linkActionId? (the closed table.open-media id), progressField? (a 0-100 field that fills a badge left to right).
filters[] {kind:'search', key, placeholderKey} (debounced) or {kind:'select', key, labelKey, options} (reloads immediately). Sent as query params; an empty value is omitted.
bulkSelect Turns declared proxy row actions into batch actions with one confirmation for the whole selection.
refreshMs / refreshOn Poll on an interval (floored at 2000 ms, paused while the tab is hidden), or re-fetch when one of the named SSE event types arrives. Prefer refreshOn; refreshMs is for a value no event announces.
rowActions[] Six kinds: route, action (the closed id set), detail (a read-only dialog of declared fields, with an optional titleKey, built from the row's own already-loaded fields, no extra route; a link field is anchored only when it is http: or https:), proxy (POST/DELETE, with :id filled from the row, an optional confirmKey, an optional confirmToggle checkbox ({ labelKey, param, hintKey? }) sent as a query param, and tone: 'danger' styling), releases (opens core's release picker on the row: search lists the releases and grab receives the picked one's body, both with :id filled from the row, under the titleKey heading) and submenu (a labelKey and children, any of the other kinds, opened beside the menu or in place of it on touch and TV; it is hidden when no child is left for the row). when gates on the viewer; visibleWhen: {key, in} gates on the row itself, pausing a paused download is not an action, it's a button that fails.
listActions[] Same proxy shape, rendered once above the rows rather than per-row; when gates it on the viewer.
defaultSortKey Applied once; there's no click-to-resort.

ui.releasePicker#

json
"releasePicker": {
  "movie":  { "work":  { "search": "/:id/releases", "grab": "/:id/grab" } },
  "series": {
    "group": { "search": "/:id/groups/:groupId/releases", "grab": "/:id/groups/:groupId/grab" },
    "item":  { "search": "/:id/items/:itemId/releases",    "grab": "/:id/items/:itemId/grab" }
  }
}

The keys are kinds of work (open lowercase words: movie, series, book, comic, album, and so on), then levels: work (the whole title), group (a season, a volume, a disc) and item (an episode, an issue, a track). Each level is a {search, grab} pair, and a kind declares at least one level. A kind the server doesn't serve is accepted and ignored. Core fills :id (the media id), :groupId and :itemId in the routes. search is a GET taking the query parameters family and language (the want aimed at; language is absent for an any-language want), q and sid; grab is a POST whose JSON body carries family, language and, for a manual pick, downloadUrl, sourceTitle, sourceId, force and infoUrl (none for a grab-best).

Every route named here must also appear in this manifest's own routes[], search as GET, grab as POST, so it carries a policy like any other. If more than one installed plugin declares releasePicker, the lexicographically smallest plugin id wins; the rest are logged and ignored. Only the winner's declaration is served from GET /plugins/ui.

ui.player#

json
"player": { "preRollRoute": "/pre-roll" }

One route, which must be a declared POST entry in this manifest's own routes[]. Before a playback-info response goes out, core POSTs { mediaFileId, mediaId, episodeId } to the winning plugin's route (same lexicographic tie-break as the release picker) and expects a JSON array of { mediaFileId, labelKey?, skippable? }, an id, never a URL or a path. The array is capped at 5 items; anything past the cap, a non-positive-integer id, a repeat, or the item about to play anyway is dropped. Every id core gets back is still resolved and ACL-checked through the exact path the main item uses, a plugin can only name a candidate, never grant access to one. If nothing answers in time, or answers anything other than exactly this shape, playback-info simply omits preRoll, the feature is invisible on failure, never a broken call. The Apple TV and Cast players don't model this field at all and only ever play the main item.

How each slot actually renders#

There's no generic "plugin slot" component; each slot is merged into an existing one, sorted by weight alongside core's own entries in the same slot:

Slot Rendered by
nav.main, nav.acquisition The app's nav/sidebar service, into the same list as core's own nav items. Icons come from a closed icon set; an unrecognised name shows a generic circle rather than nothing.
settings.page The admin settings sidebar, one section per plugin, named after it, after every core section.
media.actions, card.actions The card's context menu and the detail page's ⋯ menu, both built from one merged list (core items first, then this slot, then card.actions), rendered as an anchored dropdown on desktop or a bottom sheet on touch/TV.
media.group.actions, media.item.actions Extra buttons in the group or item action row; only action-kind rows with the two closed ids of their slot are kept.
form / providers / table config pages A generic schema-form component, a generic provider-list component, and a generic data-table component respectively, at /plugins/<id>/<pageId> or /admin/settings/plugins/<id>/<pageId>.

i18n#

Same rules as the manifest reference: one shared root per plugin, first plugin loaded keeps it, a conflicting second plugin fails registration with i18n-namespace-conflict rather than silently losing its strings.

Edit this page on GitHub

Esc