Rivulet

A Kodi client for the Stremio addon protocol.

Browse and search catalogs, install community addons, resolve streams and play them back through a streaming server — all from a custom Kodi UI.

---

Rivulet reimplements the Stremio client experience inside Kodi: browse and search catalogs from the Stremio addon protocol, addon management (install from manifest URL), meta/stream resolution, and playback through a rivulet-engine streaming server. Optional login syncs your addon collection with your Stremio account.

Disclaimer. This addon does not host, index or provide any media content — it is a client for third-party Stremio addons that you install yourself.

Contents

• Features
• Screenshots
• Install
• Streaming server
• Development

Features

• Custom Home/Browse/Search/Detail/Streams UI — no dropping to the classic Kodi directory for the parts of the flow that matter most.
• Addon manager — install Stremio addons straight from a manifest URL, and remove them again, without leaving Kodi.
• Parallel catalog/stream lookups — a slow or unavailable addon no longer stalls the rest of your catalogs or sources.
• Stremio account sync — log in to keep your addon collection in sync both ways between Kodi and Stremio.
• Resume and watch progress — resume locally when logged out, or sync progress and watched state to your Stremio account.
• Automatic next episode — continue a series after a cancellable countdown, preferring the same release group.
• Subtitles out of the box — pulled from your installed Stremio subtitle addons at playback time, with OpenSubtitles v3 preinstalled and sorted by your preferred language.
• One-click streaming server — download the right rivulet-engine build for your platform and run it embedded, or point Rivulet at any server you already run.
• Optional launch on startup — turn on Settings → Home screen → Open Rivulet automatically on Kodi startup to have a dedicated media box boot straight into Rivulet instead of Kodi's home screen. Off by default.

Screenshots

Rivulet's custom UI:

Home	Browse

Detail + streams	Addon manager

Continue	Search

Install

Kodi 19 or later. If this is your first non-official add-on, enable Settings → System → Add-ons → Unknown sources once.

Recommended (updates itself):

1. Download repository.rivulet.zip — that URL always serves the current release, and you only need it once.
2. Settings → Add-ons → Install from zip file and pick the zip.
3. Install from repository → Rivulet Repository → Video add-ons → Rivulet → Install. Kodi then offers future releases like any other repository add-on.

Fewest clicks (no auto-updates): download plugin.video.rivulet.zip, install it with Install from zip file, and open Rivulet from Add-ons → Video add-ons. Per-version zips are on the releases page.

Can't browse to a downloaded zip (set-top boxes, TVs)? Add https://rivulet-kodi.github.io/plugin.video.rivulet/ under Settings → File manager → Add source, then choose either zip above via Install from zip file → Rivulet. Kodi fetches it itself.

Prefer version-less URLs when linking people to the add-on: a repository.rivulet-1.0.0.zip style link breaks silently as soon as the next release ships. The repository is served from GitHub Pages, published by .github/workflows/repo.yml on every v* tag push.

First launch

Nothing needs configuring to start. The embedded streaming server is on by default and the background service downloads the right rivulet-engine build for your device on first start. Optionally:

• Settings → Account → Log in, then Sync add-ons to pull your Stremio collection. Without an account, add add-ons from a manifest URL in the in-app add-on manager.
• Settings → Subtitles: set your language code (default en).

Streaming server

All playback is resolved through a streaming server speaking the same enginefs HTTP API as Stremio's own server.js (rivulet-engine is a pure-Go, drop-in implementation of it). Configure it under Settings → Streaming server:

Setting	Purpose
Server URL	Where the streaming server is listening. Defaults to http://127.0.0.1:11470, the standard Stremio server port. Point this at any already-running rivulet-engine (or official Stremio server) instance, local or remote.
Run embedded server	When enabled, the addon's background service spawns and supervises a local rivulet-engine process for the lifetime of the Kodi session, and stops it on shutdown.
Server binary path	The rivulet-engine executable to run when the embedded server is enabled. Leave empty to auto-detect: the service first looks in special://profile/addon_data/plugin.video.rivulet/bin/, then on PATH.

rivulet-engine no longer needs to be installed by hand: use the Download rivulet-engine binary button under Settings → Streaming server to fetch the correct build for your platform straight from the rivulet-engine releases into the addon's bin/ folder — the download is integrity-checked before install. Subtitles are pulled from your installed Stremio subtitle addons at playback time — OpenSubtitles v3 is preinstalled — and sorted using the Preferred subtitle language setting under Settings → Subtitles.

Android. Kodi 19+ targets Android API 29 or newer, where Android 10+ forbids executing a binary from an app's own writable data directory (SELinux W^X). Rivulet therefore installs the server in two forms from the same integrity-checked rivulet-engine_Android_{arm64,armv7,x86_64,i386} archive: the executable, and librivulet-engine.so, the same server built as a shared library. It tries the executable first; when Android denies it, the service falls back to library mode, loading the .so into Kodi's own process (the approach Elementum uses) — no root and no second app needed. Settings → Streaming server → Force library mode (Android) skips the executable attempt. In library mode a server upgrade takes effect at the next Kodi restart, and a server crash takes Kodi down with it, since both share one process. Features needing external tools (yt-dlp for YouTube streams) are unavailable on Android either way. If neither form can start, point Server URL at a rivulet-engine running elsewhere (PC, NAS, Termux) and leave Run embedded server off.

Development

lib/stremio/ and lib/store.py are plain Python with no xbmc* imports, so they run and test outside Kodi. Everything Kodi-specific lives in lib/ui/, lib/service_runner.py, default.py and service.py. The Kodi-facing layer is tested against the shared fake-Kodi modules in tests/kodistubs/ (a hermetic, per-test sys.modules install/restore of xbmc* stubs), so the whole suite runs with no Kodi runtime and no network.

Set up the dev toolchain and run the tests:

python -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt

make test        # run the test suite
make cov         # tests + coverage report (gate: >=90%)
make lint        # ruff check
make typecheck   # mypy across all production Python modules
make check       # lint + typecheck + tests
make random      # tests in randomized order (order-independence)
make parallel    # tests across CPUs (pytest-xdist)

Tool config lives in pyproject.toml. CI (.github/workflows/test.yml) runs ruff + the test suite with coverage across Python 3.8/3.11/3.13 (Kodi 19 "Matrix" through current), on every push and pull request.

Screenshots in the Screenshots section above are generated, not hand-picked crops - scripts/capture_screenshots.py drives a running kodi-standalone instance over its always-on TCP JSON-RPC socket (127.0.0.1:9090, no webserver setup needed), walks every screen listed there, and writes the curated result to artwork/screenshots/. Re-run it after a UI change to refresh the gallery.

---

Rotten Tomatoes, Popcornmeter and Metacritic are trademarks of their owners; Rivulet's icons are original artwork that only identifies where a score comes from.

_{Licensed under MIT. Not affiliated with Stremio.}