watchparty/docs/architecture.md

Architecture

Goals

• Watch the same title, in sync, with other users of the same Emby server.
• Use Emby as the media source (catalog + streaming) without requiring changes to Emby itself or its official clients.
• Access gated to people with an Emby account on this server — no anonymous use, no separate identity system.

Non-goals

• Chat/reactions — deliberately out of scope.
• OIDC/SSO — an OIDC provider (LemonLDAP::NG) is available in principle, but the explicit choice was Emby-only auth: simpler, no extra infra dependency, and everyone already has an Emby account.
• Full library navigation (Shows → Seasons → Episodes) in v1 — search-based catalog only, to keep the first version achievable. Revisit if browsing turns out to matter more than searching in practice.

Why this replaced an Emby plugin

The first attempt (still in src/WatchParty/, kept for reference) was a real Emby Server plugin: sync via ISessionManager's existing remote-control commands, a settings page via IHasWebPages, and — after a fair amount of reverse-engineering — a real user-facing page integrated into Emby's own web client menu (PluginPageInfo.EnableInUserMenu, undocumented but confirmed working; required a data-controller AMD module to satisfy Emby's modern ViewManager, found by reading the target server's actual viewmanager.js).

That plugin builds and installs correctly. What it hit a hard wall on: a button inside the video player itself, or on an item's detail page. An Emby developer confirmed on their own forum that plugins have no API for this ("It's currently not possible for a plugin to do this"), and nothing found in research since suggests that's changed. The only way to get a button into Emby's own player would be patching Emby's shipped web client files directly inside the Docker container — outside the plugin entirely, guaranteed to break on every Emby image update, and requiring manual reapplication each time. That trade-off wasn't worth it.

Building a standalone app sidesteps the question entirely: it's our own player, so there's no "how do I add a button to someone else's UI" problem in the first place, and sync can be tighter than nudging Emby's remote-control commands ever allowed (see below).

Full trace of the plugin investigation (real errors, real fixes, sources consulted) is in the git history of this file and of src/WatchParty/ — worth reading if a future Emby SDK update ever makes in-player integration possible and this gets revisited.

Components

server/   Node.js + Express + ws. Owns party/room state and the realtime
          sync channel. Never touches a media byte - see "Media never
          flows through our backend" below.

client/   Static frontend, plain JS + ES modules, no build step (same bias
          as the earlier plugin's control panel). Talks to two different
          things and must not confuse them:
            - Emby directly (embyApi.js): catalog, images, streaming.
            - Our own backend (party.js): create/join/leave a party, and
              the WebSocket for realtime sync.

Auth

Emby-only, as decided. The browser calls Emby's own POST /Users/AuthenticateByName directly (same call the old plugin's control panel used) and keeps the resulting AccessToken/User.Id in localStorage. Our backend never sees a password — only ever a token the browser already obtained from Emby, sent as a header (X-Emby-Token / X-Emby-UserId) on REST calls, or as the first WebSocket message (not a query string — tokens don't belong in URLs). The backend validates a token by asking Emby itself (GET /Users/{userId} with that token) rather than trying to verify anything cryptographically — see server/src/embyAuth.js.

Media never flows through our backend

client/js/embyApi.js builds Emby URLs (images, HLS stream) directly, and the browser fetches them straight from Emby. server/ only ever sees JSON party-coordination traffic and a handful of bytes per WebSocket message. The one deliberate exception: <img>/<video> elements can't send custom headers, so their URLs carry the Emby token as an api_key query parameter — unavoidable, and the same thing Emby's own web client does for images.

Control model: host drives, everyone else follows

Now that we own the player, the classic watch-party model (Teleparty, Amazon Watch Party, ...) fits better than the old plugin's "everyone keeps their own controls, shared reference position" — that design was specifically a concession to nudging pre-existing, independently-running Emby app sessions we didn't control. Here, there's only one player implementation, so:

• The party creator is the host. Their player has normal controls.
• Everyone else's <video> has controls hidden; a small notice says the host is in charge.
• Host → server → everyone else, over the WebSocket (server/src/wsHandler.js):
  • Event-driven: every play/pause/seeked on the host's video sends {type:"playstate", isPaused, positionTicks} immediately.
  • Heartbeat: also sent every 3s regardless, so latecomers/drift get corrected even without a discrete host action.
  • Followers apply pause/unpause immediately, and only seek if drift exceeds 1.5s (DRIFT_TOLERANCE_SECONDS in client/js/views/player.js) — avoids fighting small timing noise with constant re-seeks.
• If the host leaves, the server promotes another member (same fallback logic the old plugin used for its "reference" member).

Party lifecycle

In-memory only on the backend (server/src/partyManager.js) — a restart clears every party, which is fine: a party is meant to last one watch session, not persist for weeks. removeIdleParties sweeps anything with no activity for 4 hours.

Assumptions to verify

Unlike the plugin (which got to compile against Emby's real SDK assemblies), none of the Emby REST API assumptions below have been exercised against a real server yet — only smoke-tested against a stubbed/fake Emby URL to confirm the app's own code paths (routing, error handling) don't crash (see git history). Check these first when testing for real:

• CORS — the browser calls Emby from a different origin than this app. If Emby (or the openresty reverse proxy in front of it) doesn't answer preflight requests permissively, every direct call (including login) fails with a browser-level CORS error, not a normal HTTP error. Open the browser console on first test; if you see "CORS" anywhere, the fix is routing embyApi.js's JSON calls through server/ as a proxy instead of direct — video/image src URLs wouldn't need this (no CORS for those).
• /Users/{userId} for token validation — chosen deliberately over a guessed /Users/Me shortcut (not confirmed to exist on this Emby version), but not confirmed to behave as expected either.
• /Videos/{id}/master.m3u8 for HLS playback, with VideoCodec=h264&AudioCodec=aac forcing a broadly-compatible transcode target. Works for basically anything Emby can transcode, but is never the most efficient path (no direct play, no bitrate/quality negotiation) — fine for v1, worth revisiting once the basic flow works.
• Response field names (AccessToken, User.Id, User.Name, Items[].Id/Name/Overview/ProductionYear) — long-standing Emby/Jellyfin convention, same ones the old plugin's control panel used, not independently re-confirmed for this Emby version.
• X-Emby-Authorization header format — same caveat as above.

Known limitations

• Search-only catalog (see Non-goals) — no way to browse a show's episode list yet.
• One item per party; no shared queue.
• A party member needs a browser tab open and connected for sync to apply — there's no "catch up automatically when you come back" beyond whatever the next heartbeat corrects.
• No persistence: server restart or long idle time ends every party.