# dsh-media-preview

给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 加视频 / 音频预览：在右侧栏的文档预览里直接播放 `mp4`、`mov`、`mkv`、`webm` 以及 `mp3`、`flac`、`wav`，不再出现「该格式文件暂时无法预览」。

中文（本文件）| [English](README.md)

## 为什么需要它

内置预览为文本、代码、Markdown、图片、PDF、HTML、Office、表格都注册了渲染器，却把视频 / 音频后缀列进「已知二进制容器、无渲染器」清单——所以打开视频只显示一个图标和一行字。本插件接管这些后缀，画出浏览器原生播放器，数据来自一条**带鉴权、支持 HTTP `Range` 的流式路由**：能拖进度、2 GB 的文件也不会整个读进内存或对话上下文。

## 安装

```sh
dsh plugin --profile <profile> add dsh-media-preview
```

然后重启桌面端（profile patch 在启动时读取）。无需任何配置，默认后缀已覆盖常见格式。

验证是否生效：从「文件」标签页打开任意 `.mp4`，右侧栏应出现播放器而不是「暂时无法预览」。

![视频预览](docs/video-preview.png)
![音频预览](docs/audio-preview.png)

## 它做了什么

- **渲染器** — 注册两个文档预览实现：`dsh-media-preview/media`（视频后缀）与 `dsh-media-preview/audio`（音频后缀），优先级 `extension`，`loading: 'renderer'`，后缀同时声明为二进制，因此不再提供「纯文本」兜底。
- **播放器** — 原生 `<video>` / `<audio>` 元素，带浏览器自带控件。视频用 `object-fit: contain` 装进自适应框里，竖屏、横屏都一屏完整显示（多出来的是黑边），不会撑出预览区；下方有 **倍速**（1× → 1.25× → 1.5× → 1.75× → 2× → 0.5× → 0.75× 循环切换）、**循环**，视频另有 **全屏** 与 **画中画**。倍速/循环对音频同样生效，并按浏览器记住选择。音频显示文件卡片（文件名、大小、播放器）。body 会把 `loaded` / `failed` 回报给预览所有者，标签页的加载态才能收尾。
- **流式路由** — Host 端 `GET|HEAD /api/media-preview?path=<绝对路径>`：`200` + `Accept-Ranges: bytes`；`206` + `Content-Range`（单窗口）；`416` + `Content-Range: bytes */size`；`HEAD` 只回头。实现上每次通过 `ctx.fs.readByteRange` 读一块（`chunkBytes`，默认 1 MiB），内存占用恒定。
- **鉴权** — 路由挂在 `/api/` 下，连接服务的 Host/Origin 防护与浏览器会话 cookie 校验在进入 handler 之前执行，跨站页面无法借它读本地文件。

## 配置

配置项在 `media-preview` 这一行（设置 → 插件，或 profile patch）。每个键都有代码侧默认值，只写一部分也合法。

| 键 | 默认值 | 含义 |
|---|---|---|
| `enabled` | `true` | 是否挂载路由。关掉后渲染器仍在，但不传字节（`503`）。 |
| `routePath` | `/api/media-preview` | 路由路径。必须以 `/api/` 开头，否则回退到默认值，保证鉴权防线不失效。 |
| `maxBytes` | `2147483648`（2 GiB） | 允许流式传输的最大文件，更大的回 `413`。 |
| `chunkBytes` | `1048576` | 每次范围读的字节数。 |
| `videoExtensions` | `mp4, m4v, mov, webm, ogv, ogg, mkv, avi, wmv, flv, 3gp, ts, m2ts, mts` | 视频播放器接管的后缀。 |
| `audioExtensions` | `mp3, wav, flac, m4a, aac, oga, opus, weba, wma, aiff, aif` | 音频播放器接管的后缀。 |

浏览器半在 `lib/client.js` 里另存一份同样的后缀表，改一侧要同步改另一侧。路由路径由 Host 以 `__DSH_MEDIA_PREVIEW_CONFIG__` 注入页面，配置值不会和播放器用的 URL 走偏。

## 能播什么

能不能解码取决于浏览器本身，不取决于本插件。Chromium / Electron 能播 MP4（H.264/AAC）、WebM（VP8/VP9/Opus）、Ogg 以及多数音频格式；**Matroska（`.mkv`）与 AVI 在 Chromium 里通常解不出来**，此时播放器会显示「浏览器不支持这个编码」，预览头部的「打开」仍可交给系统播放器。要可靠播放，先重封装成 MP4/WebM。

## 结构

```
lib/index.js    Host 入口：name / inject / Config / apply（路由 + 索引注入）
lib/config.js   默认值与归一化，不 import 宿主包（可单测）
lib/schema.js   schemastery Config，供 loader 与设置页
lib/range.js    HTTP Range 解析，纯函数
lib/mime.js     后缀 → media type
lib/route.js    带鉴权的流式 handler（fetch 形状、分块）
lib/client.js   浏览器 bundle：渲染器、body、样式、文案
test/           node --test：range、config、route、适配层挂载、客户端 bundle
scripts/        无头浏览器 E2E 与 HTTP 探针
```

浏览器半是手写的 module-loader bundle（`window.__ModuleLoader__.load({ id, factory })`），只向模块表要 `react` 与 `react/jsx-runtime`，因此既不需要构建链，也不可能和宿主的 React 副本走偏。

## 开发

```sh
node --test test/*.test.js
```

端到端：起一个装了本插件的宿主，然后

```sh
node scripts/e2e-browser.mjs --base http://127.0.0.1:<port> --token <token> --video "<视频绝对路径>"
```

本机 Chromium 版本不匹配时用 `E2E_BROWSER_CHANNEL=msedge` 走系统 Edge。

## 已知限制

- 一次只处理一个字节窗口；多窗口 `Range` 头回 `416`（浏览器对媒体元素只会要一个窗口）。
- `.mkv`、`.avi`、`.wmv`、`.flv` 会被接管并列出，但 Chromium 解不了，插件显示播放器的错误态而不是假装能播。
- 没有自建播放列表、字幕轨、倍速控件——这些交给原生控件。

## 许可

MIT