Stremio Addon SDK

https://github.com/stremio/stremio-addon-sdk
Admin
Stremio Addon SDK is a Node.js toolkit that simplifies the creation and deployment of addons for the...
Tokens:50,985
Snippets:288
Trust Score:8.3
License:MIT
Update:1 hour ago
Show doc for...
Tokens:
Raw
### Install dependencies and run the addon

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Commands to install the stremio-addon-sdk package and execute the addon script (addon.js). The addon will output a URL for installing it in Stremio.

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

```

--------------------------------

### serveHTTP(addonInterface, options)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Starts the addon server. Options include port, cacheMaxAge, and static file directory. Reacts to process arguments like --launch and --install.

```APIDOC
## serveHTTP(addonInterface, options)

### Description
Starts the addon server. Options include port, cacheMaxAge, and static file directory. Reacts to process arguments like --launch and --install.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
#### Request Body
- **addonInterface** (object) - Required - The addonInterface returned from `builder.getInterface()`.
- **options** (object) - Required - Configuration object with properties:
  - **port** (number) - Optional - The port to listen on.
  - **cacheMaxAge** (number) - Optional - Cache-Control max-age in seconds.
  - **static** (string) - Optional - Path to a directory of static files to be served.

### Request Example
```javascript
serveHTTP(addonInterface, { port: 3000, cacheMaxAge: 3600, static: '/public' })
```

### Response
Starts the server. No return value specified.

### Response Example
N/A
```

--------------------------------

### Run the EPG Live TV addon example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Run the complete addon example located at examples/epg-livetv.js using Node.js. This starts the addon server for the EPG (Electronic Program Guide) live TV functionality.

```bash
node examples/epg-livetv.js
```

--------------------------------

### Install and run the hand-written addon

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/README.md

Installs the SDK locally and runs the addon script. The process prints a URL for installing the addon in Stremio; the URL must be HTTPS with CORS enabled except for 127.0.0.1.

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

--------------------------------

### Example Addon Manifest JSON

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/responses/manifest.md

Example manifest for a Stremio addon that provides streams and catalogs. It defines one movie catalog and receives stream requests for meta items with IDs starting with 'tt' (IMDb IDs) for both movies and series.

```javascript
{           
    "id": "org.stremio.example",
    "version": "0.0.1",
    "description": "Example Stremio Addon",
    "name": "Example Addon",
    "resources": [
        "catalog",
        "stream"
    ],
    "types": [
        "movie",
        "series"
    ],
    "catalogs": [
        {
            "type": "movie",
            "id": "moviecatalog"
        }
    ],
    "idPrefixes": ["tt"]
}
```

--------------------------------

### require('stremio-addon-sdk')

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Imports the SDK's main functions: addonBuilder, serveHTTP, getRouter, and publishToCentral.

```APIDOC
## require('stremio-addon-sdk')

### Description
Imports the SDK's main functions: addonBuilder, serveHTTP, getRouter, and publishToCentral.

### Method
N/A (module import)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
const { addonBuilder, serveHTTP, getRouter, publishToCentral } = require('stremio-addon-sdk')
```

### Response
Returns an object with the following properties:
- **addonBuilder** (function) - Constructor for creating an addon builder.
- **serveHTTP** (function) - Starts an HTTP server for the addon.
- **getRouter** (function) - Converts an addonInterface to an Express router.
- **publishToCentral** (function) - Publishes an addon URL to the public addon catalog.

### Response Example
```javascript
{
  addonBuilder: [Function],
  serveHTTP: [Function],
  getRouter: [Function],
  publishToCentral: [Function]
}
```
```

--------------------------------

### Scaffold an addon with addon-bootstrap

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/README.md

Installs the SDK globally and scaffolds a new addon project. The --launch flag opens Stremio Web with the addon installed; use --install for the desktop app instead.

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

--------------------------------

### builder.defineSubtitlesHandler(handler)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Handles subtitle requests.

```APIDOC
## builder.defineSubtitlesHandler(handler)

### Description
Handles subtitle requests.

### Method
N/A (method on addonBuilder)

### Endpoint
N/A

### Parameters
#### Request Body
- **handler** (function) - Required - A function that takes an `args` object and returns a response.

### Request Example
```javascript
builder.defineSubtitlesHandler(function handler(args) { })
```

### Response
No direct return value; the handler is registered for subtitle requests.

### Response Example
N/A
```

--------------------------------

### builder.defineCatalogHandler(handler)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Handles catalog requests, including search.

```APIDOC
## builder.defineCatalogHandler(handler)

### Description
Handles catalog requests, including search.

### Method
N/A (method on addonBuilder)

### Endpoint
N/A

### Parameters
#### Request Body
- **handler** (function) - Required - A function that takes an `args` object and returns a response.

### Request Example
```javascript
builder.defineCatalogHandler(function handler(args) { })
```

### Response
No direct return value; the handler is registered for catalog requests.

### Response Example
N/A
```

