Add-on Docs

$ npm install stremio-addon-sdk

Introduction

Add-ons are written in NodeJS with the help of the stremio-addon-sdk module.

All of the video content Stremio provides, it gets exclusively through the Add-on System, with no content or specific provider being built into the app.

Stremio communicates to the Add-ons by requesting different types of information, such as: a main feed of items, search results for user queries, item details (descriptions, background, logo, seasons / episodes), streaming sources and subtitles.

Add-ons are being hosted separately (on a server). As such, they have increased security and support their own node modules.

As an Add-on Developer, you will need to host the Add-on yourself. But don't worry, we will go through the hosting options (including the free options) in this guide.

This is a basic documentation page aimed at new Add-on Developers. For a more complete explanation of everything related to Stremio Add-ons, please visit stremio-addon-sdk/README.md

Anatomy of an Add-on

const addonSDK = require('stremio-addon-sdk')
 
const addon = new addonSDK({
    id: 'org.myexampleaddon',
    version: '1.0.0',
 
    name: 'simple example',
 
    // Properties that determine when Stremio picks this add-on
    // this means your add-on will be used for streams of the type movie
    resources: [{
        "name": "stream",
        "types": [
            "movie"
        ],
        "idPrefixes": [
            "tt"
        ]
    }],
    types: ['movie'],
})
 
// takes function(args, cb)
addon.defineStreamHandler(function(args, cb) {
    if (args.type === 'movie' && args.id === 'tt1254207') {
        // serve one stream to big buck bunny
        const stream = { url: 'http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4' }
        cb(null, { streams: [stream] })
    } else {
        // otherwise return no streams
        cb(null, { streams: [] })
    }
})
 
addon.runHTTPWithOptions({ port: 7000 })
 
// If you want this add-on to appear in the addon catalogs, call .publishToCentral() with the publicly available URL to your manifest
addon.publishToCentral('https://my-addon.com/manifest.json')

Manifest

The first thing to define for your Add-on is the manifest, which is a JSON Object that describes it's name, purpose and some technical details.

Valid properties are:

id
- required - identifier, dot-separated, e.g. "com.stremio.vodo"

name
- required - human readable name

description
- required - human readable description

resources
- required - supported resources - for example
['catalog', 'meta', 'stream', 'subtitle']
, resources can also be added as objects instead of strings, for added details on how they should be requested, example:
{ "name": "stream", "type": "movie", "idPrefixes": [ "tt" ] }

catalogs
- optional - a list of the content catalogs your add-on provides, an array of objects in the catalog format (see below), although this is marked as "optional" it is required in all cases that serve playable streams, the only case in which this is not required is when making add-ons that serve only subtitles and no streamsRead more

types
- required - array of supported types, from all the Content Types

endpoint
- optional - HTTP(s) endpoint to the hosted version of this add-on; should point to
manifest.json
example:
https://cinemeta.strem.io/v3/manifest.json

background
- optional - background image for the add-on; URL to png/jpg, at least 1024x786 resolution

logo
- optional - logo icon, URL to png, monochrome, 256x256

contactEmail
- required - set this to true if you want to specify that all of the content in this add-on is free of charge; this is used when auto-generating a landing page for that add-on

WARNING - unlike the other platforms, getting the add-on listed on
ios
may require moderator approval

Methods

Catalog

The catalog is being handled by the
defineCatalogHandler
method. This is used for loading the meta feed and search the catalogue in Discover (Stremio).

addon.defineCatalogHandler(function(args, cb) {
    if (args.type === 'movie' && args.id === 'top') {
 
        // we will only respond with Big Buck Bunny
        // to both feed and search requests
 
        const meta = {
            id: 'imdb_id:tt1254207',
            name: 'Big Buck Bunny',
            year: 2008,
            poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
            posterShape: 'regular',
            banner: 'https://image.tmdb.org/t/p/original/aHLST0g8sOE1ixCxRDgM35SKwwp.jpg',
            isFree: true,
            type: 'movie'
        }
 
        if (args.extra && args.extra.search) {
 
            // catalog search request
 
            if (args.extra.search == 'big buck bunny') {
                cb(null, { metas: [meta] })
            } else {
                cb(null, { metas: [] })
            }
 
        } else {
 
            // catalog feed request
 
            cb(null, { metas: [meta] })
 
        }
 
    } else {
        // otherwise return empty catalog
        cb(null, { metas: [] })
    }
})
For request and response examples, visit this page.

Metadata

Serving metadata is being handled by the
defineMetaHandler
method.

addon.defineMetaHandler(function(args, cb) {
    if (args.type === 'movie' && args.id === 'tt1254207') {
        // serve metadata for Big Buck Bunny
        const metaObj = {
            id: 'imdb_id:tt1254207',
            name: 'Big Buck Bunny',
            year: 2008,
            poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
            posterShape: 'regular',
            banner: 'https://image.tmdb.org/t/p/original/aHLST0g8sOE1ixCxRDgM35SKwwp.jpg',
            isFree: true,
            type: 'movie'
        }
        cb(null, { meta: metaObj })
    } else {
        // otherwise return no meta
        cb(null, { meta: {} })
    }
})
For request and response examples, visit this page.

Stream Find

Stream links are being handled by the
defineStreamHandler
method.
First thing to keep in mind here is that Stremio supports video streaming through HTTP, BitTorrent and IPFS.

addon.defineStreamHandler(function(args, cb) {
    if (args.type === 'movie' && args.id === 'tt1254207') {
        // serve one stream to big buck bunny
        // return addonSDK.Stream({ url: '...' })
        const stream = { url: 'http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4' }
        cb(null, { streams: [stream] })
    } else {
        // otherwise return no streams
        cb(null, { streams: [] })
    }
})
For request and response examples, visit this page.

Subtitles Find

Subtitles are provided in a which represents all possible subtitle tracks (in any number of languages) for a video stream.
There are two ways to provide a :
- In the
subtitles
property of a . Recommended if you have an add-on that would provide both video streams and subtitles.
- As a response from the
defineSubtitlesHandler
method. Recommended if you are making a standalone add-on for subtitles.

addon.defineSubtitlesHandler(function(args, cb) {
    if (args.extra && args.extra.itemHash === 'tt1254207') {
        // serve one stream to big buck bunny
        // return addonSDK.Stream({ url: '...' })
        const subtitle = {
            id: 'sub1',
            url: 'https://mkvtoolnix.download/samples/vsshort-en.srt',
            lang: 'en'
        }
        cb(null, { subtitles: [subtitle] })
    } else {
        // otherwise return no streams
        cb(null, { subtitles: [] })
    }
})
For request and response examples, visit this page.

Testing

For developers looking for a quick way to test their new add-ons, you can either:


Hosting

Stremio add-ons require hosting in order to be published. You need a NodeJS hosting solution, as stremio add-ons are NodeJS apps.

We recommend:

We hugely recomment using
Now.sh
, as it is extremely easy to use.
You can also check this very comprehensive guide by nodejs.

Stremio add-ons are deployed just like regular nodejs apps, so follow the nodejs instructions provided by your particular service provider.
If you've built a great add-on, and need help with hosting your add-on, you are welcome to contact us at [email protected]

Monetization

We are in the process of adding monetization options to Stremio Add-ons. More information will be available soon.


This has been a guide aimed at new Add-on Developers. For a more detailed guide of everything related to Stremio Add-ons, please visit stremio-addon-sdk/README.md