> 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/synchronization/media-clients/stremio.md). # Stremio Synchronize Stremio History, Progress, Watchlist, and supported Ratings with other CrossWatch providers. Stremio is a separate CrossWatch sync provider. You can select it as either source or target in a pair. For connection instructions, account profiles, and connection troubleshooting, see [Stremio](/crosswatch/settings/connections/media-clients/stremio.md). {% hint style="warning" %} **Experimental** The adapter uses Stremio’s internal account API. Stremio changes can affect the connection or supported features. **Media-client sync warning:** Review [Media clients](/crosswatch/settings/synchronization/media-clients.md) before using Stremio as a source or enabling two-way sync. {% endhint %} {% tabs %} {% tab title="End users" %} ### What Stremio can synchronize The Stremio sync adapter supports: 1. History 2. Progress 3. Watchlist 4. Ratings to Stremio only Playlists are not supported. ### Supported media types #### History History synchronization supports movies and episodes. Shows and seasons cannot be synchronized as separate History items. #### Progress Progress synchronization supports movies and episodes. Shows and seasons cannot have separate Progress records. Stremio keeps one active episode Progress entry per series. Writing Progress for another episode can replace it. #### Watchlist Watchlist synchronization supports movies and shows. CrossWatch uses the Stremio Library as the Stremio Watchlist. Episodes and seasons are not supported. #### Ratings Ratings synchronization supports movies and shows only. Stremio is a destination only. CrossWatch converts numeric Ratings into Stremio reactions. By default: * Ratings below `6` create no reaction. * Ratings from `6` up to `8` become **Liked**. * Ratings from `8` up to `10` become **Loved**. Stremio does not store the original numeric value. ### Before creating a pair 1. Connect Stremio from [Stremio](/crosswatch/settings/connections/media-clients/stremio.md). 2. Confirm the Stremio connection shows as connected. 3. Configure TMDb metadata under **Settings** → **Connections** → **Metadata**. A separate Stremio application or addon is not required. Stremio items need a usable IMDb identifier. TMDb metadata can resolve missing identifiers, posters, and durations when possible. ### Create a Stremio pair Open **Settings** → **Synchronization**, then create a new pair. Stremio can be selected on either side. #### Stremio as source Use Stremio as the source for its current History, Progress, or Library items. A common starting configuration is: 1. Set **Mode** to **One way**. 2. Select Stremio as the source. 3. Select a tracker or media server as the target. 4. Enable History, Progress, or Watchlist. Stremio cannot be used as a Ratings source. Episode History does not contain individual watched dates. The target may receive watched state without its original timestamp. #### Stremio as target Use Stremio as the target to apply tracker or media-server data. A common starting configuration is: 1. Set **Mode** to **One way**. 2. Select another provider as the source. 3. Select Stremio as the target. 4. Enable History, Progress, Watchlist, or Ratings. Movie History can retain the latest available watched timestamp. Episode History retains watched state, but not its original timestamp. #### Two-way synchronization Stremio supports two-way synchronization for History, Progress, and Watchlist. Ratings are not available in two-way mode. Stremio cannot be a Ratings source. Stremio can store less information than another provider. For example, episode History retains watched state but not individual watched dates. Start with one-way synchronization. Enable two-way sync only after several clean runs. ### Recommended first pair 1. Set **Mode** to **One way**. 2. Enable one feature only. 3. Keep **Remove** disabled. 4. Enable **Dry run**. 5. Run the pair manually. 6. Review unresolved items. 7. Disable **Dry run** after confirming the result. ### History behavior CrossWatch reads and writes Stremio History for movies and episodes. For movies, Stremio stores watched state, a latest watched timestamp, and a watched count. CrossWatch synchronizes the current state and latest available timestamp. Stremio does not provide separate movie play events. For episodes, Stremio stores watched state without individual watched timestamps. CrossWatch can synchronize that an episode was watched, but not when it was watched. Removing History marks the matching movie or episode as unwatched. {% hint style="warning" %} Use Stremio carefully as a History source when watched dates matter. {% endhint %} ### Progress behavior CrossWatch reads and writes Stremio playback Progress for movies and episodes. Progress includes a playback position and total duration. A duration is required when writing Progress to Stremio. TMDb metadata can resolve a missing duration. For series, Stremio stores one active episode Progress entry. Writing another episode can replace the previous entry. Removing Progress resets the playback position. Progress does not automatically mark an item as watched. ### Watchlist behavior CrossWatch uses Stremio Library membership as Watchlist state. Adding a Watchlist item adds it to the Stremio Library. Removing it removes the item from that Library. History and Library membership are separate. A watched title can remain in the Library and return as a Watchlist item. ### Whitelisting and removals Stremio does not provide separate feature whitelisting. Use pair rules to restrict synchronized items. Stremio supports removals for History, Progress, Watchlist, and destination Ratings. A removal is applied only when global, pair-feature, and direction controls permit it. Do not enable removals during your first run. * History removal marks an item as unwatched. * Progress removal clears its playback position. * Watchlist removal removes the item from the Stremio Library. A Watchlist removal does not remove History. A History removal does not remove the item from the Library. ### Troubleshooting #### Items remain unresolved Confirm that the source item has an IMDb identifier. Configure TMDb metadata when one is unavailable. For episodes, confirm the show identifier, season number, and episode number. Specials and alternative episode orders can remain unresolved. #### No features are available A feature appears only when both providers support it in the selected direction. Stremio supports History, Progress, and Watchlist in both directions. Ratings appear only when Stremio is the target. #### Ratings are not written Confirm that Stremio is the target and that the source supports Ratings. Ratings below the configured Liked threshold create no reaction. Episode Ratings are not supported. #### Episode watched dates are missing or changed Stremio does not store individual episode watched timestamps. CrossWatch synchronizes watched state, but cannot recover unavailable dates. Do not use Stremio as the History source when exact episode dates must be preserved. #### Progress is not written Confirm that the item has a playback position and duration. Percentage-only Progress requires CrossWatch to resolve a duration. Configure TMDb metadata when the source does not provide one. #### Previous episode Progress disappeared Stremio stores one active episode Progress entry per series. Writing Progress for another episode replaces the active entry. #### Unexpected Watchlist items CrossWatch uses the Stremio Library as the Watchlist. Watched titles remain included. Remove unwanted titles from the Library or restrict them through pair rules. #### Changes are not written Confirm that **Dry run** is disabled and that **Add** or **Update** is enabled. For removals, confirm global and pair-feature removal settings. Review run details for unresolved items and missing identifiers. {% endtab %} {% tab title="Power users" %} ### How matching works CrossWatch primarily matches Stremio items using IMDb identifiers. * Movies require a movie IMDb identifier. * Episodes require the show IMDb identifier, season number, and episode number. * Watchlist and Ratings support movies and shows. History and Progress support movies and episodes. When IMDb is missing, configured TMDb metadata can resolve one from external identifiers, title, and year. Episode matching also uses the Stremio and Cinemeta episode list. The destination episode must use compatible season and episode numbering. ### Stremio History data #### Movies Movie History uses: ``` state.lastWatched state.timesWatched state.flaggedWatched ``` A movie is watched when `timesWatched` or `flaggedWatched` exceeds zero. `lastWatched` contains the latest available movie timestamp. Adding movie History sets watched state and the latest timestamp. Removing it clears watched state, count, and timestamp. #### Episodes Episode History uses: ``` state.watched ``` This serialized watched bitfield records which episodes are watched. It has no individual episode timestamps. CrossWatch does not use the Stremio Library modification timestamp as an episode watched timestamp. Library, metadata, or Progress updates can change it. Adding or removing episode History updates only the matching episode in the bitfield. Other watched episodes remain unchanged. ### Stremio Progress data Progress uses: ``` state.timeOffset state.duration state.video_id state.season state.episode ``` Movie records contain a position and duration. Series records contain one active episode through `video_id`, with one position and duration. Progress writes read, merge, and write the Stremio record. CrossWatch preserves unrelated History, Library, and metadata fields. The adapter has no automatic completion policy. High Progress does not automatically create History. ### Stremio Watchlist data CrossWatch treats Stremio Library membership as Watchlist state. An item is listed when: ``` removed = false temp = false ``` Watchlist supports movies and shows. Watched state does not exclude an item from the Library. Removing a Watchlist item changes Library membership only. It does not clear watched state or Progress. ### Stremio Ratings data Ratings are written through the Stremio reaction service. Supported values are: ``` liked loved ``` CrossWatch converts numeric Ratings using configurable thresholds. The defaults are: ```json { "stremio": { "ratings": { "liked_min": 6.0, "loved_min": 8.0 } } } ``` `liked_min` sets the lowest Rating that becomes Liked. `loved_min` sets the lowest Rating that becomes Loved. Ratings below `liked_min` are skipped. When `loved_min` is below `liked_min`, CrossWatch uses the Liked threshold as the effective Loved threshold. CrossWatch keeps pair-scoped local state for reactions it writes. This supports bookkeeping and duplicate prevention. It does not make Stremio a Ratings source. ### Multiple Stremio accounts Stremio does not expose account subprofiles through this adapter. CrossWatch supports separate connection Profiles. Each CrossWatch Profile represents one Stremio account and stores its own auth key. Select the correct Profile in each pair. Data is not shared between Stremio connection Profiles. ### Authentication CrossWatch connects with the Stremio email address and password. Stremio returns an auth key. CrossWatch stores the returned `authKey` as `auth_key`. It does not retain the email address or password after connecting. The auth key is encrypted in the CrossWatch configuration. The adapter uses Stremio’s internal account API, not the public addon API. ### Metadata enrichment IMDb is the primary Stremio identifier. Configured TMDb metadata can resolve: * A missing IMDb identifier. * A missing poster. * A missing runtime or duration. For episode Progress, CrossWatch can retrieve the runtime from TMDb. Metadata enrichment does not guarantee a match. Alternative episode orders, specials, and incorrect provider mappings can remain unresolved. ### Removal semantics History, Progress, and Watchlist expose present state. When removal synchronization is enabled, CrossWatch can apply a missing state as a removal. Ratings removal is available only when Stremio is the destination. Do not enable observed removals until the initial pair state is reviewed. The Stremio Library can contain watched titles and titles added for other reasons. ### Limitations 1. The adapter is experimental and uses an internal Stremio API. 2. Ratings are destination only and reduced to Liked or Loved. 3. Episode History has no individual watched timestamps. 4. Movie History has no complete list of separate play events. 5. One active episode Progress entry is available per series. 6. The Stremio Library is used as the Watchlist. 7. Feature whitelisting and playlists are unavailable. 8. Reliable sync needs IMDb identifiers and compatible episode numbering. 9. Stremio and Cinemeta must remain reachable during synchronization. ### Related docs * [Stremio](/crosswatch/settings/connections/media-clients/stremio.md) * [Configure Pairs](/crosswatch/settings/configure-pairs.md) * [TMDb Metadata](/crosswatch/settings/connections/metadata/tmdb-metadata.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/synchronization/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.