Stremio Addon Framework

A Python framework for building Stremio addons with async support, leveraging BlackSheep for fast HTTP handling and modern tooling.

Features ✨

• Async-first: Leverage Python's asyncio for high-performance addons.
• Decorator-based handlers: Easily register handlers for resources like stream, meta, catalog, and subtitles.
• Static file serving: Serve static directories with custom cache control.
• Central registry publishing: Publish your addon to Stremio's central API with one call.

Installation

pip install stremio

Quick Start

from stremio import Addon

# Define your addon manifest.
# See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/manifest.md
manifest = {
    "id": "org.example.myaddon",
    "version": "1.0.0",
    "name": "My Awesome Addon",
    "description": "This is a simple Awesome Addon!",
    "logo": "https://myaddon.com/logo.png",
    "catalogs": [],
    "resources": ["stream", "meta"],  # Add your supported resources here
    "types": ["movie"]
}

addon = Addon(manifest=manifest, port=7000)

# Add a stream handler
@addon.stream()
async def stream_handler(data):
    return {
        "streams": [{"name": "4K", "url": "https://example.com/cars_3.mp4"}]
    }

# Add a subtitles handler
@addon.subtitles()
async def subtitles_handler(data):
    return {
        "subtitles": [{"id": "1", "url": "https://example.com/cars_3_ar.srt", "lang": "Arabic"}]
    }

if __name__ == "__main__":
    addon.run()

Usage Guide

1. Initialize the Addon

addon = Addon(
    manifest=manifest,
    static_dir=["static"],  # Serve static files from these directories
    cache_max_age=3600,     # Cache responses for 1 hour; you can override this on handler response
    public_host="myaddon.com",
    log_level="info"
)

2. Register Resource Handlers

Use decorators to register handlers:

Stream Handler

@addon.stream()
async def stream_handler(data):
    # data = {"id": "tt12345", "type": "movie", "extraArgs": None}
    return {"streams": [...]}  # See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/stream.md

Meta Handler

@addon.meta()
async def meta_handler(data):
    return {"meta": {...}}  # See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/meta.md

Catalog Handler

@addon.catalog()
async def catalog_handler(data):
    return {"metas": [...]}  # Return list of meta items. See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/requests/defineCatalogHandler.md#returns

Subtitles Handler

@addon.subtitles()
async def subtitles_handler(data):
    return {"subtitles": [...]}  # See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/subtitles.md

3. Custom Landing Page

@addon.landing_page()
async def landing_page(request): # homepage a.k.a accessing myaddon.com/
    return "<h1>Welcome to My Addon!</h1>"

4. Publish to Central Registry

async def publish_addon():
    await addon.publishToCentral(
        manifest_url="https://myaddon.com/manifest.json",
    )

Advanced Configuration

Cache Control

Return these keys in your handler responses to set cache headers:

{
    "cacheMaxAge": 3600,          # max-age=3600
    "staleRevalidate": 86400,     # stale-while-revalidate=86400
    "staleError": 172800          # stale-if-error=172800
}

Static Files

Addon(static_dir=["assets", "public"])

Files in assets/file.txt will be available at myaddon.com/assets/file.txt.

License

This project is licensed under the MIT License.