watchparty/spec/static-watch-party.md

Watch party statique (permanente)

Objectif

Suivre une série entière, ou une playlist vidéo, en groupe sur plusieurs soirées. L'app mémorise :

• l'avancement du groupe : les éléments terminés ensemble, et où la dernière séance s'est arrêtée ;
• l'avancement de chaque personne : ce qu'elle a vu.

Une personne qui revient ou qui rejoint en cours de route voit la liste de ce qu'elle a manqué et peut le rattraper.

Contrairement à une watch party classique, qui vit en mémoire et disparaît avec son dernier membre, une watch party statique est persistée sur disque et survit aux redémarrages.

Modèle

Entité	Où	Rôle
StaticParty	server/src/types.ts, persistée	la « saison » du groupe : items, progression du groupe, membres
StaticPartyMember	dans StaticParty.members	watchedItemIds = ce que la personne a vu dans l'app
Séance	une Party live ordinaire + party.staticLink	la lecture elle-même : lecteur, sync, flux partagé et lobby réutilisés tels quels

party.staticLink.mode :

• group : la séance du groupe. Un item terminé fait avancer le groupe et est crédité à chaque participant connecté.
• catchUp : un rattrapage. L'item est crédité aux participants connectés uniquement, le groupe ne bouge pas.

party.hiddenFromLobby : un rattrapage en solo n'apparaît pas dans la liste des watch parties en cours.

Règles

• Item terminé :

  • l'hôte passe à l'item suivant (next),
  • ou le dernier item de la file se termine (itemEnded, nouvel event socket réservé à l'hôte).

  Les deux passent par PartyService.completeCurrentItem, qui gère aussi le flag Played d'Emby. Un même item n'est jamais compté deux fois de suite (lastCompletedItemId). C'est la même heuristique que PlaystateService.markPlayed : « le groupe est passé à la suite » vaut « vu ».

• Seuls les membres connectés au moment où l'item se termine sont crédités. Une personne partie en cours d'épisode l'a donc manqué ; elle peut le marquer comme vu.

• Manqués d'une personne : les items terminés par le groupe, dans l'ordre de la liste, moins ceux qu'elle a vus dans l'app (watchedItemIds), moins ceux qu'Emby a déjà en Played pour son compte (vus ailleurs). C'est la fonction pure computeMissedIds.

• Reprise : le sweep existant des 20 s enregistre la position de l'hôte (group.resumePositionTicks). La séance suivante démarre avec cette position comme position de l'hôte, que Player.ts utilise déjà pour placer la première image.

• Nouveaux épisodes : chaque lecture de la page, et chaque lancement de séance, recharge la source. Les nouveaux items sont ajoutés à la fin ; les items retirés de la source sont conservés dans l'historique (mergeItemLists).

• Accès : ouverte à tous les comptes Emby.

  • Rejoindre = devenir membre. Rejoindre la séance du groupe depuis le lobby rend aussi membre de la watch party statique.
  • N'importe quel membre peut lancer la séance ; celui qui la lance en devient l'hôte.
  • Quitter efface sa propre progression.
  • Seul le créateur peut supprimer la watch party.

• Contenus : séries et playlists vidéo uniquement. Une playlist musicale est refusée.

API (server/src/index.ts)

Méthode	Route	Rôle
GET	/api/static-parties	liste, avec le nombre de manqués de l'utilisateur et la séance en cours
POST	/api/static-parties	{sourceId, name?} : série, épisode (sa série) ou playlist
GET	/api/static-parties/:id	détail : items + état groupe / utilisateur, membres, missedItemIds
POST	/:id/join, /:id/leave	devenir membre / quitter
DELETE	/:id	supprimer (créateur uniquement)
POST	/:id/session	lancer la séance du groupe, ou rejoindre celle en cours, puis renvoyer {partyId}
POST	/:id/items/:itemId/watched	marquer comme vu
POST	/:id/catch-up	{itemIds, mode: 'solo'|'party'}, renvoie {partyId}

Persistance

• StaticPartyStore écrit un fichier JSON par watch party : ${DATA_DIR}/static-parties/<id>.json, au format {version: 1, party}.
  • DATA_DIR vaut ./data par défaut, et /data dans l'image Docker. docker-compose.yml y monte ./data.
  • Un fichier par party limite les dégâts : une écriture ne touche que la party modifiée, et un fichier corrompu ne coûte que cette party-là.
  • L'écriture est atomique (.tmp puis rename) et debouncée (2 s) party par party. Elle est flushée de façon synchrone sur SIGTERM/SIGINT.
  • Au démarrage, un .tmp restant (écriture interrompue) est supprimé ; le vrai fichier, s'il existe, est la dernière version complète.
  • Un fichier corrompu (ou dont le nom ne correspond pas à l'id) est renommé en .corrupt et ignoré ; les autres parties se chargent normalement. Le serveur ne crashe jamais pour ça.
  • Supprimer une party supprime son fichier et annule toute sauvegarde en attente pour elle.
  • Migration : l'ancien fichier unique ${DATA_DIR}/static-parties.json de la première version est éclaté en un fichier par party au premier démarrage, puis renommé en .migrated (conservé, pas supprimé).
• Pas de SQLite : l'image tourne en Node 20 (pas de node:sqlite), une dépendance native serait une première dans l'image, et les données sont minuscules.
• livePartyId n'est jamais persisté : un redémarrage termine toutes les séances, et la reprise se fait depuis la position enregistrée.

Client

• views/staticParty/ (route /static/:id) contient :
  • l'en-tête, avec la progression du groupe et le bouton lancer / rejoindre la séance ;
  • « Tu as manqué », avec pour chaque élément cases à cocher, Regarder en solo et Marquer comme vu, plus deux actions groupées : rattraper en solo, ou lancer une watch party de rattrapage ;
  • les membres ;
  • la liste complète des items.
• Bouton « Créer une watch party permanente » sur views/series et sur views/playlist (vidéo uniquement).
• Onglet dédié « Parties permanentes » (sidebar et menu mobile), route /static (views/staticParties/) : une carte par watch party avec la progression, le prochain élément, un badge « N manqués » et une pastille « séance en cours ». L'onglet reste actif sur la page d'une party.
• Séparation avec les watch parties classiques : la liste « Watch parties en cours » de l'accueil exclut les séances de watch party permanente (staticPartyId non nul) ; elles ne s'affichent que dans leur onglet.

Limites connues

• « Vu » reste une heuristique : passer à la suite compte comme vu, comme pour le flag Played d'Emby. Il n'y a pas de seuil de pourcentage.
• La liste et le détail relisent la source Emby à chaque affichage (une requête par watch party pour la liste). C'est acceptable à l'échelle d'un serveur perso ; à mettre en cache si la liste grossit.
• Plusieurs watch parties statiques peuvent exister sur la même série (des groupes différents) : c'est voulu, sans déduplication.