Stremio Add-ons Guide

https://stremio.github.io/stremio-addon-guide/
Admin
This guide teaches developers how Stremio add-ons work and how to build one, enabling them to create...
Tokens:12,717
Snippets:147
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start and Launch the Stremio Add-on

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step1

Starts the add-on's HTTP server and launches the Stremio web client with the add-on pre-installed.

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

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

### Install and Bootstrap Stremio Add-on SDK

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step1

Installs the stremio-addon-sdk globally and bootstraps a new 'hello-world' add-on. Requires sudo on Linux.

```bash
npm install --global stremio-addon-sdk # requires "sudo" if you're on Linux
addon-bootstrap hello-world
```

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

### Navigate and Install Dependencies for New Add-on

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step1

Changes the directory to the newly created add-on project and installs its npm dependencies.

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

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

### Install and Serve Add-on with http-server

Source: https://stremio.github.io/stremio-addon-guide/step2

Install the http-server globally and then run it with CORS headers enabled and caching disabled. This is useful for development as it allows immediate availability of changes.

```bash
npm -g install http-server
http-server --cors -c-1

```

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

### Full Manifest with Meta Resource

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step3

An example of a complete add-on manifest including the meta resource definition.

```javascript
const manifest = {
    "id": "community.helloworld",
    "version": "0.0.1",
    "catalogs": [
        {
            "type": "movie",
            "id": "top"
        }
    ],
    "resources": [
        "catalog",
        {
            "name": "meta",
            "types": ["movie"],
            "idPrefixes": ["hiwrld_"]
        }
    ],
    "types": [
        "movie",
        "series"
    ],
    "name": "he",
    "description": "f"
}

```

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

### Complete Manifest with Meta Resource

Source: https://stremio.github.io/stremio-addon-guide/step4

This is an example of a complete add-on manifest file that includes the 'meta' resource definition. Ensure your manifest includes 'id', 'version', 'name', 'description', 'logo', 'resources', 'types', and 'catalogs'.

```json
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [
        "catalog",
        {
            "name": "meta",
            "types": ["movie"],
            "idPrefixes": ["hiwrld_"]
        }
    ],
    "types": ["movie"],
    "catalogs": [
        {"id": "movieCatalog", "type": "movie", "name": "Hello, Movies"}
    ]
}

```

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

### Complete Manifest with Search Enabled

Source: https://stremio.github.io/stremio-addon-guide/step7

This is an example of a complete `manifest.json` file with the search capability added to the movie catalog.

```json
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [
        "catalog",
        {
            "name": "meta",
            "types": ["movie", "series"],
            "idPrefixes": ["hiwrld_"]
        },
        "stream"
    ],
    "types": ["movie", "series"],
    "catalogs": [
        {
            "id": "movieCatalog", "type": "movie", "name": "Hello, Movies",
            "extra": [
                { "name": "search", "isRequired": false }
            ]

        },
        {"id": "seriesCatalog", "type": "series", "name": "Hello, TV Shows"}
    ]
}

```

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

### Publish Add-on to Stremio Central

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step5

Call the `publishToCentral` method at startup to make your add-on appear in the Stremio Community add-ons list. Ensure you replace the example URL with your add-on's actual manifest URL.

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

publishToCentral('https://example.com/manifest.json')
```

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

### Create Filtered Catalog for 'Adventure' Genre

Source: https://stremio.github.io/stremio-addon-guide/step7

Create a JSON file for a specific genre to serve only matching meta items. This example includes 'The Wizard of Oz' in the 'Adventure' genre catalog.

```json
{
    "metas": [
        { "type": "movie", "id": "tt0032138", "name": "The Wizard of Oz", "poster": "https://images.metahub.space/poster/medium/tt0032138/img", "genres": ["Adventure", "Family", "Fantasy", "Musical"] }
    ]
}

```

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

### Define a Meta Item for a Movie

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step3

Example of a meta item object for a movie, including basic details like ID, type, name, poster, and genres.

```javascript
{
    id: "hiwrld_jellyfish",
    type: "movie",
    name: "Jellyfish",
    poster: "https://images.unsplash.com/photo-1496108493338-3b30de66f9be",
    genres: ["Demo", "Nature"]
}

