Skip to main content
J

dsh-music-deck

jimmeebingo/dsh-music-deck

Floating music controls for players that publish Windows system media sessions. Windows only.

Install

dsh plugin --profile web add github:jimmeebingo/dsh-music-deck

README

Music deck

platform license dependencies

DSH(DeepSeek Harness)的悬浮音乐播放器。它不接任何音乐服务的私有接口,只读 Windows 系统级的媒体会话(GSMTC),只显示向系统发布媒体会话的 QQ音乐、网易云音乐和 Spotify;具体信息与控制能力取决于客户端提供的支持。

功能

  • 右下角常驻圆形封面 + 播放/暂停的胶囊,点开是完整卡片。
  • 显示正在播放的曲目:封面、歌名、歌手、专辑、进度(App 提供时间轴时)。
  • 控制:上一首 / 播放暂停 / 下一首;播放器向系统提供跳转能力时,进度条可点击跳转。不支持的操作会禁用。
  • 多个播放器同时开着时,点来源标签切换控制对象。
  • 在卡片内切到另一个来源并开始播放时,会先暂停正在播放的那个客户端。
  • 卡片可拖动,吸附在左右两侧;窗口化时自动切换成不带歌名的紧凑布局。
  • 位置、展开状态存在浏览器 localStorage,重启后保留。

系统要求

  • DSH 宿主运行在 Windows 10 1809(build 17763)及以上,或 Windows 11;使用系统自带的 Windows PowerShell 5.1。
  • DSH 桌面版或 Web 版
  • 不需要任何账号、API key 或付费订阅

在非 Windows 平台上插件会安静地停在未激活状态,不会报错。

播放器需要在 DSH 宿主所在的电脑、同一 Windows 登录会话中运行,并向系统发布 SMTC 媒体会话。远程访问 DSH Web 版时,读取的是宿主电脑上的播放器,不是浏览器所在电脑的播放器。没有发布 SMTC 会话的客户端或版本不会出现在来源列表中;插件不会为它们自动添加 SMTC 支持。

安装

在 DSH 里 设置 → 插件 → 安装 bundle,输入包名:

dsh-music-deck

安装完成后确认版本为 1.0.1,启用插件并刷新页面。包名安装不需要本机安装 Git。

其他安装方式:

  • GitHub 源码:安装目标填写 git+https://github.com/Jimmeebingo/dsh-music-deck.git,宿主电脑需要 Git。
  • 插件索引:将 https://raw.githubusercontent.com/Jimmeebingo/dsh-music-deck/main/market/index.json 添加到 Discover,然后搜索「音乐台」。
  • 本地开发:把安装目标指向仓库目录。已有链接安装的开发副本直接更新原目录并重新加载,不要从 npm 覆盖安装。

从 npm 安装的旧版本可在支持版本更新的 DSH 插件页面检查新版本;安装来源为 Git 地址或本地路径时,需要按该来源更新。

使用

操作效果
点胶囊展开卡片
点卡片右上角 ⌄收起回胶囊
点来源标签(左侧色点 + 名字)在多个播放器之间切换,选择的来源会被记住
拖动卡片左右吸附;纵向自由,越过屏幕中线换边
右上角 ← / →一键换到另一侧
右上角回位按钮复位到右下角(位置改过才显示)
右键卡片弹出菜单,可隐藏卡片

窗口化(视口宽度 < 1280px 或小于屏幕宽度的 86%)时,卡片自动变成两行紧凑布局:上行来源,下行封面 + 三个控制键。

只认这三家

卡片只显示 QQ音乐 / 网易云音乐 / Spotify。浏览器标签页、抖音、哔哩哔哩等应用虽然也会向系统 发布媒体会话,但会被直接忽略,不会出现在来源列表里,也不会被当作兜底来源。三家都不在时, 卡片显示「未检测到播放器」。

识别同时看媒体 ID 和音频会话的进程名:媒体 ID 读不出来时(例如只报 cloudmusic), 仍能靠进程名认对。诊断信息里依然会列出全部会话并标出哪些被采用,便于排查"为什么某个播放器没出现"。

在这三家之间,选择顺序是:

  1. 你手动切换过的来源(记住,刷新后不变)
  2. 正在播放、且系统声明为音乐的
  3. 正在播放的
  4. 系统标记为当前的
  5. 第一个

设置

项作用
卡片不透明开 = 实色底;关 = 磨砂半透明
窗口化时自动缩小关掉后窗口化也保持完整卡片
切换音源时自动暂停关掉后允许多个客户端同时出声
复制诊断信息复制所有会话的 ID / 进程 / 状态 / 音量,反馈问题用

实现原理

