dsh-music-player

DeepSeek Harness 本地音乐/小说播放插件。

写代码写累了、想摸鱼又不想切窗口？这个插件就是你的摸鱼神器——直接在 DeepSeek Harness 的网页里塞进一个 DSH音乐播放器：扫一下你电脑上的音乐目录（默认 ~/Music）就能在浏览器里听歌，带播放条和可拖拽的播放面板，还能自己建歌单。

光听歌还不够，它还能听书：把本地 .txt/.epub 小说丢给 AI 朗读，想听哪章点哪章、声音随便挑。最绝的是它还注册了 music_play 模型工具——你连鼠标都不用动，在对话框里跟 agent 说句「播放周杰伦的歌」，音乐分分钟响起来，摸鱼摸出新境界。

特性

• 本地音频流式播放（HTTP Range），刷新后断点续播
• 顺序播放、单曲循环、乱序播放三种模式
• 实时 12 段频谱可视化（真实 FFT 频段：浏览器支持时走 captureStream()+AnalyserNode 只读旁路实时采样、t=0 即响应——它不重定向媒体元素输出，因此绝不会让播放静音；若该环境报 Chromium 的 getTopURL 媒体管线错误、取不到音轨，则回退到解码时离线预计算的包络，跟随播放位置）。实时柱高把各频段的 bin 归到对数频段取峰值、按分析器 dB 量程归一化（标准做法），柱高由绝对响度驱动（安静时柱自然低），并用一条固定、与响度无关的频率加权抹平音乐天然的 1/f 低频倾斜——低频几根不再常年钉在高位，同时安静片段也保持低柱；离线回退包络与实时共用同一条加权，切到回退时观感一致）
• 实时歌词/字幕：本地音频自动匹配同名 .lrc 逐行显示；本地没有同名 .lrc 时自动在线兜底（QQ 音乐官方歌词 → LRCLIB 免费同步歌词，结果按曲目缓存避免重复请求）；在线 QQ 歌曲自动取官方歌词（外语歌带逐句翻译「原文 ／ 翻译」）；AI 讲书时显示当前朗读句子（逐句滚动）。歌词/字幕显示在播放条频谱之后、时长之前，仅在闲置（控件组折叠）时展示，鼠标进入操作时自动收起；AI 讲书还有一条「已读字符/全书字符」的全书进度细线（按已读字数实时计算，不依赖合成时长，切块不回退，操作时再显示「N%」）
• 播放时申请屏幕唤醒锁，防止听歌时熄屏/休眠（支持 Wake Lock 的浏览器，如 Chrome/Edge）
• 播放列表面板可自由拖动，右下角可拖拽调整大小，位置与尺寸跨刷新记忆
• AI 讲书：本地 .txt / .epub 小说经 MiMo TTS 合成朗读，自动识别书名/前言/章节/尾声结构，播放条带章节目录跳转（打开即定位到当前正在播放的章节）、章节切歌，可选 4 种中文 AI 声音（默认白桦）
• music_play 模型工具：agent 可按关键词播放本地音乐，也可按小说名启动 AI 讲书
• 支持的格式：mp3 / m4a / m4b / aac / flac / wav / ogg / opus / webm / aiff（自动递归扫描子目录，上限 500 首）
• 真实音质识别：本地歌曲扫描时自动解析文件头（FLAC/WAV/AIFF 无损、MP3/AAC/OGG 码率、采样率/位深/声道），播放条显示「格式 · 音质档」（如 FLAC · 无损 / MP3 · 高音质 / MP3 · 标准），与在线 QQ 音乐的「无损/高音质/标准」三档一致
• 自建歌单：可新建多个歌单，从本地文件（支持多选、可跨目录）添加歌曲；播放条爱心按钮一键收藏到默认歌单「我最喜欢」；歌单作为播放来源时，顺序/乱序循环只在该歌单内进行
• 在线 QQ 音乐：面板内置「QQ音乐」页签——微信/QQ 扫码登录（解锁 VIP/高音质）、我的歌单/推荐歌单/分类歌单/排行榜/新歌/搜索浏览、卡片式歌单展示、一键收藏到「我喜欢」