```

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

### Add-on Resource Hierarchy

Source: https://stremio.github.io/stremio-addon-guide/basics

Illustrates the hierarchical structure of media content provided by a Stremio add-on, starting from Catalogs down to Streams.

```text
Catalog
+-- Type
    +-- Meta Item
        +-- Videos
        +--+-- Streams
```

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

### Create manifest.json using Windows CMD

Source: https://stremio.github.io/stremio-addon-guide/step1

This snippet demonstrates how to create a manifest.json file using Windows command prompt. It includes creating a directory, changing into it, and using 'copy con' to input the manifest content.

```cmd
mkdir my-stremio-addon  
cd my-stremio-addon  
copy con manifest.json  
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [],
    "types": []
}  
^Z  
```

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

### Create manifest.json using Bash

Source: https://stremio.github.io/stremio-addon-guide/step1

This snippet shows how to create a manifest.json file using bash commands. It involves creating a directory, navigating into it, and using 'cat' to input the manifest content.

```bash
mkdir my-stremio-addon  
cd my-stremio-addon  
cat > manifest.json  
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [],
    "types": []
}  
^D  
```

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

### Create Catalog Directory (Bash)

Source: https://stremio.github.io/stremio-addon-guide/step3

Use the 'mkdir -p' command in bash to create the necessary directory structure for your catalog files. This ensures the parent directories are created if they don't exist.

```bash
mkdir -p catalog/movie  

```

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

### Create Directory for Search Results (CMD)

Source: https://stremio.github.io/stremio-addon-guide/step7

Use this Windows CMD command to create the necessary directory structure for serving static search results. This is a prerequisite for the `copy` command.

```cmd
mkdir catalog\movie\movieCatalog  
copy catalog\movie\movieCatalog.json catalog\movie\movieCatalog\search=hello.json  

```

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

### Create Directory for Search Results (Bash)

Source: https://stremio.github.io/stremio-addon-guide/step7

Use this bash command to create the necessary directory structure for serving static search results. This is a prerequisite for the `copy` command.

```bash
mkdir catalog/movie/movieCatalog  
cp catalog/movie/movieCatalog.json catalog/movie/movieCatalog/search=hello.json  

```

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

### Create Series Catalog Directory (Bash)

Source: https://stremio.github.io/stremio-addon-guide/step6

Use this command to create the directory for your series catalog files.

```bash
mkdir catalog/series  

```

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

### Create Series Meta Directory (Windows)

Source: https://stremio.github.io/stremio-addon-guide/step6

Use this command to create a directory for series meta files on Windows systems.

```cmd
mkdir meta\series  
```

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

### Create Series Meta Directory (Unix)

Source: https://stremio.github.io/stremio-addon-guide/step6

Use this command to create a directory for series meta files on Unix-like systems.

```bash
mkdir meta/series  
```

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

### Create Catalog Directory (CMD)

Source: https://stremio.github.io/stremio-addon-guide/step3

Use the 'mkdir' command in Windows CMD to create the directory for your movie catalog. This command creates the specified directory.

```cmd
mkdir catalog\movie  

```

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

### Create Movie Metadata Directory (Linux/macOS)

Source: https://stremio.github.io/stremio-addon-guide/step4

Use this command to create the necessary directory structure for storing movie metadata files on Linux or macOS systems.

```bash
mkdir -p meta/movie
```

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

### Create Movie Metadata Directory (Windows)

Source: https://stremio.github.io/stremio-addon-guide/step4

Use this command to create the necessary directory structure for storing movie metadata files on Windows systems.

```bash
mkdir meta\movie
```

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

### Create Series Stream Directory (Windows CMD)

Source: https://stremio.github.io/stremio-addon-guide/step6

Use this command in the Windows Command Prompt to create the directory for series streams.

```cmd
mkdir stream\series
```

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

### Create Series Catalog Directory (CMD)

Source: https://stremio.github.io/stremio-addon-guide/step6

Use this command to create the directory for your series catalog files on Windows.

```cmd
mkdir catalog\series  

