Support thread for emby-watchparty

Synchronized watch parties for Emby media servers — watch videos together with friends in real time, no guest Emby accounts needed.

What is emby-watchparty?

A self-hosted web app that sits in front of your Emby server and proxies HLS video streams to a group of viewers while keeping them synchronized. One person picks a video, everyone else joins with a 5-character party code in their browser, and play/pause/seek events propagate to every viewer in real time.

Key features

• Secure proxy architecture: your Emby server stays on your internal network — only the watch party app needs to be reachable by guests

• Real-time sync: play, pause, and seek events broadcast to every viewer instantly via WebSocket

• No guest accounts: party members don't need Emby logins — they just need the party code and a browser

• Skip Intro overlay: uses Emby's chapter/intro data to show a skip button during intro segments

• Autoplay / binge mode: auto-queues the next episode when the current one ends, with a countdown and cancel option

• Quality presets: 360p up to 1080p-high (10 Mbps)

• Native HLS subtitles: text subtitles served via the HLS manifest, image subtitles (PGS/VobSub) burned in automatically

• Live chat: built-in chat alongside the video

• Static session mode: optional single-party-always-open mode for small groups
  

Why this exists

Emby has a no built-in SyncPlay feature. Emby-Watchparty is for the case where you want to watch a movie with friends who don't have accounts on your server, they just open a URL and join. One Emby account (yours) proxies everything.

Installation on Unraid

Install from Community Applications. The template has all the common config exposed:

Required:

• Emby Server URL — e.g. http://192.168.1.100:8096

• Emby API Key — generate in Emby Dashboard > Advanced > API Keys

• Emby Username and Password — a dedicated Emby user for the app is recommended

Optional (advanced view):

• App Prefix (for reverse proxy deployments)

• Static Session Enabled / Static Session ID

• Log level, log file, log rotation

• HLS token validation, rate limiting, max users per party

Note: both the API key and the username/password are required. The API key is used for library browsing and admin calls, and the username/password obtain the session token Emby requires to serve HLS streams.

Hardware requirements

The watch party app itself is lightweight (Python + Flask + SocketIO) — what matters is your Emby server's transcoding hardware, since every user in the party triggers HLS transcoding.

emby-watchparty forces Emby to re-encode every stream (not stream-copy) because HLS.js needs uniform segment durations to seek reliably. This means hardware encoding (QSV, NVENC, VAAPI) makes a big difference:

• Intel QuickSync (UHD 630 or newer iGPU): 4-6+ concurrent 1080p streams at ~10 W power draw

• NVIDIA NVENC (GTX 1660+): 3+ streams stock, 8-12+ with the community NVENC patch

• Software x264 (no hardware accel): 2-6 users depending on CPU — a 9900K handled 6 concurrent pathological 70 Mbit/s streams in testing, stable at 70C

Full capacity numbers and deployment guides are in the project wiki.

Requirements

• An Emby server reachable from this container (local network is fine, preferred actually)

