dsh-reel

dsh plugin --profile web add dsh-reel

<p align="center">

<img src="lib/assets/brand.svg" alt="dsh-reel logo" width="128" height="128" />

</p>

<h1 align="center">dsh-reel</h1>

<p align="center">

<strong>专为 dsh Web 打造的现代化流媒体库与沉浸式画廊插件</strong>

</p>

<p align="center">

本地多媒体目录聚合 · HTTP Range 流式秒播 · 服务端边转边播 · 动态全屏壁纸 · 触控手势连播

</p>

<p align="center">

<img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js" />

<a href="https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.1"><img src="https://img.shields.io/badge/dsh-%3E%3D_v0.2.0--rc.1-0066FF?style=for-the-badge" alt="dsh >= v0.2.0-rc.1" /></a>

<img src="https://img.shields.io/badge/Cordis-Plugin-18B26B?style=for-the-badge" alt="Cordis" />

<img src="https://img.shields.io/badge/FFmpeg-Included-007808?style=for-the-badge&logo=ffmpeg&logoColor=white" alt="FFmpeg" />

<img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License" />

</p>

<p align="center">

<img src="https://img.shields.io/github/stars/lsjspl/dsh-reel?style=flat-square&color=ffd33d&logo=github" alt="Stars" />

<img src="https://img.shields.io/github/forks/lsjspl/dsh-reel?style=flat-square&color=8957e5&logo=github" alt="Forks" />

<img src="https://img.shields.io/github/last-commit/lsjspl/dsh-reel?style=flat-square&color=3fb950" alt="Last commit" />

<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome" />

</p>

<p align="center">

<strong>简体中文</strong> · <a href="README.en.md">English</a>

</p>

---

<p align="center">

<img src="doc/screenshot/home.png" alt="dsh-reel 媒体库主界面" width="960" />

</p>

简介

dsh-reel 为 dsh Web（要求 dsh 最低版本为 v0.2.0-rc.1）提供了一站式的媒体库浏览与沉浸式影音播放体验。无需启动独立的流媒体服务或新端口，只需一条命令挂载多个本地磁盘目录，即可立即在浏览器中畅享高性能的图片画廊与流媒体播放器。

项目地址与快速访问：

http://127.0.0.1:3080/reel

---

核心特性

• 零额外进程，轻量内嵌：与 dsh Web 同端口、同 origin；宿主侧仅新增一行 Cordis 组合配置与 /reel 前缀下的只读路由，不启动新守护进程，无需额外打包构建步骤。
• 严格安全沙箱：对本地媒体目录严格只读；所有目录枚举与文件读取均限制在白名单根路径内，杜绝路径穿越风险。
• 多目录聚合 & 多维视图：
• 顶层「库」智能聚合所有已挂载的磁盘目录，层级按需惰性加载。
• 当前、全部（递归平铺）、分组（按目录折叠）三种浏览模式随心切换。
• 网格布局（小 / 中 / 大三档尺寸自适应）与紧凑列表视图。
• HTTP Range 流式秒开：视频原生采用 HTTP Range 响应流式分发，任意拖拽进度条即时起播，不阻塞带宽。
• 服务端边转边播：对于 AVI、WMV、FLV、RMVB 等浏览器无法原生解码的老旧容器，服务端由 ffmpeg 实时转封装为 fragmented MP4 边转边发，内存管道直出，零磁盘临时占用；拖动进度条自动从目标时间重新建立流。
• 悬停预览与精准帧截取：进度条悬停即时展示缩略图预览与时间戳；内置 FFmpeg / FFprobe 支持，自动提取视频时长、分辨率与高质量封面海报。
• 沉浸式全屏动态壁纸：
• 任意图片或视频一键设为全站全局动态壁纸（视频静音循环，失焦自动暂停节能）。
• 全屏半透明毛玻璃质感 UI 交互，视觉体验拉满。
• 触控手势连播 & 移动端全适配：
• 手机端与窄屏自适应布局，支持上下滑动切换上一条 / 下一条（类似 Reels / 抖音短视频跟手滑动交互）。
• 支持顺序连播、随机洗牌播放、播放位置记忆、长按 2× 快进、外挂同名字幕自动加载与当前帧截图导出。
• dsh 原生可视化设置：完全集成于 dsh 设置面板，增删媒体目录、设定缓存与壁纸热更新即刻生效。

---

界面预览

沉浸式动态壁纸模式

将喜欢的视频或图片一键设为全站背景，界面组件自动转为通透的毛玻璃半透明层：

<p align="center">

<img src="doc/screenshot/home2.png" alt="沉浸式全屏动态壁纸" width="960" />

</p>

专业级视频播放器

页内全屏播放器，支持进度条悬停缩略图、元数据探查、倍速切换、截图与循环连播：

<p align="center">