```

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

### Add-on Manifest with Catalog Configuration

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

This snippet shows the necessary fields in the add-on manifest to enable catalog resources and define a catalog. Ensure 'catalog' is in 'resources' and at least one entry exists in 'catalogs'.

```javascript
// Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/manifest.md
const manifest = {
    "id": "community.helloworld",
    "version": "0.0.1",
    "catalogs": [
        {
            "type": "movie",
            "id": "top"
        }
    ],
    "resources": [
        "catalog"
    ],
    "types": [
        "movie",
        "series"
    ],
    "name": "he",
    "description": "f"
}

```

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

### Populate Movie Catalog

Source: https://stremio.github.io/stremio-addon-guide/step3

Create a JSON file named after your catalog ID (e.g., 'movieCatalog.json') within the appropriate directory (e.g., 'catalog/movie/'). This file should contain a 'metas' array, where each object represents a movie with its type, ID, name, poster URL, and genres.

```json
{
    "metas": [
        { "type": "movie", "id": "tt0032138", "name": "The Wizard of Oz", "poster": "https://images.metahub.space/poster/medium/tt0032138/img", "genres": ["Adventure", "Family", "Fantasy", "Musical"] },
        { "type": "movie", "id": "tt0017136", "name": "Metropolis", "poster": "https://images.metahub.space/poster/medium/tt0017136/img", "genres": ["Drama", "Sci-Fi"] }
    ]
}

```

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

### Publish Add-on using Curl

Source: https://stremio.github.io/stremio-addon-guide/step8

Use this command-line snippet with curl to publish your add-on by providing its transport URL and name. Ensure the URL points to a valid add-on manifest.

```bash
curl -d '{"transportUrl": "https://example.com/manifest.json", "transportName": "http"}' -w '\n' -H 'Content-Type: application/json' -X POST 'https://api.strem.io/api/addonPublish'  

```

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

### Create Stream Directory (Windows CMD)

Source: https://stremio.github.io/stremio-addon-guide/step5

Use this command to create the necessary directory structure for storing stream JSON files on Windows.

```cmd
mkdir stream\movie
```

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

### Create Series Stream Directory (Bash)

Source: https://stremio.github.io/stremio-addon-guide/step6

Use this command in a Bash environment to create the directory for series streams.

```bash
mkdir stream/series
```

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

### Basic Stremio Add-on Manifest

Source: https://stremio.github.io/stremio-addon-guide/step1

This is the minimal required manifest for a Stremio add-on. It includes essential fields like id, version, name, and description.

```json
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [],
    "types": []
}
```

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

### Catalog Description with Skip Option

Source: https://stremio.github.io/stremio-addon-guide/step7

Configure your catalog with the 'skip' extra option to enable pagination. This allows Stremio to request subsequent pages of results.

```json
{
    "id": "movieCatalog", "type": "movie", "name": "Hello, Movies",
    "extra": [
        { "name": "search", "isRequired": false },
        { "name": "genre", "isRequired": false },
        { "name": "skip", "isRequired": false }
    ],
    "genres" : ["Adventure", "Family", "Sci-Fi", "Demo"]
}

```

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

### Declare Meta Resource in Manifest

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step3

Update your add-on's manifest to declare that it provides metadata for specific content types. Use `idPrefixes` to filter which IDs your add-on will handle.

```json
"resources": [
    "catalog",
    {
        "name": "meta",
        "types": ["movie"],
        "idPrefixes": ["hiwrld_"]
    }
]

```

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

### Define Multiple Catalogs in Manifest

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Specify multiple catalog entries in your add-on's manifest to provide different types of content.

```json
"catalogs": [
        { "type": "movie", "id": "top-by-popularity" },
        { "type": "movie", "id": "top-by-rating" },
        { "type": "series", "id": "top-by-popularity" },
        { "type": "series", "id": "top-by-rating" },
    ],
```

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

### Publish Add-on using PowerShell

Source: https://stremio.github.io/stremio-addon-guide/step8

This PowerShell snippet allows you to publish your add-on. It sends the add-on's transport URL and name in a JSON format to the Stremio API. Verify that the transport URL is correct.

```powershell
Invoke-RestMethod -Body (@{transportUrl="https://example.com/manifest.json"; transportName="http"} | ConvertTo-Json) -Method 'Post' -ContentType "application/json" -Uri "https://api.strem.io/api/addonPublish"  

