mn-video-player-v2 1.5.3 → 1.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mn-video-player-v2",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "MN Video Player for WebSocket streaming",
   "main": "./dist/mn-video-player-v2.umd.js",
   "module": "./dist/mn-video-player-v2.es.js",

package/readme.md

@@ -1,582 +1,280 @@
-# MnVideoPlayer API 文档
+# MnVideoPlayer Multi 多路视频播放器
 
 ## 概述
 
-MnVideoPlayer 是一个基于 WebSocket 的视频播放器，支持实时播放、历史回放、对讲等功能。
-
-在项目中使用时，需要排除 `mn-video-player-v2` 模块的预加载，以避免与 Worker文件资源获取失败。
+`MnVideoPlayerMulti` 在单个容器内管理**多路实时/回放视频**：统一控制（播放/暂停/倍速/音频）、多路同步播放、布局切换、窗口拖拽交换、窗口全屏、顶部通道信息栏，且每个窗口自带完整控制条（播放、码流切换、倍速、截屏、录屏、关闭、全屏等）。
 
 ```javascript
-// 示例：Vue 项目配置
-module.exports = {
-  // ... 其他配置
-  optimizeDeps: {
-    exclude: ['mn-video-player-v2']
-  },
-};
-```
-
-## 初始化
-
-### init(options)
-
-初始化播放器实例。
-
-**参数：**
+import { MnVideoPlayerMulti } from './src/index'        // 源码（开发调试）
+// import { MnVideoPlayerMulti } from 'mn-video-player-v2'  // 或发布产物
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|--------|------|
-| el | HTMLElement | 是 | 容器元素，用于显示视频 |
-| host | string | 是 | 主机地址 |
-| port | number | 是 | 端口号 |
-| ws | string | 是 | WebSocket 协议（ws 或 wss） |
-| userId | string | 是 | 用户 ID |
-| tenantId | string | 是 | 租户 ID |
-| accessToken | string | 是 | 访问令牌 |
-| phone | string | 是 | 车辆编码 |
-| channelNo | number | 是 | 通道号 |
-| beginTime | string | 否 | 开始时间（历史回放时使用） 格式为 'YYYY-MM-DD HH:mm:ss' |
-| streamType | number | 否 | 码流类型 实时：（0=主码流，1=子码流） 回放：（1=主码流，2=子码流） |
-| renderType | string | 否 | 渲染类型（wasm 或 decode） 使用wasm解码 回放时建议使用decode |
-| showControlBar | boolean | 否 | 是否显示内置控制栏（默认 true） |
-| debug | boolean | 否 | 是否显示调试信息悬浮层（时间戳、fps、延迟、网速等，每 1 秒刷新，默认 false） |
-| url | string | 否 | 直连播放地址（如 ws://host:port/mndp/stream/xxx），设置后优先于 host/port/phone/channelNo 拼接 |
-| showChannelInfo | boolean | 否 | 是否显示顶部通道信息栏（通道号/网速/设备号，默认 false） |
-| channelInfoTemplate | string | 否 | 顶部信息栏内容模板，支持占位符 `$custom`（自定义内容）/ `$code`（设备号）/ `$chn`（通道号）/ `$net`（网速，动态刷新），其余字符原样显示；未配置默认 `设备：$code CHN:$chn 网速：$net` |
-| channelInfoCustom | string | 否 | 模板中 `$custom` 占位符的内容（如摄像头名称），由使用者提供，未提供显示为空 |
-| controlItems | MnVideoPlayerControlItem[] | 否 | 控制条功能项白名单，未配置或空数组时全部显示。可选值：`play` 播放/暂停、`audio` 音频、`speed` 倍速(回放)、`refresh` 刷新(回放)、`stream` 码流切换、`snapshot` 截屏、`record` 录屏、`close` 关闭、`fullscreen` 全屏(网页或窗口全屏) |
-| enableDoubleClickFullscreen | boolean | 否 | 是否启用双击全屏（默认 true） |
-| controlCallbackFn | (type: MnVideoPlayerControlType) => boolean | 否 | 控制回调函数，返回 false 则阻止默认行为 ，返回 true 则执行默认行为 MnVideoPlayerControlType 枚举值 ： refresh 刷新  close 关闭  fullscreen 全屏/退出全屏  stream 切换码流  speedDec 降低倍速  speedInc 增加倍速 |
-
-**示例：**
-
-```javascript
-const player = new MnVideoPlayer();
-player.init({
-    el: document.getElementById('player'),
-    host: '172.16.0.150',
+const multi = new MnVideoPlayerMulti()
+multi.init({
+  el: document.getElementById('multiPlayer'),
+  layout: 4,
+  urls: [
+    { channelNo: 1, streamType: 1, channelInfoCustom: '前门摄像头' },
+    { channelNo: 4, streamType: 1 },
+  ],
+  playerOptions: {
+    host: '172.16.0.144',
     port: 16202,
     ws: 'ws',
     userId: '1',
     tenantId: '1',
     accessToken: 'your-access-token',
-    phone: '13695962147',
-    channelNo: 5,
-    beginTime: '2026-01-14 13:30:00',
+    phone: '260300380002',
+    renderType: 'wasm',
+    beginTime: '',            // 回放时间（YYYY-MM-DD HH:mm:ss）
     streamType: 1,
-    showControlBar:true,
-    renderType:'wasm' // 使用wasm解码 回放时建议使用decode
-});
+  },
+})
+multi.playAll()
 ```
 
