zemul / dsh-video-preview

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

dsh-video-preview

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

背景

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/.ts/.m2ts
  • 内联 <video controls>：播放/暂停、拖进度条（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