```

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

### Create Stream Directory (Bash)

Source: https://stremio.github.io/stremio-addon-guide/step5

Use this command to create the necessary directory structure for storing stream JSON files.

```bash
mkdir -p stream/movie
```

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

### Catalog Handler with Search, Genre, and Pagination

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Combine search, genre filtering, and pagination logic in your catalog handler. Prioritize search and genre filtering before applying pagination.

```javascript
builder.defineCatalogHandler(({type, id, extra}) => {
    let results;

    switch(type) {
        case "movie":
            results = getMoviesCatalog(id)
            break
       default:
            results = Promise.resolve( [] )
            break
    }
    if(extra.search) {
        return results.then(items => {
            metas: items.filter(meta => meta.name
            .toLowercase()
            .includes(extra.search.toLowercase()))
        })
    } else if(extra.genre) {
        return results.then(items => ({
            metas: items.filter(meta => meta.genres
            .includes(extra.genre))
        }))
    }

    const skip = extra.skip || 0;
    return results.then(items => ({
        metas: items.slice(skip, skip + 100)
    }))
 })
```

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

### Provide Detailed Movie Metadata

Source: https://stremio.github.io/stremio-addon-guide/step4

Create a JSON file for a specific meta ID (e.g., 'hiwrld_jellyfish.json') within the 'meta/movie' directory. This file contains rich metadata that Stremio will display to the user.

```json
{
    "meta": {
        "id": "hiwrld_jellyfish",
        "type": "movie",
        "name": "Jellyfish",
        "poster": "https://images.unsplash.com/photo-1496108493338-3b30de66f9be",
        "genres": ["Demo", "Nature"],
        "description": "A .mkv video clip useful for testing the network streaming and playback performance of media streamers & HTPCs.",
        "cast": ["Some random jellyfishes"],
        "director": ["ScottAllyn"],
        "logo": "https://b.kisscc0.com/20180705/yee/kisscc0-art-forms-in-nature-jellyfish-recapitulation-theor-jellyfish-5b3dcabcb00692.802484341530776252721.png",
        "background": "https://images.unsplash.com/photo-1461783470466-185038239ee3",
        "runtime": "30 sec"
    }
}
```

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

### Catalog Handler with Pagination Logic

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Implement pagination logic in your catalog handler using the 'skip' property from the 'extra' object to return items in chunks.

```javascript
builder.defineCatalogHandler(({type, id, extra}) => {
    let results;

    switch(type) {
        case "movie":
            results = getMoviesCatalog(id)
            break
       default:
            results = Promise.resolve( [] )
            break
    }

    const skip = extra.skip || 0;
    return results.then(items => ({
        metas: items.slice(skip, skip + 100)
    }))
})
```

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

### Provide Stream Data for First Series Episode

Source: https://stremio.github.io/stremio-addon-guide/step6

This JSON object defines the stream for the first episode of a series, linking to a YouTube video.

```json
{
    "streams": [
        { "title": "YouTube", "ytId": "5EQw5NYlbyE" }
    ]
}
```

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

### Enable Searching in Catalog Definition

Source: https://stremio.github.io/stremio-addon-guide/step7

Add the 'search' extra to a catalog definition in your add-on's manifest to enable searching. 'isRequired: false' makes searching optional.

```json
"catalogs": [
    {
        "id": "movieCatalog", "type": "movie", "name": "Hello, Movies",
        "extra": [
            { "name": "search", "isRequired": false }
        ]
    },
    {"id": "seriesCatalog", "type": "series", "name": "Hello, TV Shows"}
]

```

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

### Update Manifest with Stream Resource

Source: https://stremio.github.io/stremio-addon-guide/step5

Append 'stream' to the resources array in your add-on's manifest to enable stream functionality.

```json
"resources": [
    "catalog",
    {
        "name": "meta",
        "types": ["movie"],
        "idPrefixes": ["hiwrld_"]
    },
    "stream"
]
```

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

### Stremio Server Log for Search Query

Source: https://stremio.github.io/stremio-addon-guide/step7

This log entry shows how Stremio queries your add-on's catalog when a user performs a search. The 'Error (404): "Not found"' indicates that the specific search route has not been implemented yet.

```text
"GET /catalog/movie/movieCatalog/search=jellyfish.json" Error (404): "Not found"