-## 播放控制
-
-### play(data)
+> Vite 项目中使用发布产物时，建议排除依赖预加载，避免 Worker 资源获取失败：
+>
+> ```javascript
+> // vite.config.js
+> optimizeDeps: { exclude: ['mn-video-player-v2'] }
+> ```
 
-开始播放视频。
+## init(options) 配置项
 
-**参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
+| 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| streamType | number | 否 | 码流类型（0=主码流，1=子码流） |
-| beginTime | string | 否 | 开始时间（历史回放时使用） |
-**示例：**
-
-```javascript
-// 实时播放
-player.play({
-    beginTime: ''
-});
-
-// 历史回放
-player.play({
-    streamType: 0,
-    beginTime: '2026-01-14 13:30:00'
-});
-```
-
-### pause()
-
-暂停播放。
-
-**参数：** 无
-
-**示例：**
-
-```javascript
-player.pause();
-```
-
-### resume()
-
-恢复播放。
-
-**参数：** 无
-
-**说明：** 用于在暂停后恢复视频播放。
-
-**示例：**
-
-```javascript
-// 恢复播放
-player.resume();
-```
-
-### stop()
-
-停止播放。
-
-**参数：** 无
-
-**示例：**
-
-```javascript
-player.stop();
-```
-
-
-### changeSpeed(number)
-
-倍速播放 0.5-16。
-
-**参数：** number 数字
-
-**示例：**
-
-```javascript
-player.changeSpeed(2);
-```
-
-
-### switchStream(streamType)
+| el | HTMLElement | - | 多路容器元素（必填） |
+| num | number | urls 长度，缺省 1 | 初始路数 |
+| layout | number | 4 | 初始布局，取值 `1/4/6/8/9/16/24/36` |
+| urls | (string \| object)[] | [] | 每一路的配置（见「每路配置」） |
+| syncMode | boolean | false | 单路音频模式：仅允许一路发声（一路开启音频时其余路自动静音） |
+| unifiedTimer | boolean | true | 是否使用统一时钟（syncMode=true 时多路共用一个时钟调度播放节奏）；置 false 各路用自身时钟 |
+| strictSync | boolean | false | 严格同步（需 unifiedTimer=true）：任一通道断流无缓存且落后超过 `syncThreshold` 时暂停所有通道等待恢复 |
+| syncThreshold | number | 100 | 严重不同步判定阈值（ms），运行时可用 `setSyncThreshold(ms)` 动态修改 |
+| showToolbar | boolean | false | 是否显示顶部工具条（布局切换/统一控制） |
+| fullscreenMode | 'window' \| 'browser' | 'window' | 全屏方式：'window' 窗口全屏（该窗口占满整个网格，双击/按钮均走窗口全屏）；'browser' 网页全屏（requestFullscreen） |
+| playerOptions | object | - | 公共播放器参数，与每路配置合并后传给各子播放器（见下） |
+| controlCallback | (from, type) => boolean \| void | - | 通道控制监听：用户操作某一路控制条时触发；返回 `false` 可阻止该操作后续的联动/默认行为 |
 
-切换码流类型。
+## playerOptions（公共子播放器参数）
 
