zemul/dsh-video-preview

dshfind

📌 本插件已收录于 dshfind 插件超市（GitHub 仓库打 dsh-better-sidebar / dsh-plugin topic 后自动收录），点击上方徽章直达主页。

dsh-video-preview

npm version

dsh-better-sidebar 的视频文件预览插件：
在侧边栏打开 .mp4 / .webm / .mov / .mkv / .avi 等视频文件时，内联渲染一个可播放、可拖拽进度条的  播放器。

背景

better-sidebar 内置的文件预览器只有 image / pdf / markdown / html / code / binary-download，
没有视频预览——视频文件目前会落到 code 视图（乱码）或下载按钮。

直接复用内置的 /sidebar/file 媒体路由也不行：

- 该路由不支持 HTTP Range（整个文件读进内存、返回 200），浏览器无法拖动进度条（seek）；
- 受 mediaLimit（默认 20MB）限制，更大的视频会被直接拒绝。

因此本插件自带一条 支持 Range（206 Partial Content）的 /video/ 宿主路由，
用 createReadStream 分片流式下发，seek / 拖进度条 / 倍速都能正常工作。

功能

- 通过 ctx.betterSidebar.registerFileViewer 注册 video 预览器（id video，与内置 viewer 同权）：
- .mp4/.m4v/.webm/.mov/.qt/.mkv/.avi/.wmv/.flv/.ogv/.ogg/.mpeg/.mpg/.3gp/.3g2/.m2ts
- 内联 ：播放/暂停、拖进度条（Range 206）、倍速、全屏、音量、preload=metadata
- 底部文件名 + 「下载」链接（浏览器无法解码的容器格式仍可下载原文件）
- 自带 /video/ 宿主路由：HTTP Range / If-Range / suffix-range（bytes=-N），视频大小不受 mediaLimit 限制
- viewer 描述符带 title/icon，Side card 设置页自动显示启用开关（含 16px 播放器图标）
- 客户端组件自包含：不依赖 better-sidebar 的 client 内部实现，fetchStrategy: 'none'

依赖 better-sidebar 版本

需要 better-sidebar >= 0.4.0（ctx.betterSidebar.registerFileViewer 服务）。

安装（profile）

前置：DSH 已装好且 dsh web 能运行，已安装 dsh-better-sidebar。

从 npm 安装（推荐，发布后生效）：
dsh plugin --profile web add dsh-video-preview

本地开发（link: 热更新）：
dsh plugin --profile web add "link:"

从 tarball 安装（离线 / 未发布）：
dsh plugin --profile web add file:/dsh-video-preview-0.1.1.tgz

安装后重启 dsh web 进程并浏览器硬刷新（Cmd/Ctrl+Shift+R）。
说明：新增宿主半（/video 路由）需要重启一次；之后仅 client 改动硬刷新即可。

运行

- 打开侧边栏 → 在文件资源管理器中打开任意视频文件，video 预览器自动命中；
- Side card 设置页 →「文件预览」清单中可见 Video 卡片（带播放器图标），可单独启用/禁用。

开发与检查

node test/route.test.mjs   # 宿主路由回归测试（Range/206/416/403/HEAD/405，19 项）

| 检查项 | 命令 | 预期 |
|--------|------|------|
| 宿主路由测试 | node test/route.test.mjs | 全部通过 |
| client bundle | node --check client.js | 语法 OK |
| bundle 形态 | 产物首行 | window.__ModuleLoader__.load({ id: 'dsh-video-preview', ... }) |
| 安装状态 | node_modules/dsh-video-preview/client.js 存在 | True |

结构

| 文件 | 作用 |
|---|---|
| index.js | 宿主半：注册 /video/* 前缀路由（Host 头信任围栏 + 会话 cwd 越界检查 + Range/If-Range/suffix-range） |
| client.js | 客户端 bundle：经 ctx.betterSidebar.registerFileViewer 注册 video 预览器（fetchStrategy: 'none'，含 16px 图标） |
| cordis.patch.yml | dsh.bundle.patch：挂载行（entry name 与包名一致，供 client-modules 发现 client bundle） |
| test/route.test.mjs | 宿主路由回归测试（自包含，无需 ffmpeg） |

安全

- 路由复用与 /api 网关相同的 Host 头信任围栏（loopback 或 trustedHosts，拒绝跨站）；
- 解析后的路径必须位于会话权威工作目录内（大小写/分隔符容忍），.. 无法越界；
- 只读流式下发，不写文件、不设身份。

说明与限制

- 支持浏览器可解码的容器/编码（H.264 的 mp4/m4v、VP8/VP9 的 webm、mov、OGV 等）；
Chrome/Edge/Firefox 不内置解码的格式（如部分 HEVC、AV1 组合）会在播放器内报错，可用「下载」取回原文件；
- 视频大小不受 better-sidebar mediaLimit 限制；
- 不新建 Tab 页，仅作为文件预览器注册（也可按需再加 registerTab）。

许可证

MIT