OpenWatchParty Documentation

OpenWatchParty is a Jellyfin plugin that enables synchronized media playback across multiple clients. Watch movies and shows together with friends, no matter where they are.

Version 0.7 includes room chat, shared playback controls, episode queues with an up-next countdown, expiring invite links, and host recovery and transfer. See the feature guide for details.

OpenWatchParty room panel in Jellyfin

Quick Start

For Users

Deploy the session server and install the plugin. Follow the illustrated first watch-party tutorial for installation, screenshots and a two-person walkthrough. The Installation Guide covers manual alternatives.

For Developers

Set up a development environment:

git clone https://github.com/mhbxyz/OpenWatchParty.git
cd OpenWatchParty
just setup   # Install client dependencies and configure Git hooks
just up      # Build and start Jellyfin + session server
just dev     # Start with log following
just watch   # Auto-restart on file changes

The dev stack binds to loopback and defaults to unauthenticated local development when JWT_SECRET is empty. Production Compose requires JWT authentication. See Development Setup for the full workflow and First Watch Party for the illustrated host/guest steps.

Documentation

Getting Started	Operations	Technical
First Watch Party	Installation	Architecture
Overview	Guided Setup	Protocol
Features	Configuration	Server
User Guide	Deployment	Client
FAQ	Compatibility	Plugin
	Security	Sync Algorithms
	Troubleshooting	REST API
	Monitoring

Development

Development Setup - Get started contributing
Contributing Guide - Code style and PR process
Testing - Running tests
CI/CD - Automated workflows
Release Process - How releases are made

Architecture Overview

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Jellyfin Web   │     │  Session Server │     │  Jellyfin Web   │
│    (Host)       │◄───►│     (Rust)      │◄───►│   (Clients)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                        │                       │
        └────────────────────────┴───────────────────────┘
                         WebSocket (ws://)

Components:

Jellyfin Plugin (C#) - Serves client JavaScript, provides configuration UI
Session Server (Rust) - Manages rooms and relays sync messages via WebSocket
Web Client (JavaScript) - Injected into Jellyfin UI, handles playback synchronization

Glossary

Technical terms used throughout this documentation:

Term	Full Name	Description
HLS	HTTP Live Streaming	Adaptive streaming protocol that breaks video into small segments. Used by Jellyfin for transcoded content.
RTT	Round-Trip Time	Time for a message to travel from client to server and back. Displayed in the room bar as latency.
EMA	Exponential Moving Average	Smoothing algorithm used for clock synchronization. Prevents sudden jumps in time offset.
JWT	JSON Web Token	Compact, URL-safe token format for authentication. Contains user identity claims signed with a secret key.
CORS	Cross-Origin Resource Sharing	Browser security mechanism controlling which websites can connect to the session server.
WebSocket	-	Full-duplex communication protocol over a single TCP connection. Used for real-time sync.
Drift	-	Difference between expected and actual playback position. Corrected by adjusting playback rate.
Host	-	The user who created the watch party room. Has exclusive control over playback.