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 stremio-server-go 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
• Auto-updates
• 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 stremio-server-go 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

1. Download plugin.video.rivulet.zip — that URL always serves the current release. (Per-version zips are on the releases page.)
2. In Kodi: Settings → Add-ons → Install from zip file and pick the downloaded zip.
3. Open Rivulet from the Videos section of the home screen.

Auto-updates

Instead of re-downloading and reinstalling a zip for every release, install the repository once — no separate download needed, useful on set-top boxes (e.g. Nvidia Shield):

1. Settings → File manager → Add source, enter https://rivulet-kodi.github.io/plugin.video.rivulet/ as the path, and give it a name (e.g. Rivulet).
2. Settings → Add-ons → Install from zip file → Rivulet → repository.rivulet.zip (or descend into repository.rivulet/ for the versioned filename).
3. From then on, Kodi offers Rivulet — and its future updates — from Settings → Add-ons → Install from repository → Rivulet Repository, with automatic update checks like any other Kodi repo.

Alternatively, download repository.rivulet.zip directly and install it the same way as step 2 above (Install from zip file) without adding a source. Prefer these version-less URLs when linking people to the addon: 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 at rivulet-kodi.github.io/plugin.video.rivulet, published by .github/workflows/repo.yml on every v* tag push.

Streaming server

All playback is resolved through a streaming server speaking the same enginefs HTTP API as Stremio's own server.js (stremio-server-go 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 stremio-server-go (or official Stremio server) instance, local or remote.
Run embedded server	When enabled, the addon's background service spawns and supervises a local stremio-server-go process for the lifetime of the Kodi session, and stops it on shutdown.
Server binary path	The stremio-server-go 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.

stremio-server-go no longer needs to be installed by hand: use the Download stremio-server binary button under Settings → Streaming server to fetch the correct build for your platform straight from the stremio-server-go 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 stremio-server_Android_{arm64,armv7,x86_64,i386} archive: the executable, and libstremio-server.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 stremio-server-go 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.

---

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