A Python framework for building Stremio addons with async support, leveraging BlackSheep for fast HTTP handling and modern tooling.
- Async-first: Leverage Python's
asynciofor high-performance addons. - Decorator-based handlers: Easily register handlers for resources like
stream,meta,catalog, andsubtitles. - Static file serving: Serve static directories with custom cache control.
- Central registry publishing: Publish your addon to Stremio's central API with one call.
pip install stremiofrom 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()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"
)| Parameter | Description |
|---|---|
manifest |
Required Addon manifest (validated on initialization). |
static_dir |
Directories to serve static files from. |
cache_max_age |
Max cache age in seconds for responses (default: 0). |
public_host |
Public URL for addon installation links (e.g., stremio://myaddon.com/manifest.json). |
log_level |
Server log level (debug, info, warning, error, critical). |
Use decorators to register handlers:
@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@addon.meta()
async def meta_handler(data):
return {"meta": {...}} # See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/meta.md@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@addon.subtitles()
async def subtitles_handler(data):
return {"subtitles": [...]} # See: https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/subtitles.md@addon.landing_page()
async def landing_page(request): # homepage a.k.a accessing myaddon.com/
return "<h1>Welcome to My Addon!</h1>"async def publish_addon():
await addon.publishToCentral(
manifest_url="https://myaddon.com/manifest.json",
)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
}Addon(static_dir=["assets", "public"])Files in assets/file.txt will be available at myaddon.com/assets/file.txt.
This project is licensed under the MIT License.