前言¶

dsh-music-player-tui 是一個面向 dsh-tui 的 DeepSeek Harness（DSH）TUI 插件。它把本地音樂播放器放進終端場景：輸入 /music 打開全屏場景，選擇本地音樂目錄，掃描常見音頻格式，再調用本機播放器進程出聲。

它主要解決一個具體問題：在 dsh-tui 裏邊操作邊聽本地音樂，並且退出全屏場景後音樂不中斷。

這是什麼¶

heshuren371/dsh-music-player-tui 是 heshuren371 維護的 MIT 許可插件，用於 dsh-tui 宿主。

它的核心思路是：

• 在 dsh-tui 內提供 /music 全屏音樂場景。
• 掃描本地目錄中的音頻文件，生成曲目列表。
• 由宿主 spawn 本機播放器進程，例如 mpv、ffplay、afplay。
• 退出場景後播放進程繼續存在，音樂不停止，隨時可以再次輸入 /music 回到場景。

核心功能¶

已覈實的功能包括：

• 本地目錄遞歸掃描：flac / mp3 / m4a / aac / ogg / opus / wav。
• 內嵌標籤解析；缺省時回退「歌手 - 歌名」文件名約定。
• 曲目列表顯示歌名、歌手、時長。
• 使用 ↑/↓ 或 j/k 選擇曲目，窗口隨終端高度自適應。
• 鼠標支持：懸停移動選擇光標，點擊列表行直接播放。
• 排序：歌名、歌手、時長，可切換升降序；播放順序等於可見列表順序。
• 搜索過濾：歌名、歌手、文件名。
• 循環模式：列表循環、單曲循環、播完即停。
• 快進快退：←/→ 調整 ±5s，Shift 下調整 ±30s。
• 音量調整：+/- 每次調整 5%。
• 退出場景後音樂不中斷。
• 刪除曲目：場景內 x 二次確認，或 /music delete <關鍵詞>。
• 狀態持久化：目錄、音量、循環模式、最後播放曲目與進度。
• /music 子命令直達：dir / play [關鍵詞] / pause / next / prev / vol / refresh / delete。
• 標準 bundle 插件：零核心改動，進插件清單，卸載即淨。
• 播放後端自動探測：mpv、ffplay（ffmpeg）、afplay（macOS 自帶）。

安裝與啓用¶

1、確認前置條件：已安裝並能運行 dsh-tui，版本 ≥ 0.8；首次運行會自動初始化 profile。

2、添加插件：

dsh plugin --profile dsh-tui add github:heshuren371/dsh-music-player-tui

3、重啓 dsh-tui，輸入 /music 回車。全屏場景出現即表示啓用成功。

4、建議安裝 mpv，以獲得更完整的播放控制：

brew install mpv

mpv 後端支持無縫暫停、即時音量/seek、精確進度。沒有 mpv 時，插件會探測 ffplay（ffmpeg）或 afplay（macOS 自帶）。三個後端都沒有時插件照常掛載，起播會提示安裝 mpv/ffmpeg。

典型用法¶

安裝並設置目錄後，可以在 dsh-tui 內使用下面的 /music 子命令：

/music dir ~/Music
/music play
/music play 關鍵詞
/music pause
/music next
/music prev
/music vol 60
/music refresh
/music delete 關鍵詞

對應含義：

• /music dir <路徑>：設置目錄並掃描，例如 /music dir ~/Music。
• /music play [關鍵詞]：播放當前/第一首；帶關鍵詞時播放首個匹配曲目。
• /music pause：暫停或繼續。
• /music next / /music prev：切歌。
• /music vol <0-100>：設置音量。
• /music refresh：重新掃描當前目錄。
• /music delete <關鍵詞>：刪除曲目文件，需唯一匹配，不可恢復。

在 /music 全屏場景內，還可以使用：

• Enter：播放選中曲目。
• Space：暫停或繼續。
• q / Esc：退出場景，音樂繼續播放。
• x：刪除選中曲目，再按一次 x 確認；本地文件一併刪除，不可恢復。

播放後端¶

聲音由運行 dsh-tui 宿主的那臺機器上的本機播放器進程發出。插件會自動探測以下後端：

• mpv：建議安裝。支持無縫暫停、即時音量/seek、精確進度。
• ffplay（ffmpeg）：備選後端。暫停依賴 POSIX 信號（SIGSTOP/SIGCONT）；Windows 建議直接安裝 mpv。
• afplay：macOS 自帶兜底後端。不能快進快退，音量在下次起播時生效。

如果三個後端都沒有，插件照常掛載，起播時會提示安裝 mpv/ffmpeg。

適用場景與注意¶

適合：

• 在 dsh-tui 裏邊操作邊聽本地音樂。
• 希望退出全屏場景後播放不中斷。
• 只使用本地音頻文件，使用本機播放器進程出聲。
• 需要簡單的曲目列表、搜索、排序、切歌、暫停、音量控制。

注意：

• 刪除曲目會刪除本地文件，不可恢復。
• /music delete <關鍵詞> 需要唯一匹配。
• 場景內 x 刪除需要二次確認。
• afplay 爲兜底後端，不能快進快退，音量在下次起播時生效。
• 三個播放後端都沒有時，插件照常掛載，但起播會提示安裝 mpv/ffmpeg。
• 插件以 trusted-in-process 方式運行在 dsh-tui 宿主進程內，不是沙箱。
• 它實際會做三件事：讀取指定音樂目錄、spawn 本機播放器進程、在場景內二次確認或命令唯一匹配時刪除對應曲目文件；除此之外不讀寫任何文件、不訪問網絡。
• 依賴閉包僅 music-metadata（純 JS，無 native/build 步驟、無 override/patch）；狀態優先寫入用戶目錄，已安裝包目錄保持只讀。
• 狀態文件位於 ~/.dsh-music-player-tui/state.json。卸載僅移除插件包，不觸碰音頻文件；狀態文件保留，手動刪除該目錄可徹底清除。
• 規範當前爲 Draft/Experimental：本插件聲明的是實驗適配，不代表官方認證或對所有 DSH Host 的兼容性承諾。
• 插件以當前 dsh-tui 宿主進程權限運行，安裝前應檢查源碼與許可證。許可證爲 MIT。

結尾¶

dsh-music-player-tui 的價值在於把本地音樂播放放進 dsh-tui 場景：可以掃描本地目錄、排序搜索、播放暫停切歌、調整音量，並且退出場景後音樂繼續播放。

倉庫地址：https://github.com/heshuren371/dsh-music-player-tui