-**参数：**
+与每路配置合并后传给每个窗口的播放器。常用字段：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|--------|------|
-| streamType | number | 是 | 码流类型 实时：（0=主码流，1=子码流） 回放：（1=主码流，2=子码流） |
+| host / port / ws | string / number / string | 是 | WebSocket 服务器地址与协议（ws/wss） |
+| userId / tenantId / accessToken | string | 是 | 平台鉴权信息 |
+| phone | string | 是 | 设备编码 |
+| lang | string | 否 | 界面语言（如 'zh'） |
+| renderType | string | 否 | 解码方式：'wasm' / 'decode'（VideoDecoder），回放建议 decode |
+| beginTime | string | 否 | 统一回放时间（`YYYY-MM-DD HH:mm:ss`）；某路可用 `beginTime` 单独覆盖 |
+| streamType | number | 否 | 统一码流类型（实时：0=主码流/1=子码流；回放：1=主码流/2=子码流）；某路可用 `streamType` 单独覆盖 |
+| debug | boolean | 否 | 是否显示每路调试信息悬浮层（默认 false） |
+| showControlBar | boolean | 否 | 是否显示每路内置控制条（默认 true） |
+| controlItems | string[] | 否 | 控制条按钮白名单（见下），空数组/不配置表示全部显示 |
+| showChannelInfo | boolean | 否 | 是否显示顶部通道信息栏（默认 false） |
+| channelInfoTemplate / channelInfoCustom | string | 否 | 通道信息栏模板与自定义内容（见下） |
+| channelInfoPosition | 'top-left' \| 'bottom-right' | 否 | 通道信息栏位置（默认 'top-left'） |
+| onlineWorker | object | 否 | 在线解码 Worker 资源（见「特殊场景」） |
+| url | string | 否 | 直连播放地址，优先于 host/port/phone/channelNo 拼接 |
+
+### 控制条按钮（controlItems）
+
+| 值 | 按钮 | 说明 |
+|----|------|------|
+| play | ▶/⏸ | 播放/暂停 |
+| audio | 🔊/🔇 | 音频开关 |
+| speed | 倍速 | 回放时显示（- / 倍速 / +） |
+| refresh | ↻ | 刷新回放（回放时显示） |
+| stream | FHD/HD/SD | 码流切换（实时 HD/SD，回放 FHD/HD/SD） |
+| snapshot | ▲ | 截屏：当前画面导出 PNG 下载 |
+| record | ⏺/⏹ | 录屏：开始/停止（浏览器支持时输出 mp4(H.264+AAC)，否则回退 webm），录制中右上角红点"REC 录制中" |
+| close | ✕ | 关闭该路：停止播放并清为空窗口 |
+| fullscreen | ⛶/▣ | 全屏（网页全屏或窗口全屏，随 fullscreenMode） |
+
+### 顶部通道信息栏
+
+开启 `showChannelInfo: true` 后，窗口内显示通道信息栏，内容由 `channelInfoTemplate` 模板定制：
 
-**示例：**
+| 占位符 | 含义 |
+|--------|------|
+| `$custom` | 自定义内容（摄像头名称等，来自 `channelInfoCustom` 或每路配置，未提供为空） |
+| `$code` | 设备号 |
+| `$chn` | 通道号 |
+| `$net` | 网速（KB/s，播放中动态刷新） |
 
 ```javascript
-// 切换到主码流
-player.switchStream(0);
-
-// 切换到子码流
-player.switchStream(1);
-
-// 切换码流（使用变量）
-let streamType = 1;
-player.switchStream(streamType);
-streamType = streamType === 1 ? 0 : 1;
+playerOptions: {
+  showChannelInfo: true,
+  channelInfoTemplate: '$custom $code CHN:$chn $net',
+}
+// 每路也可单独覆盖：urls: [{ channelNo: 1, channelInfoCustom: '前门摄像头' }]
 ```
-### controlCallback(callback)
 
-设置控制栏按钮点击回调，返回 `false` 可阻止默认行为。
+## 每路配置（urls 元素）
 
-**参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|--------|------|
-| callback | function | 是 | 回调函数，参数为操作类型 `'play' \| 'stop' \| 'audio' \| 'speedDec' \| 'speedInc' \| 'refresh' \| 'close' \| 'fullscreen'`，返回 `true` 继续默认行为，`false` 阻止 |
-
-**示例：**
-
-```javascript
-player.controlCallback((type) => {
-  console.log('控制操作:', type);
-  return true;
-});
-```
+每路可为以下任一种：
 
-## 内置控制栏
+- **地址字符串**：`'ws://host:port/mndp/stream/xxx'`
+- **对象 `{ url }`**：同上
+- **结构化参数对象**：`{ url?, phone?, channelNo?, streamType?, beginTime?, channelInfoCustom?, ... }`，其中 `url` 可选；未给 `url` 时由公共 `host/port/phone/channelNo` 拼接
 
-播放器内置控制栏，鼠标移入视频区域时显示，位于视频底部，高度 20px。
+未配置（自动补齐的空窗口）显示虚线占位；`appendChns` 追加时会优先填充最早的空窗口。
 