截图

安装

需要已安装 dsh CLI。

从 npm 安装（推荐，已发布到 registry）

# 把 <profile> 换成实际 profile 名，如 web
dsh plugin --profile <profile> add dsh-music-player

从 GitHub 安装（备用来源）

# 把 <profile> 换成实际 profile 名，如 web
dsh plugin --profile <profile> add github:kendu76/dsh-music-player

项目是手写的纯 JS（lib/ 直接是发布产物），没有需要从源码构建的步骤，因此从 GitHub/npm 直装即可使用，无需像 TypeScript 包那样为构建脚本授权。

安装后重启 DSH，打开 Web GUI：

• 聊天输入区上方会出现「DSH音乐播放器」播放条
• 点击右侧「列表」按钮打开播放面板
• 在面板顶部点击「选择音乐目录」并选定音乐目录（默认 ~/Music），自动递归扫描
• 之后可直接在对话框里让 agent 播放，例如「播放周杰伦的歌」

从本地目录 / tarball 安装

# 本地目录
dsh plugin --profile <profile> add /path/to/dsh-music-player

# 或先打包再安装
pnpm pack
dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz

配置

插件为「Host 端 + Web 端」双面结构：

• Host 端（lib/index.js）：音乐扫描、HTTP 流式、歌单 CRUD/持久化、music_play 工具、AI 讲书（小说结构解析 + TTS 合成）
• Web 端（lib/client.js）：浏览器里的播放条 / 播放面板 / 频谱 / 歌单（收藏、一键清空）/ 讲书控制

两者由一个 cordis.patch.yml 插入 music-player 行并自动组对（在 Web 端 dsh.client 声明即指回该行名并加载浏览器半体）：

- insert:
    - id: music-player
      name: 'dsh-music-player'

播放模式与音量等播放偏好都保存在 Host 端（见下），刷新后当前曲目与进度也会恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。

状态持久化（重要）：所有播放状态都持久化在 Host 端文件 ~/.dsh/music-player-prefs.json，包括： 音量、播放顺序、AI 讲书声音、播放范围、面板位置、上次播放的曲目/进度、每本小说的进度、QQ 搜索历史、QQ 面板所在层、QQ「我喜欢」收藏兜底。 因此即使在 dsh-desktop 桌面版（每次启动随机端口、浏览器存储按源隔离）下，重启后这些状态照样能找回。 升级兼容：旧版本（<0.7）把同样的键存在浏览器 localStorage 里。升级后客户端优先读 Host，Host 没有的记录会自动回退读取旧 localStorage 副本并迁移进 Host，升级不丢用户数据。 音乐/小说目录、自建歌单、QQ 登录态也持久化在 Host 端（见下文），同样不受影响。

自建歌单（收藏）

播放面板「本地音乐」页内新增子标签：曲库 / ♥ 我最喜欢 / ＋，支持自建歌单并把歌单作为播放来源——此时顺序/乱序循环只在该歌单内进行。

• 新建歌单：点「＋」输入名称即建（可建多个）。
• 曲库加入：在「曲库」列表每首歌行尾有「＋」按钮，点击可把该曲加入任一已有歌单，或直接新建歌单加入。
• 添加歌曲：进入某歌单 → 点「添加歌曲」→ 打开本地文件多选框（可多选、可跨目录）加入歌单；歌单内每首歌支持上移/下移排序与移除。
• 清空歌单：每个歌单（含「我最喜欢」）详情内都有「清空」按钮，二次确认后一键移除全部歌曲（歌曲文件不会被删除）。
• 收藏：播放条上的爱心按钮一键把当前曲加入默认歌单「我最喜欢」，再点取消；「我最喜欢」固定不可删除/重命名。
• 播放范围：在歌单里点歌，则顺序/乱序/单曲循环都在该歌单内；在「曲库」点歌则回到全库循环。
• 命令：music_play 工具新增 playlist 参数，可让 agent 直接播放某个歌单（如「播放歌单 我最喜欢」）。
• 歌单数据保存在 ~/.dsh/music-player-playlists.json，刷新/重启不丢；歌单可包含曲库目录之外的本地音频文件。

