dsh-media-web-preview
Play video and audio inside the DSH right Sidebar — including from a remote
browser, where the native Open button would otherwise launch QuickTime or
Music on the Host Mac.
The problem
DeepSeek Harness's document preview renders text, Markdown, code, images, PDF,
HTML, Office documents and spreadsheets. It has no audio or video renderer, and
mp4, mp3, wav, flac, ogg, m4a, aac, wma and opus are listed as
known binary containers with no viewer. Opening one shows:
Preview is not available for this file type yet. Open
Open asks the Host to launch the file in a native application. On the
machine running the Host that is fine; from a phone, another laptop, or a
Tailscale peer it opens a window on a screen you are not looking at.
What this plugin does
It registers two document renderers, video and audio, and draws the
browser's native player in the preview pane. A companion Host route streams the
file with HTTP Range, so seeking works and a large video is never read into
memory or into the conversation.
- Native controls — play/pause, seek, volume, fullscreen (video), and the
browser's own picture-in-picture where available.
- Seek without downloading everything —
206 Partial Content +
Content-Range; the player asks for the bytes it needs.
- Remote-browser ready — the URL is document-relative, so the same preview
works under
http://127.0.0.1:3080, a LAN address, a Tailscale MagicDNS name,
or tailscale serve on port 80. No configuration.
- Download / open in a new tab — both actions sit under the player.
- Localized — English and Simplified Chinese dictionaries.
- Zero runtime dependencies — one Host module and one browser bundle.
Formats
| Kind | Suffixes |
|---|
| Video | mp4 m4v webm ogv mov mkv avi mpg mpeg 3gp 3g2 ts m2ts |
| Audio | mp3 m4a m4b aac wav flac ogg oga opus weba aiff aif wma mid midi |
Playback is the browser's decision: Chromium plays H.264/AAC MP4, WebM, Ogg and
most audio, but usually cannot decode Matroska (.mkv) or AVI. When a codec is
unsupported the player shows an explicit message and the download link rather
than failing silently.
Install
From npm:
dsh plugin --profile web add dsh-media-web-preview
From a local directory:
dsh plugin --profile web add file:/absolute/path/to/dsh-media-web-preview
dsh plugin add records the dependency and appends the package to
dsh.profile.bundles; the package ships dsh.bundle.patch, so no manual
insert: row is needed in the profile's cordis.patch.yml.
The Host half hot-mounts into the running dsh web; refresh the page once
so the browser bundle enters the module graph. If your build only composes
plugins at boot, restart dsh web instead.
Then open any supported file in the Sidebar's Files tab. The native Open
menu stays available at the top.
Why a second file route
DSH already has GET /api/file, used by the image and Markdown previews. It
always answers with a full 200, ignores Range, and caps the response at
the attachment image limit (20 MB by default). That is fine for images and
hopeless for video: no seeking, and a large file just returns 413.
Rather than change a shared route, this plugin adds a range-capable sibling:
| /api/file | /api/media |
|---|
| Full response | 200 | 200 |
Range request | ignored (full 200) | 206 + Content-Range |
| Seeking | must download the whole file | immediate |
| Byte cap | ~20 MB | bounded by the filesystem |
| Reads | whole file buffered | 1 MiB chunks via ctx.fs.readByteRange |
Both routes sit under /api, so the Connection service applies the same Host /
Origin check and browser-cookie authentication to both.
Implementation
lib/index.js Host: GET/HEAD /api/media, Range parsing, chunked streaming
lib/client.js Browser: documentPreviews + sidebar.right.tab.document
cordis.patch.yml bundle insert row
The browser half registers through ctx.documentPreviews with
loading: 'renderer' and declares the suffixes as binary so nothing falls back
to a text preview. The player reads the absolute path from the file resource
(useResource(resourceAddress).value.absolutePath), builds a document-relative
api/media?path=… URL, and calls content.loaded(version) once to end the
loading state.
The Host half registers ctx.connection.fetch.register({ path: '/api/media', methods: ['GET', 'HEAD'] }). Requests resolve through ctx.fs, so the Host's
own file policy still applies; parseRange turns Range into a closed
interval. 416 carries bytes */<size>; HEAD returns headers only;
download=1 adds an attachment Content-Disposition.
Security
- The route lives under
/api, so it inherits the same authentication and
Host/Origin checks as every other DSH API. Unauthenticated requests get 401;
an untrusted Host gets 403.
- Only absolute paths are accepted; there is no directory listing, and nothing
bypasses the filesystem provider's resolution and access policy.
- Responses carry
Cache-Control: private, no-store and
X-Content-Type-Options: nosniff.
- No telemetry, no outbound network requests, no runtime dependencies.
Verified
- A 59.6 s MP4 plays and seeks to 40 s over a Tailscale MagicDNS URL.
- A 28.6 MB MP4 returns
413 on /api/file but 200 / 206 on /api/media.
Range: bytes=0-1023 returns 206, Content-Length: 1024,
Content-Range: bytes 0-1023/<size>.- Unauthenticated requests return
401; an invalid range returns 416 with
bytes */<size>.
- An MP3 reads its metadata and seeks to 30 s.
Compatibility
- DSH
0.2.0-rc.2 web composition, and later versions that keep providing
ctx.documentPreviews, sidebar.right.tab.document, ctx.connection.fetch
and ctx.fs.readByteRange.
- Node 22+.
- Also usable from the DSH desktop app: the in-app route is document-relative.
Scope
This plugin focuses on the stock right Sidebar and remote-browser
playback. It does not provide playlists, subtitle tracks, playback-speed
controls, or inline media cards in the chat transcript — other community
plugins cover those. Playback behaviour is whatever the browser's native
controls provide.
Development
npm test # node --test: Range parsing and MIME mapping
There is no build step. lib/client.js is a hand-written module-loader bundle
(window.__ModuleLoader__.load) that requests only react and
react/jsx-runtime, so it uses the Host's own React.
End-to-end check: with the plugin installed in a DSH web instance, open a
supported file and confirm the <video>/<audio> element reaches readyState
4 and that currentTime follows after a seek.
License
MIT © 2026 Wilson Cheng