┌─ DSH Web 页面 ─────────────────────────┐
│  client.js  React 组件(悬浮播放器)    │
│      ↕ fetch /music-deck/state,cmd,cover│
├─ DSH Host(Node)──────────────────────┤
│  index.js  三条本地路由 + 子进程管理    │
│  ↕ %TEMP%\dsh-music-deck-<pid>-<random>\ │
├─ PowerShell 常驻代理 ──────────────────┤
│  smtc.ps1  轮询 GSMTC,转发控制指令     │
│  Cover.cs  运行时编译,读专辑封面       │
└────────────────────────────────────────┘

几个值得说明的取舍:

  • 封面为什么要编译 C#:PowerShell 拿到的 WinRT 流对象是裸 COM 对象,无法投影成 .NET 接口,AsStreamForRead、DataReader、强转全部失败。所以 Cover.cs 在首次启动时由系统自带的 csc.exe 对着 C:\Windows\System32\WinMetadata 编译一次,从内存加载;读取跑在 MTA 线程上,否则 OpenReadAsync 会永远停在 Started。
  • 为什么用文件通信:代理是长期运行的 PowerShell 循环,用 state.json 与命令队列交换,避免 stdout 解析和每次轮询起新进程。指令一条一个文件,快速连点不会互相覆盖。代理退出时宿主自动重启它。
  • 不抓接口:没有调用 QQ音乐 / 网易云的任何私有 API,没有绕过 DRM,没有抓音频流。

已知限制

限制说明
只控制已打开并发布 SMTC 会话的客户端暂停的会话也可被识别;插件不会替你启动或登录音乐 App
控制能力由播放器提供歌名、封面、进度、跳转和上下曲是否可用取决于客户端实际发布的数据及控制能力
互斥只挂在播放上卡片内点「播放/暂停」会暂停其他来源;点「下一首/上一首」不会
封面可能缺失部分 App 暂停时不发布缩略图,此时退回渐变色块
进度条可能不显示App 不发布时间轴时(QQ音乐、网易云常见)隐藏进度条
网易云音乐不显示专辑名它的 AlbumTitle 字段是空字符串;QQ音乐、Spotify 都有值
未识别的服务显示为「播放器」按进程名子串匹配,认不出时功能仍在,只是标签是通用样式

排错

先跑自检脚本,它会列出当前系统里所有媒体会话和曲目信息:

powershell -NoProfile -ExecutionPolicy Bypass -File agent\sessions.ps1
现象检查
卡片根本不出现插件列表里是否启用;刷新页面;DevTools Console 有没有 slot entry crashed
有卡片但一直「没有正在播放的音乐」跑上面的脚本。里面没有对应 App → 那个 App 没发布会话,插件看不到
封面是渐变色块脚本里 artwork : no 就是 App 没提供缩略图
显示成灰色「播放器」进程名没被识别,功能仍可用;提 issue 附上脚本里的 app 行
服务未就绪提示常驻代理起不来,看 %TEMP%\dsh-music-deck-*\cover-error.txt 与 DSH 日志

项目结构

文件作用
index.jsHost 半边:三条本地路由、子进程生命周期
client.jsClient 半边:悬浮播放器、位置记忆、紧凑布局、设置面板
agent/smtc.ps1常驻代理:轮询 GSMTC、执行控制指令
agent/Cover.cs运行时编译的专辑封面读取器
agent/Volume.cs每应用音量(Core Audio 会话)
agent/sessions.ps1自检脚本(不参与运行)
market/build-index.mjs生成插件市场索引
cordis.patch.yml插件在 DSH 里的注册行
locale/*.json插件列表里的标题与描述

开发

  • 改 client.js、locale/:刷新页面即可生效。
  • 改 index.js、agent/:需要在 DSH 插件列表里禁用再启用,重启代理进程。
  • 改 cordis.patch.yml 或 package.json 的 name:需要重新安装 bundle。
  • 发版:改 package.json 的 version,提交推送后跑 node market/build-index.mjs,再提交 market/index.json。
  • 测试:npm test;包含来源选择与接口边界测试,Windows 上还运行 PowerShell 5.1 / COM 回归测试。非 Windows 平台跳过原生测试。

编辑 package.json / locale/*.json 时不要写入 UTF-8 BOM —— DSH 读取包清单时按纯 JSON 解析,带 BOM 会直接安装失败。

隐私

  • 不访问外部音乐服务:前端只请求 DSH 宿主的 /music-deck/ 路由。远程使用 Web 版时,数据会在浏览器和宿主之间传输。临时曲目信息和封面写入宿主的 %TEMP%\dsh-music-deck-<pid>-<random>,插件退出时清理。
  • 不收集数据、不含遥测。
  • 浏览器 localStorage 保存位置、展开状态、手选来源与界面设置。

许可

MIT。图标为原创 SVG,未使用任何音乐服务的商标或 Logo。

「QQ音乐」「网易云音乐」「Spotify」是其各自所有者的商标,本项目与它们没有关联,也未获其背书。

Related plugins