--------------------------------

### Install Now CLI

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/now.md

Install the `now` command-line tool globally via npm.

```bash
npm install -g now
```

--------------------------------

### builder.getInterface()

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Turns the addon into an addonInterface, an immutable object with {manifest, get}.

```APIDOC
## builder.getInterface()

### Description
Turns the addon into an addonInterface, an immutable (frozen) object with `{manifest, get}`. `manifest` is a regular manifest object, while `get` is a function that takes one argument of the form `{ resource, type, id, extra }` and returns a Promise.

### Method
N/A (method on addonBuilder)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
const addonInterface = builder.getInterface()
```

### Response
Returns an addonInterface object with properties:
- **manifest** (object) - The manifest object.
- **get** (function) - Takes `{ resource, type, id, extra }` and returns a Promise.

### Response Example
```javascript
{
  manifest: { ... },
  get: [Function]
}
```
```

--------------------------------

### builder.defineMetaHandler(handler)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Handles metadata requests (title, releaseInfo, poster, background, etc.).

```APIDOC
## builder.defineMetaHandler(handler)

### Description
Handles metadata requests (title, releaseInfo, poster, background, etc.).

### Method
N/A (method on addonBuilder)

### Endpoint
N/A

### Parameters
#### Request Body
- **handler** (function) - Required - A function that takes an `args` object and returns a response.

### Request Example
```javascript
builder.defineMetaHandler(function handler(args) { })
```

### Response
No direct return value; the handler is registered for metadata requests.

### Response Example
N/A
```

--------------------------------

### Programme (Video) object example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Example of a scheduled programme object for the EPG meta response. Requires both startTime and endTime with endTime strictly later than startTime. Fields like id, title, released, startTime, endTime are required; others are optional.

```javascript
{
    id: 'exampletv:news:epg:2026-09-12T18:00:00.000Z',
    title: 'Evening News',
    overview: "The day's headlines.",
    thumbnail: 'https://example.com/evening-news.jpg',
    released: '2026-09-12T18:00:00.000Z',
    startTime: '2026-09-12T18:00:00.000Z',
    endTime: '2026-09-12T18:45:00.000Z',
    runtime: '45 min',
    releaseInfo: '2026',
    genres: ['News'],
    cast: ['Jane Doe'],
    directors: ['John Doe'],
    ratings: [{ value: 'PG', system: 'TVPG' }]
}
```

--------------------------------

### Guide page response (with date)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Return full Meta objects with videos for the guide page when a date is present. The date is a UTC calendar day, and videos should include programmes overlapping that day.

```javascript
{
    metasDetailed: [
        {
            id: 'exampletv:news',
            type: 'tv',
            name: 'Example News',
            poster: 'https://example.com/news.png',
            posterShape: 'square',
            behaviorHints: {
                isLive: true,
                hasScheduledVideos: true
            },
            videos: [ /* programmes overlapping that UTC day */ ]
        }
    ]
}
```

--------------------------------

### getRouter(addonInterface)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Turns the addonInterface into an Express router that serves the addon according to the protocol and a landing page on the root.

```APIDOC
## getRouter(addonInterface)

### Description
Turns the addonInterface into an Express router that serves the addon according to the protocol and a landing page on the root (`/`).

### Method
N/A (function)

### Endpoint
N/A

### Parameters
#### Request Body
- **addonInterface** (object) - Required - The addonInterface returned from `builder.getInterface()`.

### Request Example
```javascript
const router = getRouter(addonInterface)
```

### Response
Returns an Express router.

### Response Example
```javascript
[Function: router]
```
```

--------------------------------

### new addonBuilder(manifest)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Creates an addon builder object with a given manifest. Throws if the manifest is not valid.

```APIDOC
## new addonBuilder(manifest)

### Description
Creates an addon builder object with a given manifest. Throws if the manifest is not valid.

### Method
Constructor

### Endpoint
N/A

### Parameters
#### Request Body
- **manifest** (object) - Required - The manifest object defining the addon's basic information (name, description, images) and when/how it will be invoked by Stremio.

### Request Example
```javascript
const builder = new addonBuilder(manifest)
```

### Response
Returns an addon builder object with methods to define handlers and get the addon interface.

### Response Example
```javascript
{
  defineCatalogHandler: [Function],
  defineMetaHandler: [Function],
  defineStreamHandler: [Function],
  defineSubtitlesHandler: [Function],
  defineResourceHandler: [Function],
  getInterface: [Function]
}
```
```

--------------------------------

### Deploy project with beamup

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/beamup.md

Run the beamup command in the project directory to deploy. Handles initial setup and deployment.

```bash
beamup
```

--------------------------------

### Install beamup-cli globally

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/beamup.md

Install the Beamup client globally via npm. Required before using the beamup command.

```bash
npm install beamup-cli -g
```

--------------------------------

### builder.defineStreamHandler(handler)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Handles stream requests.

```APIDOC
## builder.defineStreamHandler(handler)