-从左到右按钮依次：
+## 布局与通道上限
 
-| 按钮 | 图标 | 说明 |
-|------|------|------|
-| 播放/暂停 | ▶ / ⏸ | 切换播放状态 |
-| 音频开关 | 🔊 / 🔇 | 切换音频开/关 |
-| 降低倍速 | < | 降低播放倍速（回放时显示） |
-| 当前倍速 | 0.5x ~ 32x | 显示当前倍速（回放时显示） |
-| 提高倍速 | > | 提高播放倍速（回放时显示） |
-| 刷新 | ↻ | 重新加载回放（回放时显示） |
-| 码流切换 | FHD/HD/SD | 切换主/子码流（实时显示 HD/SD，回放显示 FHD/HD/SD） |
-| 截屏 | ▲ | 当前画面导出 PNG 下载 |
-| 录屏 | ⏺ / ⏹ | 开始/停止录制（webm 或 mp4），录制中右上角显示红点"REC 录制中" |
-| 关闭 | ✕ | 停止播放并关闭 |
-| 全屏 | ⛶ / ▣ | 网页全屏（⛶）或窗口全屏（▣，多路模式默认） |
+- 布局取值 `1/4/6/8/9/16/24/36`；`6/8` 为异形布局（1 大窗 + 其余小窗）。
+- `setLayout(路数)` 自动取**不小于**输入值的最近布局（如 10 → 16）；`setNum`/`setChns`/`appendChns` 也会自动匹配布局路数。
+- **上限 36 路**：`appendChns` 追加时，先填充最早空窗口 → 不足再新增 → 已满 36 时覆盖**最久未使用（LRU）**的窗口，轮流覆盖而非总覆盖同一个。
+- 超过布局路数的窗口会按 36 上限的多行网格排布。
 
-可通过 `showControlBar: false` 禁用内置控制栏。默认支持双击视频全屏，可通过 `player.enableDoubleClickFullscreen = false` 关闭。
+## controlCallback：通道控制监听
 
-按钮组可通过 `controlItems` 配置裁剪，例如只显示播放/码流/录屏/全屏：
+用户操作某一路控制条（播放/暂停/关闭/码流切换/全屏等）时触发，可用于外部状态同步、接管或拦截。
 
 ```javascript
-player.init({
+multi.init({
   // ...其他参数
-  controlItems: ['play', 'stream', 'record', 'fullscreen']
-});
-```
-
-### 截屏与录屏
-
-- **截屏**：点击截屏按钮将当前画面导出为 PNG 并下载，无需额外配置。
-- **录屏**：点击录屏按钮开始录制（画面 + 播放声音），再次点击停止并下载视频文件。浏览器支持 mp4（H.264+AAC）时优先输出 mp4，否则回退 webm（vp9/vp8）。
-- 录制过程中右上角显示红点"REC 录制中"提示，控制栏录制按钮变 ⏹ 高亮。
-- 播放器停止（`stop()`）时若仍在录制，会保存已录制的部分片段。
-- 多路模式下各窗口独立录制，互不影响。
-
-### enableAudio(enable)
-
-开启或关闭音频。
-
-**参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|--------|------|
-| enable | boolean | 是 | true=开启音频，false=关闭音频 |
-
-**示例：**
-
-```javascript
-// 开启音频
-player.enableAudio(true);
-
-// 关闭音频
-player.enableAudio(false);
-
-// 切换音频状态（使用变量）
-let audioEnabled = false;
-player.enableAudio(!audioEnabled);
-audioEnabled = !audioEnabled;
-```
-
-### resetCanvas()
-
-重置画布大小，使其适应容器元素的当前尺寸。
-
-**参数：** 无
-
-**说明：** 当容器元素大小改变时，调用此方法可以重新调整画布大小，确保视频显示正常。
-
-**示例：**
-
-```javascript
-// 重置画布大小
-player.resetCanvas();
-
-// 窗口大小改变时重置画布
-window.addEventListener('resize', () => {
-    player.resetCanvas();
-});
-```
-
-### timeCallBack(callback)
-
-设置视频时间回调函数。
-
-**参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|--------|------|
-| callback | function | 是 | 时间回调函数，参数为视频时间（毫秒） |
-
-**示例：**
-
-```javascript
-player.timeCallBack((time) => {
-    console.log('当前视频时间:', time);
-});
-```
-
-### netSpeedCallback 属性
-
-设置网速回调函数，播放时周期性收到网速数据。与 `timeCallBack` 不同，该回调直接赋值给 player 实例。
-
-**参数：**
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| kbPerSec | number | 网速（KB/s） |
-| frame | object | 原始网速帧对象，含 `d`（本周期字节数）、`len`（缓存帧数）等 |
-
-**示例：**
-
-```javascript
-player.netSpeedCallback = (kbPerSec, frame) => {
-    console.log('当前网速:', kbPerSec, 'KB/s');
-    console.log('缓存帧数:', frame.len);
-};
-```
-
-## 调试功能
-
-### debug 选项
-
-初始化时设置 `debug: true`，会在视频左上角悬浮显示实时调试信息（每 1 秒刷新）：
-
-- **时间**：当前播放时间戳
-- **fps**：实际出帧率
-- **延迟**：帧输出相对应播时刻的平均/最大滞后（ms），流畅时接近 0
-- **网速**：KB/s 及缓存帧数
-- **帧数 / 缓存队列**：本秒输出帧数与播放队列排队帧数
-- **模式**：wasm / VideoDecoder
-
-**示例：**
-
-```javascript
-player.init({
-    // ...其他参数
-    debug: true
-});
+  controlCallback: (from, type) => {
+    console.log('通道操作', from.id, from.opts, 'type =', type)
+    // 窗口被关闭后（内部已清空该路为占位窗口）读取最新通道列表同步外部缓存：
+    if (type === 'close') {
+      setTimeout(() => console.log(multi.getAll()), 0)
+    }
+    // 返回 false 可阻止该操作后续的联动处理（含当前路默认行为）
+  },
+})
 ```
 
