Stremio Addon SDK

Build a Stremio addon in Node.js in minutes.

📚 Documentation · Addon guide · Protocol spec · Report a bug

Stremio is a modern media center that discovers, organizes and streams video content through addons. An addon is a small HTTP service that answers a handful of JSON requests: which catalogs it offers, what an item is, and where to stream it from. This SDK gives you the builder, the HTTP server and the publishing tools so you only write the handlers. Stremio runs on Windows, macOS, Linux, Android and iOS, and one addon serves all of them.

✨ Features

• 🧱 Builder API — declare a manifest, define handlers for catalogs, metadata, streams and subtitles, done
• 🌐 Serve or embed — start a server with serveHTTP, or mount the addon as an Express router with getRouter
• 🔒 CORS and caching handled — the SDK sets the headers Stremio expects; you set the cache lifetimes
• 🏠 Landing page — every addon gets a homepage with an “Install” button out of the box
• 📣 Publishing — publishToCentral submits your addon to the public addon collection
• 🧬 TypeScript types — bundled since 1.6.10, no @types/stremio-addon-sdk needed
• 📺 Live TV guides — catalogs with a programme schedule render as a native EPG, see Native EPG
• ⚙️ User settings — addons can ask for configuration through manifest.config, see user data

🚀 Getting started

You'll need Node.js 12 or newer.

Scaffold an addon

npm install -g stremio-addon-sdk # use sudo on Linux
addon-bootstrap hello-world
cd hello-world
npm install
npm start -- --launch

addon-bootstrap asks which resources and types you want to support and generates a working addon. --launch opens Stremio Web with the addon installed; use --install to install it into the desktop app instead.

Or write one by hand

This addon serves a single stream for Big Buck Bunny:

const { addonBuilder, serveHTTP, publishToCentral } = require('stremio-addon-sdk')

const builder = new addonBuilder({
    id: 'org.myexampleaddon',
    version: '1.0.0',
    name: 'simple example',
    // Properties that determine when Stremio picks this addon:
    // streams for items of type movie whose id starts with "tt"
    catalogs: [],
    resources: ['stream'],
    types: ['movie'],
    idPrefixes: ['tt']
})

builder.defineStreamHandler(function(args) {
    if (args.type === 'movie' && args.id === 'tt1254207') {
        const stream = { url: 'http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4' }
        return Promise.resolve({ streams: [stream] })
    }
    return Promise.resolve({ streams: [] })
})

serveHTTP(builder.getInterface(), { port: process.env.PORT || 7000 })
// publishToCentral('https://your-domain/manifest.json') // once the addon is publicly reachable

npm install stremio-addon-sdk
node ./addon.js

The process prints a URL you can use to install the addon in Stremio. Addon URLs must be served over HTTPS with CORS enabled, except for 127.0.0.1; the SDK handles CORS, HTTPS is up to your host.

🛠 How it works

Stremio never runs your code. The app reads your manifest, decides which addons are relevant for a request from their types, idPrefixes and catalog extra filters, and calls the matching resources over HTTP. The SDK turns those calls into handler invocations and turns your return values into protocol-conformant JSON.

flowchart LR
    App["Stremio app<br>(web, desktop, mobile)"] -- "GET /manifest.json" --> SDK["Your addon<br>(this SDK)"]
    App -- "GET /catalog/…<br>GET /meta/…<br>GET /stream/…<br>GET /subtitles/…" --> SDK
    SDK -- "handlers" --> Src["Your data sources"]
    App -- "publishToCentral" --> Central["Public addon collection"]

Loading

Resource	Handler	Answers
manifest	the addonBuilder constructor	What the addon is and when to call it, see manifest
catalog	defineCatalogHandler	Lists of meta previews for the Board, Discover and Search
meta	defineMetaHandler	The full meta object for the details page
stream	defineStreamHandler	Streams: HTTP, BitTorrent, YouTube and more
subtitles	defineSubtitlesHandler	Subtitle files for a video
addon_catalog	defineResourceHandler	A list of other addons

📚 Documentation

Guide	What you'll find
SDK reference	Every export: addonBuilder, serveHTTP, getRouter, publishToCentral and the addonInterface
Resources	How catalogs, metas, videos, streams and subtitles relate, and how Stremio picks an addon
Advanced usage	Searching and filtering catalogs, pagination, Cinemeta, user data and configuration pages
Native EPG	Live TV channels with a programme guide, with a runnable example in examples/epg-livetv.js
Deep links	Linking into Stremio with the stremio:// protocol
Testing	Trying your addon in the Stremio app and in Stremio Web
Deploying	Hosting options, with BeamUp as the recommended one
Examples	Demo addons, examples in other languages and video tutorials
Protocol spec	The HTTP protocol itself, for addons written without this SDK

The addon guide walks through building an addon step by step, both with this SDK and in any other language. addon-helloworld is a complete addon to copy from, and the static addon example shows that an addon can be nothing more than JSON files on a web server.

🚢 Deploying

An addon has to be reachable on the internet before other people can install it. Deploy it to BeamUp, which we run for this purpose, or to any Node.js host; for a quick demo from your own machine, localtunnel works too.

To get listed in Stremio's community addons, call publishToCentral with your public manifest URL or submit it through the web form.

🧪 Development

For contributors to the SDK itself:

Command	Description
npm test	Lint the sources, then run the tape suite in test/
npm run typecheck	Check the bundled TypeScript declarations
node examples/epg-livetv.js	Run the live TV example addon

🤝 Contributing

Bug reports and pull requests are welcome — good first issue is a good place to start. Documentation lives in docs/ next to the code, so protocol changes and their docs can land together.

Migrating from v0.x

• new addonSDK(manifest) became new addonBuilder(manifest)
• addon.run(opts) became serveHTTP(addon.getInterface(), opts)
• Handlers return a Promise instead of taking a callback

🧩 Ecosystem

Repository	What it is
stremio-web	The web UI that installs and calls your addon
stremio-core	The Rust engine that implements the addon protocol client side
addon-helloworld	Reference addon built with this SDK
stremio-static-addon-example	An addon made of static JSON files
stremio-addon-sdk-rs	Third-party Rust SDK by Sleeyax, built on stremio-core
go-stremio	Third-party Go SDK by doingodswork

💬 Community

Website · Blog · Reddit · X · Help center

📄 License

Copyright © 2019-2026 Smart Code OOD. Released under the MIT license — see LICENSE.