dock-media

English

DSH 生态中最好用的媒体播放插件 —— 没有之一。 MP3、WAV、FLAC、M4A 等纯音频用音乐播放器呈现；MP4、WebM、MOV 等视频支持全屏播放。播放不走整文件 base64，而是**流式（HTTP Range / 206 分片）**读取，大文件也能秒开、随时拖动进度条。

dock 系列的媒体播放插件：为 dock-files 文件域注册 media 文件查看器（音频 + 视频扩展名）与对应的编辑器区视图，通过自己的 /dock-media/source 主机路由流式传输媒体字节（支持 Range 分段请求，便于 <audio> / <video> 元素边看边下、拖拽定位）。

效果预览

功能

• 双模式播放：纯音频（MP3/WAV/OGG/OPUS/FLAC/AAC/M4A/WebA…）进入音乐播放器（旋转唱片 + 均衡器动画 + 自定义走带条）；视频（MP4/M4V/WebM/MOV/MKV/OGV/AVI/TS/3GP…）进入原生视频播放器，带全屏播放。
• 流式传输：不同于 dock-images 的整文件 base64，dock-media 通过 /dock-media/source 直接流式返回文件字节，支持 HTTP Range → 206 Partial Content + Accept-Ranges: bytes，因此大文件也能秒开、拖拽进度条、边下边播，不会把整个文件读进内存。
• 全屏：视频与音乐播放器都支持一键全屏（浏览器 Fullscreen API，容器全屏；不可用时退化为固定 inset:0 覆盖层）。全屏时头部变为半透明悬浮条，沉浸式观看。
• 音乐播放器：播放/暂停、拖动进度、当前/总时长、音量、静音、播放速度（0.5x–2x）、单曲循环；旋转唱片 + 均衡器随播放状态动效。
• 格式徽章与大小：/dock-media/probe 返回文件大小与媒体种类，头部实时显示 .MP3/.MP4 徽章与大小。
• 优雅降级：浏览器无法解码的封装/编码（如 AVI、FLV、WMV、MPG、MIDI、WMA）会给出提示，而不是黑屏/转圈。
• 安全渲染：媒体通过 src 交给原生 <audio>/<video> 解码，绝不做 innerHTML / 危险 DOM 注入。

支持格式

类别	扩展名
音频	mp3, wav, ogg, oga, opus, flac, aac, m4a, weba, wma, mid, midi
视频	mp4, m4v, webm, mov, mkv, ogv, avi, mpg, mpeg, flv, wmv, ts, 3gp

说明：浏览器能否解码头由解码器决定，与容器/扩展名无必然关系。mp4(H.264)、webm(VP8/VP9/AV1)、mp3、flac、ogg 等主流编码基本都能播；avi、flv、wmv、mpg 等旧封装在多数浏览器里无法解码，dock-media 会如实提示（建议用系统播放器）。

依赖

依赖	类型	说明
dock >= 0.1.0	peer（必需）	工作台外壳：编辑器区视图、浮窗、ctx.workbench 由它提供
dock-files >= 0.1.0	peer（必需）	文件域服务：dock-media 作为 media 查看器被分发打开
DSH Web 环境	运行时	必需，客户端平台为 Web
cordis ^4.0.0-rc.7	peer	插件框架（DSH 自带）
react ^18.2.0	peer（可选）	客户端渲染需要；未提供时查看器 UI 不激活

可选搭档：与 dock-editor、dock-markdown、dock-images 等查看器共存，按扩展名各自接管对应文件类型。

安装

需要 dock 与 dock-files：

dsh plugin add github:AKS1st/dock
dsh plugin add github:AKS1st/dock-files
dsh plugin add github:AKS1st/dock-media

安全

/dock-media 路由只接受受信任来源（回环地址 / trustedHosts + 同源检查）的请求；source 为 GET（流式），probe 为 POST（元数据）。读取路径只要求是绝对路径、不限定会话工作区——对话上下文可能提及工作区外的媒体（如 ~/Music/...、~/.dsh/skills/...），播放器可打开它们；路径只读、绝不写回。

License

MIT