在线 QQ 音乐

播放面板顶部切到「QQ音乐」页签即可在线听歌。需先扫码登录（QQ 登录或微信登录），登录后可浏览/搜索/播放并访问「我的歌单」，VIP 曲目可播高音质。

使用声明（重要）：在线 QQ 音乐功能通过非官方接口访问 QQ 音乐资源，所播放/收藏的内容版权归 版权方及 QQ 音乐平台所有。本功能仅供个人学习、技术研究、日常试听使用， 严禁用于任何商业用途、公开传播、二次分发或盈利行为。使用本功能即表示您已知悉并同意：

1. 您应对自己的使用行为及其后果负责；
2. 因使用非官方接口登录/播放导致的账号风控、封禁、限流，以及可能引发的法律、版权纠纷，均由使用者自行承担；
3. 本项目作者不承担任何因此产生的直接或间接责任。 如您不同意以上条款，请勿使用本功能。

• 登录：两种扫码方式——QQ 登录或微信登录（推荐）。登录态保存在 Host 端（~/.dsh/music-player-qq-cookie.json），刷新/重启不丢；面板右上角可退出登录。
• 浏览：6 个子页签——我的歌单 / 推荐歌单 / 分类歌单 / 排行榜 / 新歌 / 搜索。
  • 我的歌单：登录后展示当前账号的歌单（卡片式），本人创建的歌单卡片右上角可一键删除（二次确认；「我喜欢」不可删除）。
  • 推荐歌单：热门推荐 12 条，底部「加载更多」可续载。
  • 分类歌单：60+ 分类（默认折叠显示 8 个，可展开），每个分类的歌单支持「加载更多」。
  • 排行榜：巅峰榜/地区榜/特色榜等分组，点榜单看歌曲（带榜单封面卡片），榜单详情底部「加载更多」可分页续载全部歌曲。
  • 新歌：新歌速递（最新/内地/港台/欧美/韩国等）。
  • 搜索：搜歌曲与歌单，带搜索历史（Host 持久化，最近 10 条）。
• 播放：点击任意歌曲即可播放（同一播放条 + 频谱）；VIP 标识显示在歌名后，行尾显示歌手名。进入歌单/播放列表时自动定位到正在播放的那一首，且正在播放的条目以高亮选中态显示。
• 收藏：播放条爱心按钮把当前在线曲目收藏到 QQ 音乐「我喜欢」，已收藏歌曲爱心实时点亮。
• 续播：在线播放进度（当前曲目 + 队列）刷新后自动恢复，点 ▶ 续播。
• 在线曲目不占本地曲库的 500 首上限，与本地/讲书完全隔离。

AI 讲书

把本地 .txt / .epub 小说交给 AI 朗读。AI 语音目前仅支持xiaomi提供方（限时免费），请在设置中配置好再使用此功能。

前置

在 DSH 的模型设置里配置一个xiaomi提供方（含 api key）。未配置时，小说列表会提示"未配置xiaomi提供方"。

使用

1. 打开播放面板，切到「小说」标签，点「选择小说目录」选定包含 .txt / .epub 的目录（默认与音乐目录相同）。
2. 点击某一本小说开始朗读；也可让 agent 用 music_play 工具按小说名播放（如「播放《中国制造》」）。
3. 播放条上的讲书控制：
   • 章节目录（📖 按钮）：自动识别全书结构（书名/前言/章节/尾声），点击弹出位于按钮正上方的目录（自动定位到当前正在播放的章节），点击任意章节即从该章开头朗读
   • 后退 / 前进：讲书模式下跳上一章 / 下一章（音乐模式下仍是上一首 / 下一首）
   • AI 声音：点音量按钮，在弹层选择声音——冰糖（女）、茉莉（女）、苏打（男）、白桦（男，默认）
   • 全书进度：播放条底部有一条「已读字符/全书字符」的进度细线，操作时显示「N%」——按已读字数实时计算，无需先合成全书就能给出稳定的整体进度（切块不回退；字符量来自源文本，因此总长总是可知，而总时长得合成完才知道），刷新页面后也会立即恢复显示（无需先点播放）
