SynCinema

Self-hosted watch parties with synchronized playback, built-in chat, WebRTC calls, invite links, and an admin panel.

SynCinema is for small private groups who want a single app to:

• watch local media in sync
• talk in chat while watching
• jump into video or audio calls beside player
• manage invites, users, and media from one admin UI

Feature Overview

• Synchronized playback: play, pause, seek, and switch movies for everyone in room.
• Real-time chat: persistent chat history with reactions and spoiler messages.
• WebRTC calls: peer-to-peer video and audio calls built into viewing layout.
• Invite links: create expiring or limited-use sign-up links from admin panel.
• Admin tools: manage users, movies, downloads, server stats, and broadcasts.
• SQLite storage: simple self-hosted setup with local databases in instance/.
• Optional Cloudflare tunnel: share session without router setup.
• Health endpoint: GET /api/health for smoke checks and container health probes.

Quick Start

Choose one path:

1. Docker Quick Start for fastest self-hosted setup.
2. Local Dev if you want to run SynCinema directly with Python.

First run is built in:

1. Start SynCinema.
2. Open /login.
3. If no users exist yet, SynCinema shows a first-run setup form.
4. Create first account. It becomes admin immediately.
5. Add media to movies/, then invite everyone else from Admin panel.

Docker Quick Start

Requirements:

• Docker
• Docker Compose plugin

Commands:

cp .env.example .env
docker compose up --build

Then open:

• http://127.0.0.1:17701/login

Persistent data lives in mounted project folders:

• movies/: movie files and .vtt subtitles
• pfp/: uploaded avatars
• instance/: SQLite databases and generated TLS certs

Useful Docker commands:

docker compose up --build
docker compose down
docker compose logs -f

Local Dev

Requirements:

• Python 3.11+ recommended
• pip

Commands:

cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Then open:

• http://127.0.0.1:17701/login

Quick smoke check:

python -m unittest discover -s tests -p "test_*.py"
curl http://127.0.0.1:17701/api/health

Windows PowerShell activation:

.venv\Scripts\Activate.ps1

Configuration

SynCinema reads configuration from .env in project root. Start from .env.example.

Important settings:

Variable	Default	What it does
SECRET_KEY	temporary local fallback	Flask session secret. Set this for persistent or shared deployments.
HOST	127.0.0.1	Bind address for local runs. Docker overrides to 0.0.0.0.
PORT	17701	HTTP port.
INSTANCE_FOLDER	instance	Stores SQLite databases and generated certs.
MOVIE_FOLDER	movies	Media library path.
AVATAR_FOLDER	pfp	Uploaded avatar storage.
USE_HTTPS	False	Generates self-signed certs for LAN/WebRTC use.
USE_CLOUDFLARE_TUNNEL	False	Starts Cloudflare Quick Tunnel for remote access.
ADMIN_USER	empty	Optional username to auto-promote to admin after registration.
MAX_CHAT_MESSAGES	100	Chat history restored on startup.

Notes:

• If SECRET_KEY is left unset, SynCinema uses a temporary in-memory key for local runs.
• If USE_CLOUDFLARE_TUNNEL=True, SynCinema requires a real SECRET_KEY at startup.
• Runtime folders are created automatically if missing.

Media and Storage

Place media files in movies/.

Supported flow:

• video files: .mp4, .mkv, .webm, .mov, and other common formats
• subtitles: .vtt files beside movie file with matching base name
• avatars: uploaded automatically into pfp/

Example:

movies/
  BladeRunner2049.mkv
  BladeRunner2049.en.vtt
  BladeRunner2049.it.vtt

First-Run Onboarding

Fresh installs no longer require a manual bootstrap hack.

When SynCinema has zero users:

1. Open /login
2. Create first account
3. That account becomes admin
4. Open Admin panel
5. Generate invite links for everyone else

This keeps public registration closed while still giving new self-hosted installs a clean starting path.

Production Notes

• USE_HTTPS=True is useful on LAN when browsers need secure context for camera and microphone access.
• Self-signed HTTPS will trigger a browser warning until you trust cert once.
• Cloudflare Quick Tunnel is optional and best for lightweight remote access.
• For any shared deployment, set a real SECRET_KEY in .env.

Project Structure

app.py                  Flask entrypoint and startup flow
src/config.py           environment parsing and runtime defaults
src/routes/             auth, media, invites, admin, health, main pages
src/modules/            Socket.IO event handlers for playback, chat, calls
src/models.py           SQLAlchemy models
templates/              Jinja templates
static/                 CSS, JS, images
.github/workflows/      GitHub Actions workflows
tests/                  minimal smoke and startup tests

GitHub Actions Cloud Session

SynCinema includes a GitHub Actions workflow for temporary cloud-hosted sessions.

High-level flow:

1. Fork repository
2. Open Actions
3. Run 🎬 Run SynCinema
4. Register admin account with provided username
5. Share generated invite link

Use this for temporary sessions, not durable hosting. Runner storage is ephemeral.

Verification

Local checks used in this repo:

python -m compileall app.py src tests
python -m unittest discover -s tests -p "test_*.py"
curl http://127.0.0.1:17701/api/health

Expected health response looks like:

{"cloudflare_tunnel":false,"current_movie":null,"movies":0,"status":"ok","users":0}

License

MIT. See LICENSE.