> 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
{% hint style="warning" %}
**Media-client sync warning:** Review [Media clients](/crosswatch/settings/connections/media-clients.md) 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. CW uses Stremio's internal account API. It can change without notice.
{% endhint %}
### What it supports
* **History:** read and write for movies and episodes.
* **Progress:** read and write for movies and episodes.
* **Watchlist:** read and write for movies and shows.
CW uses the Stremio Library as the Watchlist.
**Ratings** support writes from another provider to Stremio. Stremio cannot be a Ratings source.
**Playlists** are not supported.
### 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.
### Connection profiles
Each Stremio connection represents one Stremio account.
Stremio account profiles are not supported. Create another CW connection profile for another account.
### 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 %}
### 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.
### 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
Disconnecting removes the stored Stremio auth key from CW.
It does not change existing History, Progress, Library items, or reactions in Stremio.
CW may require you to remove or update pairs 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](/crosswatch/settings/connections/metadata/tmdb-metadata.md) 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.
{% endtab %}
{% tab title="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.
### 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 duration. It does not guarantee a match. Episode ordering, specials, and provider numbering can still prevent matching.
### Supported item types
* **History:** movies and episodes.
* **Progress:** movies and episodes.
* **Watchlist:** movies and shows.
* **Ratings:** movies and shows, destination 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.
### Related docs
* [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* [TMDb Metadata](/crosswatch/settings/connections/metadata/tmdb-metadata.md)
* [Profiles](/crosswatch/settings/connections/profiles.md)
{% 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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.