### Description
Handles stream requests.

### Method
N/A (method on addonBuilder)

### Endpoint
N/A

### Parameters
#### Request Body
- **handler** (function) - Required - A function that takes an `args` object and returns a response.

### Request Example
```javascript
builder.defineStreamHandler(function handler(args) { })
```

### Response
No direct return value; the handler is registered for stream requests.

### Response Example
N/A
```

--------------------------------

### Create a basic Stremio addon with addonBuilder and serveHTTP

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Defines an addon that provides a stream for Big Buck Bunny (movie tt1254207) and serves it over HTTP on port 7000. Uses stremio-addon-sdk's addonBuilder, serveHTTP, and publishToCentral (commented out). Save as addon.js and run with Node.js.

```javascript
#!/usr/bin/env node

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
    // this means your addon will be used for streams of the type movie
    resources: ['stream'],
    types: ['movie'],
    idPrefixes: ['tt']
})

// takes function(args), returns Promise
builder.defineStreamHandler(function(args) {
    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' }
        return Promise.resolve({ streams: [stream] })
    } else {
        // otherwise return no streams
	return Promise.resolve({ streams: [] })
    }
})

serveHTTP(builder.getInterface(), { port: 7000 })

// If you want this addon to appear in the addon catalogs, call .publishToCentral() with the publicly available URL to your manifest
//publishToCentral('https://my-addon.com/manifest.json')

```

--------------------------------

### builder.defineResourceHandler('addon_catalog', handler)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Handles addon catalog requests, which can be used to send a list of other addon manifests.

```APIDOC
## builder.defineResourceHandler('addon_catalog', handler)

### Description
Handles addon catalog requests, which can be used to send a list of other addon manifests.

### Method
N/A (method on addonBuilder)

### Endpoint
N/A

### Parameters
#### Request Body
- **resource** (string) - Required - Must be 'addon_catalog'.
- **handler** (function) - Required - A function that takes an `args` object and returns a response.

### Request Example
```javascript
builder.defineResourceHandler('addon_catalog', function handler(args) { })
```

### Response
No direct return value; the handler is registered for addon catalog requests.

### Response Example
N/A
```

--------------------------------

### addonInterface.get({ resource, type, id, extra })

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Returns a Promise for the requested resource. Part of the addonInterface returned from builder.getInterface().

```APIDOC
## addonInterface.get({ resource, type, id, extra })

### Description
Returns a Promise for the requested resource. Part of the addonInterface returned from builder.getInterface().

### Method
N/A (method on addonInterface)

### Endpoint
N/A

### Parameters
#### Request Body
- **resource** (string) - Required - The resource type (e.g., 'catalog', 'meta', 'stream', 'subtitles').
- **type** (string) - Required - The type of the resource.
- **id** (string) - Required - The ID of the resource.
- **extra** (object) - Optional - Additional parameters.

### Request Example
```javascript
addonInterface.get({ resource: 'stream', type: 'movie', id: 'tt123', extra: { } })
```

### Response
Returns a Promise that resolves to the resource data.

### Response Example
```javascript
Promise.resolve({ streams: [] })
```
```

--------------------------------

### Manifest with epgProvider and date extra

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Example manifest that opts in as an EPG provider. Declares a tv catalog with the date extra, sets behaviorHints.epgProvider to true, and includes the skip extra for pagination.

```javascript
{
    id: 'org.example.livetv',
    version: '1.0.0',
    name: 'Example Live TV',
    description: 'Live channels with a programme guide',
    resources: ['catalog', 'meta', 'stream'],
    types: ['tv'],
    idPrefixes: ['exampletv:'],
    catalogs: [
        {
            type: 'tv',
            id: 'channels',
            name: 'Channels',
            extra: [
                { name: 'skip' },
                { name: 'date' }
            ]
        }
    ],
    behaviorHints: {
        epgProvider: true
    }
}
```

--------------------------------

### Configure beamup-cli

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/beamup.md

Run beamup config after installation and whenever GitHub keys are modified.

```bash
beamup config
```

--------------------------------

### GET /meta/tv/{channelId}.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Retrieves channel details and the programme guide for a TV channel. Used for the channel details page and for refreshing an expired schedule.

```APIDOC
## [GET] /meta/tv/{channelId}.json

### Description
Retrieves channel details and the programme guide for a TV channel. Used for the channel details page and for refreshing an expired schedule.

### Method
GET

### Endpoint
/meta/tv/{channelId}.json

