mn-video-player-v2 1.4.9

package/readme.md

@@ -0,0 +1,403 @@
+# MnVideoPlayer API 文档
+
+## 概述
+
+MnVideoPlayer 是一个基于 WebSocket 的视频播放器，支持实时播放、历史回放、对讲等功能。
+
+在项目中使用时，需要排除 `mn-video-player` 模块的预加载，以避免与 Worker文件资源获取失败。
+
+```javascript
+// 示例：Vue 项目配置
+module.exports = {
+  // ... 其他配置
+  optimizeDeps: {
+    exclude: ['mn-video-player']
+  },
+};
+```
+
+## 初始化
+
+### init(options)
+
+初始化播放器实例。
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|--------|------|
+| 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） |
+| 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',
+    port: 16202,
+    ws: 'ws',
+    userId: '1',
+    tenantId: '1',
+    accessToken: 'your-access-token',
+    phone: '13695962147',
+    channelNo: 5,
+    beginTime: '2026-01-14 13:30:00',
+    streamType: 1,
+    showControlBar:true,
+    renderType:'wasm' // 使用wasm解码 回放时建议使用decode
+});
+```
+
+## 播放控制
+
+### play(data)
+
+开始播放视频。
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|--------|------|
+| 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)
+
+切换码流类型。
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|--------|------|
+| streamType | number | 是 | 码流类型 实时：（0=主码流，1=子码流） 回放：（1=主码流，2=子码流） |
+
+**示例：**
+
+```javascript
+// 切换到主码流
+player.switchStream(0);
+
+// 切换到子码流
+player.switchStream(1);
+
+// 切换码流（使用变量）
+let streamType = 1;
+player.switchStream(streamType);
+streamType = streamType === 1 ? 0 : 1;
+```
+### controlCallback(callback)
+
+设置控制栏按钮点击回调，返回 `false` 可阻止默认行为。
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|--------|------|
+| callback | function | 是 | 回调函数，参数为操作类型 `'play' \| 'stop' \| 'audio' \| 'speedDec' \| 'speedInc' \| 'refresh' \| 'close' \| 'fullscreen'`，返回 `true` 继续默认行为，`false` 阻止 |
+
+**示例：**
+
+```javascript
+player.controlCallback((type) => {
+  console.log('控制操作:', type);
+  return true;
+});
+```
+
+## 内置控制栏
+
+播放器内置控制栏，鼠标移入视频区域时显示，位于视频底部，高度 20px。
+
+从左到右按钮依次：
+
+| 按钮 | 图标 | 说明 |
+|------|------|------|
+| 播放/暂停 | ▶ / ⏸ | 切换播放状态 |
+| 音频开关 | 🔊 / 🔇 | 切换音频开/关 |
+| 降低倍速 | < | 降低播放倍速 |
+| 当前倍速 | 0.5x ~ 32x | 显示当前倍速 |
+| 提高倍速 | > | 提高播放倍速 |
+| 刷新 | ↻ | 重新加载回放 |
+| 关闭 | ✕ | 停止播放并关闭 |
+| 全屏 | ⛶ | 全屏/退出全屏 |
+
+可通过 `showControlBar: false` 禁用内置控制栏。默认支持双击视频全屏，可通过 `player.enableDoubleClickFullscreen = false` 关闭。
+
+### 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);
+});
+```
+
+
+
+## 完整示例
+
+### 实时播放示例
+
+```javascript
+import MnVideoPlayer from 'mn-video-player'
+
+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
+});
+```
+
+### 历史回放示例
+
+```javascript
+import MnVideoPlayer from 'mn-video-player'
+
+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'
+});
+```
+
+### 完整控制示例
+
+```javascript
+import MnVideoPlayer from 'mn-video-player'
+
+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
+});
+
+```
+
+## 注意事项
+
+1. **容器元素**：初始化时必须提供一个有效的 DOM 元素作为容器
+2. **WebSocket 连接**：确保 WebSocket 服务器地址可访问
+4. **码流切换**：实时播放和历史回放都支持码流切换
+5. **时间格式**：历史回放的 beginTime 格式为 'YYYY-MM-DD HH:mm:ss'
+7. **资源清理**：停止播放时会自动清理资源
+
+
+## 浏览器兼容性
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+需要支持：
+- WebSocket API
+- Canvas API
+- Web Audio API
+- WebAssembly (WASM)