```

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

### Stream Objects with Direct URLs

Source: https://stremio.github.io/stremio-addon-guide/step5

Define multiple stream objects for a video using direct URLs. This allows for various quality and format options.

```json
{
    "streams": [
        { "title": "Web, 3 MBps, HD", "url": "http://jell.yfish.us/media/jellyfish-3-mbps-hd-h264.mkv" },
        { "title": "Web 15 MBps, HD", "url": "http://jell.yfish.us/media/jellyfish-15-mbps-hd-h264.mkv" },
        { "title": "Web, 120 MBps, 4K", "url": "http://jell.yfish.us/media/jellyfish-120-mbps-4k-uhd-h264.mkv" }
    ]
}
```

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

### Populate Series Catalog

Source: https://stremio.github.io/stremio-addon-guide/step6

Define the series metadata, including ID, name, poster, and genres, in the series catalog JSON file.

```json
{
    "metas": [
        { "type": "series", "id": "tt1748166", "name": "Pioneer One", "poster": "https://images.metahub.space/poster/medium/tt1748166/img", "genres": ["Drama", "Sci-Fi"]},
        { "type": "series", "id": "hiwrld_tt0147753", "name": "Captain Z-Ro", "poster": "https://www.captain-z-ro.com/images/FLYER-PAGE-1_250.gif", "genres": ["Sci-Fi", "Children", "Educational"] }
    ]
}

```

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

### Update Manifest for Catalog Resource

Source: https://stremio.github.io/stremio-addon-guide/step3

Modify your add-on's manifest to include 'catalog' in the resources array, define the 'types' your add-on supports, and specify catalog details in the 'catalogs' array. This allows Stremio to recognize and display your add-on's catalogs.

```json
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": ["catalog"],
    "types": ["movie"],
    "catalogs": [
        {"id": "movieCatalog", "type": "movie", "name": "Hello, Movies"}
    ]
}

```

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

### Enable Searching with 'search' Extra Property

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Include the 'search' extra property in your catalog definition to allow users to search within your catalog. 'isRequired: false' makes searching optional.

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

```

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

### Update Manifest for Series Support

Source: https://stremio.github.io/stremio-addon-guide/step6

Modify your manifest.json to include 'series' in the 'resources', 'types', and 'catalogs' arrays to support TV shows.

```json
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [
        "catalog",
        {
            "name": "meta",
            "types": ["movie", "series"],
            "idPrefixes": ["hiwrld_"]
        },
        "stream"
    ],
    "types": ["movie", "series"],
    "catalogs": [
        {"id": "movieCatalog", "type": "movie", "name": "Hello, Movies"},
        {"id": "seriesCatalog", "type": "series", "name": "Hello, TV Shows"}
    ]
}

```

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

### Function to Populate Movie Catalog

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

This function retrieves movie data for a specific catalog ID. It returns a Promise resolving to an array of movie meta objects.

```javascript
// Populate the catalog from somewhere
function getMoviesCatalog(catalogName) {
    let catalog;

    switch(catalogName) {
        case "top":
            catalog = [
                {
                    id: "tt1254207",
                    type: "movie",
                    name: "The Big Buck Bunny",
                    poster: "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c5/Big_buck_bunny_poster_big.jpg/220px-Big_buck_bunny_poster_big.jpg",
                    genres: [ "Animation", "Short", "Comedy" ]
                },
            ]
            break
        default:
            catalog = []
            break
    }

    return Promise.resolve(catalog)
}

```

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

### Enable Pagination with 'skip' Extra Property

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Add the 'skip' extra property to your catalog definition to enable pagination. This property is passed to the handler to control item slicing.

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

```

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

### Update Stremio Add-on Manifest with Catalogs

Source: https://stremio.github.io/stremio-addon-guide/step7

Modify your add-on's manifest to include the 'catalogs' section, defining different types of catalogs like movies and series, and specifying genre filters for movie catalogs.

```json
{
    "id": "my.first.stremio.add-on",
    "version": "1.0.0",
    "name": "Hello, World",
    "description" : "My first Stremio add-on",
    "logo": "https://www.stremio.com/website/stremio-logo-small.png",
    "resources": [
        "catalog",
        {
            "name": "meta",
            "types": ["movie", "series"],
            "idPrefixes": ["hiwrld_"]
        },
        "stream"
    ],
    "types": ["movie", "series"],
    "catalogs": [
        {
            "id": "movieCatalog", "type": "movie", "name": "Hello, Movies",
            "extra": [
                { "name": "search", "isRequired": false },
                { "name": "genre", "isRequired": false }
            ],
            "genres" : ["Adventure", "Family", "Sci-Fi", "Demo"]
        },
        {"id": "seriesCatalog", "type": "series", "name": "Hello, TV Shows"}
    ]
}

