Emby Watch Together 插件

Watch Together 是一个运行在 Emby Server 内的双人同步观看插件，当前项目版本为 1.4.3.0。它读取同一台服务器上的会话状态，并通过 Emby 远程控制协调起播、暂停/继续、手动拖动进度、切换视频和停止播放。

本文面向 Emby Server 管理员和插件使用者。维护者或开发者需要构建、测试、签名发布、接口和运行时细节时，请阅读开发者与维护者技术文档。

插件只负责房间内的协调，不会修改媒体库、转码设置或播放器客户端。正常播放期间不会为了消除网络延迟和小幅播放差异而反复跳转。

功能

• 管理员创建一个包含两名用户的房间，并指定主用户；每名用户同时只能属于一个房间。
• 两位参与者打开相同视频后，插件会先暂停双方，以主用户位置为基准对齐另一端，再恢复起播前的暂停/播放状态。
• 播放过程中会同步明确的暂停/继续和明显的手动拖动，不会为了消除小幅播放差异而持续跳转。
• 切换到不同视频时回到等待状态，不会跨视频追赶；两人同时播放时按安全规则处理，单人播放受到保护。
• Watching 已开始后，一方停止状态持续达到 2 秒才确认停止，默认暂停另一方并发送提示；临时同用户替换的会话（不同 SessionId，包括不可远控的快照）不能清除观察，只有原 Previous SessionId + ItemId 且在线、未停止并支持远程控制才算恢复。暂停和提示行为可以分别关闭。
• Emby 管理页提供房间创建、加入/退出、暂停、继续、重新同步、删除和状态查看。
• 遇到网络或 Emby 暂时不可用时，插件会有限重试并显示状态；单个房间异常不会终止其他房间的同步。
• 同一用户的多会话只有在存在唯一历史 SessionId + ItemId 关联时才会沿用；没有历史或关联失效时保持等待，不会猜测会话。
• 管理员手动暂停/继续遇到 Barrier 或任一参与者存在 Pending 时整次拒绝，不覆盖正在进行的同步；成功操作不会误报陈旧的运行时错误。
• 退出触发的自动暂停返回稳定的 Attempted、Succeeded、Failed 汇总，管理页分别显示成功、失败和未尝试；群发消息单目标异常会继续发送其余目标并区分 Sent、Failed、Skipped。

兼容性与边界

• 目标环境为 Emby Server 4.9 API。
• 一个房间恰好两名参与者，且两人必须登录同一台 Emby Server；不支持跨服务器或多人同步。
• 两个会话必须打开相同视频、媒体时长相差不超过 3 秒、播放速率接近正常速度，并同时支持暂停、继续和拖动进度等远程控制。客户端没有这些能力时房间会停留在 Waiting。
• 同步基于服务器提供的会话状态，不是播放器内部时钟；不保证每一帧完全相同，也不主动消除长期的小幅漂移。
• 不依赖外部运行时、脚本或额外服务；消息展示、远程控制和确认延迟仍取决于实际 Emby 客户端。

安装已构建插件

1. 在 Emby Server 管理后台确认服务器已停止写入旧版本（升级前建议备份旧 DLL）。
2. 从发布产物解压 EmbyWatchTogether.zip，得到根目录下的 Emby.Plugins.WatchTogether.dll。
3. 将 DLL 直接复制到 Emby Server 数据目录的 plugins 目录，不要再套一层 EmbyWatchTogether 子目录。若不确定数据目录位置，可在 Emby 管理后台的服务器路径页面查看。
4. 启动或重启 Emby Server。进入 Dashboard → Plugins → Watch Together，确认设置页能够打开。

插件是单 DLL 交付，不需要复制源码、NuGet 包或其他旁车进程。升级时停止 Emby、替换 DLL 后再启动；回滚时恢复备份的旧 DLL。插件默认使用 stable，管理员可在插件配置页选择 beta；stable 只读取 releases/latest，beta 按 GitHub Releases API 获取预发布版本。两种通道都由“Watch Together 更新检查”任务按所选通道自动安装，Emby 的任务开关和计划仍是控制入口。beta 仍是预发布版，自动安装不等于真实客户端验收。

插件更新

插件更新由 Emby 计划任务处理，插件配置页提供更新通道选择，但不提供独立的检查或安装按钮。服务器启动后，Dashboard → 计划任务 中会出现名为“Watch Together 更新检查”的任务，默认每 24 小时运行一次；管理员可以在那里调整检测时间、禁用任务或手动执行。任务会按插件配置中的 stable/beta 通道检查并自动安装。

stable 使用固定的官方 releases/latest 资产；beta 使用 GitHub Releases API 选择 prerelease 后构造对应 tag 的官方资产。两种通道都会在安装前校验发布签名、文件大小、哈希、程序集名称和版本；校验失败时不会安装。安装由 Emby 的插件安装器负责，插件不会自行覆盖 DLL，也不会调用重启或关机。安装成功后插件会通知 Emby“等待重启”，仪表盘会出现重启提示；如果检查后已是最新版本，当前管理员会话也会收到同样的短横条提示；重启前同一版本不会重复安装。

首次信任引导版本 1.2.0.9 必须由运营人工部署；完成后版本方可使用签名自动更新。如果服务器尚未完成首次信任引导，请先按人工安装方式部署该版本。正式版更新的发布资产、签名格式和信任根约束见技术文档中的更新实现说明。

使用方法

创建房间

1. 使用管理员账号打开 Watch Together 页面。

2. 填写房间名称，选择两名不同的参与者，并从两人中指定主用户。

3. 创建后让两名用户登录同一 Emby Server、打开同一个视频；必要时在房间卡片上点击“加入房间”。

4. 房间状态依次可能显示为：

   • Waiting（等待参与者或等待双方打开同一 Item）；
   • Barrier（正在暂停、Seek 和恢复）；
   • Watching（已完成起播同步）；
   • Unavailable（房间归属的服务器 ID 与当前实例不一致）。

进入 Watching 后，暂停/继续和明显的手动拖动会传播到另一端。管理员可以对房间执行暂停、继续或重新同步；重新同步会清理运行时状态并重新执行 Barrier。

停止行为设置

设置页的“播放停止行为”区域提供两个独立开关，默认均开启：

配置项	默认值	作用
PauseOtherOnPlaybackStop	true	一方被会话快照持续确认停止后，暂停仍在播放的另一方
NotifyOtherOnPlaybackStop	true	同一停止状态确认后向另一方发送文字提示

配置由 Emby 保存，只有管理员可以修改。两个停止行为开关保存后会在下一轮同步中生效。轮询参数、配置热更新行为以及当前保留但不参与实时策略的字段见技术文档。

排错清单

• 状态长时间为 Waiting：确认两人已加入、在线会话打开相同 Item，且客户端报告了 Pause、Unpause、Seek 能力。
• 状态出现不同视频提示：两端 ItemId 不一致；插件不会跨视频追赶，重新打开相同视频即可触发新的 Barrier。
• Barrier 失败：查看房间卡片的错误信息，确认 Emby 能返回更新后的 SessionInfo；命令会有限重试，冷却结束后自动重试。
• 频繁跳转：本插件只对明显单次跳变发送 Seek。若正常播放仍反复跳转，应先检查其他客户端、插件或遥控器是否在发送 Seek。
• 停止后另一端未暂停或未收到消息：检查设置页两个开关，以及目标客户端是否支持 Pause 或 DisplayMessage。

维护者和开发者需要的版本规则、构建/测试/打包、签名发布、项目结构、运行时持久化和 REST API 说明见开发者与维护者技术文档。