一起听 · 使用指南

一、文档概述

• 功能简介： 一起听让你和朋友进入同一个房间，同步播放、同步进度、同步切歌，配合内置聊天，把"分别戴着耳机听同一首歌"的体验做成实时联机。
• 适用平台： Windows、macOS 桌面客户端
• 适用用户： 所有澜音用户（需要登录账号）

二、两种房间模式

模式	容量	控制权	适用场景
亲密模式 (intimate)	2 人	双方对等，谁都能切歌、暂停、拖进度	情侣 / 闺蜜 / 室友 1v1
多人房间 (group)	默认 50 人，可调	三级权限（房主 → 管理员 → 成员），仅 admin+ 能控制播放	直播、共听派对、读书会等

普通成员在多人房间里可以点歌（进待审批）+ 聊天，但不能直接切歌。

三、创建房间

1. 进入「全屏播放器」(点击底部播放栏的封面)
2. 点右上角的 一起听 按钮 → 选「新建房间」
3. 选模式（亲密 / 多人）+ 房间名（多人模式必填）
4. 创建成功 → 自动加入并展开浮层

四、邀请朋友加入

每个房间有一个 6 位口令(如 XTYASG)和一条分享文案。点房间顶栏的 分享 按钮即可一键复制以下文案到剪贴板：

「一起听」时迁酱：我的耳机分你一半,快和我一起听歌吧～
点开看看：https://ceru.share.shiqianjiang.cn/r/XTYASG
或复制本条打开 CeruMusic 加入：#XTYASG#

朋友拿到文案后有 三种加入方式：

方式 1: 点开链接 → 在澜音中打开（推荐）

朋友打开 https://ceru.share.shiqianjiang.cn/r/XTYASG：

• 网页展示房间名、模式、最大人数、6 位口令
• 点 「在 澜音 中打开」 按钮
• 浏览器把口令写入剪贴板 + 拉起 cerumusic://lt/XTYASG
• 澜音弹起 → 自动检测到剪贴板里的口令 → 弹「加入房间 XXX？」对话框

方式 2: 复制整段文案 → 打开澜音

朋友把上面这段文案 ctrl+C，然后打开（或切回到）澜音：

• 澜音在「发现」页 / 任何页面切焦点回来时，会自动扫剪贴板
• 识别 #XTYASG# 中的口令 → 弹同样的加入对话框

方式 3: 手动输口令

进入「一起听」入口 → 「通过口令加入」 → 粘贴或输入 6 位口令。

五、房间内操作

播放控制（有控制权时可用）

操作	行为
播放 / 暂停	房间内所有人同步
拖动进度条	所有人都对齐到目标位置
切下一首 / 上一首	沿共享队列切换
点击歌曲封面（在播放器里）	切到该歌曲
点击列表中的某首	跳到队列指定位置播放

同步算法： 服务端记录"在某时刻 T 处于位置 P"作为锚点，客户端按 now - T + P 推算应该在哪儿。漂移超过 0.5s 会硬 seek 对齐；切歌、seek 等显式动作走强对齐。

队列与点歌

• 多人模式普通成员搜歌后点「分享给房间」→ 进入待审批列表 (pending)
• 管理员在「待审批」面板批 / 拒，通过的歌进入正式队列
• 管理员自己搜歌可以直接「加入队列」跳过审批
• 队列项可以删（自己点的成员可删自己的，admin+ 可删任意）

角色管理（仅多人模式）

• 房主：唯一，可解散房间、提升 / 撤销管理员
• 管理员：可控制播放、审批、踢人，但不能改其它管理员
• 成员：点歌（要审批）+ 聊天

聊天

• 文本（Enter 发送，Shift+Enter 换行）
• 表情（单击直接发一条表情消息，右键插入到输入框）
• 系统消息（成员加入 / 点歌请求 / 审批结果 / 踢人 等）会以居中半透明形式插在消息流里

六、断线重连

短暂网络抖动（30 秒内）回来时：

• 不会触发 leave/join 跳动
• 房间内只看到一条 member:reconnect 静默事件
• 你自己重连后会收到一份完整的 room:state 快照，UI 自动恢复

30 秒墓碑期过了仍未回来才会走完整的离开流程，可能触发房主自动转移。

七、注意事项

• 必须登录 —— 一起听服务靠 Logto access token 鉴权，未登录无法创建 / 加入房间
• 房间 30 分钟无活动自动清理 —— 有人发消息、控制播放等都会续期；全员离开后 30 分钟才彻底回收
• 同一时刻只能在一个房间 —— 试图加入第二个房间时会提示「你已经在另一个房间中」
• 网页落地页只用于写剪贴板 —— 实际所有的"加入"决策都在澜音客户端做，网页本身不会替你加入
• 自己创建的房间不会重复弹窗 —— 客户端识别到剪贴板里的 code 是自己当 owner 的房间会静默放行

八、常见问题

Q1：网页点了"在 澜音 中打开"后没弹窗？

A：① 确认澜音已经登录；② 看下系统是否拦截了 cerumusic:// 协议跳转（首次会弹权限）；③ 退到「发现」页或切到其它窗口再回来，焦点变化时会再扫一次剪贴板；④ 如果还不行，从浏览器复制下方的口令，手动在澜音首页搜索框旁边的「一起听」入口粘贴。

Q2：切歌时另一边没跟上？

A：检查双方网络是否都连通；切歌走的是显式同步动作（forceAlign），正常情况下应在 1 秒内对齐。如果一直对不齐，看下浏览器 DevTools / 客户端日志里有没有 [lt] socket disconnected。

Q3：被踢之后还能再回来吗？

A：可以。被踢只是把你从当前房间移出，重新拿到口令再加入即可（不像封号）。

Q4：房间里不同地理位置的人时差很大，听到的会一致吗？

A：客户端做了 NTP 风格的时钟同步（每次进房会快速 ping 5 次取中位数估算时钟偏差），跨大洲一般也能控制在 200ms 以内的人耳难以察觉的偏差。

九、相关文档

• Scheme URL - cerumusic://lt/<code> 协议链接
• 听歌识曲与分享
• 一起听 · 后端接口（开发者）