vue3-easyplayer-pro

基于 EasyPlayerPro.js 的 Vue 3 播放器组件，支持 HTTP-FLV、HLS、WebRTC 等多种流媒体协议。

功能特性

  • 支持多种流媒体协议：HTTP-FLV、HLS、WebRTC、RTSP 等
  • 支持多种解码模式：MSE、WCS、WASM、WebGPU、GPU 硬解码
  • 支持 HEVC/H.265 视频解码
  • 支持直播和点播两种模式
  • 支持 PTZ 云台控制
  • 支持视频水印
  • 支持截图、录屏、全屏等常用功能
  • 支持清晰度切换
  • 支持语音对讲（需 PTZ 支持）
  • 支持 TypeScript

安装

npm install vue3-easyplayer-pro

引入方式

全局引入（作为 Vue 插件）

import { createApp } from 'vue'
import App from './App.vue'
import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

const app = createApp(App)
app.use(Vue3EasyPlayerPro)
app.mount('#app')

局部引入（按需引入）

import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

export default {
  components: {
    Vue3EasyPlayerPro
  }
}

组件使用前置条件

使用此组件前，需要先在项目中引入 EasyPlayerPro.js 库：

  1. 将 node_modules/vue3-easyplayer-pro/dist/lib 目录下的文件拷贝到项目中（通常拷贝到 public 目录下）
  2. 在 index.html 中引入 EasyPlayerPro.js 文件：
<script src="/EasyPlayer-pro.js"></script>

基础使用

Vue 单文件组件

<template>
  <Vue3EasyPlayerPro
    :url="videoUrl"
    :is-live="true"
    @ready="onPlayerReady"
    @error="onPlayerError"
  />
</template>

<script setup lang="ts">
import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

const videoUrl = 'http://example.com/live.flv'

const onPlayerReady = (player) => {
  console.log('播放器已就绪', player)
  player.play()
}

const onPlayerError = (error) => {
  console.error('播放错误', error)
}
</script>

通过 ref 调用方法

<template>
  <div>
    <Vue3EasyPlayerPro ref="playerRef" :url="videoUrl" />
    <button @click="handlePlay">播放</button>
    <button @click="handlePause">暂停</button>
    <button @click="handleScreenshot">截图</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

const playerRef = ref<InstanceType<typeof Vue3EasyPlayerPro>>()

const handlePlay = () => {
  playerRef.value?.play()
}

const handlePause = () => {
  playerRef.value?.pause()
}

const handleScreenshot = () => {
  const data = playerRef.value?.screenshot()
  console.log('截图数据', data)
}
</script>

配置说明

Props 属性

属性类型默认值说明
urlstring''视频地址
is-livebooleantrue是否为直播模式
has-audiobooleantrue是否解析音频
is-mutebooleanfalse是否静音
stretchbooleantrue是否拉伸视频以填充容器
posterstring''视频封面图片地址
buffer-timenumber1最小缓冲时长（秒），播放器会自动消除延迟
load-time-outnumber10视频加载超时时间（秒）
load-time-replaynumber3重连次数，-1 表示一直重连
autoplaybooleanfalse是否自动播放

解码模式配置

属性类型默认值说明
MSEbooleanfalse是否使用 MSE 模式解码
WCSbooleanfalse是否使用 WCS 模式解码
WASMbooleanfalse是否使用 WASM 模式解码
WASMSIMDbooleanfalse是否使用 WASM SIMD 模式解码（适合高分辨率）
gpu-decoderbooleanfalse是否启用 GPU 硬解码
is-flvbooleanfalse是否强制使用 FLV 解码
webGPUbooleanfalse是否使用 WebGPU 渲染
canvas-renderbooleanfalse是否使用 Canvas 渲染容器

流媒体类型配置

属性类型默认值说明
is-rtc-s-r-Sbooleanfalse是否为 SRS 类型流媒体
is-rtc-z-l-Mbooleanfalse是否为 ZLM 类型流媒体
is-flowbooleanfalse是否为裸流模式

水印配置

