Records what you watch to Popfeed, via ATProto, using a Cloudflare Worker. Currently supports Jellyfin and Stremio.
README.md

watch-bridge #

Records what you finish watching on Jellyfin or Stremio to Popfeed, via ATProto, using a Cloudflare Worker.

Runs comfortably inside the Cloudflare free tier. The Worker is about 4 KiB gzipped and has no runtime dependencies.

How it works #

Jellyfin pushes. Stremio cannot -- its addon protocol has no playback event, and scrobbling is a first-party feature -- so its library is polled hourly.

Jellyfin (webhook) #

webhookcreateRecordid lookup (cached in KV)Jellyfin (LAN)Cloudflare Workeryour PDSTMDb

Stremio (hourly poll) #

poll hourlywatched librarycreateRecordid lookup (cached in KV)Cloudflare WorkerStremio cloudyour PDSTMDb

It follows the conventions the Popfeed app itself uses:

You finish Record written
A movie One social.popfeed.feed.listItem, creativeWorkType: movie, in your watched-movies list
An episode The series' listItem gets the episode appended to watchedEpisodes

Both kinds carry the same metadata the Popfeed app writes, fetched from TMDb: poster, backdrop, genres, release date, and the main credit — the director for a movie, the network for a series. Series records created before this was added are backfilled on the next episode, without overwriting anything the app wrote.

Enrichment is best-effort. If TMDb is unreachable the record is still written, and the app falls back to hydrating from tmdbId.

Nothing is ever posted to your feed. The bridge only updates your library.

Jellyfin never sends the series TMDb id, only the episode's own external ids, so TMDb resolves it. Lookups are cached in KV for 30 days.

Requirements #

  • A Cloudflare account (free plan)
  • A Bluesky/ATProto account, and an app password — not your real one
  • A free TMDb API key — required for TV, and used to enrich movie records
  • Jellyfin with the Webhook plugin installed, and/or a Stremio account

Setup #

1. Install.

npm install
cp .env.example .env      # then fill in your handle and app password

.env is only used by the local CLI. The Worker reads Cloudflare secrets.

2. Create your lists in the Popfeed app. Mark one movie and one TV show as watched. The app creates the lists with the listType values the Worker needs. Check them with:

node scripts/popfeed.mjs lists

3. Configure.

cp wrangler.example.toml wrangler.toml
npx wrangler login
npx wrangler kv namespace create BRIDGE    # paste the id into wrangler.toml
node scripts/popfeed.mjs config            # paste the four lines into wrangler.toml

wrangler.toml is gitignored, so your namespace id and DID stay local.

4. Deploy, then set the secrets.

npx wrangler deploy

npx wrangler secret put BLUESKY_HANDLE
npx wrangler secret put BLUESKY_APP_PASSWORD
npx wrangler secret put WEBHOOK_SECRET      # any long random string
npx wrangler secret put TMDB_TOKEN          # TMDb v4 read token, or a v3 key

Generate a webhook secret with openssl rand -base64 32.

If more than one person uses your Jellyfin server, set JELLYFIN_USER in wrangler.toml to your username or user id. The bridge writes to one Popfeed account, so without it everyone's viewing lands in yours. Prefer the username: the plugin sends the user id with dashes through a template and without them in raw mode, while the username is the same in both.

5. Configure Jellyfin. Dashboard → Plugins → Webhook → Add Generic Destination.

Setting Value
Webhook Url https://<your-worker>.workers.dev/jellyfin-webhook
Notification Type Playback Stop only
Item Type Movies and Episodes
Add Request Header Authorization = Bearer <your WEBHOOK_SECRET>
Template paste the contents of src/sources/jellyfin/template.hbs

The Template box must not be empty. The plugin sends the rendered template as the request body, so an empty template means an empty body.

6. Test. Run npx wrangler tail, then play something and skip to the end.

Optional: Stremio #

Stremio syncs your library to its own servers. That is the same state its first-party Trakt integration reads, so the bridge polls it hourly.

Put your Stremio email and password in .env, then:

node scripts/stremio.mjs login      # prints an authKey
node scripts/stremio.mjs preview    # shows what would be recorded

Your password never leaves your machine. Send only the authKey to Cloudflare:

npx wrangler secret put STREMIO_AUTH_KEY

Then delete STREMIO_EMAIL and STREMIO_PASSWORD from .env. Leave the secret unset to disable Stremio entirely; the Jellyfin side is unaffected.

Force a poll without waiting for the cron tick:

curl -X POST https://<your-worker>.workers.dev/sync/stremio \
     -H "Authorization: Bearer $WEBHOOK_SECRET"

How episodes are found. A series LibraryItem names only the most recently watched episode by hand. The full set lives in a compressed bitfield whose indices mean nothing without the series' ordered video list, which the bridge fetches from Cinemeta and decodes. The bitfield carries its own anchor checksum, so if Cinemeta has changed since Stremio wrote the field, nothing is decoded rather than the wrong episodes being recorded.

Local CLI #

Inspects and repairs your Popfeed records. Reads credentials from .env.

