> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/connections/media-clients/stremio.md).
# Stremio
Connect Stremio to synchronize History, Progress, Watchlist, and supported Ratings. Stremio can also scrobble what you play to your trackers through the CrossWatch add-on.
{% hint style="warning" %}
**Media-client sync warning:** Review Media clients before using a media client as a source or enabling two-way sync.
{% endhint %}
{% tabs %}
{% tab title="End users" %}
{% hint style="warning" %}
Stremio support is experimental. Sync uses Stremio's internal account API. Scrobbling uses add-on playback events that Stremio has not officially announced yet. Both can change without notice.
{% endhint %}
#### What it supports
| Feature | Supported items | Direction |
| ---------- | ------------------- | ------------------- |
| History | Movies and episodes | Read and write |
| Progress | Movies and episodes | Read and write |
| Watchlist | Movies and shows | Read and write |
| Ratings | Movies and shows | Write only |
| Scrobbling | Movies and episodes | Watcher source only |
CW uses the Stremio Library as the Watchlist.
Ratings write from another provider to Stremio. Stremio cannot be a Ratings source. Playlists are not supported.
Stremio cannot be a scrobble destination.
#### Two separate parts
The Stremio connection has two tabs. They work independently.
* **Authentication:** your Stremio account login. Needed for sync pairs.
* **Scrobbling:** the CrossWatch add-on. Needed for live scrobbling.
You can use one without the other. Scrobbling does not need the account login.
#### Connect Stremio
1. Open **Settings** → **Connections** → **Media clients** → **Stremio**.
2. Enter your Stremio email address and password.
3. Select **Connect Stremio**.
4. Wait until the connection shows **Stremio connected**.
CW uses your credentials once to request an auth key. CW does not store your email address or password. It stores only the returned auth key.
#### Scrobbling
Stremio can report what you play to an add-on. CW acts as that add-on and sends the playback to your trackers.
{% hint style="warning" %}
Scrobbling needs CW on an **HTTPS** address. Stremio does not install add-ons from plain HTTP. It works with **Stremio 5 Desktop** and **Stremio Web** only.
{% endhint %}
**Turn it on**
1. Open **Settings** → **Connections** → **Media clients** → **Stremio**.
2. Open the **Scrobbling** tab.
3. Select **Turn on scrobble add-on**.
4. CW shows an **Add-on URL** for this connection profile.
**Install the add-on in Stremio**
Use one of these:
* **Install in Stremio** opens the install dialog in Stremio Desktop.
* **Open in Stremio Web** opens the install dialog in Stremio Web.
* **Copy** the URL, then paste it into **Add addon** in Stremio.
Stremio asks you to trust the add-on with your watch activity. Tick the box and select **Install**.
If a button does not open the install dialog, copy and paste the URL. This always works.
The tab shows **Installed in Stremio** once Stremio has loaded the add-on.
**Add a Watcher route**
Installing the add-on is not enough. CW ignores the playback until a route exists.
1. Open **Settings** → **Scrobbler**.
2. Enable the **Watcher**.
3. Add a route with **Stremio** as the source.
4. Choose the tracker and profile as the destination.
Stremio works with Watcher routes only. It is not available under Webhooks.
**What gets scrobbled**
* **Start**, **pause**, and **stop** go to the destination of the route.
* A stop above your watched threshold marks the item as watched.
* A stop below it is kept as paused.
Stremio does not report progress while playing. CW learns the position on start, pause, seek, and stop.
**Things to know**
* The add-on has no user. The URL is the identity. Anyone who installs your URL scrobbles as this profile.
* Routes have no username filter for Stremio. **Ignore specials** is the only filter.
* Items need an IMDb, TMDb, or TVDb identifier. Other items, such as Kitsu anime, are ignored.
* If Stremio closes without a stop, CW ends the session on its own. It uses the last reported position, so nothing is marked watched by guess.
* **New URL** creates a new address. The installed add-on stops working until you install the new one.
**Turn it off**
Select **Turn off** in the **Scrobbling** tab. Then remove the add-on in Stremio.
CW blocks this while a Watcher route uses the profile. Remove the route first.
#### Connection profiles
Each Stremio connection represents one Stremio account.
Stremio account profiles are not supported. Create another CW connection profile for another account.
Each profile has its own add-on URL. Install each URL in the Stremio account it belongs to.
A profile with only the add-on turned on shows as **Scrobble add-on** in the Connections overview.
#### History
**Movies**
Stremio stores watched state, latest watched date, and watched count.
CW synchronizes watched state and the latest available watched date.
Stremio does not expose every play event and date. CW cannot recover a complete viewing history for repeatedly watched movies.
**Episodes**
Stremio stores watched state for each episode. It does not store an individual watched date.
When Stremio is the source, other providers can show episodes watched on the sync date. The original dates cannot be recovered.
When CW writes dated History to Stremio, it retains watched state but discards episode dates.
{% hint style="warning" %}
Do not use Stremio as the source of truth when historical episode dates matter.
{% endhint %}
{% hint style="info" %}
Scrobbling helps here. A scrobble reaches your tracker at the moment you watch, so the tracker gets the real date.
{% endhint %}
#### Progress
Stremio stores playback position and duration for movies and episodes.
Writing Progress requires a duration. CW can resolve a missing duration through configured metadata when possible.
Stremio keeps one active episode Progress entry per series. Writing Progress for another episode can replace the active entry.
Writing Progress does not automatically mark an item as watched.
#### Watchlist
CW treats the Stremio Library as the Watchlist.
Movies and shows are supported. Episodes and seasons are not Watchlist items.
Listed Library items can return as Watchlist items, including already watched titles.
#### Ratings
Stremio supports Ratings as a destination only. CW converts ratings from another provider into reactions.
By default:
1. Ratings below 6 create no reaction.
2. Ratings from 6 through 8 become **Liked**.
3. Ratings from 8 through 10 become **Loved**.
Only movies and shows are supported. Episode Ratings cannot be written.
Stremio stores reactions, not numeric ratings. A rating of 8 and 10 both become **Loved**. CW cannot read reactions as their original numeric rating.
#### Matching
Stremio relies mainly on IMDb identifiers.
CW can use configured TMDb metadata to resolve an IMDb identifier, poster, or runtime.
Items can remain unresolved when:
1. No IMDb identifier is available.
2. Stremio or Cinemeta cannot resolve the show.
3. The season or episode cannot be matched.
4. Progress has no usable position or duration.
5. The selected feature does not support the item type.
#### Recommended setup
1. Use a provider with complete dated History as the source of truth.
2. Use Stremio as a History and Ratings destination.
3. Start with a one-way pair and run **Dry run**.
4. Review unresolved items before enabling **Remove** or two-way sync.
5. Create a capture before importing a large History.
6. Use scrobbling for new plays, so your tracker gets real watched dates.
Do not send the same plays twice. If a route scrobbles Stremio to a tracker, avoid a pair that also syncs Stremio History to that tracker.
#### Common pair examples
**Plex to Stremio**
Movie History, episode watched state, and supported Progress synchronize to Stremio.
Stremio discards individual episode watched dates. CW writes only items mapped to Stremio identifiers.
**Stremio to Plex**
Movies can include their latest available watched date.
Episodes have watched state but no individual watched date. Plex can show imported episodes as watched on the sync date.
**Trakt to Stremio**
Movie and episode watched state synchronize to Stremio.
Separate Trakt play events become the current Stremio watched state. Individual episode dates are not retained.
**Stremio to Trakt**
Movie History can include the latest available movie date.
Stremio cannot preserve episode watched dates.
**Provider Ratings to Stremio**
Movie and show Ratings become **Liked** or **Loved** reactions.
The original numeric rating cannot be recovered from Stremio.
#### Disconnect Stremio
**Delete connection** removes the stored Stremio auth key from CW. It also turns off the scrobble add-on for that profile.
It does not change existing History, Progress, Library items, or reactions in Stremio. Remove the add-on in Stremio yourself.
CW may require you to remove or update pairs and Watcher routes that still use the connection.
#### Troubleshooting
**Stremio rejected the credentials**
Verify the email address and password by signing in to Stremio. Then reconnect.
**Stremio API is unreachable**
Check CW's internet connection and test again. The internal Stremio API may be temporarily unavailable.
**Missing IMDb identifier**
Configure TMDb Metadata and retry. Review unresolved items when no IMDb identifier exists.
**Stremio episode unresolved**
Confirm that the show exists in Cinemeta. Check that source season and episode numbering match Stremio.
**Stremio duration missing**
CW cannot calculate Progress from a percentage without a duration. Configure TMDb metadata or use a source with a runtime.
**Episode watched dates changed after synchronization**
Stremio does not store individual episode watched dates. CW cannot recover them later.
**Unexpected Watchlist items**
CW uses every listed Stremio Library item as the Watchlist. Watched items remain included.
**Exact rating disappeared**
Stremio stores reactions rather than numeric ratings. The source provider remains authoritative.
**Failed to get addon manifest**
Stremio could not load the add-on URL.
1. Check that the URL starts with `https://`. Plain HTTP does not work, also not on your own network.
2. Check that the URL still has its port, for example `:9898`. Copy and paste the URL when a button drops it.
3. Check that the device running Stremio can reach CW on that address.
**No install buttons, only a warning**
You opened CW over plain HTTP. Open CW through its HTTPS address and copy the URL from there.
**Add-on is installed but nothing is scrobbled**
1. Check that the Watcher is enabled.
2. Check that a route with Stremio as the source exists.
3. Play, pause, and stop something. The **Scrobbling** tab shows the last playback event.
4. Check the log for `STREMIO-WATCH` lines. Each event shows why it was accepted or ignored.
**Nothing arrives from my phone or TV**
Only Stremio 5 Desktop and Stremio Web send playback events for now.
**The first start is ignored**
Stremio can send a start before it knows the length of the video. CW sends it when the position is near the beginning. Otherwise it waits for the next event.
{% endtab %}
{% tab title="Power users" %}
### Power users
#### Authentication
CW authenticates through Stremio's internal login endpoint.
The email address and password are sent to Stremio during connection. Stremio returns an `authKey`, which CW stores as `auth_key`.
CW clears credentials after the connection attempt. It does not write them to the configuration.
CW treats the auth key as a secret. It encrypts the key when saving the configuration.
The internal API is not part of Stremio's public addon API. An API change can break the connection until CW is updated.
#### Configuration
The default Stremio configuration is:
```json
{
"stremio": {
"auth_key": "",
"ratings": {
"liked_min": 6.0,
"loved_min": 8.0
}
}
}
```
Use the connection interface. Do not store a Stremio email address or password in the configuration.
#### Rating thresholds
Configure reaction thresholds under `stremio.ratings`:
```json
{
"stremio": {
"ratings": {
"liked_min": 5.0,
"loved_min": 9.0
}
}
}
```
`liked_min` sets the lowest rating that becomes **Liked**. `loved_min` sets the lowest rating that becomes **Loved**.
`loved_min` cannot be lower than `liked_min`. CW adjusts it when necessary.
Ratings below `liked_min` are skipped. Stremio Ratings remain destination-only.
#### Scrobble add-on
**Token and URL**
Turning the add-on on creates a token per connection profile:
```
security.webhook_ids["stremioaddon:"]
```
The token is the switch. No token means the add-on is off for that profile.
The add-on URL is:
```
https:///webhook/stremio//manifest.json
```
The token is in the path, because Stremio uses the path as the add-on address. CW hides it in the access log. Treat the URL as a secret.
These endpoints need no CW login. The token is the only protection.
**Manifest**
The manifest declares one resource:
```json
{
"resources": [
{ "name": "player", "types": ["movie", "series"], "idPrefixes": ["tt", "tmdb:", "tvdb:"] }
]
}
```
The default profile uses the add-on id `app.crosswatch.scrobble`. Other profiles add their profile id, so two can be installed side by side.
CW does not declare the `library` resource. Library changes and manual watched marks in Stremio are not received.
**Events**
Stremio calls:
```
GET /webhook/stremio//player///action=¤tTime=&duration=.json
```
* Movies use the IMDb id, for example `tt0133093`.
* Episodes use `::`, for example `tt0903747:2:5`.
* A seek sends the current state again.
* There is no heartbeat.
* Stremio ignores the response.
CW looks up the title and year in Cinemeta. A failed lookup does not block the scrobble.
**How CW handles events**
* A pause that arrives before any start, without a duration, is skipped. Stremio sends it while the player loads.
* A start or pause without a duration is sent as 1 percent when the position is within the first 2 minutes.
* Further in, CW estimates progress from the Cinemeta runtime. Without a runtime the event is dropped.
* A stop only counts toward watched when Stremio sent a real duration. With estimates only, the stop is capped at 50 percent.
* A repeated event with the same action and progress is skipped.
**Sessions without a stop**
A session ends on its own when no stop arrives:
* **Playing:** after the remaining runtime plus 15 minutes.
* **Paused:** after 30 minutes.
CW sends a stop at the last reported position.
The playing card is refreshed every 2 minutes while a session is open.
**Routes**
Stremio is a Watcher source. Each profile has one watcher that waits for events. It does not poll, so the poll interval options do not apply.
A route assigned to a user profile needs no account whitelist for Stremio.
**Log reasons**
Events are logged under `STREMIO-WATCH`. An ignored event shows one of these reasons:
| Reason | Meaning |
| ------------------------ | --------------------------------------------------- |
| `watcher_disabled` | The Watcher source is off. |
| `no_routes` | No enabled route uses this Stremio profile. |
| `no_matching_route` | A route exists, but its filters rejected the event. |
| `progress_unknown` | No usable position or duration yet. |
| `not_started` | A pause arrived before playback started. |
| `duplicate` | Same action and progress as the previous event. |
| `no_ids` | The item has no IMDb, TMDb, or TVDb identifier. |
| `missing_episode_number` | A series event without season and episode. |
| `unsupported_media` | Not a movie or series. |
| `unsupported_event` | Not a start, pause, or stop. |
A request with an unknown token is rejected with `invalid_token` under `WEBHOOK`.
#### Stremio data model
CW reads and updates Stremio `libraryItem` records.
**Movie History**
Movie History uses:
```
state.lastWatched
state.timesWatched
state.flaggedWatched
```
A movie is watched when `timesWatched` or `flaggedWatched` exceeds zero.
CW uses `lastWatched` as the watched date. It can use the record modification time as a fallback. Complete play history is unavailable.
**Episode History**
Episode History uses:
```
state.watched
```
This serialized bitfield records episode watched states. It does not include per-episode timestamps.
CW does not expose record modification time as an episode watched date. The timestamp can reflect an unrelated series change.
CW maps episodes through Stremio and Cinemeta video lists. It uses the show IMDb identifier, season, and episode number.
**Progress**
Progress uses:
```
state.timeOffset
state.duration
state.video_id
state.season
state.episode
```
Movie records contain the active movie position. Series records contain one active episode, position, and duration.
A later write for another episode replaces those active fields. CW reads, merges, and writes the record to preserve unrelated fields.
**Watchlist**
CW treats the Stremio Library as the Watchlist. An item is listed when:
```
removed = false
temp = false
```
CW includes watched listed items. Removing a Watchlist item changes Library membership but preserves History.
**Ratings**
CW writes Ratings through Stremio's reactions service:
```
liked
loved
```
CW stores pair-scoped state for reactions it writes. This supports bookkeeping and duplicate prevention. It does not make Stremio a Ratings source.
#### Identifiers and metadata
IMDb is the primary Stremio identifier.
Episodes require a show IMDb identifier, season number, and episode number.
TMDb metadata can resolve a missing IMDb identifier, poster, or runtime. It does not guarantee a match. Episode ordering, specials, and provider numbering can still prevent matching.
#### Supported item types
| Feature | Movies | Shows | Seasons | Episodes | Direction |
| ---------- | ------ | ----- | ------- | -------- | ------------------- |
| History | Yes | No | No | Yes | Read and write |
| Progress | Yes | No | No | Yes | Read and write |
| Watchlist | Yes | Yes | No | No | Read and write |
| Ratings | Yes | Yes | No | No | Write only |
| Scrobbling | Yes | No | No | Yes | Watcher source only |
Shows, seasons, and episodes are not interchangeable. Feature support varies by item type.
#### Operational behavior
CW reads the current Stremio record before writing. It merges only fields required by the chosen feature.
For example, writing Progress preserves the episode watched bitfield. Writing History preserves unrelated Library metadata.
History and Watchlist removals are supported. Stremio uses present-state semantics.
When a relevant state disappears, CW can treat it as a removal if removal synchronization is enabled.
Enable **Remove** only after a successful initial sync. Confirm that the Stremio Library is your intended Watchlist.
Scrobbling does not write to Stremio. It only reads what Stremio reports.
#### Related docs
* Configure Pairs
* TMDb Metadata
* Profiles
{% endtab %}
{% endtabs %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/media-clients/stremio.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
