29 KiB
音乐模块 · 手机端连接与控制规划(Music Remote Plan)
状态:规划中(未开始实施) 定位:音乐模块的"手机互联"子能力,不是独立模块——挂靠
music模块,Rust 侧新增music/remote/子系统 日期:2026-09-25 关联文档:AI_DEV_GUIDE.md(模块注册 / IPC 范式——注意其未涵盖 specta,绑定范例见lib.rs的export_bindings())、TERMINAL_MODULE_PLAN.md(规划文档范式) 对端文档:F:\AtieProject\LFMusic\PLAN.md(手机端 LFMusic 的功能与实现规划,协议以本文 §4(协议)/ §5(实现)为准)
0. 结论先行
四个关键判断,先摆在这里,后文展开论证:
-
"获取电脑端正在播放的内容(不管是不是 Thing 播的)"必须走 GSMTC(
GlobalSystemMediaTransportControlsSessionManager),而不是扩展现有的smtc.rs。smtc.rs以"Thing → 系统"的元数据/进度上报为主(ISystemMediaTransportControlsInterop::GetForWindow),并经TypedEventHandler接收系统按钮回传(双向)——但它只管自己这条会话;要读到系统里所有应用的媒体会话(网易云、QQ 音乐、浏览器、Thing 自己……),唯一官方通道是 GSMTC 的全局会话管理器。两者方向相反、互不冲突,smtc.rs原样保留。 -
控制链路统一走 GSMTC 的
Try*Async,Thing 自己不特殊处理。手机发的播放/暂停/切歌 → Thing 的 GSMTC 调用 → 系统把按钮事件派发给目标会话。Thing 自己因为已在smtc.rs注册了 SMTC 会话并有按钮事件回传链路(music-smtc-button→ 前端执行),这条环路是现成的,对 Thing 自身会话近乎零新增执行代码(需补的是 cmd-ack 语义与派发时序定义,见 §4.2 / §5.2)。不要为 Thing 自建"直通 AudioEngine"的旁路——多一条路径就多一类不一致(P1 若延迟体感明显再优化)。 -
局域网服务用 axum(已有依赖)新增 HTTP + WebSocket 双通道,发现用"电脑广播 beacon + 手动扫码"双保险。axum 已在
download_engine/server.rs和feiniu/proxy.rs两处落地,范式现成。发现协议不选 mDNS 做 P0 主路径:Android/iOS 的 mDNS 栈碎片化、路由器 AP 隔离下失效、iOS 后台受限;而电脑端周期性 UDP 广播 + 手机被动监听实现最简、权限最友好,配合二维码手动配对兜底已覆盖 99% 场景。mDNS 降级为 P1 增强。 -
安全按"配对制"设计,不做裸奔。首次连接用一次性配对码(Thing 弹窗展示,手机扫码/手输),换取长期设备 token;token 两侧持久化(Thing 侧入 keyring,手机侧入系统安全存储),后续连接 WS 握手鉴权,设置页可随时撤销设备。局域网明文 HTTP 在 P0 可接受(风险面:同网段已配对 token 泄露才会被利用),TLS 自签放 P2。
工作量估算:P0(系统会话捕获 + LAN 服务 + 发现配对 + 基础遥控)约 69 个工作日;P1(mDNS、多会话切换、系统音量、投播)约 58 个工作日;P2(TLS、队列投播完善)按需。
1. 需求解构
用户需求拆成可执行的规格:
| 用户原话 | 解构为 | 落点 |
|---|---|---|
| 「手机端 app 打开后自动连接局域网电脑上的 Thing」 | 电脑端局域网服务(HTTP+WS)+ 自动发现(UDP beacon)+ 配对与鉴权 | §3.2 / §3.3 / §3.4 |
| 「可以获取到电脑端正在播放的内容(不管是 Thing 自己播放的,或是其他应用播放的)」 | GSMTC 全局会话监视:当前活跃会话的元数据、进度、播放状态、封面 | §3.1 / §5.2 |
| 「显示例如歌曲名,歌手,专辑,封面,进度」 | NowPlaying 状态模型 + WS 增量推送 + 封面 HTTP 端点 |
§4 / §5.2 |
| 「控制等等」 | 播放/暂停/上一首/下一首/seek/停止,走 GSMTC Try*Async;音量 P1 |
§3.1 / §5.3 |
| (自然延伸,非本次明说) | 投播:手机选歌 → 电脑播放(Thing 曲库播放队列控制) | §7 P2 |
| 「打开后自动连接」的边界 | 首次需用户在电脑设置页点「连接手机」弹出配对码/二维码,5 分钟内完成一次配对;此后已配对设备才自动重连 | §3.4 / 对端文档 §5.1 |
2. 现状勘察(2026-09-25 从仓库实际读取)
2.1 已具备的基建(直接复用)
| 能力 | 现有实现 | 本功能可复用的部分 |
|---|---|---|
| 播放引擎 | music/audio/engine.rs:AudioEngine(symphonia + cpal/WASAPI 独立线程),AudioState 快照 + music-audio-ended / music-audio-error 事件 |
Thing 自身播放状态的事实来源;封面/元数据兜底可直读播放队列 |
| SMTC 上报 | music/smtc.rs:SmtcController(GetForWindow 全字段上报 + 系统按钮事件 music-smtc-button 回传前端) |
零改动保留;它让 Thing 拥有一条标准 SMTC 会话,GSMTC 控制才能作用到 Thing 自己 |
| HTTP 服务范式 | download_engine/server.rs、feiniu/proxy.rs 均为 axum + tokio::net |
新 LAN 服务照抄此范式(axum::serve + tokio) |
| WebSocket | tokio-tungstenite 0.24 已在依赖树 |
备选;WS 通道直接用 axum 的 ws feature 更统一 |
| 凭据存储 | secrets.rs(keyring + Windows 凭据管理器)、music/secrets.rs |
设备 token / 配对密钥持久化 |
| 类型绑定 | tauri-specta 自动生成 src/lib/bindings.ts |
remote 命令与消息类型走 specta,前端零手写类型 |
| 设置持久化 | MusicManager::load_settings / save_settings(settings.json + 500ms 缓存) |
remote 开关/端口等设置项追加到 MusicSettings |
| 日志 | logger.rs 统一日志 |
remote 全链路日志 |
2.2 关键缺口(需新增)
| 缺口 | 现状 | 方案 |
|---|---|---|
| 系统媒体会话读取 | 无。windows crate 未开 Media_Control feature |
开启 feature,新增 music/remote/glsmtc.rs(见 §3.1) |
| 局域网服务 | axum 仅用于本机/代理场景,无对外 LAN 端点 | 新增 music/remote/server.rs,监听 0.0.0.0 |
| 设备发现 | 无 | 新增 music/remote/discovery.rs(UDP beacon) |
| 配对与设备管理 | 无 | 新增 music/remote/pairing.rs |
| 二维码渲染 | 无 | 前端引入 qrcode/qr-code-styling(纯前端生成即可) |
3. 技术选型
3.1 系统媒体捕获:GSMTC
Windows 10 1809+ 的 Windows.Media.Control 命名空间是唯一能枚举/监视/控制系统全部 SMTC 会话的公开 API。凡是有标准系统集成(SMTC)的播放器——网易云、QQ 音乐、foobar2000、浏览器、以及 Thing 自己——都会出现在会话列表里。
Rust 侧路径:windows crate(当前 0.52)增加 "Media_Control" feature,类型位于 windows::Media::Control:
use windows::Media::Control::{
GlobalSystemMediaTransportControlsSessionManager,
GlobalSystemMediaTransportControlsSession,
};
核心 API 清单:
| API | 用途 |
|---|---|
SessionManager::RequestAsync() |
取全局管理器单例(惰性初始化,失败则整个能力降级关闭) |
manager.GetSessions() |
枚举所有会话——同步返回 IVectorView(0.52 投影无 Async 版本,计划原文 GetSessionsAsync 有误,以实测为准) |
manager.GetCurrentSession() |
当前"活跃"会话(系统自动判定:最近操作的会话);同步,无会话时 ABI 返回 null → windows-rs 投影为 Err(E_POINTER),按"无会话"分支处理。实测修正:WinRT 没有 SetCurrentSessionAsync——P1 多会话切换采用 Thing 侧"选中覆盖"(§7),不修改系统判定 |
session.SourceAppUserModelId |
来源应用标识(用于显示"正在播放的应用",也作为会话 key) |
session.TryGetMediaPropertiesAsync() |
元数据:Title / Artist / AlbumTitle / AlbumArtist / Thumbnail |
session.GetTimelineProperties() |
Position / EndTime / LastUpdatedTime(进度推算基准,见 §6.4) |
session.GetPlaybackInfo() |
PlaybackStatus / Controls(IsPlayEnabled 等能力位)/ PlaybackRate |
TryPlayAsync / TryPauseAsync / TryStopAsync / TrySkipNextAsync / TrySkipPreviousAsync |
控制(即手机端全部按钮的实现) |
TryChangePlaybackPositionAsync(ticks) |
seek(仅当会话 IsSeekEnabled) |
事件:CurrentSessionChanged / MediaPropertiesChanged / TimelinePropertiesChanged / PlaybackInfoChanged / SessionsChanged |
状态变更推送源 |
线程与套间(沿用 smtc.rs 已验证的范式,但有一处关键差异):
- 初始化(
RequestAsync)与事件订阅在主线程执行(run_on_main_thread抛过去),与smtc.rs一致。 Try*Async的.get()阻塞等待必须放专用工作线程,不能在主线程.get()——STA 上阻塞等待 WinRT async 有死锁风险,而smtc.rs那种"fire-and-forget 更新属性"不涉及等待所以没踩到。设计上:主线程只做"发起",等待统一丢给tokio::task::spawn_blocking或专用线程。- 所有 GSMTC 对象是 agile 的,跨线程传引用安全(与 smtc.rs 注释同源结论)。
失败策略:与 smtc.rs 同哲学——GSMTC 任何一步失败只记日志,不影响播放;GSMTC 初始化失败时整个"远程查看/控制其他应用"能力降级为"仅 Thing 自身"(可从 AudioEngine.state() 兜底聚合,见 §5.2)。
3.2 局域网服务:axum HTTP + WebSocket
单端口(默认候选 26124,被占则 +1 重试至 26139,实际端口写进 beacon 与二维码):
| 端点 | 方法 | 用途 |
|---|---|---|
/ws |
GET(Upgrade) | 主通道:鉴权、状态推送(server→client)、控制指令(client→server) |
/api/state |
GET | REST 兜底快照(WS 不可用/调试用),Bearer token 鉴权 |
/cover/:hash |
GET | 封面字节流(内存缓存,hash 由状态推送携带,?v= 控制刷新),Bearer token(query 参数 t=,<img> 标签无法带 header);访问日志不打印 query,token 不落日志 |
/pair |
POST | 配对:{ pairingCode, deviceName } → { token, deviceId } |
WS 承载双向消息(协议见 §4.2);HTTP 承载资源(封面)与低频操作。全部监听 0.0.0.0。
防火墙注意:首次监听 LAN 端口 Windows 会弹防火墙授权(专用网络勾选即可)。在设置页 remote 开关旁给出说明文案;不做 netsh 自动加规则(改系统防火墙属于越权行为,且需要管理员)。
3.3 设备发现:UDP beacon(P0 主)+ 扫码兜底(P0)+ mDNS(P1)
| 方案 | 机制 | 判断 |
|---|---|---|
| UDP beacon(推荐 P0) | 电脑每 3s 向 255.255.255.255:26123 与各网卡定向广播地址发 JSON 包:{ "service": "thing-music", "deviceId", "name", "port", "protoVer" };手机监听 26123 被动收集 |
实现最简(一个 tokio interval + UdpSocket);手机端只需 bind 收包,Android 免多播权限问题,iOS 不触发 multicast entitlement(仍会触发本地网络权限弹窗,属正常) |
| 扫码/手输(P0 兜底) | Thing 设置页展示二维码:thingmusic://connect?ip=…&port=…&code=…;手机扫码或手输 IP+配对码 |
AP 隔离下 beacon 不可达时的最后手段;同时它就是配对入口(见 §3.4) |
| mDNS(P1 增强) | mdns-sd crate 注册 _thingmusic._tcp.local.,手机 browse |
生态标准、后台发现友好;但依赖各端 mDNS 栈质量,放 P1 不阻塞 |
beacon 里不含任何敏感信息(无 token、无配对码),只描述"这里有一个 Thing 音乐服务"。手机端根据 deviceId 去重。
3.4 安全与配对
流程(对齐业界遥控 App 的标准做法):
- 手机端发起配对:beacon 得到 ip:port 后 POST
/pair,携带 6 位一次性配对码 + 设备名。 - 配对码由 Thing 侧生成:用户在设置页点击「连接手机」→ 弹窗展示 6 位码 + 二维码(码内含 ip/port/code,扫码即完成 1、2 两步),有效期 5 分钟,一次性。
- 校验通过 → 生成 32 字节随机 hex 设备 token,返回手机;Thing 侧持久化
{deviceId, deviceName, token}到 keyring(复用secrets.rs范式),列表落 settings。 - 后续连接:WS 握手首条消息
hello { token }(或 HTTPAuthorization: Bearer),校验失败 3 次即拉黑该 IP 60s;/pair的配对码校验执行同一限速(防 6 位码爆破,配对响应也只在成功时下发 token)。 - 设置页设备列表:展示在线/离线、最后连接时间,可撤销(吊销 token)。
P2 增强:自签 TLS(rcgen 生成 + rustls,二维码里带证书指纹)。P0 明文 HTTP 的风险面评估:同局域网内明文嗅探只能看到 token 之后的媒体元数据;token 本身仅在配对响应中明文传输一次,可接受。
4. 状态模型与协议设计
4.1 NowPlaying(核心状态, specta 类型双端共享)
interface NowPlaying {
sessionId: string // 会话 key(SourceAppUserModelId;Thing 自身 = "thing.self")
sourceApp: string // 来源应用显示名(AUMID 末段或注册表友好名)
isThing: boolean // 是否 Thing 自身播放(决定封面/元数据兜底来源)
title: string
artist: string
album: string
coverHash: string | null // 封面缓存键;封面从 /cover/:hash 拉
status: 'playing' | 'paused' | 'stopped'
durationSec: number
positionSec: number // 推送时刻的位置
positionUpdatedAtMs: number // 电脑时钟毫秒(源自 TimelineProperties.LastUpdatedTime,见 §6.4);仅供校准,手机端 elapsed 一律以本地收包时刻起算(见 §6.10)
playbackRate: number
canControl: { play: boolean; pause: boolean; next: boolean; prev: boolean; seek: boolean }
deviceId: string // 电脑标识(多电脑预留)
}
4.2 WS 消息(JSON,type 字段区分)
| 方向 | type | 载荷 | 时机 |
|---|---|---|---|
| c→s | hello |
{ token, deviceName, protoVer } |
连接后首条;失败即断开 |
| s→c | welcome |
{ deviceId, deviceName, protoVer } |
鉴权通过 |
| s→c | state |
NowPlaying(全量) |
连接后、以及任何变更(见 §6.3 节流;由 cmd 触发的变更立即推一帧,绕过节流) |
| c→s | cmd |
{ id, action, args? },action ∈ play / pause / toggle / next / prev / stop / seek(posSec) |
用户操作 |
| s→c | cmd-ack |
{ id, ok, error? } |
回执语义 = "指令已被接受/派发"(GSMTC 路径 = Try*Async 完成;前端兜底路径 = 事件已投递),不代表播放状态已切换;UI 轻提示,真实状态以随后的 state 为准 |
| c→s | ping / s→c pong |
{ ts } |
30s 心跳,双向判活 |
版本策略:protoVer 从 1 起,不匹配时 welcome 带最新版本号,手机端提示升级。
5. 架构与模块设计
5.1 Rust 侧:src-tauri/src/music/remote/
src-tauri/src/music/remote/
├── mod.rs # RemoteManager:manage() 进 State;启动/停止服务与 beacon;开关状态
├── server.rs # axum app:路由 /ws /api/state /cover /pair;WS 会话表(fanout 广播)
├── glsmtc.rs # GsmtcMonitor:GSMTC 初始化、事件订阅 → 聚合 NowPlaying → 广播
├── discovery.rs # UdpBeacon:3s 周期广播(255.255.255.255 + 各网卡定向广播)
├── pairing.rs # 配对码生成/校验、设备 token 签发、设备表(keyring + settings)
└── proto.rs # NowPlaying / WS 消息类型(serde + specta,前端 bindings 自动生成)
数据流:
GSMTC 事件(主线程订阅)──→ GsmtcMonitor 聚合/节流 ──→ Server 广播到全部 WS 客户端
AudioEngine.state()(兜底聚合,isThing 时封面/元数据来源之一)┘
手机 cmd ──→ server.rs ──→ glsmtc.rs(spawn_blocking 调 Try*Async)──→ 系统派发给目标会话
└─ Thing 自身会话:SMTC 按钮 → smtc.rs 既有链路 → 前端 feiniuStore 执行(既有链路,约束见 §5.2)
MusicManager 增加 remote: RemoteManager 字段(或平级 manage,倾向后者,避免 MusicManager 继续膨胀);lib.rs 注册 remote_* 系列命令:
| 命令 | 用途 |
|---|---|
remote_get_config / remote_set_enabled |
开关(MusicSettings 追加 remote_enabled、remote_port) |
remote_status |
服务状态、端口、在线设备 |
remote_start_pairing |
生成配对码 + 二维码 payload(前端渲染二维码) |
remote_cancel_pairing |
取消 |
remote_list_devices / remote_revoke_device |
设备管理 |
5.2 双来源聚合规则(GSMTC 为主,AudioEngine 兜底)
- GSMTC 可用:一切以 GSMTC 当前会话为准。Thing 自身播放时它就是一条普通会话(
SourceAppUserModelId识别后标isThing: true)。 - GSMTC 无会话但
AudioEngine在播放(GSMTC 初始化失败或会话丢失的兜底):从AudioEngine.state()+ 播放队列聚合出NowPlaying(isThing: true);控制指令由 server 复用music-smtc-button事件(同名、同 payload)emit 给前端执行。既有架构约束:队列控制逻辑(toggle/next/prev/播放模式)在前端feiniuStore,AudioEngine 本身只有 play/set_playing/seek/stop——兜底路径依赖 WebView 存活,WebView 未就绪时直接回cmd-ack { ok: false, error: "frontend-unavailable" }。 - 两者都无:
status: 'stopped',手机端显示"电脑未在播放"。
5.3 前端侧
src/modules/music/components/settings/RemoteSettings.vue:总开关、端口、设备列表(在线状态/撤销)、「连接手机」按钮 → 配对码 + 二维码(qrcode库,5s 轮询 status 刷新倒计时/在线态)。- 状态存放:P0 用 RemoteSettings 组件本地状态(5s 轮询
remote_status),不扩 musicStore——当前无其他消费方;遥控 UI 出现共享需求时再入 store。 constants.rs:REMOTE_WS_*等消息类型常量(如需要);本功能的"事件"主要是 WS 而非 Tauri event,前端基本只走 invoke + bindings。
5.4 生命周期
- 随应用启动初始化(不随模块启用——music 默认启用且常驻),
remote_enabled = false时仅不启服务/beacon,GSMTC 监视可保持惰性。 - 应用退出:axum graceful shutdown、beacon 停发(
cleanup_on_exit挂钩,参照MusicManager::cleanup_on_exit范式)。 - 系统休眠/网络切换:WS 断开由心跳判活;beacon 无状态持续广播即可,无需额外处理。
6. 关键实现细节与已知的坑
- GSMTC 在非打包桌面应用可用(unpackaged desktop app 明确支持,1809+)。不要被"WinRT 需要 package identity"的泛泛说法劝退——GSMTC 不在受限之列,开源社区大量此类工具可佐证。2026-09-25 已实证:
examples/gsmtc_probe.rs(unpackaged 控制台进程)跑通,读到当前会话元数据/状态/时间轴,核心假设成立。 - 封面(Thumbnail)是
RandomAccessStreamReference:OpenReadAsync()→ 按ContentType(image/png|jpeg)读全量字节 → 以hash(sourceApp + title + album + 尺寸)为键存内存 LRU(上限 ~20 张)。推送里只带coverHash,封面走 HTTP 拉取,避免 WS 帧被几百 KB 图片打爆。 - 事件风暴节流:
TimelinePropertiesChanged在部分播放器上高频触发(每次内部时钟更新都发)。聚合层统一节流:任何状态变更合并后最快 1Hz 推送state;进度靠手机端positionSec + elapsed本地推算(status=playing时每秒 +1,收到新state校准),不依赖高频推送。例外:由cmd触发的状态变更立即推一帧(绕过 1Hz 节流),避免按钮"没反应"的体感——节流仅约束进度等自然高频变更。 - 进度推算基准用
TimelineProperties.LastUpdatedTime,不要用"收到事件的本地时刻"——事件分发有延迟,LastUpdatedTime是播放器侧的权威时间戳。(本条约束 Thing 侧把 GSMTC 事件组装成positionSec/positionUpdatedAtMs的动作;手机侧 elapsed 的起算基准见 §6.10,两层不要混用。) - 会话 key 的稳定性:GSMTC 无显式 sessionId,用
SourceAppUserModelId作 key;同一应用双会话(极少见)时后者覆盖前者,P1 的多会话切换再处理。 Try*Async的返回值不可全信:部分播放器对不可用操作静默成功,回执只做 UI 轻提示,真实状态以下一帧state为准(canControl能力位已尽力过滤)。- AUMID → 友好名:
SourceAppUserModelId是PackageFamilyName!App或注册表 AUMID,显示名需查Get-StartApps等价逻辑(注册表HKCU\Software\Classes\AppUserModelId);先显示末段兜底,友好名缓存 LRU。 - 防火墙弹窗只出现一次(每个 exe 路径 × 网络类型),开发期
tauri dev与正式版 exe 路径不同会各弹一次,属预期。 - Windows 通知区域"媒体"浮层与 GSMTC 互不干扰:
smtc.rs的上报会话照常工作;手机控制 Thing 自身时,系统面板同步可见,是 feature 不是 bug。 - 进度推算的时钟基准分两层,不要混用:Thing 侧组装
positionSec/positionUpdatedAtMs用TimelineProperties.LastUpdatedTime(§6.4);手机侧elapsed一律以本地收到该条state的时刻起算,禁止拿positionUpdatedAtMs与手机本机时间直接做差——电脑时钟偏差(手动对时/休眠漂移可差数秒以上)会整体拖偏进度条。手机端检测到两端时钟偏差 >5s 时冻结推算、只显示基准值,等待下一条state校准。两端时钟正常时(NTP 同步)此方案残差 ≤ 推送延迟(LAN 上 <1s,且播放中 ~1Hz 校准)。
7. 分阶段计划
P0:可用版本(目标:手机能看到并控制电脑当前播放)
windowscrate 开Media_Controlfeature;10 行探测 demo 验证 GSMTC 在本机可用 —— 2026-09-25 实测通过(examples/gsmtc_probe.rs,unpackaged 控制台进程:读到 1 会话 + 元数据/状态/时间轴全通;注意GetSessions/GetCurrentSession是同步 API,见 §3.1)remote/proto.rs:类型定义(serde,未进 specta——WS 对端是手机,Thing 前端不消费)+ 单测(序列化往返/时间换算/会话 key)——2026-09-26 完成,8 单测全绿remote/glsmtc.rs:初始化、事件订阅、NowPlaying聚合、封面 LRU、节流(1Hz + cmd Force 例外)——完成;订阅 P0 只挂 Manager 级两事件 + 500ms 节拍轮询(会话级事件需随会话订阅/退订,列入 P1)remote/server.rs:axum 路由 + WS 会话表 + 广播 + 心跳判活 + Bearer/hello 鉴权(+ /pair 限速、封面 token 走 query)——完成remote/discovery.rs:UDP beacon(GetAdaptersAddresses 各网卡定向广播)——完成remote/pairing.rs:配对码 + token 签发 + 设备表(keyringmusic-remote-token-*)——完成(单测含限速)- 控制指令:play/pause/toggle/next/prev/stop/seek →
Try*Async(spawn_blocking);Thing 自身 seek 直通 AudioEngine(SMTC 回环无 seek 通道)——完成 - 命令注册(collect_commands + generate_handler 双处)+
RemoteSettings.vue(开关/配对二维码/设备列表;qrcode 库前端生成)——完成;改为组件本地状态,不扩 musicStore(当前无其他消费方,需要时再入 store) AudioEngine兜底聚合(+SmtcMetaCache回填标题/歌手/专辑)——完成- 运行时冒烟(2026-09-26):自启绑定
0.0.0.0:26124✓、beacon 实收(addrs=["192.168.110.40"]、deviceId 落盘)✓、/api/state401 ✓、/pair错码 403 ✓、日志「GSMTC 已初始化(专用线程 MTA)」✓、运行时 bindings 导出含 remote 命令 ✓ - 联调:真机 E2E 完成(2026-09-26)——LFMusic 真机客户端全流程实测:配对码 142919 →
/pair成功(192.168.110.27)→ WS hello 鉴权 → state 推送(封面/元数据/thing.self/能力位)→ 播放暂停上下首控制生效 → App 重启后自动重连。过程修复:手机端 deviceId 语义(存电脑 id 而非 Thing 分配的行 id)与对端显示名两处关联 bug - P0 验收口径(联调时执行):遥控界面显示 GSMTC
GetCurrentSession判定的活跃会话("最近操作"语义,多会话切换只留 UI 入口);进度推算按 §6.10 时钟基准联调;cmd后 1s 内看到状态变化
P1:体验完善 —— 2026-09-26 除两项暂缓外全部完成
- mDNS 发现(mdns-sd 注册
_thingmusic._tcp)——暂缓:beacon 在目标网络 100% 可用且扫码兜底已覆盖;双端 mDNS(含 Android MulticastLock/Kotlin 桥)成本高、当前无失效场景驱动,等 beacon 实际失效案例再做 - 多会话列表与手动切换——完成:
sessionsWS 消息(watch 变化推送 + 连接首帧)+select动作(WinRT 无 SetCurrentSession,实测修正:Thing 侧选中覆盖,空 id = 跟随系统 current;选中会话消失自动回落);手机端 chips UI(高亮isCurrent)+「跟随系统」 - 会话级事件精细化订阅——完成:
SessionSubs随目标会话换绑MediaPropertiesChanged/TimelinePropertiesChanged/PlaybackInfoChanged(切换时先退订后订阅,线程退出统一清理);Manager 级两事件 + 500ms 节拍轮询保留为保底 - 系统音量控制 + 手机端音量条——完成:
volume.rs(MMDevice →IAudioEndpointVolume,每次现取 COM 对象避免 Send/Sync 争议);监视线程 500ms 轮询进NowPlaying.volume/muted(指纹纳入、变化即推);volume动作 0~1、>0 自动解除静音;手机端 🔊 音量条(松手发送) - Thing 直通控制路径评估——评估结论:落地直通:
isThing按钮类指令直接 emitmusic-smtc-button(跳过 GSMTC→系统→SMTC 回环,少一跳系统派发延迟);seek 本就直通 AudioEngine;非 Thing 会话仍走 GSMTCTry*Async。系统面板同步不受影响(面板状态由前端持续上报 smtc.rs)。真机复测:非 Thing 路径(QQMusic 播放恢复)通过;isThing 直通与 P0 事件链同码,待 Thing 下次自身播放时自然覆盖 - AUMID 友好名缓存、封面本地持久化缓存——完成:
friendly_name(HKCU\Software\Classes\AppUserModelId\<aumid>\DisplayName查询 + 128 条缓存,查不到退回 AUMID 简化段;路径形 AUMID 跳过注册表);CoverStore写透{app_data}/remote_covers(内存+磁盘双层 LRU 各 20 张,冷启动可回源)。真机复测:友好名生效(QQMusic / Microsoft.ZuneMusic);持久化目录已创建,落盘写入待下次取到封面时自然验证(当前可见会话均无缩略图) - 手机端通知栏/锁屏媒体控件联动(LFMusic 侧 native-audio / MediaSession,见对端文档)——暂缓:被 LFMusic M1(集成
tauri-plugin-native-audio)阻塞,M1 完成后按对端文档回填
P2:增强(按需)
- 自签 TLS(rcgen + rustls,二维码带证书指纹)
- 投播:手机浏览 Thing 曲库 → 远程下发放进 Thing 播放队列(
/queue端点 + AudioEngine 队列 API 暴露) - 歌词推送(Thing 已有 lyric 能力,同步到手机端滚动显示)
- 多电脑:beacon 天然支持,配对表按 deviceId 区分,UI 侧完善
8. 风险与开放问题
| 风险/问题 | 影响 | 对策 |
|---|---|---|
| GSMTC 某播放器不上报专辑/封面(上报方行为,非 bug) | 手机端显示缺字段 | UI 兜底占位;Thing 自身播放时从曲库元数据补全(lofty 已有) |
| 路由器 AP 隔离导致广播不可达 | 手机发现不了电脑 | 扫码/手输 IP 兜底(P0 已含);mDNS 同样受影响,不是银弹 |
| 防火墙/杀软拦截 LAN 监听 | 手机连不上 | 设置页说明 + 连接失败诊断提示(检测本机端口监听、提示放行) |
| 手机休眠断 WS | 状态不实时 | 心跳 + 重连退避(手机端职责,见对端文档);恢复前台即拉 /api/state 快照 |
TryChangePlaybackPositionAsync 部分应用不支持 |
seek 无效 | canControl.seek 能力位隐藏进度条拖动 |
| 多网段/VPN 虚拟网卡产生杂音 beacon | 发现列表脏数据 | beacon 携带本机各网卡地址,手机端按连通性优选;显示名可区分 |
开放问题(实施前确认):
- 是否需要"电脑端显示已连接手机"的托盘/OSD 提示?(倾向 P1,托盘菜单加一行在线设备数即可)
- 投播的队列控制 API 形态(P2 前与 LFMusic 端一起定)。
- 遥控界面是否需要歌词显示?用户需求"显示音乐信息"是否含歌词——Thing 已有 lyric 能力,但"歌词推送"列在 P2,需两端确认是否提前。
- 音量控制是否提前到 P0?用户"控制电脑端"可能隐含音量——当前计划在 P1(
IAudioEndpointVolume)。