属性类型默认值说明
watermarkWatermarkConfig见下方水印配置
full-watermarkFullWatermarkConfig见下方全屏水印配置
WatermarkConfig 水印配置
{
  text: {
    content: '',      // 水印文本内容
    color: '',        // 水印颜色
    opacity: 0,      // 水印透明度 (0-1)
    fontSize: ''      // 水印字体大小
  },
  right: 0,           // 距离容器右侧的距离 (px)
  top: 0              // 距离容器顶部的距离 (px)
}
FullWatermarkConfig 全屏水印配置
{
  text: '',           // 水印文本内容
  angle: '',          // 水印旋转角度
  color: '',          // 水印颜色
  fontSize: '',       // 水印字体大小
  opacity: ''         // 水印透明度
}

其他配置

属性类型默认值说明
qualitystring[]['普清', '高清', '超清', '4K', '8K']清晰度列表
default-qualitystring''默认显示的清晰度，不设置则显示第一个
ptz-configPtzConfig{ ptz: true, ptzMore: true }PTZ 云台控制配置
btnsBtnsConfig{}播放器按钮配置
debugbooleanfalse是否在控制台打印日志
is-bandbooleantrue是否显示网络状态

PtzConfig 云台控制配置

{
  ptz: true,       // 是否启用 PTZ 控制
  ptzMore: true    // 是否显示更多 PTZ 控制选项
}

BtnsConfig 按钮配置

{
  fullscreen: true,   // 全屏按钮
  screenshot: true,   // 截图按钮
  play: true,         // 播放/暂停按钮
  audio: true,        // 音量按钮
  record: true,       // 录屏按钮
  stretch: true,      // 拉伸按钮
  zoom: true,         // 电子放大按钮
  ptz: true,         // PTZ 控制按钮
  quality: true       // 清晰度切换按钮
}

组件方法

通过 ref 可以调用以下方法：

方法参数返回值说明
play(url?: string)url?: stringvoid播放直播流，不传参使用 props.url
playback(url?: string)url?: stringvoid播放点播视频，不传参使用 props.url
pause()-void暂停播放
isPause()-boolean获取是否处于暂停状态
setMute(mute: boolean)mute: booleanvoid设置静音状态
isMute()-boolean获取是否静音
screenshot(filename?: string, format?: string, quality?: number, type?: string)见下方string | null截图
setFullscreen()-void进入全屏
exitFullscreen()-void退出全屏
setQuality(quality: string)quality: stringvoid设置清晰度
setRate(rate: number)rate: numbervoid设置播放速率（点播有效）
seekTime(time: number)time: numbervoid跳转到指定时间（点播有效）
getVideoInfo()-VideoInfo | null获取视频信息
getAudioInfo()-AudioInfo | null获取音频信息
setMic(status: boolean)status: booleanvoid设置语音对讲状态（需开启 PTZ）
destroy()-void销毁播放器，释放资源
getPlayer()-PlayerInstance | null获取播放器实例

screenshot 方法参数

screenshot(
  filename?: string,   // 文件名，默认 'screenshot'
  format?: string,     // 格式，支持 'png' | 'jpeg' | 'webp'，默认 'png'
  quality?: number,    // 压缩质量 (0-1)，默认 0.92
  type?: string        // 返回类型，支持 'download' | 'base64' | 'blob'
): string | null

事件说明

事件名参数类型说明
readyPlayerInstance播放器就绪回调
playEvent播放事件
pauseEvent暂停事件
videoInfoVideoInfo视频信息回调
audioInfoAudioInfo音频信息回调
fullscreenboolean全屏状态变化回调
muteboolean静音状态变化回调
kBpsnumber当前网速回调，单位 KB/s，每秒触发一次
stretchboolean拉伸状态变化回调
ptzunknownPTZ 控制回调
screenshotsstring截图回调
contextmenuClose-右键菜单关闭回调
decodeHevcstring视频编码回调（如 H265）
liveEnd-直播结束事件
timeout-加载超时事件
recordEndBlob录制结束事件
recordStart-录制开始事件
qualityChangestring清晰度切换回调
playbackSeeknumber录像时间轴跳转回调
playbackRatenumber录像播放速率回调
timestampsnumber播放时间回调
errorError播放错误回调

