Build a plugin

Quickstart

A plugin is a folder with a manifest and a script. That's the whole toolchain.

my-plugin/
├── manifest.json    metadata + what the plugin contributes
└── index.js         the code, plain JavaScript

The manifest declares who you are and what the plugin adds to the app. This one contributes an information section to artist detail pages:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Fun facts about the artist you're playing",
  "minAppVersion": "0.9.5",
  "contributes": {
    "informationTypes": [
      {
        "id": "artist_facts",
        "name": "Facts",
        "entity": "artist",
        "displayKind": "rich_text",
        "ttl": 604800
      }
    ]
  }
}

The script receives the api object, registers handlers in activate, and returns its exports:

function activate(api) {
  api.informationTypes.onFetch("artist_facts", function (entity) {
    var url = "https://api.example.com/facts?artist="
      + encodeURIComponent(entity.name);
    return api.network.fetch(url).then(function (resp) {
      if (resp.status !== 200) {
        return { status: "error", message: "HTTP " + resp.status };
      }
      return resp.json().then(function (data) {
        if (!data.summary) return { status: "not_found" };
        return { status: "ok", value: { summary: data.summary } };
      });
    });
  });
}

function deactivate() {}

return { activate: activate, deactivate: deactivate };

Fetch handlers resolve to { status: "ok", value }, { status: "not_found" }, or { status: "error", message? } — the app takes care of caching (per-type ttl, in seconds), retries, and rendering. That's a complete, publishable plugin.

What a plugin can add

Everything a plugin contributes is declared under contributes in the manifest, then wired up with a matching api handler in activate.

Shelves, context-menu items, and now-playing info items can also be registered at runtime (api.home.registerShelf, api.contextMenu.registerItem, api.nowPlayingInfo.registerItem) when the set depends on user state.

The sandbox

Plugins run inside the app with a deliberately small surface — everything flows through api.

• No DOM, no direct network. There is no window, document, or fetch. You get console, timers, and the standard built-ins (JSON, Math, Promise, …); HTTP goes through api.network.fetch, files through api.storage.
• Scoped storage. Key-value data and files are namespaced to your plugin — you can't read another plugin's data or arbitrary paths.
• Allow-listed subprocesses. api.system.exec only runs binaries the host registers (currently yt-dlp and ffmpeg).
• Declared API usage. The optional apiUsage manifest field ([{ "api": "network.fetch", "reason": "…" }]) tells users what your plugin touches and why — shown in the Extensions view.
• Version gates. minAppVersion blocks install and update on older apps. Bumping your plugin's version clears its cached information values, forcing a clean re-fetch.
• Maturity flags. "stability": "experimental" badges the plugin and keeps it out of onboarding recommendations; debugOnly: true hides it outside debug mode.