-如需自行展示，也可通过 `player.timerCtrl.perfSnapshot()` 获取 fps/延迟统计（返回 `{ fps, avgLatency, maxLatency, frames, cache }`），取完后调用 `player.timerCtrl.perfReset()` 重置统计窗口。
+`type` 取值：`'play' | 'stop' | 'audio' | 'speedDec' | 'speedInc' | 'fullscreen' | 'close' | 'refresh' | 'stream0' | 'stream1' | 'stream2' | 'windowFullscreen'`
 
-## 缓存流控（TimerCtrl）
+## 常用方法
 
-`timerCtrl` 维护播放缓存队列（`timeList`），当缓存帧数超过上限时会通知 worker **暂停解析**，低于下限时通知 worker **恢复解析**，保证播放流畅的同时控制缓存空间。阈值均为配置项：
+| 方法 | 说明 |
+|------|------|
+| `setLayout(n)` | 切换布局（自动取最近不小于 n 的布局） |
+| `setNum(n)` | 设置路数（多于当前追加空位，少于当前移除多余） |
+| `createChns(num, opts)` | 重置为 num 路（用于整批重建） |
+| `setChns(opts)` | 批量替换每路配置（截取/补齐/重建播放器） |
+| `appendChns(opts)` | 追加路及配置（填充空位 → 新增 → 达上限 LRU 覆盖） |
+| `removeChns(index \| index[])` | 按索引删除窗口 |
+| `destroyChns()` | 清空所有通道（保留网格空位）；`stop()` 即调用它 |
+| `getAll()` | 返回当前所有路副本 `MnVideoMultiChn[]` |
+| `getHasChnNum()` | 已配置（可播放）的路数，不含空占位 |
+| `playChn(id)` | 播放指定路（按该路 streamType/beginTime，缺省取全局） |
+| `playAll()` | 播放全部已配置路 |
+| `pause()` / `resume()` | 统一暂停/恢复 |
+| `stop()` | 停止并清理所有路（销毁统一时钟、worker 等） |
+| `changeSpeed(spd)` | 统一倍速（0.5–16，所有路同步） |
+| `resetSpeed()` | 恢复 1x |
+| `enableAudio(enable)` | 统一音频开关；syncMode 下仅一路发声 |
+| `toggleAudio()` | 切换统一音频开关 |
+| `setSyncThreshold(ms)` | 动态修改严重不同步判定阈值 |
+| `setStrictSync(on)` | 动态开关严格同步 |
+| `swapChn(aId, bId)` | 交换两路窗口（拖拽换位内部使用） |
+| `timeCallBack(fn)` | 设置时间回调（继承自单路；统一时钟模式下回调为全局同步时间） |
+| `setSyncTime(t)` | 供统一时钟写入全局同步时间（一般内部使用） |
+
+`MnVideoMultiChn` 结构（来自 `getAll()`）：
+
+| 字段 | 说明 |
+|------|------|
+| id | 窗口自增 ID |
+| url / opts | 该路播放地址 / 每路覆盖参数（phone/channelNo/... 或 null） |
+| streamType / beginTime | 该路独立码流/回放时间（缺省回退全局） |
+| lastUsed | LRU 序号（appendChns 覆盖时用到） |
+| el / body | 窗口容器 / 播放器挂载容器 |
+| player | 该路子播放器（`MnVideoPlayer`，播放中可用） |
 