4. 刷新页面后从上次位置续读（断点续播）。

支持的格式：

• .txt（自动识别 UTF-8 / UTF-16 / GBK/GB18030 编码，无需手工转码）
• .epub（自动解压并按其目录（spine）顺序把章节转成纯文本朗读；标题/作者取自 epub 元数据，可识别章节结构；加密/DRM 的章节会自动跳过）

开发

需要 Node.js ≥ 20（vitest 建议 20.19+）与 npm。开发依赖：vitest + react/react-dom/jsdom（用于前端渲染冒烟测试）：

npm install
npm test        # 跑 vitest 测试套件（Host 单测 + Web 渲染冒烟，共 120+ 用例）

修改 lib/ 后，在本机 profile 里用 link 方式本地调试并验证：

dsh plugin --profile <profile> add ./   # 或直接改 profile 里的 link 目标

项目结构、测试策略与发布流程详见 CONTRIBUTING.md。

常见问题

播放没有声音 / 显示"浏览器拦截了自动播放"？ 浏览器安全策略禁止未经交互的音频播放。首次自动播放被拦截是正常的——在播放条上点一次 ▶ 即可解锁，之后恢复播放。

音乐面板显示"暂无音乐"或"不是有效的音乐目录"？ 点面板顶部「选择音乐目录」，选一个包含音频文件的实际目录（默认 ~/Music）。目录路径不可读或不存在时会回退到默认目录而不是报错。

改了音乐目录/新增了歌曲，但列表没更新？ 播放器在启动时扫描一次，并支持手动重扫：点「选择音乐目录」旁边的新增 「刷新」按钮，会重新遍历当前目录并更新列表（音乐与小说通用；无需重选目录）。扫描上限 500 首、递归子目录深度上限 4 层。

music_play 工具说"音乐库为空"？ 说明还没有可用的音乐目录。请先打开播放面板，点「选择音乐目录」配置一次。

小说列表提示"未配置 xiaomi/MiMo TTS 模型"？ AI 语音目前仅支持 xiaomi 提供方（限时免费）。请先在 DSH 模型设置里配置 xiaomi/MiMo provider（含 api key），再使用讲书功能。

讲书播放时点后退/前进没反应？ 讲书模式下后退/前进是跳上一章/下一章；如果当前小说没有识别出章节结构（目录按钮提示"暂无章节结构"），则无法跳章，只能整本顺序播。

听书偶尔"没声音但时间还在走"？ 这种一般是某一段的合成结果异常（返回了退化/静音音频），或瞬时合成失败。0.3.3 起 Host 端会严格校验合成音频（拒绝空数据/非 PCM 等退化 WAV）并自动重试一次瞬时失败，同时把每次合成结果记录在诊断日志里。若再遇到，可访问 http://<DSH地址>/dsh-music/tts-logs 查看最近 60 条合成记录（含失败原因、退化音频事件），据此定位具体是哪个块出的问题。

本地音乐没有 .lrc，歌词是怎么来的？ 播放器会在线兜底取词：先用文件名（可带歌手/时长）在 QQ 音乐匿名接口匹配官方歌词（外语歌带逐句翻译），QQ 无果再查 LRCLIB（免费公开歌词库，返回同步 LRC）。结果按曲目在进程内缓存（正命中 6 小时 / 空命中 30 分钟），避免重复请求；无匹配或失败时静默保持无歌词，不影响播放。歌词为版权内容，仅供个人试听。

想支持更多音频格式？ 格式支持由 Host 端 AUDIO_TYPES 表驱动，在 lib/index.js 里加扩展名与 MIME 即可（播放器本身用浏览器原生 <audio> 解码，最终能否播放还取决于浏览器对该编码的支持）。

License

MIT © kendu76