Nicolas
5d535d18d8
All checks were successful
Publier l'image Docker / publish (push) Successful in 10s
Requested: Socket.IO instead of raw WebSockets, and explicit attention
to memory leaks. Auditing for the second turned up two real, concrete
leaks, independent of the transport library:
1. Server-side: a raw `ws` server has no idea a client is gone unless
it gets a proper close frame - a sleeping laptop, a network drop, a
killed tab never fire 'close', so the PartyMember's socket
reference (and everything it closes over) sat in memory forever,
and the party was never cleaned up by anything else either
(removeIdleParties only looks at lastActivityUtc). Socket.IO's
built-in heartbeat (pingInterval/pingTimeout) detects and closes
these out on its own - a real, not just cosmetic, reason to prefer
it here.
2. Client-side: router.js only ever did currentRoot.innerHTML = ''
between routes, destroying DOM but never telling the outgoing
view's JS to stop. Leaving the player any way other than its own
"Quitter" button (a sidebar link, browser back) left the 3s
heartbeat setInterval, the realtime connection, and the hls.js
instance all running against a detached <video> indefinitely, for
as long as the tab stayed open.
Fixes:
- server/src/socketHandler.js replaces wsHandler.js: same protocol
(see its own top comment), over Socket.IO. Rooms (socket.join/
io.to) replace manually iterating party.members to broadcast.
Error event renamed to "errorMessage" - Socket.IO reserves "error".
- server/src/index.js: socket.io server instead of a raw
WebSocketServer, same-origin (no CORS config needed).
- client/js/party.js: socket.io-client (window.io, loaded via
<script> in index.html) instead of hand-rolled WebSocket + JSON
framing - also gets automatic reconnection for free.
- router.js: route() handlers may now return a cleanup function;
render() calls whatever the previous view returned before switching
to the next route, regardless of how navigation happened.
- player.js returns a cleanup that clears the heartbeat, destroys
hls, disconnects the socket, and removes its document-level click
listener (now named, not inline-anonymous, specifically so it CAN
be removed - an anonymous one added fresh per visit would itself
have been a slow leak even with everything else fixed). The
"Quitter" button is now just navigate('/home') - cleanup runs the
same way regardless of how you leave.
Verified for real (see session history): a real Socket.IO client
connected to a really-running local server end to end. Then, with
document.addEventListener/removeEventListener and setInterval/
clearInterval instrumented, drove the router through repeated "join a
party, then navigate away without clicking Quitter" cycles - adds and
removes matched exactly every time (3/3 listeners over three cycles,
2/2 intervals over two), nothing left pending.
docs/architecture.md has the full writeup under "Realtime transport:
Socket.IO, and two real memory leaks".
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
115 lines
5 KiB
Markdown
115 lines
5 KiB
Markdown
# Watch Party for Emby
|
|
|
|
A standalone web app for watching the same title, in sync, with other users
|
|
of the same Emby server. It reads your Emby catalog and streams your Emby
|
|
media, but it's its own app with its own player — not an Emby plugin.
|
|
|
|
See [docs/architecture.md](docs/architecture.md) for the full design,
|
|
including why this replaced an earlier Emby-plugin attempt (still in
|
|
[src/WatchParty/](src/WatchParty/) for reference — see below).
|
|
|
|
## How it works
|
|
|
|
1. Sign in with your Emby account (just username/password — the server
|
|
address is fixed server-side, see Deploying below).
|
|
2. A sidebar lists your Emby libraries; the home page shows every ongoing
|
|
watch party plus a "recently added" row per library, Emby-style.
|
|
3. Pick a movie/episode tile and hit "Lancer une watch party" (or drill into
|
|
a Series' seasons/episodes first) — you become the host — or join one
|
|
with a 6-character code.
|
|
4. The host's play/pause/seek drives everyone else's player automatically;
|
|
starting from an episode queues the rest of the series so the host can
|
|
just hit "Épisode suivant" instead of restarting a party each time.
|
|
|
|
Everything — catalog, images, video, sync — flows through this app's own
|
|
backend, which proxies whatever it needs from Emby server-side. The browser
|
|
never talks to Emby directly and never holds an Emby access token; it only
|
|
ever has a session cookie for this app.
|
|
|
|
Music isn't part of this yet — it needs its own player and a collaborative
|
|
playlist, different enough to be its own pass. The sidebar already lists a
|
|
Music library if you have one; the page just says so for now.
|
|
|
|
## Status
|
|
|
|
Login, and the rendering/navigation logic for the sidebar/home/library/series
|
|
pages, have been exercised end to end (login against the real Emby server
|
|
with intentionally-wrong credentials; the pages against mocked API
|
|
responses). See [docs/architecture.md](docs/architecture.md#assumptions-to-verify)
|
|
for exactly what that does and doesn't confirm — the real Emby response
|
|
shapes this now depends on (library `CollectionType`, seasons/episodes,
|
|
`PlaybackInfo`'s media streams) and actual HLS playback are still unverified.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
server/ Node.js backend: proxies ALL Emby access (auth, catalog,
|
|
images, HLS streaming) and coordinates party/room state +
|
|
realtime sync. The browser only ever talks to this.
|
|
src/index.js Express app + REST endpoints
|
|
src/embyAuth.js server-side login against Emby + session cookies
|
|
src/embyProxy.js generic Emby request/response proxying (incl. HLS)
|
|
src/socketHandler.js Socket.IO protocol (see comments in the file)
|
|
src/partyManager.js in-memory room state
|
|
|
|
client/ Static frontend (plain JS, ES modules, no build step).
|
|
Talks only to server/ - never to Emby directly.
|
|
js/shell.js persistent sidebar + #mainContent the router swaps
|
|
js/tiles.js poster-tile rendering shared by home.js and library.js
|
|
js/embyApi.js calls our own /api/* routes (auth, catalog, playback options)
|
|
js/party.js our own backend's party REST + Socket.IO client
|
|
js/views/ one file per screen: login, home, library, series, player
|
|
|
|
src/WatchParty/ The earlier Emby-plugin attempt. Builds fine and installs,
|
|
but Emby has no supported extension point for a player
|
|
button, and even menu integration required reverse-
|
|
engineering undocumented internals - see
|
|
docs/architecture.md for the full story. Kept for
|
|
reference; not the active direction.
|
|
|
|
docs/architecture.md full design doc for the standalone app
|
|
```
|
|
|
|
## Running locally
|
|
|
|
```bash
|
|
cd server
|
|
npm install
|
|
EMBY_SERVER_URL=https://your-emby-server npm start
|
|
```
|
|
|
|
Then open `http://localhost:3000`.
|
|
|
|
## Deploying
|
|
|
|
Build the Docker image from the **repo root** (it needs both `server/` and
|
|
`client/`):
|
|
|
|
```bash
|
|
docker build -f server/Dockerfile -t watchparty .
|
|
docker run -d --name watchparty -p 3000:3000 -e EMBY_SERVER_URL=https://theater.media.kyuno.fr watchparty
|
|
```
|
|
|
|
Then put it behind your existing reverse proxy like everything else
|
|
(`theater.media.kyuno.fr`, `git.dev.kyuno.fr`, ...), e.g.
|
|
`watchparty.kyuno.fr` → `http://<container>:3000`.
|
|
|
|
## Roadmap
|
|
|
|
- [x] Design + scaffold the standalone app
|
|
- [x] Proxy all Emby access server-side; Emby-themed UI (sidebar, carousels)
|
|
- [x] TV show navigation (Series → Seasons → Episodes) + episode auto-queue
|
|
- [x] Player language/subtitle/quality pickers
|
|
- [x] Socket.IO instead of raw WebSockets; fixed two real memory leaks
|
|
(dead-connection cleanup server-side, view teardown on navigation
|
|
client-side) — see docs/architecture.md
|
|
- [ ] Try a full party end-to-end with two real accounts (still the main gap)
|
|
- [ ] Music: dedicated player, artist/album browsing, collaborative playlist
|
|
- [ ] Tune transcoding target / support direct play when possible
|
|
|
|
No chat, no OIDC — deliberately out of scope (Emby-only auth was the
|
|
explicit choice; see docs/architecture.md).
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|