# 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/media-preview)](https://www.npmjs.com/package/media-preview)

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

When an assistant message or tool result contains a local media path or an online http(s) media link, it is replaced inline with a playable `<audio>` / `<video controls playsInline>` / `<img>` element. Local paths are proxied through `/api/media-preview/<base64-path>`; online links use the direct URL.

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.

## Companion plugins

Part of a **generate → orchestrate → preview** loop with two sibling DSH plugins by the same author:

| Plugin | Role | npm |
|---|---|---|
| [dsh-llm-multimodal](https://github.com/xiaokaizhou/dsh-llm-multimodal) | Produces the media: `generate_image` / `generate_video` / `generate_vision` / `generate_tts` / `generate_music` / `generate_text` | [npm: dsh-llm-multimodal](https://www.npmjs.com/package/dsh-llm-multimodal) |
| [dsh-media-studio](https://github.com/xiaokaizhou/dsh-media-studio) | Orchestrates it: multi-project infinite canvas, asset library, global search, soft references | [npm: dsh-media-studio](https://www.npmjs.com/package/dsh-media-studio) |

**Where each one renders.** The two plugins serve media over different routes for different surfaces, and they complement rather than duplicate each other:

- **This plugin** handles the **chat surface**: a `file://` path or `http(s)` link in an assistant message or tool result becomes an inline player. It serves any DSH-readable file (`unrestricted` mode) at `/api/media-preview/<base64-path>`.
- **media-studio** handles the **canvas surface**: files inside a project are served at `/api/media-studio/media-file` with `ETag` / `304` and `Cache-Control: private, max-age=86400, immutable`, plus a Service Worker that pre-heats video/audio headers for near-zero-buffer playback on the canvas.

Since `dsh-llm-multimodal` writes generated media into the active media-studio project by default, installing all three means: generate → see it on the canvas → read the `file://` path in chat as a player. Install order does not matter; none of the three has a hard dependency on another.

---

## 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)

Both local paths and online links are supported:

**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`

Online examples: `https://example.com/clip.mp4`, `https://cdn.site.com/img/photo.webp`

### 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 from the npm registry
dsh plugin --profile web add media-preview

# Option 2: dsh CLI from GitHub
dsh plugin --profile web add xiaokaizhou/dsh-media-preview

# Option 3: pnpm from the registry (requires a manual step, see below)
pnpm add 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>