Files
Thing/MUSIC_REMOTE_PLAN.md
T
2026-09-28 00:21:12 +08:00

29 KiB
Raw Permalink Blame History

音乐模块 · 手机端连接与控制规划(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. 结论先行

四个关键判断,先摆在这里,后文展开论证:

  1. "获取电脑端正在播放的内容(不管是不是 Thing 播的)"必须走 GSMTC(GlobalSystemMediaTransportControlsSessionManager),而不是扩展现有的 smtc.rs。smtc.rs 以"Thing → 系统"的元数据/进度上报为主(ISystemMediaTransportControlsInterop::GetForWindow),并经 TypedEventHandler 接收系统按钮回传(双向)——但它只管自己这条会话;要读到系统里所有应用的媒体会话(网易云、QQ 音乐、浏览器、Thing 自己……),唯一官方通道是 GSMTC 的全局会话管理器。两者方向相反、互不冲突,smtc.rs 原样保留。

  2. 控制链路统一走 GSMTC 的 Try*Async,Thing 自己不特殊处理。手机发的播放/暂停/切歌 → Thing 的 GSMTC 调用 → 系统把按钮事件派发给目标会话。Thing 自己因为已在 smtc.rs 注册了 SMTC 会话并有按钮事件回传链路(music-smtc-button → 前端执行),这条环路是现成的,对 Thing 自身会话近乎零新增执行代码(需补的是 cmd-ack 语义与派发时序定义,见 §4.2 / §5.2)。不要为 Thing 自建"直通 AudioEngine"的旁路——多一条路径就多一类不一致(P1 若延迟体感明显再优化)。

  3. 局域网服务用 axum(已有依赖)新增 HTTP + WebSocket 双通道,发现用"电脑广播 beacon + 手动扫码"双保险。axum 已在 download_engine/server.rs 和 feiniu/proxy.rs 两处落地,范式现成。发现协议不选 mDNS 做 P0 主路径:Android/iOS 的 mDNS 栈碎片化、路由器 AP 隔离下失效、iOS 后台受限;而电脑端周期性 UDP 广播 + 手机被动监听实现最简、权限最友好,配合二维码手动配对兜底已覆盖 99% 场景。mDNS 降级为 P1 增强。

  4. 安全按"配对制"设计,不做裸奔。首次连接用一次性配对码(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 的标准做法):

  1. 手机端发起配对:beacon 得到 ip:port 后 POST /pair,携带 6 位一次性配对码 + 设备名。
  2. 配对码由 Thing 侧生成:用户在设置页点击「连接手机」→ 弹窗展示 6 位码 + 二维码(码内含 ip/port/code,扫码即完成 1、2 两步),有效期 5 分钟,一次性。
  3. 校验通过 → 生成 32 字节随机 hex 设备 token,返回手机;Thing 侧持久化 {deviceId, deviceName, token} 到 keyring(复用 secrets.rs 范式),列表落 settings。
  4. 后续连接:WS 握手首条消息 hello { token }(或 HTTP Authorization: Bearer),校验失败 3 次即拉黑该 IP 60s;/pair 的配对码校验执行同一限速(防 6 位码爆破,配对响应也只在成功时下发 token)。
  5. 设置页设备列表:展示在线/离线、最后连接时间,可撤销(吊销 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. 关键实现细节与已知的坑

  1. GSMTC 在非打包桌面应用可用(unpackaged desktop app 明确支持,1809+)。不要被"WinRT 需要 package identity"的泛泛说法劝退——GSMTC 不在受限之列,开源社区大量此类工具可佐证。2026-09-25 已实证:examples/gsmtc_probe.rs(unpackaged 控制台进程)跑通,读到当前会话元数据/状态/时间轴,核心假设成立。
  2. 封面(Thumbnail)是 RandomAccessStreamReference:OpenReadAsync() → 按 ContentType(image/png|jpeg)读全量字节 → 以 hash(sourceApp + title + album + 尺寸) 为键存内存 LRU(上限 ~20 张)。推送里只带 coverHash,封面走 HTTP 拉取,避免 WS 帧被几百 KB 图片打爆。
  3. 事件风暴节流:TimelinePropertiesChanged 在部分播放器上高频触发(每次内部时钟更新都发)。聚合层统一节流:任何状态变更合并后最快 1Hz 推送 state;进度靠手机端 positionSec + elapsed 本地推算(status=playing 时每秒 +1,收到新 state 校准),不依赖高频推送。例外:由 cmd 触发的状态变更立即推一帧(绕过 1Hz 节流),避免按钮"没反应"的体感——节流仅约束进度等自然高频变更。
  4. 进度推算基准用 TimelineProperties.LastUpdatedTime,不要用"收到事件的本地时刻"——事件分发有延迟,LastUpdatedTime 是播放器侧的权威时间戳。(本条约束 Thing 侧把 GSMTC 事件组装成 positionSec/positionUpdatedAtMs 的动作;手机侧 elapsed 的起算基准见 §6.10,两层不要混用。)
  5. 会话 key 的稳定性:GSMTC 无显式 sessionId,用 SourceAppUserModelId 作 key;同一应用双会话(极少见)时后者覆盖前者,P1 的多会话切换再处理。
  6. Try*Async 的返回值不可全信:部分播放器对不可用操作静默成功,回执只做 UI 轻提示,真实状态以下一帧 state 为准(canControl 能力位已尽力过滤)。
  7. AUMID → 友好名:SourceAppUserModelId 是 PackageFamilyName!App 或注册表 AUMID,显示名需查 Get-StartApps 等价逻辑(注册表 HKCU\Software\Classes\AppUserModelId);先显示末段兜底,友好名缓存 LRU。
  8. 防火墙弹窗只出现一次(每个 exe 路径 × 网络类型),开发期 tauri dev 与正式版 exe 路径不同会各弹一次,属预期。
  9. Windows 通知区域"媒体"浮层与 GSMTC 互不干扰:smtc.rs 的上报会话照常工作;手机控制 Thing 自身时,系统面板同步可见,是 feature 不是 bug。
  10. 进度推算的时钟基准分两层,不要混用:Thing 侧组装 positionSec/positionUpdatedAtMs 用 TimelineProperties.LastUpdatedTime(§6.4);手机侧 elapsed 一律以本地收到该条 state 的时刻起算,禁止拿 positionUpdatedAtMs 与手机本机时间直接做差——电脑时钟偏差(手动对时/休眠漂移可差数秒以上)会整体拖偏进度条。手机端检测到两端时钟偏差 >5s 时冻结推算、只显示基准值,等待下一条 state 校准。两端时钟正常时(NTP 同步)此方案残差 ≤ 推送延迟(LAN 上 <1s,且播放中 ~1Hz 校准)。

7. 分阶段计划

P0:可用版本(目标:手机能看到并控制电脑当前播放)

  • windows crate 开 Media_Control feature;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 签发 + 设备表(keyring music-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/state 401 ✓、/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 实际失效案例再做
  • 多会话列表与手动切换——完成:sessions WS 消息(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 按钮类指令直接 emit music-smtc-button(跳过 GSMTC→系统→SMTC 回环,少一跳系统派发延迟);seek 本就直通 AudioEngine;非 Thing 会话仍走 GSMTC Try*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 携带本机各网卡地址,手机端按连通性优选;显示名可区分

开放问题(实施前确认):

  1. 是否需要"电脑端显示已连接手机"的托盘/OSD 提示?(倾向 P1,托盘菜单加一行在线设备数即可)
  2. 投播的队列控制 API 形态(P2 前与 LFMusic 端一起定)。
  3. 遥控界面是否需要歌词显示?用户需求"显示音乐信息"是否含歌词——Thing 已有 lyric 能力,但"歌词推送"列在 P2,需两端确认是否提前。
  4. 音量控制是否提前到 P0?用户"控制电脑端"可能隐含音量——当前计划在 P1(IAudioEndpointVolume)。