### Getting Started Example

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

A basic example demonstrating how to create a Stremio addon that provides streams for a specific movie and how to serve it via HTTP.

```APIDOC
## Getting Started Example

This example creates an addon that provides a stream for Big Buck Bunny and outputs an HTTP address where you can access it.

### Code Example

```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')
```

### Installation and Running

Save the code as `addon.js` and run the following commands:

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

This will output a URL that can be used to install the addon in Stremio.
```

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

### Quick Start Addon Example

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

This example demonstrates how to create a basic Stremio addon that provides a stream for a specific movie. It includes setup for the addon's metadata, stream handling, and HTTP serving. Ensure you have Node.js and npm installed.

```javascript
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
    catalogs: [],
    resources: ['stream'],
    types: ['movie'],
    idPrefixes: ['tt']
})

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

serveHTTP(builder.getInterface(), { port: process.env.PORT || 7000 })
//publishToCentral("https://your-domain/manifest.json") // <- invoke this if you want to publish your addon and it's accessible publicly on "your-domain"
```

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

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

### Install and Run the Addon

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

These commands install the necessary SDK and run the addon script. After running, an HTTP address will be outputted, which can be used to install the addon in Stremio.

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

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

### Create and Serve a Basic Stremio Addon

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

This example creates a simple addon that provides a stream for Big Buck Bunny. It configures the addon manifest, defines a stream handler, and serves the addon over HTTP on port 7000. Ensure you have Node.js installed and run `npm install stremio-addon-sdk` before executing.

```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')

```

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

### Starting the Addon Server

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

This section explains how to start the addon server using the `serveHTTP` method and its configuration options.

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

### Description
Starts the addon server.

### Parameters
#### Request Body
- **addonInterface** (object) - Required - The addon interface object obtained from `builder.getInterface()`.
- **options** (object) - Optional - An object containing server configuration.
  - **port** (number) - The port number to run the server on.
  - **cacheMaxAge** (number) - Cache maximum age in seconds. Sets the `Cache-Control` header to `max-age=$cacheMaxAge`.
  - **static** (string) - Path to a directory of static files to be served (e.g., `/public`).

### Special Process Arguments
This method also reacts to specific process arguments:
- `--launch`: Launches Stremio in the web browser and automatically installs/upgrades the addon.
- `--install`: Installs the addon in the desktop version of Stremio.
```

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

### Example Addon Manifest

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

This manifest example is for an addon that provides streams and catalogs, includes a movie catalog, and will receive stream requests for meta items with IDs starting with 'tt'.

```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"]
}
```

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

### Install Now CLI

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

Installs the Now.sh command-line interface globally, which is necessary for deploying your project to Now.sh.

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

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

### Install Addon in Stremio Desktop

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

Use this command to open the desktop version of Stremio and present a prompt for installing your addon. This is suitable for testing the installation process on the desktop client.

```bash
npm start -- --install
```

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

### Complete Addon Example

Source: https://context7.com/stremio/stremio-addon-sdk/llms.txt

This is a full addon example demonstrating all handler types, caching, error handling, and integration with external APIs. It includes manifest definition, data structures, and handlers for catalog, meta, stream, and subtitles.

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

const manifest = {
    id: 'org.complete.example',
    version: '1.0.0',
    name: 'Complete Example Addon',
    description: 'Demonstrates all SDK features',
    logo: 'https://example.com/logo.png',
    background: 'https://example.com/background.jpg',
    contactEmail: 'contact@example.com',

    resources: ['catalog', 'meta', 'stream', 'subtitles'],
    types: ['movie', 'series'],
    idPrefixes: ['tt'],

    catalogs: [
        {
            type: 'movie',
            id: 'trending',
            name: 'Trending Movies',
            extra: [
                { name: 'search', isRequired: false },
                { name: 'genre', options: ['Action', 'Comedy', 'Drama', 'Sci-Fi'], isRequired: false },
                { name: 'skip', isRequired: false }
            ]
        },
        {
            type: 'series',
            id: 'popular',
            name: 'Popular Series',
            extra: [{ name: 'search', isRequired: false }]
        }
    ],

    behaviorHints: {
        adult: false,
        p2p: true
    }
}

const builder = new addonBuilder(manifest)

// In-memory database for demo
const database = {
    movies: [
        { id: 'tt1254207', name: 'Big Buck Bunny', year: '2008', genres: ['Animation', 'Comedy'] },
        { id: 'tt0468569', name: 'The Dark Knight', year: '2008', genres: ['Action', 'Crime', 'Drama'] }
    ],
    series: [
        { id: 'tt0386676', name: 'The Office', years: '2005-2013', genres: ['Comedy'] }
    ]
}

// Catalog handler with search, filter, and pagination
builder.defineCatalogHandler(async (args) => {
    try {
        let items = args.type === 'movie' ? database.movies : database.series

        // Search filter
        if (args.extra?.search) {
            const query = args.extra.search.toLowerCase()
            items = items.filter(item => item.name.toLowerCase().includes(query))
        }

        // Genre filter
        if (args.extra?.genre) {
            items = items.filter(item => item.genres.includes(args.extra.genre))
        }

        // Pagination
        const skip = parseInt(args.extra?.skip) || 0
        items = items.slice(skip, skip + 100)

        const metas = items.map(item => ({
            id: item.id,
            type: args.type,
            name: item.name,
            poster: `https://via.placeholder.com/300x450?text=${encodeURIComponent(item.name)}`,
            releaseInfo: item.year || item.years,
            genres: item.genres
        }))

        return { metas, cacheMaxAge: 1800 }
    } catch (error) {
        console.error('Catalog error:', error)
        return { metas: [] }
    }
})

