Sandbox plug-in tutorial

Workshop sandbox plug-ins are not the same runtime as local plug-ins. Index → Workshop SDK.

sources:provide / sources:direct expose author-owned HTTP(S) direct links only — not Netease, Spotify, or similar platforms. Legal boundary → Download and plug-in source policy.

Plug-in project layout

my-plugin/
├── content/
│   ├── echo.workshop.json
│   └── community.echo          # generated by check/sync — do not hand-edit
├── src/
│   └── plugin.js               # main entry
└── .echo-sdk/echo-workshop-plugin.d.ts

Walkthrough A: hello plug-in

1. node .\bin\echo-workshop-sdk.mjs example hello-plugin .\my-hello then cd .\my-hello
2. Read src/plugin.js — one command, playback:read only.
3. To call echo.library.*, first npm run add -- --permission library:read
4. After every edit: npm run check (syncs into community.echo)
5. npm run dev — undeclared echo.* calls fail with capability-denied

Users enable via Workshop Use, then open Plugins at the bottom right → Steam Workshop.

Walkthrough B: source catalog

1. init .\my-catalog --recipe source-catalog
2. npm run add -- --permission network:request if calling the network
3. Declare networkHosts (bare domain, no protocol/port) in the outer manifest
4. Implement search / browse / listCollection / resolve — resolve returns one playable http(s) URL
5. npm run check — mock rejects undeclared hosts and custom ports

Presets

Preset / recipe	Includes
basic / hello	One command
complete / plugin-complete	Commands, panel, agent, providers
catalog / source-catalog	Direct-link catalog + panel
lyrics / lyrics-source	Lyrics provider + panel

Look up permissions:

node .\bin\echo-workshop-sdk.mjs api echo.queue.moveItem
node .\bin\echo-workshop-sdk.mjs api errors

Package limits

32 files max, 512 KiB per UTF-8 file, 2 MiB serialized. Inner apiVersion must match outer compatibility.pluginApiVersion (2 for new items).

Do not port local plug-in folders directly — re-init with the SDK.

Advanced: metadata, lyrics, listen-together

See examples and snippets.

• Metadata / cover — examples/metadata-provider/; user selects candidates only.
• Lyrics provider — lyrics-source recipe + lyrics-provider snippet.
• Listen-together — playback:share + declared upload host; see examples/listen-together/.

Before publish