前言¶

在 DSH 里写代码或跑智能体时，有人会在同一浏览器工作区里挂背景音乐。系统标签页要联网、还要把文件交给站点；单独的桌面播放器又得切窗口。dsh-music-player 把播放列表、传输条和均衡器做成客户端插件：从本机选文件或拖入面板即可播放，零联网、零 npm 依赖，音频不上传服务器。

下面按定位、功能、安装、用法和限制说明。

这是什么¶

dsh-music-player 由 koishi-fumo-code 维护，归类为 DSH 社区目录中的客户端插件。左侧图标条增加「音乐」入口，点开后在主工作区（main 槽位）播放本机音频；交互参考 foobar2000 / foobox（列表、封面、传输条、18 段 EQ），引擎跑在浏览器与 Web Audio 里。

当前版本 0.4.0（见仓库 package.json），要求 DSH >=0.1.7-rc.1、Node >=22（仅安装脚本需要），许可证 MIT。社区目录页：https://www.skillhub.cn/plugins/koishi-fumo-code/dsh-music-player；源码：https://github.com/koishi-fumo-code/dsh-music-player。

核心功能¶

入口与加歌¶

• 入口挂在 sidebar.panellist，面板渲染在主工作区。
• 点「添加音乐」可多选或选整个文件夹，也可把文件拖进面板。
• 传输条或设置页里的齿轮可打开设置页；全局设置里也有「音乐播放器」一页。

播放列表与持久化¶

• 列表显示标题、歌手、时长；单击选中、双击播放（误点不会突然出声）。
• 搜索框按配置的范围过滤；悬停行尾可移除单曲。
• 开启「记住播放列表」后，列表元数据与文件本体写入浏览器 IndexedDB，关页面或升级插件后默认保留；设置项 rememberList 可关或一键清除。单文件大于 512MB 不写入存储。

封面与标签¶

• MP3 读 ID3v2；FLAC 读 Vorbis comment 与内嵌 PICTURE。
• 无内嵌封面时退回文件名。元数据只读文件头约 4MB，超大标签或封面可能读不全（不影响播放）。

传输与播放顺序¶

• 上一首 / 播放暂停 / 停止 / 下一首、进度拖动、时间与音量、静音。
• 播放顺序对齐 foobar 的 Playback order：顺序 → 列表循环 → 单曲循环 → 随机。
• 播放引擎在模块作用域：切到会话或其他面板时歌曲继续；回到面板接上当前进度。卸载插件时自动停声。

18 段均衡器¶

• 频段约 55 Hz～16 kHz，±20 dB；对齐 foobar 的 foo_dsp_eq。
• 20 个预设取自 foobar2000 的 Equalizer Presets 目录（.feq 原值），含 Flat、1965、Air、Metal、Pop 等名称；另有预增益与「自定义」。
• 关闭 EQ 时各段增益归 0，音频仍走已建立的 Web Audio 图。

DSD 软解¶

• 支持 DSF 与未压缩 DFF（DSD64/128/256）：在浏览器内 box 抽取、低通后转成 44.1 kHz PCM，再封装 WAV 播放。
• 不是 foobar + ASIO 的硬件 DSD 直通；DST 压缩的 DFF 不支持；大于 768MB 拒绝转码；转码在内存中进行，长曲占用较高。

与 foobar 教程的默认对齐¶

插件把《Foobar2000 与小尾巴使用的配置教程》相关默认值写进 localStorage['dsh-music-player.settings']，例如 gainMode: 'processing'、bufferMs: 1000、dsdDecode: true、dsdMode: 'passthrough' 等；设置页可改，「重置全部设置」回到教程默认。浏览器无法实现 ASIO 独占选设备、DoP 原生 DSD 输出，以及 foobar 式 ReplayGain 扫描——README 中对此有逐项说明。

浏览器格式与策略¶

• Chromium 下常见 MP3、FLAC、WAV、OGG、M4A 等一般可播；APE、WMA、ALAC 通常不行。
• 受自动播放策略限制，首次需用户点播放；加歌时只选中、不自动出声。

安装与启用¶

插件以当前 DSH 进程权限运行；安装前建议自行查看仓库源码与 MIT 许可证。社区目录与 GitHub 无 DeepSeek / 幻方官方从属关系，属于 DSH「一切皆插件」生态中的第三方条目。

方式一：本机开发（插件管理器）¶

包内带 cordis.patch.yml，用插件管理器安装：

plugin_manager  action=install_bundle  target=<插件目录的绝对路径>

链接安装后改源码刷新页面即可加载；卸载可在管理器中卸 dsh-music-player。

方式二：换机或分发（推荐）¶

使用自带安装器，不修改你的 cordis.patch.yml：

# Windows 可直接双击 install.cmd

# 任意系统，Node 22+
node scripts/install.mjs              # 装到所有 profile
node scripts/install.mjs --dry        # 仅预览将修改的内容
node scripts/install.mjs --verify-only
node scripts/install.mjs --uninstall  # 卸载

脚本会查找 DSH_HOME、扫描 profiles/*、建链接并登记 bundles。安装完成后需完全重启一次 DSH。侧栏出现音乐图标即表示装好。

打成可分发的 .tgz 时，可先自检再打包：

node scripts/portability-check.mjs
node scripts/simulate-foreign-pc.mjs
node scripts/make-tgz.mjs --verify

细节见仓库内 分发说明.md。介绍视频（约 2 分 19 秒）见 releases v0.4.0 附件。

典型用法¶

1. 按上文任选一种方式安装，重启 DSH。
2. 点击左侧「音乐」图标，打开主工作区播放器。
3. 「添加音乐」或拖入本机音频；需要 DSD 时在设置中保持 DSD 软解开启（默认 dsdDecode: true），拖入 DSF 或未压缩 DFF。
4. 双击列表项开始播放；在传输条切换顺序、音量；在设置中调整 EQ 预设、rememberList、列表列显示等。
5. 播放相关偏好另存于 localStorage['dsh-music-player.prefs']（音量、静音、播放顺序）。

适用场景与注意¶

适合：在 DSH Web 工作区里听本机曲库、对照 foobar EQ 预设做试听、偶尔播放 DSD 软解 PCM，且不希望音频出网或依赖额外后端。

注意：

• 列表「记住」依赖本浏览器站点存储，换浏览器或清站点数据会丢。
• outputDevice、exclusive 等项主要影响缓冲策略记录，不能代替 foobar 的设备枚举与独占输出。
• 大 DSD 转码等待与内存占用需有预期；超大普通文件可能无法持久化到 IndexedDB。

结尾¶

dsh-music-player 把 foobar 风格的列表与 18 段 EQ、DSD 软解收进 DSH 客户端面板，强调本机文件、零依赖、零联网。若要安装或看更新，可访问 SkillHub 目录页 与 GitHub 仓库。