stremio-core

The Rust engine that powers every Stremio app.

📚 API Docs · Website · Report a bug

Stremio is a modern media center — a one-stop solution for discovering, organizing and streaming video content via addons. stremio-core is the single Rust codebase that contains all the logic shared between Stremio apps: user/addon state, the addon protocol, library, notifications, playback state and deep links. The UIs are thin layers on top — this crate is the app.

Goals

• Flexibility — integrates into any codebase, across the entire stack and in different paradigms: types alone can be used by addons, or the full Ctx model can be the backbone of a whole Stremio app
• Emphasis on correctness
• No cruft / legacy — not burdened by obsolete decisions and solutions

🧠 Architecture

The state management is inspired by the Elm Architecture: state flows in one direction, side effects are explicit, and the platform is abstracted away behind a trait.

flowchart LR
    UI["Platform UI"] -- "Action" --> RT["Runtime"]
    RT -- "Msg" --> M["Models<br>(Ctx, Player, ...)"]
    M -- "Effects" --> ENV["Env<br>(fetch, storage, exec)"]
    ENV -- "Internal Msg" --> RT
    RT -- "NewState / CoreEvent" --> UI

Loading

1. The UI dispatches an Action to the Runtime.
2. The Runtime routes it as a Msg to the state models, which update themselves and return Effects — explicit descriptions of side effects (futures) to run.
3. Effects execute through the Env trait and resolve back into the loop as Internal messages.
4. Changed models are announced to the UI as NewState; noteworthy happenings are emitted as Events.

Each platform only has to implement Env — HTTP fetch, storage, task execution and time — and compose its own model out of the building blocks with #[derive(Model)].

📦 What's inside

Module / crate	What it is
src/types	The vocabulary: addon manifests and resources, meta items, streams, subtitles, library, profile, API types
src/models	The state models: Ctx (profile, library, notifications — the backbone), CatalogWithFilters, MetaDetails, Player, LibraryWithFilters, StreamingServer, Calendar and more
src/runtime	The reactive engine: Runtime, Effects, Env, messages
src/addon_transport	Addon protocol client — modern HTTP(S) JSON plus a legacy JSON-RPC adapter
src/deep_links	Deep link generation for every platform
stremio-core-web/	WASM bridge published to npm as @stremio/stremio-core-web — runs core in a Web Worker for stremio-web
stremio-derive/	#[derive(Model)] proc macro
stremio-watched-bitfield/	Compact encoding of per-video watched state

Feature flags

Feature	Effect
derive	Re-exports #[derive(Model)] from stremio-derive
analytics	Enables the analytics module
env-future-send	Adds Send bounds to Env futures (incompatible with the WASM target)
deflate	Forwards to stremio-official-addons/deflate

🚀 Development

You'll need Rust 1.77 or newer (MSRV, checked in CI).

cargo fmt --all -- --check
cargo clippy --all --no-deps -- -D warnings
cargo test
cargo build

Docs are built with the nightly toolchain pinned in docs.yml:

RUSTDOCFLAGS="--cfg docsrs -Z unstable-options --enable-index-page" cargo +nightly build-docs

For the WASM bridge, see stremio-core-web/README.md.

Tips

• New actions are defined in src/runtime/msg/action.rs — the message enums there are the public API surface of the crate.
• WASM output can get large, especially when deriving Serialize/Deserialize where it isn't needed. Run twiggy top ..._bg.wasm to find the biggest code size offenders.

🧩 Ecosystem

Repository	What it is
stremio-web	The web UI, driven by this crate through stremio-core-web
stremio-core-kotlin	Kotlin/JNI bindings for Android (archived)
stremio-addon-sdk	Build your own addon in Node.js
local-search	Search suggestions engine used by the LocalSearch model

📄 License

Copyright © 2019-2026 Smart Code OOD. Released under the MIT license — see LICENSE.