前言¶

在 DSH 裏用 dsh-better-sidebar 瀏覽工作區文件時，圖片往往可以直接在側欄卡片裏打開，而 .mp4、.mp3 等常見媒體卻容易落到代碼兜底或「不支持預覽 · 下載查看」。側欄自帶的 /sidebar/file 對非圖片常回 application/octet-stream，也不支持 Range，瀏覽器既選不到合適的 demuxer，也拖不動進度條。下面介紹社區插件 dsh-media-viewer：它不修改側欄源碼，只註冊一個文件查看器，用 Blob 在側欄裏播放音視頻，側欄升級時不會被覆蓋。

這是什麼¶

dsh-media-viewer 由維護者 feigo313 發佈，歸類爲 DSH 客戶端插件。倉庫自述爲 dsh-better-sidebar 的「插件中的插件」：宿主側幾乎爲空殼，客戶端通過 betterSidebar.registerFileViewer 補上側欄缺的媒體預覽能力。項目爲自用取向，不上插件市場、不發 npm；想用需把倉庫放到本地，在 profile 的 package.json 裏用 file: 引用。

核心功能¶

側欄內直接播放¶

在側欄中點開支持的音視頻擴展名，會出現 <video> 或 <audio> 播放器，可播放、可拖動時間軸，無需先下載文件，也無需另起本地 HTTP 服務。

實現要點¶

1. 宿主半（index.js）：只導出 name、inject: [] 與空的 apply()，不起路由、不讀會話、不依賴隨宿主變化的 webRuntime 等服務。
2. 客戶端半：在 effect 裏調用公開 API 註冊查看器，fetchStrategy 爲 mediaUrl，由側欄解析路徑並給出 /sidebar/file URL；支持約 26 種音視頻容器擴展名，priority 爲 50。
3. 播放路徑：fetch(mediaUrl) → 構造帶正確 MIME 的 Blob → 交給媒體元素。字節在內存中，拖動進度不依賴服務端 Range。單文件大於 256 MB 時自動退化爲直鏈播放；解碼失敗時給出明確提示並提供「下載原文件」，而不是黑屏。

支持的容器¶

• 視頻：mp4、m4v、webm、mov、qt、ogv、mkv、avi、wmv、flv、mpeg、mpg、3gp、3g2、m2ts
• 音頻：mp3、m4a、aac、wav、flac、oga、ogg、opus、weba、aiff、aif

能否出畫面取決於宿主 Electron 自帶的 ffmpeg 能力。H.264、VP9、AAC 等常見編碼一般可用；QuickTime Animation RLE（qtrle，常見於帶通道的特效素材）、ProRes 等可能無法在側欄內解碼——外部播放器能播不代表 Chromium 能播，這類素材需先轉碼。README 示例：

# 保留透明通道，Chromium 可解
ffmpeg -i in.mov -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 out.webm
# 或丟掉通道，最通用
ffmpeg -i in.mov -c:v libx264 -pix_fmt yuv420p -movflags +faststart out.mp4

邊界¶

只做預覽：不轉碼、不做縮略圖、不做播放列表、不記憶播放進度。/sidebar/file 缺少媒體 MIME 與 Range 屬於上游側欄議題（README 指向 DSH-better-sidebar#1027），本插件用 Blob 繞開。若側欄日後變更 registerFileViewer 簽名，伴生插件需同步適配。

安裝與啓用¶

依賴 dsh-better-sidebar（提供 betterSidebar 服務）。未安裝側欄時本插件不會激活，也不會報錯。Node 引擎要求 >=20（見 package.json）。

官方 README 安裝方式：複製倉庫到任意目錄，在 profile 中聲明本地路徑並加入 bundle，再在 profile 目錄執行 pnpm install：

# 複製到任意目錄，然後把路徑寫進 profile
#   ~/.dsh/profiles/desktop/package.json
#     "dependencies": { "dsh-media-viewer": "file:G:/dsh-media-viewer" }
#     "dsh": { "profile": { "bundles": [ ... , "dsh-media-viewer" ] } }

cd $env:USERPROFILE\.dsh\profiles\desktop
pnpm install

Linux/macOS 用戶將路徑改爲本機 clone 目錄，例如 file:/home/you/dsh-media-viewer，profile 路徑對應爲 ~/.dsh/profiles/desktop。

宿主半安裝後需重啓一次 DSH App；之後側欄客戶端會按內容哈希自動加載插件客戶端包。

典型用法¶

1. 確保 profile 已啓用 dsh-better-sidebar 與 dsh-media-viewer，並完成上述 pnpm install 與 App 重啓。
2. 在側欄文件樹中打開工作區內的 .mp4 或 .mp3 等已註冊擴展名文件。
3. 在卡片內使用播放器控件；若提示無法解碼，按 README 用 ffmpeg 轉碼後重試，或使用側欄提供的下載原文件。

適用場景與注意¶

適合已在 DSH 桌面 profile 中使用 dsh-better-sidebar、需要在側欄快速試聽/試看媒體、又不想改側欄源碼的開發者。插件以當前 DSH 進程權限運行，安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證。

DSH 生態強調「一切皆插件」；SkillHub 目錄頁 爲社區收錄，與 DeepSeek / 幻方無官方從屬關係。倉庫當前 GitHub 星標爲 1，版本 1.0.0。

結尾¶

dsh-media-viewer 用獨立包補上側欄音視頻預覽，升級側欄不會被覆蓋。需要本地 file: 安裝與側欄依賴，能力邊界清晰。更多信息見目錄頁與倉庫：

• 目錄：https://www.skillhub.cn/plugins/feigo313/dsh-media-viewer
• GitHub：https://github.com/feigo313/dsh-media-viewer