// Meta handler for detailed information
builder.defineMetaHandler(async (args) => {
    try {
        const item = [...database.movies, ...database.series].find(i => i.id === args.id)

        if (!item) {
            return { meta: {} }
        }

        const meta = {
            id: item.id,
            type: args.type,
            name: item.name,
            poster: `https://via.placeholder.com/300x450?text=${encodeURIComponent(item.name)}`,
            background: `https://via.placeholder.com/1920x1080?text=${encodeURIComponent(item.name)}`,
            releaseInfo: item.year || item.years,
            genres: item.genres,
            description: `This is the description for ${item.name}.`
        }

        // Add episodes for series
        if (args.type === 'series') {
            meta.videos = [
                { id: `${item.id}:1:1`, title: 'Episode 1', season: 1, episode: 1, released: '2005-03-24T00:00:00.000Z' },
                { id: `${item.id}:1:2`, title: 'Episode 2', season: 1, episode: 2, released: '2005-03-31T00:00:00.000Z' }
            ]
        }

        return { meta, cacheMaxAge: 86400 }
    } catch (error) {
        console.error('Meta error:', error)
        return { meta: {} }
    }
})

// Stream handler
builder.defineStreamHandler(async (args) => {
    try {
        const streams = []

        // Demo stream for Big Buck Bunny
        if (args.id === 'tt1254207' || args.id.startsWith('tt1254207:')) {
            streams.push({
                url: 'http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4',
                name: '1080p',
                title: 'Big Buck Bunny - 1080p Direct',
                behaviorHints: { bingeGroup: 'example-1080p' }
            })
        }

        return { streams, cacheMaxAge: 3600 }
    } catch (error) {
        console.error('Stream error:', error)
        return { streams: [] }
    }
})

// Subtitles handler
builder.defineSubtitlesHandler(async (args) => {
    try {
        if (args.id === 'tt1254207') {
            return {
                subtitles: [

```

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

### Deploy project with beamup

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

Navigate to your project directory and use the `beamup` command to deploy. This command handles both initial setup and subsequent deployments.

```bash
beamup
```

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

### Define Addon Catalog Handler

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

Use defineResourceHandler to specify how your addon will provide a catalog of other installable addons. This example demonstrates returning a static list of addons.

```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']
                }
            }
        ]
    })
})
```

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

### serveHTTP

Source: https://context7.com/stremio/stremio-addon-sdk/llms.txt

Starts an HTTP server to serve the addon. It supports command-line flags for launching Stremio with the addon pre-installed and configuring cache behavior.

```APIDOC
## serveHTTP

### Description
Starts an HTTP server to serve the addon. Supports command-line flags for launching Stremio with the addon pre-installed and configuring cache behavior.

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

### Parameters
#### `addonInterface`
- **addonInterface** (object) - The addon interface obtained from `builder.getInterface()`.