### Parameters
#### Path Parameters
- **channelId** (string) - Required - The ID of the TV channel.

### Response
#### Success Response (200)
- **behaviorHints.hasScheduledVideos** (boolean) - Set to `true` when `videos` is a programme guide.
- **behaviorHints.isLive** (boolean) - Optional if `type` is already `tv`; set to `true` for live channels.
- **videos** (array) - The current and nearby programmes.

#### Response Example
```json
{
  "behaviorHints": {
    "hasScheduledVideos": true,
    "isLive": true
  },
  "videos": [
    {
      "id": "exampletv:news:epg:2026-09-12T18:00:00.000Z",
      "title": "Evening News",
      "overview": "The day's headlines.",
      "thumbnail": "https://example.com/evening-news.jpg",
      "released": "2026-09-12T18:00:00.000Z",
      "startTime": "2026-09-12T18:00:00.000Z",
      "endTime": "2026-09-12T18:45:00.000Z",
      "runtime": "45 min",
      "releaseInfo": "2026",
      "genres": ["News"],
      "cast": ["Jane Doe"],
      "directors": ["John Doe"],
      "ratings": [{ "value": "PG", "system": "TVPG" }]
    }
  ]
}
```
```

--------------------------------

### Handle skip in catalog handler

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/advanced.md

Example of using skip in a catalog handler. It slices a meta list using skip as the starting point, returning up to 20 items. Rejects with an error for unknown catalog requests.

```javascript
// we only have one meta item
const meta = {
  id: 'tt1254207',
  name: 'Big Buck Bunny',
  releaseInfo: '2008',
  poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
  posterShape: 'poster',
  banner: 'https://image.tmdb.org/t/p/original/aHLST0g8sOE1ixCxRDgM35SKwwp.jpg',
  type: 'movie'
}

const metaList = []

// but we'll make an array that includes our meta 60 times
for (let i = 0; i++; i < 60) {
  metaList.push(meta)
}

builder.defineCatalogHandler(function(args) {
  return new Promise(function(resolve, reject) {
    if (args.id == 'testcatalog') {
      // we'll slice our meta list using
      // skip as the starting point
      const skip = args.extra.skip || 0
      resolve({ metas: metaList.slice(skip, skip + 20) })
    } else {
      reject(new Error('Unknown catalog request'))
    }
  })
})
```

--------------------------------

### publishToCentral(url)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/README.md

Publishes an addon URL to the central server, making it available in the Community Addons list in Stremio.

```APIDOC
## publishToCentral(url)

### Description
Publishes an addon URL to the central server, making it available in the Community Addons list in Stremio. The addon must be publicly available with a URL.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
#### Request Body
- **url** (string) - Required - The URL to your `manifest.json` file.

### Request Example
```javascript
publishToCentral('https://example.com/manifest.json')
```

### Response
No return value specified.

### Response Example
N/A
```

--------------------------------

### Video object - series example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/responses/meta.md

Example of a Video object for a series episode, including id, title, released, season, episode, and overview fields.

```javascript
{
    id: "tt0108778:1:1",
    title: "Pilot",
    released: new Date("1994-09-22 20:00 UTC+02"),
    season: 1,
    episode: 1,
    overview: "Monica and the gang introduce Rachel to the real world after she leaves her fiancé at the altar."
}
```

--------------------------------

### GET /catalog/tv/channels.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Retrieves a list of TV channels as Meta Preview objects. Supports optional pagination via the 'skip' parameter.

```APIDOC
## [GET] /catalog/tv/channels.json

### Description
Retrieves a list of TV channels as Meta Preview objects. Supports optional pagination via the 'skip' parameter.

### Method
GET

### Endpoint
/catalog/tv/channels.json

### Parameters
#### Query Parameters
- **skip** (integer) - Optional - Number of channels to skip for pagination.

### Response
#### Success Response (200)
- **metas** (array of Meta Preview objects) - List of channel metadata.