-- **maxCache**（默认 `60`）：缓存帧数上限，超过则暂停 worker 解码
-- **minCache**（默认 `10`）：缓存帧数下限，低于则恢复 worker 解码
+## 示例
 
-可通过 `player.timerCtrl` 直接调整（或修改 `TimerCtrl` 构造参数 `{ maxCache, minCache, onCacheChange }`）：
+### 通道管理
 
 ```javascript
-player.timerCtrl.maxCache = 90; // 提高缓存上限
-player.timerCtrl.minCache = 20; // 提高恢复阈值
+// 追加两个通道（自动填充空位；已满 36 时覆盖最久未使用窗口）
+multi.appendChns([
+  { phone: '13695962142', channelNo: 2, streamType: 1 },
+  { channelNo: 3 },
+])
+
+// 删除最后一路
+multi.removeChns(multi.getHasChnNum() - 1)
+
+// 读取当前通道（如持久化到 localStorage，供下次重建 urls）
+const snapshot = multi.getAll().map(c => ({
+  url: c.url,
+  phone: c.opts?.phone,
+  channelNo: c.opts?.channelNo,
+  streamType: c.streamType,
+}))
 ```
 
-销毁（`player.stop()` / `stop()`）时 `TimerCtrl` 会清空全部缓存队列以释放内存。
-
-## 顶部通道信息栏
-
-开启 `showChannelInfo: true` 后，在视频顶部显示通道信息栏（默认内容：设备号、通道号、网速）。
-
-内容可通过 `channelInfoTemplate` 模板定制，支持以下占位符：
-
-| 占位符 | 含义 |
-|--------|------|
-| `$custom` | 自定义内容（如摄像头名称，来自 `channelInfoCustom`，未提供显示为空） |
-| `$code` | 设备号 |
-| `$chn` | 通道号 |
-| `$net` | 网速（KB/s，播放中动态刷新） |
-
-其余字符原样显示。
+### 同步模式（多路帧级同步）
 
 ```javascript
-player.init({
+multi.init({
   // ...其他参数
-  showChannelInfo: true,
-  channelInfoTemplate: '$custom $code CHN:$chn $net', // 如：前门摄像头 260300380002 CHN:1 124 KB/s
-  channelInfoCustom: '前门摄像头',
-});
+  syncMode: true,        // 统一倍速 / 单路音频
+  unifiedTimer: true,    // 多路共用统一时钟，帧时间同步（< syncThreshold）
+  strictSync: true,      // 某路断流无缓存且落后时暂停所有路等待
+  syncThreshold: 100,    // 判定严重不同步的阈值（ms）
+})
+
+multi.setSyncThreshold(150)   // 运行时动态调整阈值
+multi.setStrictSync(false)    // 或临时关闭严格同步
+multi.changeSpeed(2)          // 所有路同步 2x
 ```
 
-多路模式下可在 `playerOptions` 中统一配置，也可在每路配置（`urls` 数组元素）中单独覆盖。
+> 同步模式下任一路窗口上的播放/暂停、倍速、码流等**用户操作会联动到所有路**；程序化调用（playAll/changeSpeed 等）本身即面向全体。`unifiedTimer: false` 时各路使用自身时钟，但 syncMode 的联动/单路音频/统一倍速仍生效。
 
-## 多路播放器（MnVideoPlayerMulti）
-
-多路播放器在单个容器内管理多路画面，支持布局切换、窗口拖拽交换、统一控制、多路同步播放等。
+### 窗口全屏与网页全屏
 
 ```javascript
-import { MnVideoPlayerMulti } from './src/index' // 或 dist 产物
-
-const multi = new MnVideoPlayerMulti();
 multi.init({
-  el: document.getElementById('multiPlayer'),
-  layout: 4,
-  urls: [
-    { channelNo: 1, streamType: 1, channelInfoCustom: '前门摄像头' },
-    { channelNo: 4, streamType: 1 },
-    // ... 每路可为：地址字符串 / { url } / 结构化参数对象
-  ],
-  playerOptions: { // 公共播放器参数，与每路配置合并
-    host: '172.16.0.144',
-    port: 16202,
-    ws: 'ws',
-    userId: '1',
-    tenantId: '1',
-    accessToken: '...',
-    phone: '260300380002',
-    lang: 'zh',
-    renderType: 'wasm',
-    beginTime: '2026-08-21 11:34:00',
-    streamType: 1,
-    showChannelInfo: true,
-  },
-});
+  // ...其他参数
+  fullscreenMode: 'window',   // 默认：控制条 ▣ + 双击 → 该窗口占满整个网格
+  // fullscreenMode: 'browser', // 控制条 ⛶ + 双击 → 浏览器原生网页全屏
+})
 ```
 
