DOCSEARCHbyAlgolia
Submit Docs

Stremio Addon SDK

repository·master·Indexed 22 days ago

https://github.com/stremio/stremio-addon-sdk

A Node.js toolkit for creating and publishing add-ons for the Stremio streaming platform. The SDK provides tools like addonBuilder for defining manifests and resource handlers (catalog, metadata, streams, and subtitles), serveHTTP for hosting the addon, and addon-bootstrap for project scaffolding. It includes guides for deploying to platforms such as Beamup, Heroku, and Glitch, and supports integration with Express via getRouter.

Tokens
20K
Snippets
35
Records
94
Agent score
79%

What's inside stremio-addon-sdk

  1. Understand Stremio addon resource types

    master

    To display data in Stremio, an addon must provide specific resources. The manifest is the only mandatory resource. Other optional resources allow your addon to provide content like catalogs, detailed metadata, streams, and subtitles.

    ResourceHandlerResponseDescription
    manifest-manifestThe addon description and capabilities.
    catalogdefineCatalogHandlermeta_previewSummarized collection of meta preview items. Used in Board, Discover, and Search.
    metadatadefineMetaHandlermetaDetailed description of a meta item (shown on the Detail page).
    streamsdefineStreamHandlerstreamInstructions on how to obtain media content (e.g., torrent info hash, HTTP URL).
    subtitlesdefineSubtitlesHandlersubtitlesSubtitles for the chosen media.
    addon_catalogdefineResourceHandleraddon_catalogA catalog (list) of other addon manifests.

  2. Configure Resource Filtering with resources, types, and idPrefixes

    master

    You can control which requests your addon responds to using filtering properties.

    • resources: An array of supported resources (e.g., ["catalog", "meta", "stream", "subtitles", "addon_catalog"]).
    • types: An array of supported content types (e.g., ["movie", "series"]).
    • idPrefixes: An optional array of strings. If set, your addon will only be called for IDs starting with these prefixes (e.g., ["tt"] for IMDb IDs).

    Advanced Resource Configuration: Instead of using strings for resources, you can use objects to provide specific types and idPrefixes for a particular resource. This allows different settings for different resources.

    Example of a complex resource: { "name": "stream", "types": [ "movie" ], "idPrefixes": [ "tt" ] }

  5. Beamup deployment requirements and constraints

    master

    To ensure a successful deployment to Beamup, your project must adhere to the following requirements:

    Server Configuration

    • Your project must support using the PORT environment variable as the HTTP server port if it is provided.

    Build System

    • Beamup is based on Dokku. Your repository must support a Heroku buildpack or include a Dockerfile.
    • For Node.js projects, simply having a package.json in the repository is usually sufficient.
    • Note on Buildpacks: Currently, only projects using the Dokku 'Herokuish' buildpack are supported. If you are using a project built with the Dokku 'Dockerfile' buildpack, you can use the workaround of including docker in your project name.

    Limitations

    • Custom NGINX configurations are not supported.

    Language Support

    • Beamup supports any programming language; Node.js is not a requirement for building addons.

  6. How Stremio data flows from Catalog to Subtitles

    master

    Stremio follows a hierarchical data structure to load content as a user navigates the interface:

    1. Catalog: When a user opens Discover or the Board, Stremio loads catalog resources from all installed addons. These return meta_preview objects (stripped-down versions of full meta items).
    2. Meta Item: When a user selects an item, the Detail page opens and requests the full metadata object.
    3. Videos/Streams: When a user selects a specific video (like an episode), Stremio requests streams. For movies (which have only one video object), streams are requested immediately upon opening the Detail page.
    4. Subtitles: Once a stream is active, subtitles can be requested for that media.

    Hierarchy: Catalog $\rightarrow$ Meta Item $\rightarrow$ Videos $\rightarrow$ Streams $\rightarrow$ Subtitles

  7. Understand Archive and Usenet Source Limitations

    master

    When providing streams via archives or Usenet, be aware of the following technical constraints:

    Source TypeMulti-volumeDecompressionSeeking Support
    NZBN/ASupported (unpacks archives)Partial (requires first/last segments)
    RARSupportedNot supportedSupported
    ZIPSupportedSupportedNot supported
    7zipSupportedSupported (LZMA)Supported only if no compression used
    TGZSupportedSupportedNot supported
    TARNot supportedNot supportedSupported

    Additional Notes:

    • NZB: PAR2 recovery is not supported.
    • File Selection: For archives (NZB, RAR, ZIP, etc.), you can use fileIdx to specify the video file. You can also use fileMustInclude (a regex string like "/.mkv$|.mp4$/i") to match a specific file type, though this is not yet supported for torrents.

  8. Implement Crawler or Scraping Addons

    master

    To build an addon that scrapes data from web pages, you need to download the HTML source and parse it.

    Commonly used Node.js modules for this include:

    • needle: For making HTTP requests to fetch HTML.
    • cheerio: To provide a jQuery-like syntax for parsing the DOM.
    • jsdom: For a full DOM implementation.
    • xpath: For navigating XML/HTML via XPath expressions.

  9. Use User Data via Addon Repository URL

    master

    The Addon SDK supports passing user-specific data through the Addon Repository URL. Instead of a standard manifest URL, users install via a URL containing a parameter segment.

    Example URL structure: https://www.mydomain.com/{someParameter}/manifest.json

    This is useful for:

    • Authentication: Passing an API token (e.g., https://domain.com/TOKEN/manifest.json).
    • Personalization: Passing user preferences.
    • Proxying: Passing the ID of another addon to create a proxy addon that modifies stream URLs (e.g., for Real Debrid).
    // Example using Express to capture the parameter
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) {
  // Use req.params.someParameter to identify the user or target addon
  res.send({ streams: [] })
})

