ht-player

一个基于 Vue 3 的视频监控播放器组件，支持预览、回放、对讲等功能。该组件专为视频监控场景设计，提供了丰富的控制功能和灵活的配置选项。

特性

• 🎥 支持多路视频预览
• 🔄 支持视频回放
• 🎤 支持双向对讲
• 📸 支持视频抓图
• 📹 支持视频录制
• 🔊 支持音量控制
• 🖥️ 支持多分屏显示
• 📱 支持移动端适配
• 🎨 支持自定义控制面板
• 🚀 支持自动播放

安装

# 使用 npm
npm install ht-player-demo

# 使用 yarn
yarn add ht-player-demo

# 使用 pnpm
pnpm add ht-player-demo

快速开始

基础使用

<template>
  <div class="player-container">
    <ht-player
      ref="playerRef"
      :urls="{
        realplay: 'ws://your-realplay-url',
        talk: 'wss://your-talk-url',
        playback: 'wss://your-playback-url'
      }"
      :show-controls="true"
      :autoplay="true"
    />
  </div>
</template>

<script setup>
import HtPlayer from 'ht-player-demo'
import 'ht-player-demo/dist/style.css'
import { ref, onMounted, onBeforeUnmount } from 'vue'

const playerRef = ref(null)

onMounted(() => {
  // 确保播放器 JS 文件已加载
  if (!window.JSPlugin) {
    console.error('播放器JS文件未加载，请检查')
    return
  }
  console.log('播放器已加载')
})

onBeforeUnmount(() => {
  // 组件销毁前停止所有播放
  playerRef.value?.stopAllPlay()
})
</script>

<style scoped>
.player-container {
  width: 100%;
  height: 600px;
  background: #000;
}
</style>

Props 配置

| 属性 | 类型 | 默认值 | 必填 | 说明 | |------|------|--------|------|------| | urls | Object | - | 是 | 播放地址配置，包含 realplay、talk、playback 三个地址 | | showControls | Boolean | false | 否 | 是否显示控制面板 | | width | String/Number | '100%' | 否 | 播放器宽度 | | height | String/Number | '100%' | 否 | 播放器高度 | | autoplay | Boolean | false | 否 | 是否自动播放，设为 true 时会在播放器初始化完成后自动调用预览方法 |

初始化回调

播放器提供了多个初始化相关的回调函数，用于监听播放器的不同状态：

| 回调函数 | 说明 | 参数 | 示例 | |----------|------|------|------| | onInit | 播放器初始化完成回调 | player: 播放器实例 | onInit: (player) => { console.log('播放器初始化完成', player) } | | onReady | 播放器准备就绪回调 | player: 播放器实例 | onReady: (player) => { console.log('播放器准备就绪', player) } | | onError | 播放器错误回调 | error: 错误信息 | onError: (error) => { console.error('播放器错误:', error) } | | onLoad | 播放器加载完成回调 | player: 播放器实例 | onLoad: (player) => { console.log('播放器加载完成', player) } | | onDestroy | 播放器销毁回调 | - | onDestroy: () => { console.log('播放器已销毁') } |

使用示例：

<template>
  <div class="player-container">
    <ht-player
      ref="playerRef"
      :urls="urls"
      :on-init="onInit"
      :on-ready="onReady"
      :on-error="onError"
      :on-load="onLoad"
      :on-destroy="onDestroy"
    />
    <div class="control-buttons">
      <button @click="startPreview">开始预览</button>
      <button @click="stopPreview">停止预览</button>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import HtPlayer from 'ht-player'
import 'ht-player/dist/style.css'

// 播放器配置
const urls = {
  realplay: 'ws://your-realplay-url',
  talk: 'wss://your-talk-url',
  playback: 'wss://your-playback-url'
}

// 播放器引用
const playerRef = ref(null)
const playerInstance = ref(null)

// 播放器初始化完成回调
const onInit = (player) => {
  console.log('播放器初始化完成')
  playerInstance.value = player
}

// 播放器准备就绪回调
const onReady = (player) => {
  console.log('播放器准备就绪')
  // 可以在这里进行一些初始化后的操作
  // 例如：设置分屏、开始预览等
  player.JS_ArrangeWindow(2) // 设置为2x2分屏
}

// 播放器错误回调
const onError = (error) => {
  console.error('播放器错误:', error)
  // 可以在这里添加错误提示UI
}

// 播放器加载完成回调
const onLoad = (player) => {
  console.log('播放器加载完成')
  // 可以在这里进行一些加载完成后的操作
  // 例如：开始预览、设置音量等
  player.JS_OpenSound() // 开启声音
  player.JS_SetVolume(0, 50) // 设置音量为50
}

// 播放器销毁回调
const onDestroy = () => {
  console.log('播放器已销毁')
  // 可以在这里进行一些清理操作
}

// 使用播放器实例的方法
const startPreview = () => {
  if (playerInstance.value) {
    const index = playerInstance.value.currentWindowIndex
    playerInstance.value.JS_Play(urls.realplay, { playURL: urls.realplay, mode: 0 }, index)
  }
}

// 停止预览
const stopPreview = () => {
  if (playerInstance.value) {
    const index = playerInstance.value.currentWindowIndex
    playerInstance.value.JS_Stop(index)
  }
}
</script>

<style scoped>
.player-container {
  width: 100%;
  height: 600px;
  background: #000;
}

.control-buttons {
  margin-top: 16px;
  display: flex;
  gap: 8px;
}

button {
  padding: 8px 16px;
  border: 1px solid #d9d9d9;
  border-radius: 4px;
  background: white;
  cursor: pointer;
}

button:hover {
  border-color: #1890ff;
  color: #1890ff;
}
</style>

