- JavaScript 100%
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) #
Stremio (hourly poll) #
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
PlayedToCompletiondecides what counts as watched. Tune it in Dashboard > Playback > Maximum resume percentage. It also handles exact-end playback and items shorter thanMinResumeDurationSeconds, which a plain percentage gets wrong. The bridge computes the percentage anyway and puts it in the log line, sowrangler tailshowscreated movie "X" at 97%. - A watched list holds each film once. Rewatching reports
already-loggedrather than adding a second entry, the same way a rewatched episode does. - Jellyfin fires several
PlaybackStopevents per viewing. KV dedupes byItemIdfor 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/stremioin 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.
.envandwrangler.tomlare gitignored. - The webhook and
/sync/stremioboth 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_EMAILandSTREMIO_PASSWORDfrom.envonce 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
expclaim 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.