完整示例

直播播放器

<template>
  <div class="player-container">
    <Vue3EasyPlayerPro
      ref="playerRef"
      :url="liveUrl"
      :is-live="true"
      :has-audio="true"
      :is-mute="false"
      :buffer-time="1"
      :load-time-out="10"
      :load-time-replay="-1"
      :watermark="watermarkConfig"
      :quality="['普清', '高清', '超清']"
      :debug="true"
      @ready="onReady"
      @error="onError"
      @kBps="onKBps"
      @decodeHevc="onDecodeHevc"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

const playerRef = ref<InstanceType<typeof EasyPlayerPro>>()
const liveUrl = 'http://example.com/live.flv'

const watermarkConfig = {
  text: {
    content: '测试水印',
    color: '#ffffff',
    opacity: 0.5,
    fontSize: '12px'
  },
  right: 10,
  top: 10
}

const onReady = (player) => {
  console.log('播放器已就绪')
  player.play(liveUrl)
}

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

const onKBps = (speed) => {
  console.log('当前网速:', speed, 'KB/s')
}

const onDecodeHevc = (codec) => {
  console.log('视频编码:', codec)
}
</script>

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

点播播放器（VOD）

<template>
  <div class="player-container">
    <Vue3EasyPlayerPro
      ref="playerRef"
      :url="vodUrl"
      :is-live="false"
      :poster="posterUrl"
      :autoplay="false"
      @ready="onReady"
      @videoInfo="onVideoInfo"
      @timestamps="onTimestamps"
    />
    <div class="controls">
      <button @click="playVideo">播放</button>
      <button @click="pauseVideo">暂停</button>
      <button @click="screenshot">截图</button>
      <button @click="setFullscreen">全屏</button>
      <input type="number" v-model.number="seekTarget" placeholder="跳转时间(秒)" />
      <button @click="seekTo">跳转</button>
      <select v-model.number="playRate" @change="changeRate">
        <option :value="0.5">0.5x</option>
        <option :value="1">1x</option>
        <option :value="1.5">1.5x</option>
        <option :value="2">2x</option>
      </select>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

const playerRef = ref<InstanceType<typeof Vue3EasyPlayerPro>>()
const vodUrl = 'http://example.com/video.mp4'
const posterUrl = 'http://example.com/poster.jpg'

const seekTarget = ref(0)
const playRate = ref(1)

const onReady = (player) => {
  console.log('播放器已就绪')
}

const onVideoInfo = (info) => {
  console.log('视频信息:', info)
  // { width: 1920, height: 1080, duration: 3600 }
}

const onTimestamps = (time) => {
  // console.log('当前播放时间:', time)
}

const playVideo = () => {
  playerRef.value?.play(vodUrl)
}

const pauseVideo = () => {
  playerRef.value?.pause()
}

const screenshot = () => {
  const data = playerRef.value?.screenshot('my-screenshot', 'png', 0.92, 'base64')
  if (data) {
    console.log('截图数据:', data)
    // 可以将 data 发送到服务器或保存
  }
}

const setFullscreen = () => {
  playerRef.value?.setFullscreen()
}

const seekTo = () => {
  playerRef.value?.seekTime(seekTarget.value)
}

const changeRate = () => {
  playerRef.value?.setRate(playRate.value)
}
</script>

<style scoped>
.player-container {
  width: 100%;
  max-width: 1200px;
}
.controls {
  margin-top: 16px;
  display: flex;
  gap: 8px;
  flex-wrap: wrap;
  align-items: center;
}
button {
  padding: 8px 16px;
  cursor: pointer;
}
input, select {
  padding: 8px;
}
</style>

PTZ 云台控制

<template>
  <Vue3EasyPlayerPro
    :url="cameraUrl"
    :ptz-config="{ ptz: true, ptzMore: true }"
    :btns="{ ptz: true }"
    @ptz="onPtz"
    @decodeHevc="onCodec"
  />