-### init(options) 配置项
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| el | HTMLElement | - | 多路容器元素（必填） |
-| num | number | urls 长度 | 初始路数 |
-| layout | number | 4 | 布局：1/4/6/8/9/16/24/36（6/8 为异形：1 大窗 + 其余小窗） |
-| urls | (string \| { url } \| 结构化对象)[] | [] | 每一路的配置，可含 url/phone/channelNo/streamType/channelInfoCustom 等 |
-| syncMode | boolean | false | 多路联动：统一倍速、单路音频（仅一路发声）等联动行为 |
-| unifiedTimer | boolean | true | 是否使用统一时钟（多路共用一个时钟调度播放节奏，需 syncMode=true 才生效）；置 false 时各路用自身时钟 |
-| strictSync | boolean | false | 严格同步（需统一时钟）：任一通道断流无缓存且落后超过 syncThreshold 时暂停所有通道等待恢复 |
-| syncThreshold | number | 100 | 严重不同步判定阈值（ms），运行时可用 `setSyncThreshold(ms)` 动态修改 |
-| showToolbar | boolean | false | 是否显示顶部工具条（布局切换/统一控制） |
-| fullscreenMode | 'window' \| 'browser' | 'window' | 多路模式全屏方式：'window' 窗口全屏（该窗口占满网格，双击/按钮均走窗口全屏）/ 'browser' 网页全屏 |
-| playerOptions | MnVideoPlayerOptions（不含 el） | - | 公共播放器参数，与每路配置合并后传给各子播放器 |
-
-### 常用方法
-
-| 方法 | 说明 |
-|------|------|
-| setLayout(n) / setNum(n) | 切换布局 / 设置路数（数字自动取不小于它的最近布局） |
-| setChns(chns) / appendChns(chns) / removeChns(n) / destroyChns() | 批量设置 / 追加 / 删除 / 清空通道 |
-| playAll() / pause() / resume() / stop() | 统一播放控制 |
-| changeSpeed(spd) | 统一倍速（所有路同步） |
-| enableAudio(enable) | 统一音频开关（syncMode 下仅一路发声） |
-| setSyncThreshold(ms) | 动态修改严重不同步阈值 |
-| setStrictSync(on) | 动态开关严格同步 |
-
-### 注意事项
-
-- **窗口数上限**：最多 36 路。超出后 `appendChns` 不再新增，改为覆盖**最久未使用（LRU）**的窗口。
-- **联动行为**：控制条上的播放/暂停/码流切换/刷新/关闭等用户操作会联动到所有窗口；程序化调用（如 `playAll`）不联动。
-- **窗口全屏**：多路默认窗口全屏（▣，占满整个网格而非网页全屏），退出后自动恢复原布局（含 6/8 异形布局）。
-
+- 窗口全屏退出后自动恢复原布局（含 6/8 异形）。
+- 若某路正在窗口全屏，切换布局/销毁时会自动退出全屏。
 
-
-## 完整示例
-
-### 实时播放示例
+### 播放/暂停/恢复
 
 ```javascript
-import MnVideoPlayer from 'mn-video-player-v2'
-
-const player = new MnVideoPlayer();
-
-// 初始化播放器
-player.init({
-    el: document.getElementById('player'),
-    host: '172.16.0.150',
-    port: 16202,
-    ws: 'ws',
-    userId: '1',
-    tenantId: '1',
-    accessToken: 'your-access-token',
-    phone: '13695962147',
-    channelNo: 5
-});
-
-// 开始播放
-player.play({
-    streamType: 0
-});
+multi.playAll()      // 播放全部已配置路（空占位窗口跳过）
+multi.pause()        // 全部暂停
+multi.resume()       // 全部恢复
+multi.stop()         // 停止并清理（保留网格空位）
+multi.playChn(3)     // 只播放指定 id 的路
 ```
 