#### `options` (object)
- **port** (number) - The port number for the HTTP server. Defaults to `process.env.PORT || 7000`.
- **cacheMaxAge** (number) - Default cache duration in seconds for responses. Defaults to 3600 (1 hour).
- **static** (string) - Path to a directory to serve static files from.

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

const builder = new addonBuilder({
    id: 'org.myexampleaddon',
    version: '1.0.0',
    name: 'My Addon',
    resources: ['stream'],
    types: ['movie'],
    catalogs: []
})

builder.defineStreamHandler(function(args) {
    return Promise.resolve({ streams: [] })
})

// Start the HTTP server
serveHTTP(builder.getInterface(), {
    port: process.env.PORT || 7000,
    cacheMaxAge: 3600,                    // Default cache: 1 hour
    static: './public'                     // Serve static files from ./public
})

// Server will be available at http://127.0.0.1:7000
// Manifest at http://127.0.0.1:7000/manifest.json
// Install URL: stremio://127.0.0.1:7000/manifest.json

// Command line usage:
// node addon.js --launch    // Opens Stremio web with addon installed
// node addon.js --install   // Installs addon in desktop Stremio
```
```

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

### Install beamup-cli

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

Install the beamup command-line interface globally using npm. This command is required before you can configure and use beamup for deployments.

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

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

### 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. Ensure the 'released' field is in ISO 8601 format.

```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."
}
```

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

### Serve HTTP

Source: https://context7.com/stremio/stremio-addon-sdk/llms.txt

Starts an HTTP server to serve the addon. Supports command-line flags for launching Stremio with the addon pre-installed and configuring cache behavior.

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

const builder = new addonBuilder({
    id: 'org.myexampleaddon',
    version: '1.0.0',
    name: 'My Addon',
    resources: ['stream'],
    types: ['movie'],
    catalogs: []
})

builder.defineStreamHandler(function(args) {
    return Promise.resolve({ streams: [] })
})

// Start the HTTP server
serveHTTP(builder.getInterface(), {
    port: process.env.PORT || 7000,
    cacheMaxAge: 3600,                    // Default cache: 1 hour
    static: './public'                     // Serve static files from ./public
})

// Server will be available at http://127.0.0.1:7000
// Manifest at http://127.0.0.1:7000/manifest.json
// Install URL: stremio://127.0.0.1:7000/manifest.json

// Command line usage:
// node addon.js --launch    # Opens Stremio web with addon installed
// node addon.js --install   # Installs addon in desktop Stremio

```

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

### Scaffolding a New Addon with addon-bootstrap

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

Use the `addon-bootstrap` tool to quickly set up a new Stremio addon project. This command installs the SDK globally and then bootstraps a new addon in a specified directory. Follow the prompts to configure resources and types.

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

```bash
cd hello-world
npm install
npm start -- --launch
```

```bash
npm start -- --install
```

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

### Subtitle Response Example

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

Defines subtitle tracks for a video. This example shows how to specify subtitle URL and language.

```json
{
    "subtitles": [
        {
            url: "https://mkvtoolnix.download/samples/vsshort-en.srt",
            lang: "en"
        },
        ...
    ]
}
```

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

### Node.js Express Example for User Data

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

This example demonstrates how to pass user-specific data, such as an API authentication token, in the Addon URL using Node.js and Express. This approach is useful when not using the Addon SDK directly.

```javascript
const express = require('express');
const app = express();

app.get('/user/:userId/data', (req, res) => {
  const userId = req.params.userId;
  // In a real application, you would fetch user-specific data here
  // For example, retrieve an API token from a database based on userId
  const userSpecificData = {
    token: `user_${userId}_api_token`
  };
  res.json(userSpecificData);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});
```

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

### Serve HTTP Addon with Stremio Addon SDK

Source: https://context7.com/stremio/stremio-addon-sdk/llms.txt

Starts an HTTP server for a Stremio addon using the SDK. Ensure the builder is configured before calling serveHTTP. The port can be set via the PORT environment variable.

```javascript
const port = process.env.PORT || 7000
serveHTTP(builder.getInterface(), { port })