• Emby Premiere for hardware-accelerated transcoding (Emby's own licensing requirement, not ours)

• The app port (default 5000) reachable by your guests — use Tailscale, ZeroTier, or a VPN if you can't port-forward
  

Links

• Project: https://github.com/Oratorian/emby-watchparty

• Container image: ghcr.io/oratorian/emby-watchparty:latest

• Unraid template: https://github.com/Oratorian/unraid-templates/blob/main/emby-watchparty/emby-watchparty.xml

• Wiki (deployment guides, hardware planning, troubleshooting): https://github.com/Oratorian/emby-watchparty/wiki

• Technical deep-dive on Emby's HLS quirks: Emby quirks we learned the hard way

• Bug reports: https://github.com/Oratorian/emby-watchparty/issues

• Discord (for community support): https://discord.gg/RWUpxq9xsA
  

Support development

If the app has been useful, a small tip helps fund hardware and late-night reverse-engineering sessions:

ko-fi.com/jedziah

Current version

v1.6.4

A 2.0 rewrite is in progress, moving to FastAPI + Vue 3 with per-user transcodes, but is not yet stable or released.

Feedback welcome

If you run into issues on Unraid specifically — template config, GPU passthrough quirks, networking — please post here. Wiki edits are open too (the wiki has an Unraid deployment page that I'd love to keep current with real user experience).

Thanks for checking it out!

Heads up: Emby Watch Party 2.0.0 is landing soon - templates have split

Quick note for anyone running the emby-watchparty template from Community Applications.
The 2.0.0 release is imminent (currently on 2.0.0-beta18 plus the final round of pre-release fixes), and the CA template has been reshuffled to make room for it. If you don't change anything, an upgrade will eventually pull 2.0 automatically - that's fine for many setups, but you have a supported way to stay on 1.x.

What changed on the template side

The single emby-watchparty CA entry has become two:

• emby-watchparty (2.0, pinned to :latest) — the new default. This is the Vue 3 + FastAPI rewrite: per-user HLS streams, in-party admin panel, late-joiner voting, custom avatars, reverse-proxy support, and a lot more. Different env keys, different mount points.

• emby-watchparty-legacy (1.x, pinned to :legacy) — for anyone who wants to keep their existing 1.6.x install running unchanged. This tracks the legacy branch and the :legacy Docker tag, which currently equals 1.6.7.

What you should do

If you want to stay on the 1.x line for now:

1. Stop and uninstall your current emby-watchparty container (keep the appdata directory untouched).

2. Install the new emby-watchparty-legacy template from Community Applications.

3. Point it at the same appdata directory. Your .env, config, and behavior are unchanged.

You'll now be pinned to ghcr.io/oratorian/emby-watchparty:legacy, which will keep receiving security-only fixes through 2026-12-31. No feature work will land on the 1.x line after that date; migrate to 2.0 before then if you're security-conscious.

If you're happy to move to 2.0:

1. Stop and uninstall your current emby-watchparty container (again, keep appdata).

2. Install the new emby-watchparty template (2.0).

3. Fill out the new required fields: Emby Server URL, Emby API Key, Session Secret (generate once with openssl rand -hex 32), and Session Cookie Secure (true if you're behind HTTPS, false for LAN HTTP).

4. Add three host-path mounts: /app/data, /app/images/avatars, and /app/config.json. Touch the config.json host file first or Docker creates it as a directory and the backend crashes.

5. Boot the container, open the UI, click Login to Become Host, and give it your Emby credentials. EMBY_USERNAME / EMBY_PASSWORD are gone from the env — host auth is in-party now.

Detailed step-by-step for Unraid (and Docker Compose, TrueNAS SCALE, bare metal) is in the migration guide: docs/Migration-HowTo.md. It covers the full breaking-change list, the new session-cookie hardening block from beta18 (SESSION_SECRET, SESSION_COOKIE_SECURE, CORS_ALLOWED_ORIGINS), and the registry/branch renames.

What 2.0 gives you

Short version, since the full changelog is enormous:

• Per-user transcodes. Each viewer gets their own audio track, subtitles, and quality tier without disturbing the rest of the party. Change any of it mid-playback and only you re-buffer.

• In-party admin panel. 17+ runtime settings hot-reloadable from /admin. No more restarts for REQUIRE_LOGIN, log levels, rate limits, or the new binge-watch toggles.

• Late-joiner voting. When someone joins mid-video, existing viewers vote on whether to admit them (with an automatic video restart so everyone lands on a keyframe-aligned segment).

• Reverse-proxy support that actually works end-to-end. Set APP_PREFIX=/watchparty and one uvicorn process serves the whole app under that subpath, WebSocket included. One image, any path.

• Emby's own "Continue Watching" is respected. Resume prompt on partially-watched items, progress bars on library cards, and the "played %" pulled from Emby's own UserData.

• Custom avatars with recovery codes — upload once, get a three-word code, restore on any browser without an account.

• A-Z jump bar in the library, multi-version playback (Director's Cut vs Theatrical vs whatever Emby offers), binge-watching auto-advance, jump-to-timestamp input, and a UI refresh built on the Refined Cyber design language.

Full per-beta breakdown lives in SUMMARY-OF-CHANGES.md.

About 1.6.7 (the current :legacy image)

While you're here — 1.6.7 shipped a security bump for CVE-2026-48804 in python-socketio and dropped a stale rotation workaround now that rsyslog-logger 1.0.6 fixed it upstream. If you're on the legacy template you already have this via :legacy; if you're pinning to :1.6.6 explicitly, consider bumping.

---

Links

• Repository: github.com/Oratorian/emby-watchparty

• Migration guide: docs/Migration-HowTo.md

• Full 2.0 changelog: SUMMARY-OF-CHANGES.md

• Issues: github.com/Oratorian/emby-watchparty/issues

Anything unclear or breaking on your setup — reply here or open an issue with your platform, current version, and the exact error. Happy watching.