Build for RELAY.

01 Quick start

Install the public package in a Node.js project. No RELAY account or API key is needed for this example.

npm install https://docs.streamparallax.com/sdk/streamparallax-relay-addon-sdk-0.1.1.tgz

Save this as addon.cjs, then run node addon.cjs.

const http = require('node:http');
const { createAddon, createNodeHandler } =
  require('@streamparallax/relay-addon-sdk');

const item = {
  id: 'myrelay:demo', type: 'movie', name: 'My first title'
};
const addon = createAddon({
  id: 'com.example.myrelay', name: 'My RELAY Catalogue',
  version: '1.0.0', description: 'My first catalogue.',
  resources: ['catalog', 'meta'], types: ['movie'],
  catalogs: [{ type: 'movie', id: 'picks', name: 'My picks' }],
  relay: { categories: ['catalogue'], permissions: [] }
});
addon.defineCatalogHandler(async () => ({ metas: [item] }));
addon.defineMetaHandler(async ({ id }) => ({
  meta: id === item.id ? item : null
}));
http.createServer(createNodeHandler(addon)).listen(7000);

Open http://localhost:7000/manifest.json. This example exposes a catalogue and metadata; it does not provide a video stream.

02 Protocol & handlers

Handlers receive { type, id, extra } and return JSON. Register only the resources your addon provides.

Routes follow /{resource}/{type}/{id}.json. Optional extras are query-string encoded in a path segment, for example /catalog/movie/picks/search=A%26B&skip=20.json. CORS is enabled for all origins; GET, HEAD and OPTIONS are supported.

See the Stremio protocol specification for resource object formats.

03 Official RELAY addons

In RELAY, open Addons → Official Addons. To install by URL, use Add addon and paste the relevant manifest link. If it already shows Installed, no reinstall is needed.

The package includes server-side implementations in official/. Self-hosting requires your own TMDB_API_READ_TOKEN or TMDB_API_KEY, and OPENSUBTITLES_API_KEY or SUBDL_API_KEY. Keep credentials on your server, never in a manifest, browser bundle or repository. Provider quotas and terms still apply.

04 Test & publish

1. Save your manifest and run npx relay-addon validate manifest.json.
2. Test each advertised route and its empty/error responses. Manifest validation is not a complete compatibility test.
3. Host your addon on a public HTTPS endpoint. Install its manifest URL in RELAY and test catalogue, episode, stream or subtitle behaviour as applicable.
4. Test separately in Stremio if you advertise Stremio compatibility.

Distribute your manifest URL directly. This SDK release does not automatically submit addons to a community directory. Official status is assigned by RELAY, not by a manifest label.

The SDK is MIT licensed. Third-party data and artwork retain their own terms. Package checksum

05 Source availability

RELAY Windows checks locally for torrent metadata, a video file and connected peers. A complete local video can also qualify. Availability checking is separate from the buffering required to start playback.

Playable means the source passed those checks at that moment—not that the entire file was downloaded or every codec was decoded. Not confirmed means discovery timed out or could not finish; it does not prove the source is dead. Temporary probe sessions are removed after checking.

06 Open protocol. Clear boundaries.

RELAY's SDK uses the Stremio HTTP JSON addon protocol. It does not implement legacy or IPFS transports, provide DRM access, or guarantee every third-party authentication and playback workflow.

The optional relay manifest metadata describes categories, permissions and developer links. Permission declarations are descriptive; they are not an execution sandbox. Only expose content and services you are authorised to distribute.