console.log(`Addon running at http://127.0.0.1:${port}`)
console.log(`Install in Stremio: stremio://127.0.0.1:${port}/manifest.json`)
```

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

### Video Object - YouTube Video Example

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

Example of a Video object for a YouTube video. The 'id' should be prefixed with 'yt_id:'.

```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"
}
```

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

### Serve Addon Manifest with User Parameters (Node.js/Express)

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

This example demonstrates how to create an Express.js server to handle addon requests, specifically extracting a user-defined parameter from the manifest URL. This parameter can be used to personalize addon behavior.

```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')
})
```

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

### Configure beamup

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

Run the beamup config command after installation or whenever GitHub keys are modified. This step is essential for setting up your deployment environment.

```bash
beamup config
```

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

### Interface and Router

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

Methods for getting the addon interface and converting it to an Express router.

```APIDOC
## Interface and Router

Methods for obtaining the addon's interface and creating an Express router.

### `builder.getInterface()`

Returns an `addonInterface`, which is an immutable object containing the addon's manifest and a `get` function. The `get` function takes an object with `resource`, `type`, `id`, and `extra` arguments and returns a Promise.

### `getRouter(addonInterface)`

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

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

### defineResourceHandler API

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

Handles addon catalog requests, returning a list of other addons that can be installed in Stremio.

```APIDOC
## defineResourceHandler

### Description
This method handles addon catalog requests. It is used to provide a list of addon manifests, enabling an addon to serve as a catalog for other installable Stremio addons.

### Method
POST (or equivalent for defining a handler)

### Endpoint
Not directly applicable as this is a method definition within the SDK.

### Parameters
#### Arguments
`args` - object - Request object containing parameters for the catalog request.

- **type** (string) - Required - The type of the catalog's content (e.g., `movie`, `series`, `channel`, `tv`).
- **id** (string) - Required - The string ID of the catalog being requested, as defined in the addon's manifest.
- **config** (object) - Optional - An object containing user settings, as described in the Manifest's User Data section.

### Returns
A promise that resolves to an object containing an `addons` array. Each element in the array is a Catalog Addon Object.

- **addons** (array) - An array of Catalog Addon Objects.
- **cacheMaxAge** (int) - Optional - Cache duration in seconds. Sets the `Cache-Control: max-age` header.
- **staleRevalidate** (int) - Optional - Cache duration in seconds. Sets the `Cache-Control: stale-while-revalidate` header.
- **staleError** (int) - Optional - Cache duration in seconds. Sets the `Cache-Control: stale-if-error` header.

### 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 Example (Success)
```json
{
  "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"]
      }
    }
  ],
  "cacheMaxAge": 3600
}
```
```

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

### Now.sh Configuration File

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

The `now.json` file configures Now.sh deployments. This setup specifies using `@now/node` for the serverless function and routes all incoming traffic to `serverless.js`.

```json
{
    "version": 2,
    "builds": [
        { "src": "serverless.js", "use": "@now/node" }
    ],
    "routes": [
        { "src": "/.*", "dest": "/serverless.js" }
    ]
}
```

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

### Custom Meta Request Example

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

Handles meta requests when not using IMDB ID prefixes. This requires defining a 'meta' resource in the manifest.

```json
{
    "meta": [
        {
            "id": "exampleid1",
            "type": "movie",
            "name": "Big Buck Bunny",
            "poster": "https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg"
        }
    ]
}
```

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

### Define Stream Handler Example

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

Handles stream requests for movies and series. Returns a promise with stream objects or an empty array if no streams are found. Ensure to handle different content types and IDs appropriately.

```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: [] })
    }
})
```

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

### Define Catalog Handler Example

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

Handles movie catalog requests and search queries. Responds with 'Big Buck Bunny' meta for specific search terms or general movie catalog requests. Returns an empty catalog for other types or unmatching search terms.