addon.listen(7000)

  10. Understand the Stremio Addon Protocol

    master

    The Stremio addon protocol is a universal interface for describing multimedia content (catalogs, metadata, and streams) via a REST-like paradigm. Addons are typically transported over HTTP or IPFS.

    Core Requirements:

    • An HTTP server/endpoint serving a /manifest.json file.
    • Responses to resource requests at /{resource}/{type}/{id}.json.
    • CORS: Every route, including /manifest.json, must serve CORS headers that allow all origins.
    • Minimum Viable Addon: Must provide at least one resource and a manifest.

    Supported Resources:

    • catalog: Catalogs of media items. Path: /catalog/{type}/{id}.json. id is a custom catalog ID specified in your manifest.
    • meta: Detailed metadata for an item. Path: /meta/{type}/{id}.json. id is the item ID found in the catalog.
    • stream: List of streams for an item. Path: /stream/{type}/{videoID}.json. For single-video items (like movies), videoID equals the item ID.
    • subtitles: List of subtitles. Path: /subtitles/{type}/{id}.json. Here, id is the Open Subtitles file hash, while extraArgs is used for videoID and videoSize.

  11. How addonBuilder and addonInterface work together

    master

    The addonBuilder is the primary tool for constructing an addon. You use it to define the manifest and register handlers for different Stremio resources.

    Once configured, you call builder.getInterface() to obtain an addonInterface. The addonInterface is an immutable (frozen) object containing:

    • manifest: The addon's manifest object.
    • get({ resource, type, id, extra }): A function that returns a Promise resolving to the requested resource data.

    This interface is what you pass to serveHTTP or getRouter to actually expose your addon to the network.

  12. Requirements for remote addon deployment

    master

    When deploying an addon to a remote server (not 127.0.0.1), you must ensure:

    1. HTTPS: The addon URL must be loaded via https.
    2. CORS: The server must support Cross-Origin Resource Sharing (CORS). The Stremio Addon SDK handles CORS automatically for local development, but you must configure it on your remote hosting provider.