#### Response Example
{
  "metas": [
    {
      "id": "exampletv:news",
      "type": "tv",
      "name": "Example News",
      "poster": "https://example.com/news.png",
      "posterShape": "square",
      "behaviorHints": { "isLive": true }
    }
  ]
}
```

--------------------------------

### Programme overlap filter

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Filter videos to programmes that overlap the requested UTC day. Use these conditions to include programmes whose end time is after the day start and start time is before the day end.

```plaintext
program.endTime >  dateT00:00:00.000Z
program.startTime < dateT23:59:59.999Z
```

--------------------------------

### Video object - Native EPG programme example (live TV)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/responses/meta.md

Example of a Video object for a live TV programme using Native EPG fields, including startTime, endTime, runtime, and genres.

```javascript
{
    id: "exampletv:news:epg:2026-09-12T18:00:00.000Z",
    title: "Evening News",
    overview: "The day's headlines.",
    released: "2026-09-12T18:00:00.000Z",
    startTime: "2026-09-12T18:00:00.000Z",
    endTime: "2026-09-12T18:45:00.000Z",
    runtime: "45 min",
    genres: ["News"]
}
```

--------------------------------

### Video object - YouTube video example (channels)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/responses/meta.md

Example of a Video object for a YouTube channel video, including id, title, released, and thumbnail fields.

```javascript
{
    id: "yt_id:UCrDkAvwZum-UTjHmzDI2iIw:9bZkp7q19f0",
    title: "PSY - GANGNAM STYLE",
    released: new Date("2012-07-15 20:00 UTC+02"),
    thumbnail: "https://i.ytimg.com/vi/9bZkp7q19f0/hqdefault.jpg"
}
```

--------------------------------

### GET /catalog/tv/channels/date=2026-09-12.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Retrieves detailed channel information including programmes for a specific UTC calendar day. The 'date' parameter is required and must be in YYYY-MM-DD format.

```APIDOC
## [GET] /catalog/tv/channels/date=2026-09-12.json

### Description
Retrieves detailed channel information including programmes for a specific UTC calendar day. The 'date' parameter is required and must be in YYYY-MM-DD format.

### Method
GET

### Endpoint
/catalog/tv/channels/date=2026-09-12.json

### Parameters
#### Path Parameters
- **date** (string) - Required - UTC calendar day in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **metasDetailed** (array of Meta objects) - List of channels with full metadata and programmes.

#### Response Example
{
  "metasDetailed": [
    {
      "id": "exampletv:news",
      "type": "tv",
      "name": "Example News",
      "poster": "https://example.com/news.png",
      "posterShape": "square",
      "behaviorHints": {
        "isLive": true,
        "hasScheduledVideos": true
      },
      "videos": [ /* programmes overlapping that UTC day */ ]
    }
  ]
}
```

--------------------------------

### Channel list response (no date)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Return Meta Preview objects for the channel list endpoint when no date is provided. The response includes an array of channel objects with behaviorHints.isLive set to true.

```javascript
{
    metas: [
        {
            id: 'exampletv:news',
            type: 'tv',
            name: 'Example News',
            poster: 'https://example.com/news.png',
            posterShape: 'square',
            behaviorHints: { isLive: true }
        }
    ]
}
```

--------------------------------

### defineResourceHandler(args)

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineResourceHandler.md

Handles addon catalog requests, returning a list of addons that can be installed in Stremio. This is distinct from defineCatalogHandler() which handles meta catalogs.

```APIDOC
## defineResourceHandler(args)

### Description
Handles addon catalog requests, returning a list of addons that can be installed in Stremio. This is distinct from defineCatalogHandler() which handles meta catalogs.

### Method
Function call

### Endpoint
`builder.defineResourceHandler('addon_catalog', function(args) { ... })`

### Parameters
#### Arguments
- **args** (object) - Required - Request object containing the following parameters:
  - **type** (string) - Required - Type of the catalog's content; e.g. `movie`, `series`, `channel`, `tv`
  - **id** (string) - Required - String id of the catalog that is requested; these are set in the Manifest Object
  - **config** (object) - Required - Object with user settings, see Manifest - User Data

### Returns
A promise that resolves to an object containing `{ addons: [] }` with an array of Catalog Addon Objects.

The resolving object can also include the following cache related properties:
- **cacheMaxAge** (int) - Optional - In seconds; sets the `Cache-Control` header to `max-age=$cacheMaxAge` and overwrites the global cache time set in `serveHTTP` options
- **staleRevalidate** (int) - Optional - In seconds; sets the `Cache-Control` header to `stale-while-revalidate=$staleRevalidate`
- **staleError** (int) - Optional - In seconds; sets the `Cache-Control` header to `stale-if-error=$staleError`

### Request Example
```javascript
builder.defineResourceHandler('addon_catalog', function(args) {
    return Promise.resolve({
        addons: [
            {
                transportName: 'http',
                transportUrl: 'https://example.addon.org/manifest.json',
                manifest: {
                    id: 'org.myexampleaddon',
                    version: '1.0.0',
                    name: 'simple example',
                    catalogs: [],
                    resources: ['stream'],
                    types: ['movie'],
                    idPrefixes: ['tt']
                }
            }
        ]
    })
})
```

### Response
#### Success Response
- **addons** (array) - Array of Catalog Addon Objects
- **cacheMaxAge** (int) - Optional - Cache-Control max-age in seconds
- **staleRevalidate** (int) - Optional - Cache-Control stale-while-revalidate in seconds
- **staleError** (int) - Optional - Cache-Control stale-if-error in seconds