```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 Addon Interface

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

Converts the configured addon builder into an immutable `addonInterface` object. This interface contains the addon's manifest and a `get` function for handling resource requests.

```javascript
builder.getInterface()
```

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

### Launch Addon in Stremio Web

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

Use this command to launch your addon and automatically open a web version of Stremio with the addon pre-installed. This is useful for quick testing in a browser environment.

```bash
npm start -- --launch
```

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

### Create Now.sh Serverless Handler

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

This script acts as the entry point for Now.sh serverless functions. It uses the Stremio addon SDK's router to handle incoming requests and forwards them to your addon interface.

```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();
    });
}
```

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

### Initialize Addon Builder

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

Creates an addon builder instance with a provided manifest object. The manifest defines the addon's basic information and dictates how Stremio invokes it. Invalid manifests will cause this to throw an error.

```javascript
const builder = new addonBuilder(manifest)
```

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

### Catalog Response for Movies

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

Provides a list of movies for a specific catalog. This example includes 'Big Buck Bunny' with its IMDB ID.

```json
{
    "metas": [
        {
            "id": "tt1254207",
            "type": "movie",
            "name": "Big Buck Bunny",
            "poster": "https://image.tmdb.org/t/p/w600_and_h900_bestv2/uVEFQvFMMsg4e6yb03xOfVsDz4o.jpg"
        }
    ]
}
```

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

### Define a Basic Catalog in Manifest

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

Declare a catalog resource in the addon manifest. This is the minimum configuration required to define a catalog.

```json
{
  "resources": ["catalog"],
  "catalogs": [
    {
      "id": "testcatalog",
      "type": "movie"      
    }
  ]
}
```

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

### Initialize Addon Builder

Source: https://context7.com/stremio/stremio-addon-sdk/llms.txt

Creates a new addon builder instance with a manifest defining its properties, resources, and supported content types. Configure ID prefixes, catalog definitions, and behavior hints.

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

const builder = new addonBuilder({
    id: 'org.myexampleaddon',
    version: '1.0.0',
    name: 'My Example Addon',
    description: 'An addon that provides movie streams',

    // Resources this addon provides
    resources: ['catalog', 'meta', 'stream', 'subtitles'],

    // Content types supported
    types: ['movie', 'series'],

    // Only respond to IMDB IDs (starting with 'tt')
    idPrefixes: ['tt'],

    // Catalog definitions
    catalogs: [
        {
            type: 'movie',
            id: 'topmovies',
            name: 'Top Movies',
            extra: [
                { name: 'search', isRequired: false },
                { name: 'genre', options: ['Action', 'Comedy', 'Drama'], isRequired: false },
                { name: 'skip', isRequired: false }
            ]
        }
    ],

    // Optional branding
    logo: 'https://example.com/logo.png',
    background: 'https://example.com/background.jpg',

    // Behavior hints
    behaviorHints: {
        adult: false,
        p2p: true,
        configurable: true
    }
})
```

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

### Addon Builder

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

How to create an addon builder instance with a manifest.

```APIDOC
## Addon Builder

Creates an addon builder object with a given manifest. This will throw if the manifest is not valid.

### Method

```javascript
const builder = new addonBuilder(manifest)
```

### Parameters

#### Request Body

- **manifest** (object) - Required - An object containing the addon's metadata and configuration. See [Manifest Object Definition](./api/responses/manifest.md) for details.
```

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

### Initialize Addon Builder

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

Standard initialization for a Stremio addon using the addon-sdk. Ensure the 'addon' variable is defined before exporting the interface.

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

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

### Migrate from addon.run to serveHTTP

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

For migration from v0.x, change `addon.run(opts)` to `serveHTTP(addon.getInterface(), opts)`. This is imported via `const serveHTTP = require('stremio-addon-sdk').serveHTTP`.

```javascript
const serveHTTP = require('stremio-addon-sdk').serveHTTP
```

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

### Stream Response for a Movie

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

Defines the video streams available for a given movie ID. This example provides a direct URL to the Big Buck Bunny video.

```json
{
    "streams": [
        {
            "name": "", // name is optional
            "url": "http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4"
        },
        // add more streams:
        {
            "name": "",
            "url": ""
        }
    ]
}
```

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

### Define Genre Filter Extra Property

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

Configure filtering by genre for your catalog. This example shows how to set up the 'genre' extra property with a list of predefined options.

```javascript
extra: [{ name: "genre", isRequired: false, options: ["Action", "Comedy", "Drama"] }]
```

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

### Import Stremio Addon SDK Components

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

Imports essential components from the SDK, including `addonBuilder` for defining addons, `serveHTTP` for serving the addon, `getRouter` for creating an Express router, and `publishToCentral` for publishing to the addon catalog.

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

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

### Define Catalog Handler

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