node scripts/popfeed.mjs whoami
node scripts/popfeed.mjs scan                        # every social.popfeed.* record
node scripts/popfeed.mjs lists
node scripts/popfeed.mjs config                      # wrangler.toml vars
node scripts/popfeed.mjs records <collection> [n]
node scripts/popfeed.mjs unwatch <rkey> <season> <episode>
node scripts/popfeed.mjs delete <collection> <rkey>

node scripts/stremio.mjs login
node scripts/stremio.mjs library [n]
node scripts/stremio.mjs preview

Tests #

npm test

Node's built-in runner, no dependencies. Covers the bitfield decoder, the poll cursor, the webhook parser and the cache.

Notes #

  • Jellyfin's own PlayedToCompletion decides what counts as watched. Tune it in Dashboard > Playback > Maximum resume percentage. It also handles exact-end playback and items shorter than MinResumeDurationSeconds, which a plain percentage gets wrong. The bridge computes the percentage anyway and puts it in the log line, so wrangler tail shows created movie "X" at 97%.
  • A watched list holds each film once. Rewatching reports already-logged rather than adding a second entry, the same way a rewatched episode does.
  • Jellyfin fires several PlaybackStop events per viewing. KV dedupes by ItemId for 6 hours, before any TMDb call is made.
  • Episode appends use swapRecord, so two episodes finishing at the same moment cannot overwrite each other.
  • Items with no TMDb or IMDb id are skipped. Fix them with Identify in Jellyfin, then refresh metadata.
  • The Stremio poll handles at most 4 items per run, because a Worker allows 50 subrequests. Anything left over is picked up by the next poll: the cursor advances only over items that actually finished, and it records which ids it covered at its own timestamp, so an item is never skipped past and never replayed forever. A run stops at the first failure and retries it next time; an item that fails three runs in a row is abandoned with a loud log, so one broken item cannot stall the library. A large first import takes several hours; POST /sync/stremio in a loop drains it faster.
  • Handlebars escapes for HTML, not for JSON, so "Rock & Roll" arrives as "Rock & Roll". Titles are decoded on the way in. A title containing a backslash makes the rendered template invalid JSON outright; that is repaired rather than dropped, and anything still unparseable is logged with the body.
  • Episode ids for a whole series cost one TMDb request, not one per season. TMDb appends up to 20 sub-resources to a single call, so even a long-running show fits comfortably inside a Worker's subrequest budget.
  • Popfeed's published lexicons do not fully match what the app writes. The app ignores unknown collections silently, so a "successful" write can still be invisible. Verify by reading records back.
  • TODO.md lists the known issues that are not fixed, and what to check before fixing each one.

Layout #

Each source owns a directory, and everything specific to it lives inside.

File Responsibility
src/index.js Router. Nothing else.
src/watch-event.js The normalized shape every source produces
src/sources/jellyfin/index.js All Jellyfin-specific knowledge
src/sources/jellyfin/template.hbs The webhook template, next to the code that parses it
src/sources/stremio/index.js All Stremio-specific knowledge
src/sources/stremio/watched.js Decodes Stremio's watched-episode bitfield
src/scrobble.js WatchEvent to Popfeed records. Source-agnostic.
src/records.js Reads and writes listItem records
src/tmdb.js Id resolution and metadata, all cached
src/session.js ATProto session, cached and refreshed
src/xrpc.js Minimal XRPC client
src/util.js Shared helpers
test/ npm test. No dependencies, no runner.

Adding another source #

Add a directory under src/sources/ whose index.js produces WatchEvent objects and calls scrobble(env, event). Nothing else changes. Dedupe keys and series lookup keys are both namespaced by event.source, so two sources cannot collide.

A WatchEvent carries a source name and id, a kind of movie or series, a title, optional series/season/episode, whatever of tmdbId/imdbId/tvdbId the source knows, and a timestamp. See src/watch-event.js for the full shape.

One field is easy to miss: seriesKey. It is whatever the source uses to name a series that stays the same across all of its episodes, and it exists only to be a cache key. Jellyfin's per-episode ids all differ, so without it the series lookup is repeated for every single episode.

Security notes #

  • Secrets live in Cloudflare, never in this repo. .env and wrangler.toml are gitignored.
  • The webhook and /sync/stremio both require a bearer secret, compared in constant time.
  • Error responses are generic. Details go to the logs only.
  • The Stremio auth key is never included in an error message.
  • Your Stremio password is only ever used by the local login script. Delete STREMIO_EMAIL and STREMIO_PASSWORD from .env once you have an authKey; they are not needed again.
  • External ids from a webhook are validated before they reach a TMDb request path, a KV key, or a permanent record.
  • The cached ATProto session expires from KV on its own, at whatever its refresh token's exp claim says, so it cannot outlive the credential it holds.
  • Stremio's watched bitfield is decompressed with a hard output bound. It is attacker-shaped data: zlib turns 200 KB into 200 MB, and a Worker has 128 MB.

Record shapes #

The record shapes here were derived by doing each action once inside the Popfeed app, then dumping the repo with node scripts/popfeed.mjs scan and copying what the app actually wrote.

Popfeed's published lexicons are community-maintained and disagree with the app in practice, so they are not used or vendored here. If Popfeed changes its format, run scan again and compare.

License #

MIT, see LICENSE.

This product uses the TMDb API but is not endorsed or certified by TMDb.