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.

Quick Start

For Users

Install OpenWatchParty on your existing Jellyfin server:

1. Deploy the Session Server

   docker run -d --name owp-session -p 3000:3000 \
     -e ALLOWED_ORIGINS="http://your-jellyfin:8096" \
     ghcr.io/mhbxyz/openwatchparty-session-server:latest
   

2. Install the Plugin via Jellyfin UI
   • Go to Dashboard > Plugins > Repositories
   • Add: https://mhbxyz.github.io/OpenWatchParty/jellyfin-plugin-repo/manifest.json
   • Go to Catalog > OpenWatchParty > Install
   • Restart Jellyfin
3. Enable the Client Script
   • Go to Dashboard > General > Custom HTML
   • Add: <script src="/web/plugins/openwatchparty/plugin.js"></script>
   • Save and hard refresh (Ctrl+F5)

See Installation Guide for detailed instructions.

For Developers

Set up a development environment:

git clone https://github.com/mhbxyz/OpenWatchParty.git
cd OpenWatchParty
make up      # Build and start Jellyfin + session server
make dev     # Start with log following
make watch   # Auto-restart on file changes

See Development Setup for the full workflow.

---

Documentation

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

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 Watch Party panel as latency indicator.
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.