</template>

<script setup lang="ts">
import { Vue3EasyPlayerPro } from 'vue3-easyplayer-pro'

const cameraUrl = 'rtsp://example.com/camera1'

const onPtz = (data) => {
  console.log('PTZ 控制数据:', data)
  // { type: 'up' | 'down' | 'left' | 'right' | 'zoomIn' | 'zoomOut', ... }
}

const onCodec = (codec) => {
  console.log('视频编码:', codec)
}
</script>

多清晰度切换

<template>
  <Vue3EasyPlayerPro
    :url="currentUrl"
    :quality="['流畅', '标清', '高清', '超清']"
    :default-quality="'高清'"
    @qualityChange="onQualityChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const qualityUrls = {
  '流畅': 'http://example.com/stream_low.flv',
  '标清': 'http://example.com/stream_sd.flv',
  '高清': 'http://example.com/stream_hd.flv',
  '超清': 'http://example.com/stream_fhd.flv'
}

const currentUrl = ref(qualityUrls['高清'])

const onQualityChange = (quality) => {
  console.log('切换到:', quality)
  currentUrl.value = qualityUrls[quality]
}
</script>

注意事项

  1. 播放器容器：组件会占据父容器的全部空间，请确保父容器有明确的高度：

    .player-container {
  width: 100%;
  height: 600px; /* 必须设置高度 */
}

  2. 自动播放限制：现代浏览器对自动播放有严格限制，如需自动播放请确保：

    • 视频有声音时需要用户交互后才能自动播放
    • 或设置 is-mute="true" 配合 autoplay="true"

  3. 跨域问题：如果视频存在跨域问题，需要在服务器端设置正确的 CORS 头。

  4. 流媒体协议：确保服务器支持对应的流媒体协议，不同协议需要不同的解码器支持。

类型定义

组件导出了以下类型，可以直接导入使用：

import type {
  Vue3EasyPlayerPro,     // 组件类型（用于 ref 类型定义）
  EasyPlayerProProps,      // 组件 Props 类型
  PlayerInstance,          // 播放器实例类型
  VideoInfo,              // 视频信息类型
  AudioInfo,              // 音频信息类型
  WatermarkConfig,        // 水印配置类型
  FullWatermarkConfig,    // 全屏水印配置类型
  PtzConfig,             // PTZ 配置类型
  BtnsConfig,            // 按钮配置类型
  EmitsMap               // 事件类型映射
} from 'vue3-easyplayer-pro'

License

MIT

# vue.js # javascript # http
Logo
火山引擎视频云技术社区

邀请您加入社区

更多推荐

cover

11 天的后期压成 30 分钟：我用火山引擎 AI MediaKit Skill 做完了一条成片

avatar 火山引擎视频云技术社区

Stagewise + Remotion 视频配音实战：用 ElevenLabs 逐场景生成语音并动态对齐画面时长

> 本文基于仓库内 [create-remotion-video 技能](https://link.gitcode.com/i/1dcbae309c34a2dfa32d905717d19b85) 中内置的配音规则文档 [voiceover.md](https://link.gitcode.com/i/1d2dca6455f0c22dd7ffb7d71df6ccfe) 展开。该技能是 Stagewi

avatar 火山引擎视频云技术社区

[流媒体开发】H264/AAC封装格式、ADTS头、SPS/PPS、RTP打包全解

在做流媒体服务器（RTMP/RTSP/HLS 互转）时，封装格式是最容易踩坑的地方。很多同学能跑通 Demo，但一遇到花屏、音画不同步、SPS/PPS 丢失就抓瞎。本文从底层字节讲起，覆盖：H264 的 NALU 结构与两种封装（Annex-B / AVCC）AAC 的三种格式（raw / ADTS / ASC）ADTS 头 7 字节逐位分析SPS/PPS 的作用与传输RTP 封包完整实现（H26

avatar 火山引擎视频云技术社区