# dsh-media-preview

[![中文](https://img.shields.io/badge/lang-zh-CN-blue)]((./README.md)) [![English](https://img.shields.io/badge/language-English-lightgrey)](./README.en.md) [![npm](https://img.shields.io/npm/v/@xiaokaizhou/dsh-media-preview)](https://www.npmjs.com/package/@xiaokaizhou/dsh-media-preview)

> **DSH plugin: renders local audio/video paths as inline, playable previews in chat**

When an assistant message or tool result contains a local path to an audio or video file, the path is replaced inline with an `<audio controls>` or `<video controls playsInline>` player backed by the same-origin `/api/media-preview/<base64-path>` route.

Default mode is **unrestricted**: any file readable by the DSH process can be served. Permission and IO errors are returned as explicit HTTP statuses and reason strings so the browser's native `<video>` and `<audio>` error events display meaningful messages.

---

## Features

- **Range requests** (`bytes=start-end`) → `206 Partial Content` for seeking in `<video>`
- **Whole-file GET** → `200 OK`
- **Caching** → `Cache-Control: private, max-age=60`
- **Client regex** matches only `/Users|/tmp|/private/tmp|/var/folders|/var/tmp` roots with supported extensions, avoiding arbitrary URLs or paths outside the user's home/temp tree
- **UTF-8 safe** path encoding for non-ASCII folder names
- **`<style>` cleanup**: injected CSS is owned by the client Fiber and removed automatically when the plugin unloads

### Supported extensions (27)

**Audio/Video (15)**: `mp3 wav m4a flac ogg opus aac mp4 mov mkv m4v webm avi 3gp ogv`

**Images (12)**: `png jpg jpeg gif bmp webp svg tiff ico avif heic heif`

### Preview

![Demo](https://raw.githubusercontent.com/xiaokaizhou/dsh-media-preview/main/.github/demo-preview.png)

---

## Install

```bash
# from your DSH web profile
cd ~/.dsh/profiles/web

# Option 1 (recommended): dsh CLI (auto-writes bundles and cordis.patch.yml)
dsh plugin --profile web add xiaokaizhou/dsh-media-preview

# Option 2: pnpm (requires a manual step, see below)
pnpm add xiaokaizhou/dsh-media-preview
```

The profile `package.json` lives at:

- Default: `~/.dsh/profiles/web/package.json` (macOS / Linux)
- Windows: `%USERPROFILE%\.dsh\profiles\web\package.json`
- Custom `$DSH_HOME`: `$DSH_HOME/profiles/web/package.json` (override via `DSH_HOME` env)
- Multiple profiles: `~/.dsh/profiles/<profile-name>/package.json` for each

For Option 2, add this to the profile `package.json` above:

```json
"dsh": {
  "profile": {
    "bundles": [
      "media-preview"
    ]
  }
}
```

Restart `dsh web` after any source change.

---

## Limitations

- Whole-file buffered through `fs.readBytes` (cap 500 MB). Large videos can be slow to start — `<video>` needs metadata before it can render the first frame. Range requests slice the same in-memory buffer.
- No directory listing. No symlink policy beyond what `fs.stat` reports.
- The 500 MB cap is per-request, not per-session. Future versions could stream chunks via `child_process` `dd` if the cap proves too low.

---

## Failure modes

| Condition | Status | Reason |
|-----------|--------|--------|
| File missing | `404` | `not found: <errno>` |
| Permission denied | `500` | `permission denied: <errno>` |
| Is a directory | `415` | `is a directory, not a file` |
| Symlink loop | `400` | `symlink loop or too many links` |
| Path too long | `400` | `path too long` |
| Unsupported extension | `415` | `unsupported media type: <ext>` |
| File > 500 MB | `413` | `file too large: <bytes> > 524288000 cap` |
| Range invalid | `416` | `Content-Range: bytes */<total>` |

---

## License

MIT

## Sponsorship

If this plugin saves you time, you can buy me a coffee with one of the following QR codes.

<table>
  <tr>
    <td align="center">
      <img src="https://raw.githubusercontent.com/xiaokaizhou/dsh-media-preview/main/.github/wechat-pay.jpg" width="180" alt="WeChat Pay"><br>
      <strong>WeChat Pay</strong>
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/xiaokaizhou/dsh-media-preview/main/.github/alipay.jpg" width="180" alt="Alipay"><br>
      <strong>Alipay</strong>
    </td>
  </tr>
</table>