#### Response Example
```javascript
{
    addons: [
        {
            transportName: 'http',
            transportUrl: 'https://example.addon.org/manifest.json',
            manifest: {
                id: 'org.myexampleaddon',
                version: '1.0.0',
                name: 'simple example',
                catalogs: [],
                resources: ['stream'],
                types: ['movie'],
                idPrefixes: ['tt']
            }
        }
    ]
}
```
```

--------------------------------

### Basic defineResourceHandler example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineResourceHandler.md

Defines a resource handler for an addon catalog that returns a list of addons. The handler receives an args object with type, id, and config parameters, and must resolve to an object containing an addons array of Catalog Addon Objects. The response can include cache-related properties like cacheMaxAge, staleRevalidate, and staleError to control Cache-Control headers.

```javascript
builder.defineResourceHandler('addon_catalog', function(args) {
    return Promise.resolve({
        addons: [
            {
                transportName: 'http',
                transportUrl: 'https://example.addon.org/manifest.json',
                manifest: {
                    id: 'org.myexampleaddon',
                    version: '1.0.0',
                    name: 'simple example',
                    catalogs: [],
                    resources: ['stream'],
                    types: ['movie'],
                    idPrefixes: ['tt']
                }
            }
        ]
    })
})
```

--------------------------------

### EPG request flow diagram

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Shows the sequence of requests Stremio makes when a user opens Live TV with a native EPG provider: catalog with date, meta details, and stream by channel id.

```txt
User opens Live TV
        ↓
Stremio Native EPG is shown
        ↓