```

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

### Implement Meta Handler Function

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step3

Function to retrieve movie metadata by ID. It returns a promise resolving to the meta object or null if not found.

```javascript
function getMovieMeta(id) {
    const metas = {
        hiwrld_jellyfish: {
            id: "hiwrld_jellyfish",
            type: "movie",
            name: "Jellyfish",
            poster: "https://images.unsplash.com/photo-1496108493338-3b30de66f9be",
            genres: ["Demo", "Nature"],
            description: "A .mkv video clip useful for testing the network streaming and playback performance of media streamers & HTPCs.",
            cast: ["Some random jellyfishes"],
            director: ["ScottAllyn"],
            logo: "https://b.kisscc0.com/20180705/yee/kisscc0-art-forms-in-nature-jellyfish-recapitulation-theor-jellyfish-5b3dcabcb00692.802484341530776252721.png",
            background: "https://images.unsplash.com/photo-1461783470466-185038239ee3",
            runtime: "30 sec"
        },
    }
    return Promise.resolve(metas[id] || null)
}

```

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

### Updated Catalog Structure

Source: https://stremio.github.io/stremio-addon-guide/step4

This shows the complete catalog structure after adding the custom 'Jellyfish' movie entry alongside existing IMDB-indexed movies.

```json
{
    "metas": [
        { "type": "movie", "id": "tt0032138", "name": "The Wizard of Oz", "poster": "https://images.metahub.space/poster/medium/tt0032138/img", "genres": ["Adventure", "Family", "Fantasy", "Musical"] },
        { "type": "movie", "id": "tt0017136", "name": "Metropolis", "poster": "https://images.metahub.space/poster/medium/tt0017136/img", "genres": ["Drama", "Sci-Fi"] },
        {
            "id": "hiwrld_jellyfish",
            "type": "movie",
            "name": "Jellyfish",
            "poster": "https://images.unsplash.com/photo-1496108493338-3b30de66f9be",
            "genres": ["Demo", "Nature"]
        }
    ]
}
```

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

### Handle Empty Genre Catalog

Source: https://stremio.github.io/stremio-addon-guide/step7

Return an empty 'metas' array when a genre filter is applied but no content is available for that genre. This prevents errors and provides a valid response.

```json
{
    "metas": []
}

```

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

### Define Meta Handler with Builder

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step3

Register the meta handler using the add-on SDK builder. This function is called by Stremio to fetch metadata for a given ID and type.

```javascript
builder.defineMetaHandler(({type, id}) => {
    // Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineMetaHandler.md
    let results;

    switch(type) {
        case 'movie':
            results = getMovieMeta(id)
            break
       default:
            results = null
            break
    }
    return Promise.resolve({ meta: results })
})

```

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

### Implement Movie Stream Handler

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step4

Create a function to retrieve stream information for a given movie ID. It returns a promise resolving to an array of stream objects.

```javascript
function getMovieStreams(id) {
    const streams = {
        tt1254207: [
            { "title": "HTTP location", "yt_ID": "aqz-KE-bpKQ"}
        ]
        hiwrld_jellyfish: [
            { "title": "Web, 3 MBps, HD", "url": "http://jell.yfish.us/media/jellyfish-3-mbps-hd-h264.mkv" },
            { "title": "Web 15 MBps, HD", "url": "http://jell.yfish.us/media/jellyfish-15-mbps-hd-h264.mkv" },
            { "title": "Web, 120 MBps, 4K", "url": "http://jell.yfish.us/media/jellyfish-120-mbps-4k-uhd-h264.mkv" }
        ]
    }
    return Promise.resolve(streams[id] || [])
}
```

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

### Catalog Handler with Search Logic

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Add search functionality to your catalog handler by checking for the 'search' property in the 'extra' object and filtering results accordingly.

```javascript
builder.defineCatalogHandler(({type, id, extra}) => {
    let results;

    switch(type) {
        case "movie":
            results = getMoviesCatalog(id)
            break
       default:
            results = Promise.resolve( [] )
            break
    }
    if(extra.search) {
        return results.then(items => ({
            metas: items.filter(meta => meta.name
            .toLowercase()
            .includes(extra.search.toLowercase()))
        }))
    }

    const skip = extra.skip || 0;
    return results.then(items => ({
        metas: items.slice(skip, skip + 100)
    }))
 })
