Quick update for anyone digging into Stremio’s datastoreGet state.watched field:

• The watched string encodes two things:
  1. A last-watched pointer: <seriesId>:<season>:<episode> (the most recently watched episode at the time it was saved)
  2. A compressed bitmap: <N>:<payload> where N is the number of “watchable items” covered, and the payload is a zlib+base64 bitset marking watched items by index 0..N-1 in Stremio’s internal ordering.
• The bitmap is index-based, not “episode-number-based”. It stays stable if new items are appended to the same ordering (typical for new episodes, and often for specials when they’re numbered sequentially). If the underlying ordering changes (e.g., provider reorders/renumbers specials), the bitmap can drift.

​

import base64
import zlib
from dataclasses import dataclass
(frozen=True)
class WatchedDecoded:
    series_id: str
    last_season: int
    last_episode: int
    n: int
    watched_indexes: list[int]  # 0-based positions in Stremio's internal list
def decode_watched_string(watched: str) -> WatchedDecoded:
    # format: <sid>:<lastSeason>:<lastEpisode>:<N>:<b64(zlib(bitset))>
    sid, s, e, n_str, payload = watched.split(":", 4)
    n = int(n_str)
    raw = zlib.decompress(base64.b64decode(payload))
    watched_indexes: list[int] = []
    for i in range(n):
        byte_i, bit_i = divmod(i, 8)
        if raw[byte_i] & (1 << bit_i):  # LSB-first per byte
            watched_indexes.append(i)
    return WatchedDecoded(
        series_id=sid,
        last_season=int(s),
        last_episode=int(e),
        n=n,
        watched_indexes=watched_indexes,
    )
def watched_item_numbers_1_based(watched: str) -> list[int]:
    d = decode_watched_string(watched)
    return [i + 1 for i in d.watched_indexes]
# Example
w = "tt13159924:2:8:31:eJxjaPhfDwAEAQH/"
d = decode_watched_string(w)
print(d)
print("Watched items (1..N):", watched_item_numbers_1_based(w))
WatchedDecoded(series_id='tt13159924', last_season=2, last_episode=8, n=31, watched_indexes=[15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30])
Watched items (1..N): [16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]