GET /catalog/tv/{catalogId}/date=YYYY-MM-DD.json
        → { metasDetailed: [ channel + that day's videos ] }
        ↓
GET /meta/tv/{channelId}.json   (details / refresh)
        ↓
GET /stream/tv/{channelId}.json (playback of the channel)
```

--------------------------------

### GET /manifest.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/protocol.md

Serves the addon manifest, which describes the addon and its capabilities. This endpoint is required for every addon.

```APIDOC
## GET /manifest.json

### Description
Serves the addon manifest, which describes the addon and its capabilities. This endpoint is required for every addon.

### Method
GET

### Endpoint
/manifest.json

### Response
#### Success Response (200)
- Manifest object describing the addon.

#### Response Example
{
  "id": "example.addon",
  "name": "Example Addon",
  "resources": ["catalog", "meta", "stream", "subtitles"],
  "catalogs": []
}
```

--------------------------------

### Basic defineMetaHandler example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineMetaHandler.md

Handles metadata requests by checking the type and id arguments. Returns a promise resolving to an object with a meta property, either with the requested metadata or an empty object if not found.

```javascript
builder.defineMetaHandler(function(args) {
    if (args.type === 'movie' && args.id === 'tt1254207') {
        // serve metadata for Big Buck Bunny
        const metaObj = {
            id: 'tt1254207',
            name: 'Big Buck Bunny',
            releaseInfo: '2008',
            poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
            posterShape: 'poster',
            type: 'movie'
        }
        return Promise.resolve({ meta: metaObj })
    } else {
        // otherwise return no meta
        return Promise.resolve({ meta: {} })
    }
})
```

--------------------------------

### Define stream handler for TV channel

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/epg.md

Implement defineStreamHandler for type 'tv' and the channel id 'exampletv:news'. Returns a stream with a live URL. Do not attach video.streams on programmes unless intentionally locking the video to those streams.

```javascript
builder.defineStreamHandler(function (args) {
    if (args.type === 'tv' && args.id === 'exampletv:news') {
        return Promise.resolve({
            streams: [{
                name: 'News',
                description: 'Live',
                url: 'https://example.com/news.m3u8'
            }]
        })
    }
    return Promise.resolve({ streams: [] })
})
```

--------------------------------

### Handle search requests in the catalog handler

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/advanced.md

Example handler that responds to search requests for 'big buck bunny' and rejects with 'No search results found' otherwise. Uses args.extra.search to detect search requests.

```javascript
const meta = {
  id: 'tt1254207',
  name: 'Big Buck Bunny',
  releaseInfo: '2008',
  poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
  posterShape: 'poster',
  banner: 'https://image.tmdb.org/t/p/original/aHLST0g8sOE1ixCxRDgM35SKwwp.jpg',
  type: 'movie'
}
builder.defineCatalogHandler(function(args) {
  return new Promise(function(resolve, reject) {
    if (args.id == 'testcatalog') {
      // this is a request to our catalog id
      if (args.extra.search) {
        // this is a search request
        if (args.extra.search == 'big buck bunny') {
          // if someone searched for "big buck bunny" (exact match)
          // respond with our meta item
          resolve({ metas: [meta] })
        } else {
          reject(new Error('No search results found'))
        }
      } else {
        // this is a standard catalog request
        // just respond with our meta item
        resolve({ metas: [meta] })
      }
    } else {
      reject(new Error('Unknown catalog request'))
    }
  })
})
```

--------------------------------

### Basic defineCatalogHandler example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineCatalogHandler.md

Handles catalog feed and search requests for a movie catalog. Checks args.type and args.id, returns a single meta object for 'big buck bunny' search or feed, otherwise empty metas. Uses Promise.resolve with { metas: [] }.

```javascript
builder.defineCatalogHandler(function(args) {
    if (args.type === 'movie' && args.id === 'top') {

        // we will only respond with Big Buck Bunny
        // to both feed and search requests

        const meta = {
            id: 'tt1254207',
            name: 'Big Buck Bunny',
            releaseInfo: '2008',
            poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
            posterShape: 'poster',
            banner: 'https://image.tmdb.org/t/p/original/aHLST0g8sOE1ixCxRDgM35SKwwp.jpg',
            type: 'movie'
        }

        if (args.extra && args.extra.search) {

            // catalog search request

            if (args.extra.search == 'big buck bunny') {
                return Promise.resolve({ metas: [meta] })
            } else {
                return Promise.resolve({ metas: [] })
            }

        } else {

            // catalog feed request

            return Promise.resolve({ metas: [meta] })

        }

    } else {
        // otherwise return empty catalog
        return Promise.resolve({ metas: [] })
    }
})
```

--------------------------------

### GET /{resource}/{type}/{id}/{extraArgs}.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/protocol.md

Allows passing extra arguments to any resource, such as search, skip, or date for catalog resources. The extraArgs is a stringified query string object.

```APIDOC
## GET /{resource}/{type}/{id}/{extraArgs}.json

### Description
Allows passing extra arguments to any resource, such as search, skip, or date for catalog resources. The extraArgs is a stringified query string object.

### Method
GET

### Endpoint
/{resource}/{type}/{id}/{extraArgs}.json

### Parameters
#### Path Parameters
- **resource** (string) - Required - The resource type (e.g., catalog, meta, stream, subtitles).
- **type** (string) - Required - The type of media.
- **id** (string) - Required - The ID of the item or catalog.
- **extraArgs** (string) - Required - The stringified query string object of extra arguments (e.g., "search=game%20of%20thrones&skip=100").

### Response
#### Success Response (200)
- The response for the specified resource.

#### Response Example
{
  "metas": []
}
```

--------------------------------

### Handle genre filter requests in the catalog handler

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/advanced.md

Example handler that responds with the meta item only when the genre is 'Action', otherwise returns an empty metas array. Uses args.extra.genre to detect filter requests.

```javascript
const meta = {
  id: 'tt1254207',
  name: 'Big Buck Bunny',
  releaseInfo: '2008',
  poster: 'https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg',
  posterShape: 'poster',
  banner: 'https://image.tmdb.org/t/p/original/aHLST0g8sOE1ixCxRDgM35SKwwp.jpg',
  type: 'movie'
}
builder.defineCatalogHandler(function(args) {
  return new Promise(function(resolve, reject) {
    if (args.id == 'testcatalog') {
      // this is a request to our catalog id
      if (args.extra.genre) {
        // this is a filter request
        if (args.extra.genre == "Action") {
          // in this example we'll only respon with our
          // meta item if the genre is "Action"
          resolve({ metas: [meta] })
        } else {
          // otherwise with no meta item
          resolve({ metas: [] })
        }
      } else {
        // this is a standard catalog request
        // just respond with our meta item
        resolve({ metas: [meta] })
      }
    } else {
      reject(new Error('Unknown catalog request'))
    }
  })
})
```

--------------------------------

### Express addon reading user data from URL parameter

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/advanced.md

Shows how to read user data passed in the Addon Repository URL using Express. The parameter is used in manifest and stream routes. This is a simplistic example, not a working addon.

```javascript
const express = require('express')
const addon = express()

addon.get('/:someParameter/manifest.json', function (req, res) {
  res.send({
    id: 'org.parameterized.'+req.params.someParameter,
    name: 'addon for '+req.params.someParameter,
    resources: ['stream'],
    types: ['series'],
  })
})

addon.get('/:someParameter/stream/:type/:id.json', function(req, res) {
  // @TODO do something depending on req.params.someParameter
  res.send({ streams: [] })
})

addon.listen(7000, function() {
  console.log('http://127.0.0.1:7000/[someParameter]/manifest.json')
})
```

--------------------------------

### GET /catalog/{type}/{id}.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/protocol.md

Returns a catalog of media items for a given type and catalog ID. The type can be movie, series, channel, tv, etc., and the ID is specified in the manifest.

```APIDOC
## GET /catalog/{type}/{id}.json

### Description
Returns a catalog of media items for a given type and catalog ID. The type can be movie, series, channel, tv, etc., and the ID is specified in the manifest.

### Method
GET

### Endpoint
/catalog/{type}/{id}.json

### Parameters
#### Path Parameters
- **type** (string) - Required - The type of media (e.g., movie, series, channel, tv).
- **id** (string) - Required - The catalog ID, custom and specified in the manifest.

### Response
#### Success Response (200)
- Catalog object containing media items.

#### Response Example
{
  "metas": [
    {
      "id": "tt1234567",
      "type": "movie",
      "name": "Example Movie"
    }
  ]
}
```

--------------------------------

### GET /meta/{type}/{id}.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/protocol.md

Returns detailed metadata about a particular item. The type denotes the media type, and the ID is the item's ID as found in the catalog.

```APIDOC
## GET /meta/{type}/{id}.json

### Description
Returns detailed metadata about a particular item. The type denotes the media type, and the ID is the item's ID as found in the catalog.

### Method
GET

### Endpoint
/meta/{type}/{id}.json

### Parameters
#### Path Parameters
- **type** (string) - Required - The type of media (e.g., movie, series, channel, tv).
- **id** (string) - Required - The ID of the particular item.

### Response
#### Success Response (200)
- Metadata object for the item.

#### Response Example
{
  "meta": {
    "id": "tt1234567",
    "type": "movie",
    "name": "Example Movie",
    "videos": []
  }
}
```

--------------------------------

### Basic defineSubtitlesHandler example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineSubtitlesHandler.md

Handles subtitle requests by checking the video ID and returning a subtitle for 'tt1254207' or an empty list. The handler returns a promise resolving to an object with a 'subtitles' array.

```javascript
builder.defineSubtitlesHandler(function(args) {
    if (args.id === 'tt1254207') {
        // serve one subtitle for big buck bunny
        const subtitle = {
            url: 'https://mkvtoolnix.download/samples/vsshort-en.srt',
            lang: 'eng'
        }
        return Promise.resolve({ subtitles: [subtitle] })
    } else {
        // otherwise return no subtitles
        return Promise.resolve({ subtitles: [] })
    }
})
```

--------------------------------

### GET /subtitles/{type}/{id}.json

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/protocol.md

Returns a list of all subtitles for a particular item. The type denotes the media type, and the id is the Open Subtitles file hash. Extra args are used for videoID and videoSize.

```APIDOC
## GET /subtitles/{type}/{id}.json

### Description
Returns a list of all subtitles for a particular item. The type denotes the media type, and the id is the Open Subtitles file hash. Extra args are used for videoID and videoSize.

### Method
GET

### Endpoint
/subtitles/{type}/{id}.json

### Parameters
#### Path Parameters
- **type** (string) - Required - The type of media (e.g., movie, series, channel, tv).
- **id** (string) - Required - The Open Subtitles file hash.

#### Query Parameters
- **videoID** (string) - Required - The ID of the particular item or video ID.
- **videoSize** (number) - Required - Video file size in bytes.

### Response
#### Success Response (200)
- Subtitles object containing a list of subtitles.

#### Response Example
{
  "subtitles": [
    {
      "id": "1",
      "url": "https://example.com/subtitle.vtt",
      "lang": "en"
    }
  ]
}
```

--------------------------------

### Basic defineStreamHandler example

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineStreamHandler.md

Handles stream requests by checking the type and ID, returning a stream for a specific movie or an empty array otherwise. The returned object can include cache-related properties like cacheMaxAge, staleRevalidate, and staleError to control Cache-Control headers.

```javascript
builder.defineStreamHandler(function(args) {
    if (args.type === 'movie' && args.id === 'tt1254207') {
        // serve one stream for big buck bunny
        const stream = { url: 'http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4' }
        return Promise.resolve({ streams: [stream] })
    } else {
        // otherwise return no streams
        return Promise.resolve({ streams: [] })
    }
})
```

--------------------------------

### Create serverless.js

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/now.md

Create a `serverless.js` file that uses `getRouter` to handle requests and returns a 404 if no route matches.

```javascript
const { getRouter } = require("stremio-addon-sdk");
const addonInterface = require("./addon");
const router = getRouter(addonInterface);
module.exports = function(req, res) {
    router(req, res, function() {
        res.statusCode = 404;
        res.end();
    });
}
```

--------------------------------

### Define addon builder

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/now.md

Create the `addon` object using `addonBuilder` from the SDK.

```javascript
const { addonBuilder } = require("stremio-addon-sdk")
const addon = new addonBuilder(manifest);
```

--------------------------------

### Export addon interface for serverless

Source: https://github.com/stremio/stremio-addon-sdk/blob/master/docs/deploying/now.md

Replace `addon.serveHTTP` with `module.exports = addon.getInterface()` in your `index.js` to make the project serverless.

```javascript
module.exports = addon.getInterface()
```
Tokens:
Raw