```

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

### Add Genre Filter to Catalog Manifest

Source: https://stremio.github.io/stremio-addon-guide/step7

Include a 'genres' array in your catalog definition within the manifest to specify the genres your add-on supports. Ensure 'isRequired' is false for 'genre' extra parameters to avoid catalog rejection.

```json
{
    "id": "movieCatalog", "type": "movie", "name": "Hello, Movies",
    "extra": [
        { "name": "search", "isRequired": false },
        { "name": "genre", "isRequired": false }
    ],
    "genres" : ["Adventure", "Family", "Sci-Fi", "Demo"]
}

```

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

### Publish Add-on

Source: https://stremio.github.io/stremio-addon-guide/step8

This API endpoint allows you to publish your Stremio add-on to the community add-ons list. It requires the transport URL of your add-on's manifest.

```APIDOC
## POST /api/addonPublish

### Description
Publishes a Stremio add-on to the community add-ons list.

### Method
POST

### Endpoint
https://api.strem.io/api/addonPublish

### Parameters
#### Request Body
- **transportUrl** (string) - Required - The URL where the add-on manifest is hosted.
- **transportName** (string) - Required - The transport method, typically "http".

### Request Example
```json
{
  "transportUrl": "https://example.com/manifest.json",
  "transportName": "http"
}
```

### Response
#### Success Response (200)
This endpoint does not specify a success response body in the documentation. It is assumed to be a success if no error is returned.

#### Response Example
(No example provided in source)
```

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

### Update Manifest for Streams

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step4

Ensure your add-on's manifest includes 'streams' in the resources array to handle stream requests.

```json
"resources": [
    "catalog",
    {
        "name": "meta",
        "types": ["movie"],
        "idPrefixes": ["hiwrld_"]
    },
    "streams"
]
```

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

### Provide Stream Data for Second Series Episode

Source: https://stremio.github.io/stremio-addon-guide/step6

This JSON object defines the stream for the second episode of a series, linking to a YouTube video.

```json
{
    "streams": [
        { "title": "YouTube", "ytId": "ZzdBKcVzx9Y" }
    ]
}
```

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

### Define Stream Handler in Add-on Builder

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step4

Use the add-on builder to define how your add-on handles stream requests based on type and ID. Return an empty array for unsupported types or when no streams are found.

```javascript
builder.defineStreamHandler(({type, id}) => {
    // Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineStreamHandler.md
    let results;

    switch(type) {
        case 'movie':
            results = getMovieStreams(id)
            break
       default:
            results = Promise.resolve( [] )
            break
    }
    return results.then(streams => ({streams}))
})
```

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

### Enable Genre Filtering with 'genre' Extra Property

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

Configure genre filtering by adding the 'genre' extra property and a 'genres' array to your catalog definition. Ensure only one 'extra' property is 'isRequired: true'.

```json
"catalogs": [
    {
        "type": "movie",
        "id": "top",
        "extra": [
            { "name": "search", "isRequired": false },
            { "name": "genre", "isRequired": false },
        ],
        "genres": [ "Animation", "Comedy" ]
    },
],

```

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

### Create Filtered Catalog for 'Family' Genre with Multiple Items

Source: https://stremio.github.io/stremio-addon-guide/step7

Populate a catalog for the 'Family' genre with multiple items, including 'The Wizard of Oz' and 'Jellyfish'. Note that 'Jellyfish' will appear even if its listed genres don't strictly match 'Family'.

```json
{
    "metas": [
        { "type": "movie", "id": "tt0032138", "name": "The Wizard of Oz", "poster": "https://images.metahub.space/poster/medium/tt0032138/img", "genres": ["Adventure", "Family", "Fantasy", "Musical"] },
        {
            "id": "hiwrld_jellyfish",
            "type": "movie",
            "name": "Jellyfish",
            "poster": "https://images.unsplash.com/photo-1496108493338-3b30de66f9be",
            "genres": ["Demo", "Nature"]
        }
    ]
}