Sets up a handler for catalog requests, which includes search functionality. Refer to the API documentation for detailed information on catalog request parameters and examples.

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

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

### Define Resource Handler

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

Allows handling of custom addon catalog requests. This can be used for an addon to list other addon manifests. Refer to the API documentation for request parameters and examples.

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

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

### Create Express Router from Addon Interface

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

Transforms an `addonInterface` into an Express router. This router serves the addon according to the Stremio protocol and provides a landing page at the root URL.

```javascript
getRouter(addonInterface)
```

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

### Define Subtitles Handler

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

Configures the addon to handle subtitle requests. The handler function receives arguments and should return subtitle data. Refer to the API documentation for request parameters and examples.

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

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

### Define Meta Handler

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

Implements a handler for metadata requests, responsible for providing information such as title, release info, posters, and backgrounds. Consult the API documentation for request parameters and examples.

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

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

### Publish Addon to Central Catalog

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

Publishes the addon to the central Stremio addon catalog, making it available for users to install. This method requires a publicly accessible URL to the addon's `manifest.json` file.

```javascript
publishToCentral(url)
```

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

### Define Catalog with Pagination Support

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

Configure a catalog to support pagination by including 'skip' in its 'extra' parameters. Stremio will automatically request 'skip' when the end of the catalog is reached if 'options' are not specified.

```json
catalogs: [
  {
    "id": "testcatalog",
    "type": "movie",
    "extra": [
      {
        "name": "skip",
        "isRequired": false
      }
    ]
  }
]
```

```json
catalogs: [
  {
    "id": "testcatalog",
    "type": "movie",
    "extra": [
      {
        "name": "skip",
        "options": ["0", "100", "200"],
        "isRequired": false
      }
    ]
  }
]
```

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

### Subtitle Handling Tips

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

Provides practical tips for working with subtitles in Stremio addons, including encoding solutions and direct torrent linking.

```APIDOC
### Tips

- **Encoding Issues**: If subtitles are incorrectly encoded, set the `url` to `http://127.0.0.1:11470/subtitles.vtt?from=` followed by the subtitle file URL. This forces the local streaming server to attempt guessing the encoding.
- **Linking Subtitles within Torrents**: You can link to subtitle files directly from torrents. This requires knowing the file index of the subtitle within the torrent. The format is `http://127.0.0.1:11470/<torrent_infohash>/<file_index>`. For example: `http://127.0.0.1:11470/6366e0a6d44d49c8fa09c04669375c024e42bf7e/3`. It is recommended to use the `subtitles` property from the [Stream Object](./stream.md) when linking to subtitles inside torrents.
```

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

### User Configuration with manifest.config

Source: https://context7.com/stremio/stremio-addon-sdk/llms.txt

Defines configurable settings for users, creating an auto-generated configuration page. Access user configuration via args.config in handlers.

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

const builder = new addonBuilder({
    id: 'org.configurable.addon',
    version: '1.0.0',
    name: 'Configurable Addon',
    description: 'An addon with user settings',
    resources: ['stream'],
    types: ['movie'],
    catalogs: [],

    // Enable configuration
    behaviorHints: {
        configurable: true,
        configurationRequired: false  // Set true if addon requires config to work
    },

    // Define configuration fields
    config: [
        {
            key: 'apiKey',
            type: 'text',
            title: 'API Key',
            required: true
        },
        {
            key: 'quality',
            type: 'select',
            title: 'Preferred Quality',
            options: ['1080p', '720p', '480p'],
            default: '1080p'
        },
        {
            key: 'includeAdult',
            type: 'checkbox',
            title: 'Include Adult Content',
            default: 'false'
        },
        {
            key: 'maxResults',
            type: 'number',
            title: 'Maximum Results',
            default: '50'
        }
    ]
})

builder.defineStreamHandler(function(args) {
    // Access user configuration via args.config
    const apiKey = args.config.apiKey
    const quality = args.config.quality
    const includeAdult = args.config.includeAdult === 'true'
    const maxResults = parseInt(args.config.maxResults) || 50

    console.log(`User config: quality=${quality}, maxResults=${maxResults}`)

    // Use configuration in your handler logic
    return Promise.resolve({ streams: [] })
})

serveHTTP(builder.getInterface(), { port: 7000 })
// Configuration page available at http://127.0.0.1:7000/configure
```