-### 历史回放示例
-
-```javascript
-import MnVideoPlayer from 'mn-video-player-v2'
-
-const player = new MnVideoPlayer();
-
-// 初始化播放器
-player.init({
-    el: document.getElementById('player'),
-    host: '172.16.0.150',
-    port: 16202,
-    ws: 'ws',
-    userId: '1',
-    tenantId: '1',
-    accessToken: 'your-access-token',
-    phone: '13695962147',
-    channelNo: 5,
-    renderType:"decode" 
-});
-
-// 历史回放
-player.play({
-    streamType: 0,
-    beginTime: '2026-01-14 13:30:00'
-});
-```
+## 特殊场景：file:// 直开等环境的解码 Worker（onlineWorker）
 
-### 完整控制示例
+多路播放器各窗口的解码 Worker 默认与页面同源部署（相对路径加载 mn-common-c.js / mn-media-v2.js / mn-media-v2.wasm）。当插件运行在 `file://` 直开、离线壳等无法按相对路径加载的环境时，可通过 `playerOptions.onlineWorker` 传入这三份构建产物的**在线地址**（须为同一版本、允许 CORS），播放器将以「内置 worker 源码 + Blob URL」方式创建解码 Worker：
 
 ```javascript
-import MnVideoPlayer from 'mn-video-player-v2'
-
-const player = new MnVideoPlayer();
-
-// 初始化播放器
-player.init({
-    el: document.getElementById('player'),
-    host: '172.16.0.150',
-    port: 16202,
-    ws: 'ws',
-    userId: '1',
-    tenantId: '1',
-    accessToken: 'your-access-token',
-    phone: '13695962147',
-    channelNo: 5
-});
-
-// 播放按钮
-document.getElementById('playBtn').addEventListener('click', () => {
-    player.play({
-        streamType: 0,
-        beginTime: '2026-01-14 13:30:00'
-    });
-});
-
-// 暂停按钮
-document.getElementById('pauseBtn').addEventListener('click', () => {
-    player.pause();
-});
-
-// 停止按钮
-document.getElementById('stopBtn').addEventListener('click', () => {
-    player.stop();
-});
-
-// 切换码流按钮
-let streamType = 1;
-document.getElementById('switchBtn').addEventListener('click', () => {
-    player.switchStream(streamType);
-    streamType = streamType === 1 ? 0 : 1
-});
-
-// 音频开关按钮
-let audioEnabled = false;
-document.getElementById('playAudioBtn').addEventListener('click', () => {
-    player.enableAudio(!audioEnabled);
-    audioEnabled = !audioEnabled
-});
-
+playerOptions: {
+  onlineWorker: {
+    common: 'https://cdn.example.com/mn-common-c.js',
+    media:  'https://cdn.example.com/mn-media-v2.js',
+    wasm:   'https://cdn.example.com/mn-media-v2.wasm',
+  },
+}
 ```
 
-## 注意事项
+> 说明：地址缺失或创建失败会自动回退内置加载方式；宿主环境若完全禁止创建 Worker（含 Blob），则该模式也无法生效。
 
-1. **容器元素**：初始化时必须提供一个有效的 DOM 元素作为容器
-2. **WebSocket 连接**：确保 WebSocket 服务器地址可访问
-4. **码流切换**：实时播放和历史回放都支持码流切换
-5. **时间格式**：历史回放的 beginTime 格式为 'YYYY-MM-DD HH:mm:ss'
-7. **资源清理**：停止播放时会自动清理资源
+## 注意事项
 
+1. **容器元素**：init 时必须提供有效 DOM 元素；重建实例前先调用旧实例的 `stop()` 并清空容器。
+2. **联动范围**：控制条上的用户操作（播放/暂停/码流切换/关闭/全屏等）在 syncMode 下联动全体；程序化 API 不重复联动。
+3. **资源清理**：`stop()`/`destroyChns()` 会停止所有路播放器、销毁统一时钟并释放 worker 等资源；单路关闭（✕）只清空该窗口。
+4. **网速/调试**：各窗口独立统计，可通过 `multi.getAll()[i].player` 访问对应子播放器的 `netSpeedCallback`/`timerCtrl` 等。
+5. **录屏声音**：录屏时同步录制该路播放声音；多路各窗口独立录制。
 
 ## 浏览器兼容性
 
-- Chrome 90+
-- Firefox 88+
-- Safari 14+
-- Edge 90+
-
-需要支持：
-- WebSocket API
-- Canvas API
-- Web Audio API
-- WebAssembly (WASM)
+- Chrome 90+ / Edge 90+ / Firefox 88+ / Safari 14+
+- 需要支持：WebSocket、Canvas、Web Audio、WebAssembly（WASM 解码时）、VideoDecoder（decode 解码时）