```

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

### Stream Object with Torrent Info Hash

Source: https://stremio.github.io/stremio-addon-guide/step5

Define a stream object for a video using its torrent info hash. This is suitable for peer-to-peer streaming.

```json
{
    "streams": [
        { "title": "Torrent", "infoHash": "1588987DB4C7D98F74FB436AD8FEDE1CBE9F1F63" }
    ]
}
```

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

### Stremio Request for Next Page

Source: https://stremio.github.io/stremio-addon-guide/step7

When a user scrolls past the last item on a page, Stremio will request the next batch of data using the 'skip' parameter. Ensure your add-on responds to these requests.

```http
GET /catalog/movie/movieCatalog.json

```

```http
GET /catalog/movie/movieCatalog/skip=100.json

```

```http
GET /catalog/movie/movieCatalog/skip=200.json

```

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

### Create Filtered Catalog for 'Sci-Fi' Genre

Source: https://stremio.github.io/stremio-addon-guide/step7

Define a catalog for the 'Sci-Fi' genre, including only 'Metropolis'. This demonstrates how to create genre-specific content lists.

```json
{
    "metas": [
        { "type": "movie", "id": "tt0017136", "name": "Metropolis", "poster": "https://images.metahub.space/poster/medium/tt0017136/img", "genres": ["Drama", "Sci-Fi"] }
    ]
}

```

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

### Series Meta JSON Structure

Source: https://stremio.github.io/stremio-addon-guide/step6

Define the meta information for a series, including general details and a list of episodes. This structure is used for each series in your catalog.

```json
{
    "meta": {
            "id": "hiwrld_tt0147753",
            "type": "series",
            "name": "Captain Z-Ro",
            "description": "From his secret laboratory, Captain Z-Ro and his associates use their time machine, the ZX-99, to learn from the past and plan for the future.",
            "releaseInfo": "1955-1956",
            "logo": "https://fanart.tv/fanart/tv/70358/hdtvlogo/captain-z-ro-530995d5e979d.png",
            "imdbRating": 6.9,
            "poster": "https://www.captain-z-ro.com/images/FLYER-PAGE-1_250.gif",
            "background": "https://www.captain-z-ro.com/images/Captain-Z--R0_500.jpg",
            "genres": ["Sci-Fi", "Children", "Educational"],
            "runtime": "15 mins.",
            "videos": [
                { "season": 1, "episode": 1, "id": "hiwrld_tt0147753:1:1", "title": "Christopher Columbus", "released": "1955-12-18" },
                { "season": 1, "episode": 2, "id": "hiwrld_tt0147753:1:2", "title": "Daniel Boone", "released": "1955-12-25" }
            ]
    }
}

```

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

### Define Stremio Catalog Handler

Source: https://stremio.github.io/stremio-addon-guide/sdk-guide/step2

This snippet defines the handler for catalog requests. It uses the 'getMoviesCatalog' function to fetch data based on the requested type and ID, returning metas in the expected format.

```javascript
// Docs: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineCatalogHandler.md
builder.defineCatalogHandler(({type, id}) => {
    let results;

    switch(type) {
        case "movie":
            results = getMoviesCatalog(id)
            break
       default:
            results = Promise.resolve( [] )
            break
    }

    return results.then(items => ({
        metas: items
    }))
})

```

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

### Add Custom Movie to Catalog

Source: https://stremio.github.io/stremio-addon-guide/step4

Append this JSON object to your catalog's 'metas' array to include a new movie, particularly useful for items not indexed by IMDB.

```json
{
    "id": "hiwrld_jellyfish",
    "type": "movie",
    "name": "Jellyfish",
    "poster": "https://images.unsplash.com/photo-1496108493338-3b30de66f9be",
    "genres": ["Demo", "Nature"]
}
```

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

### Stream Object with YouTube ID

Source: https://stremio.github.io/stremio-addon-guide/step5

Define a stream object for a video using its YouTube ID. This is used for linking to YouTube videos.

```json
{
    "streams": [
        { "title": "YouTube", "ytId": "AvtWDIZtrAE" }
    ]
}
```
Tokens:
Raw