前言¶

在 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 倉庫。