<img src="doc/screenshot/play1.png" alt="专业级全功能视频播放器" width="960" />

</p>

竖屏视频与移动端短视频连播

无论是在桌面端还是移动设备，竖屏视频均自适应居中或铺满，支持滑动手势畅快刷剧：

<p align="center">

<img src="doc/screenshot/play2.png" alt="竖屏视频氛围光播放" width="580" />

&nbsp;&nbsp;

<img src="doc/screenshot/play3.png" alt="移动端触控滑动连播" width="340" />

</p>

移动端响应式画廊

针对手机触控优化，单列自适应卡片与手势放大浏览：

<p align="center">

<img src="doc/screenshot/home1.png" alt="移动端自适应网格列表" width="460" />

</p>

dsh 设置中心原生集成

在 dsh 设置中轻松配置媒体目录、指定缓存位置并管理全局壁纸：

<p align="center">

<img src="doc/screenshot/setting.png" alt="dsh 原生设置面板" width="800" />

</p>

---

安装指南

前置要求

• dsh：要求最低版本为 v0.2.0-rc.1 及以上（0.2.0 起 settings 客户端契约变更，旧版不再兼容）
• Node.js：>= 20

标准安装

在 dsh 运行环境下，执行以下命令安装插件：

dsh plugin --profile web add dsh-reel

重启 dsh web，在浏览器打开：

http://127.0.0.1:3080/reel

安装未发布版本 / 源码本地开发

# 从 GitHub 仓库直接安装最新开发版
dsh plugin --profile web add "github:lsjspl/dsh-reel"

# 本地源码调试软链模式（修改代码后直接刷新页面生效）
dsh plugin --profile web add "link:C:\path\to\dsh-reel"

卸载插件

dsh plugin --profile web remove dsh-reel

---

配置说明

配置存放在 profile 的 cordis.patch.yml 里 reel 的 config 段——设置面板保存的也是这一层。其中媒体目录、缓存目录、全屏壁纸三项热生效，无需重启服务。

方式一：可视化界面配置（推荐）

打开 侧边栏「插件」面板 → 「已安装」分组 → dsh-reel，配置区就在包描述下方：

• 媒体目录：点击「添加目录」添加多个本地文件夹（如 D:\Photos、E:\Videos）。
• 缓存目录：指定视频封面帧与悬停预览的缓存磁盘位置。
• 全屏壁纸：配置全站默认壁纸（可填文件绝对路径或库相对 key）。

卡片顶部还有「在浏览器里打开」按钮和一行浏览页地址（带复制按钮）。地址是绝对 http URL，来自 dsh 实际服务的端口，因此桌面端与 Web 端显示的都不一样、也都点得开。

这三个字段是热生效的：保存后立即作用于正在运行的服务，不需要重启 dsh web。

[!NOTE]

配置入口是「插件」面板里的 bundle 详情页，不是「设置 → 内置插件」。后者是只读的插件清单，不提供任何配置项。

方式二：配置文件 / cordis.patch.yml

在 profile 的 cordis.patch.yml 中声明（设置面板保存的也是这一层）：

- id: reel
  config:
    roots:
      - D:\Photos
      - E:\电影
    # cacheDir: 'D:\dsh-cache'              # 缩略图与悬停动画缓存目录，留空使用系统临时目录
    # wallpaper: 'D:\Photos\wallpaper.jpg'  # 全局默认壁纸路径
    # ffmpegPath: 'D:\ffmpeg\bin\ffmpeg.exe' # 手动指定 ffmpeg 路径；留空自动探查
    # requireTrustedRequest: true           # 局域网访问信任拦截，设为 false 允许非回环直连
    # maxScanEntries: 20000                 # 单次扫描目录条目上限 (50 ~ 200000)

[!NOTE]

- 当 roots 为空时，将依次回退至环境变量 REEL_ROOTS（多路径用 ; 分隔）以及 $DSH_HOME/media。

- cacheDir 请务必放置在媒体目录之外，避免生成的缩略图文件被误扫入媒体库中。

- roots / cacheDir / wallpaper 改完即热生效；ffmpegPath / requireTrustedRequest / maxScanEntries 属于进程级决策，改动需要重启。

关于端口

插件没有自己的端口，也不需要配。 浏览页挂在 dsh 自己的 webServer 上，和 dsh 的界面同端口、同源：

运行环境 · 地址

Web（dsh web） · http://127.0.0.1:<dsh 的 --port>/reel，默认 3080

桌面端（Electron） · http://127.0.0.1:19387/reel（端口由 dsh 桌面端固定传入）

桌面端不是例外：它通过 dsh-desktop-host 启动同一套 web bundle（@deepseek-ai/dsh-base + @deepseek-ai/dsh-web-app），并向它传入 --port 19387，因此 webServer 一样存在，浏览页一样挂在上面。要换桌面端端口，改的

…(truncated)