方法

分屏控制

<script setup>
const playerRef = ref(null)

// 设置分屏数量（1x1、2x2、3x3、4x4）
const setSplitScreen = (num) => {
  playerRef.value.splitNum = num
  playerRef.value.arrangeWindow()
}

// 整体全屏
const toggleFullScreen = () => {
  playerRef.value.wholeFullScreen()
}
</script>

预览控制

<script setup>
const playerRef = ref(null)

// 开始预览
const startPreview = async () => {
  try {
    await playerRef.value.realplay()
  } catch (error) {
    console.error('预览失败:', error)
  }
}

// 停止预览
const stopPreview = () => {
  playerRef.value.stopPlay()
}

// 停止所有窗口预览
const stopAllPreview = () => {
  playerRef.value.stopAllPlay()
}
</script>

对讲控制

<script setup>
const playerRef = ref(null)

// 开始对讲
const startTalk = async () => {
  try {
    await playerRef.value.talkStart()
  } catch (error) {
    console.error('对讲失败:', error)
  }
}

// 停止对讲
const stopTalk = () => {
  playerRef.value.talkStop()
}
</script>

回放控制

<script setup>
const playerRef = ref(null)

// 开始回放
const startPlayback = async (startTime, endTime) => {
  try {
    await playerRef.value.playbackStart(startTime, endTime)
  } catch (error) {
    console.error('回放失败:', error)
  }
}

// 暂停回放
const pausePlayback = () => {
  playerRef.value.playbackPause()
}

// 恢复回放
const resumePlayback = () => {
  playerRef.value.playbackResume()
}

// 停止回放
const stopPlayback = () => {
  playerRef.value.stopPlay()
}
</script>

声音控制

<script setup>
const playerRef = ref(null)

// 开启声音
const openSound = () => {
  playerRef.value.openSound()
}

// 关闭声音
const closeSound = () => {
  playerRef.value.closeSound()
}

// 设置音量（0-100）
const setVolume = (volume) => {
  playerRef.value.setVolume(volume)
}
</script>

录制与抓图

<script setup>
const playerRef = ref(null)

// 抓图
const capture = () => {
  playerRef.value.capture()
}

// 开始录制
const startRecord = (format = 'MP4') => {
  playerRef.value.recordStart(format)
}

// 停止录制
const stopRecord = () => {
  playerRef.value.recordStop()
}
</script>

事件

组件支持以下事件：

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | ready | 播放器准备就绪 | - | | error | 播放器错误 | error: 错误信息 | | play | 开始播放 | - | | pause | 暂停播放 | - | | stop | 停止播放 | - | | fullscreen | 全屏状态改变 | isFullscreen: 是否全屏 |

使用示例：

<template>
  <ht-player
    ref="playerRef"
    :urls="urls"
    @ready="onReady"
    @error="onError"
    @play="onPlay"
    @pause="onPause"
    @stop="onStop"
    @fullscreen="onFullscreen"
  />
</template>

<script setup>
const onReady = () => {
  console.log('播放器准备就绪')
}

const onError = (error) => {
  console.error('播放器错误:', error)
}

const onPlay = () => {
  console.log('开始播放')
}

const onPause = () => {
  console.log('暂停播放')
}

const onStop = () => {
  console.log('停止播放')
}

const onFullscreen = (isFullscreen) => {
  console.log('全屏状态:', isFullscreen)
}
</script>

最佳实践

1. 错误处理

建议对所有播放器操作进行错误处理：

<script setup>
const handlePlayerOperation = async (operation) => {
  try {
    await operation()
  } catch (error) {
    console.error('操作失败:', error)
    // 可以在这里添加错误提示UI
  }
}
</script>

2. 资源管理

确保在组件销毁时正确释放资源：

<script setup>
onBeforeUnmount(() => {
  // 停止所有播放
  playerRef.value?.stopAllPlay()
  // 关闭声音
  playerRef.value?.closeSound()
  // 停止录制
  playerRef.value?.recordStop()
})
</script>

3. 性能优化

• 使用 v-show 而不是 v-if 来控制播放器的显示/隐藏
• 在不需要时及时停止播放和释放资源
• 合理使用分屏数量，避免同时打开过多视频流

注意事项

1. 播放地址配置

   • 确保提供的播放地址可访问
   • 建议在使用前先测试地址可用性
   • 注意区分 ws 和 wss 协议

2. 浏览器兼容性

   • 建议使用现代浏览器（Chrome、Firefox、Safari、Edge 等）
   • 移动端仅支持 1x1 和 2x2 分屏模式

3. 资源加载

   • 确保播放器相关的 JS 文件已正确加载
   • 建议在 index.html 中预加载播放器文件

4. 性能考虑

   • 避免同时打开过多视频流
   • 及时释放不需要的资源
   • 合理使用录制和抓图功能

5. 安全建议

   • 使用 HTTPS/WSS 协议传输视频流
   • 注意保护播放地址等敏感信息
   • 实现适当的访问控制

常见问题

1. Q: 播放器无法加载怎么办？ A: 检查播放器 JS 文件是否正确加载，确保网络连接正常。

2. Q: 视频流无法播放怎么办？ A: 检查播放地址是否正确，确认服务器是否正常运行。

3. Q: 对讲功能无响应怎么办？ A: 检查麦克风权限是否已授权，确认对讲服务器是否正常。

4. Q: 录制文件保存在哪里？ A: 录制文件默认保存在浏览器的下载目录，文件名包含时间戳。

更新日志

v1.0.0

• 初始版本发布
• 支持基础播放功能
• 支持分屏控制
• 支持对讲功能
• 支持回放功能

贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。

许可证

MIT License