zwplayervue3

Vue 3.x wrapper component for zwplayer, providing easy-to-use video playback capabilities.

English | 中文

Vue 3.x wrapper component for zwplayer, providing easy-to-use video playback capabilities.

About zwplayer

zwplayer (Zero Web Player) is a web video player built on the "zero-effort" design philosophy, dedicated to reducing the developer's integration cost to as close to zero as possible.

Core Principles

• Zero Cost - Completely free, forever free, no payment required
• Zero Learning Curve - Provides a clean, unified API; the smart engine handles all streaming technical details automatically
• Zero Upgrade Cost - The API is permanently stabilized; upgrading only requires replacing a single file
• Zero Risk - Clean codebase with no ads, no analytics, no network backdoors
• Zero Deployment Cost - No dependency on third-party libraries or CDNs; works on private networks and intranets

Key Features

• Broad Protocol Support: HLS, DASH, HTTP-FLV, HTTP-TS, WebSocket, WebRTC (WHEP/ARTC/BRTC/TRTC)
• Unique Protocol: RTSP web playback support (no browser plugin required)
• Local File Playback: Play video/audio files directly from the user's device
• Smart Subtitles: Dual subtitles, subtitle search, subtitle translation, chapter search, drag-and-drop loading of local subtitle/chapter files
• Rich Functionality: Danmaku (bullet comments), progress bar preview, image adjustment, screenshots, volume boost, A-B loop, recording, audio extraction, and more
• Live Streaming Optimization: Ultra-low latency streaming, live catch-up, multi-bitrate switching
• Flexible Modes: Picture-in-Picture, browser fullscreen, auto mini-window, forced lock mode

What's New in v3.3.0

• Casting: Cast to external devices via the browser Presentation API / AirPlay
• Watermarks: Multiple watermarks, image watermarks, text watermarks, animated roaming watermarks; backward-compatible with the legacy logo configuration
• Playlists: XML-format playlists, multi-episode group management, auto-play next episode
• Interactive Video Annotations (Hotspots): Visual drag-and-drop design of interactive video hotspots, supporting form, quiz, vote, and other interactive nodes
• Frame-by-Frame Stepping: Precise frame-by-frame playback control via keyboard arrow keys
• Subtitle Translation: Configurable translation API with a real-time subtitle translation panel
• Volume Boost: Volume gain beyond 100% via the Web Audio API
• Time Format: Display time in seconds or milliseconds
• Magnifier: Fully rewritten magnifier feature

Online Tools

ZWPlayer provides 8 free online tools — no registration required, ready to use:

| # | Tool | Description | Link | |---|------|-------------|------| | 1 | Online Player | Universal protocol player for live testing and local file preview, supporting WebRTC/RTSP/HLS/DASH/FLV and all other protocols | videoplayer | | 2 | Code Generator | Visually configure player UI skins, autoplay policies, subtitle attachment, and video hotspots; one-click export of integration code | generator | | 3 | Annotation Editor | Visual drag-and-drop design of interactive video hotspots, supporting form, quiz, vote, and other interactive nodes | annotation | | 4 | Subtitle Editor | Create, translate, and export subtitles in SRT, VTT, BCC, JSON, and other formats online | subtitle | | 5 | Chapter Editor | Visually create and export video chapter marker data | chapter | | 6 | Thumbnail Generator | Quickly generate video sprite sheets and ZWMAP JSON configuration | thumbnail | | 7 | Playlist Editor | Visually manage and export playlist data, with group and auto-play support | playlist | | 8 | Watermark Editor | Visually configure image watermarks, text watermarks, animated roaming watermarks, and tiled watermarks | watermark |

For more details, please visit:

• zwplayer Official Website
• Vue Framework Integration Guide

Getting Started

Installation

npm install zwplayervue3 --save

Installation Notes

Important: This component depends on the zwplayer core library. Please note the following during installation:

1. Automatic Configuration: npm install will automatically run the postinstall script, which will:

   • Create the public directory (if it does not exist)
   • Copy the zwplayer core library to the public/zwplayer directory

2. Core Library Must Be Deployed: The public/zwplayer directory must be deployed along with your project to production

3. Dynamic Loading Mechanism: zwplayer uses a dynamic loading mechanism, supporting seamless upgrades without modifying your application code

4. Intranet / Offline Deployment: zwplayer does not depend on CDNs and fully supports intranet and offline environments

Component Registration

Global Registration

Add in src/main.js:

import { createApp } from 'vue'
import App from './App.vue'
import ZwModule from 'zwplayervue3'

createApp(App)
  .use(ZwModule)
  .mount('#app')

After global registration, you can use the <zwplayer> component anywhere in your project.

Local Registration

Register in a single component:

import { zwplayer } from 'zwplayervue3'

export default {
  name: 'MyComponent',
  components: {
    zwplayer
  },
  data() {
    return {
      movieUrl: 'https://d2zihajmogu5jn.cloudfront.net/elephantsdream/ed_hd.mp4',
      playerOpen: true
    }
  },
  methods: {
    onPlayerReady() {
      console.log('player ready event.')
    },
    onPlayerMediaEvent(event) {
      console.log('media event:', event.type)
    },
    sendDanmu(danmu) {
      console.log('sendDanmu:', danmu)
    }
  }
}

Component Usage

<template>
  <div class="player-container">
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      nodeid="main-player"
      :murl="movieUrl"
      @onready="onPlayerReady"
      @onmediaevent="onPlayerMediaEvent"
      :snapshotButton="true"
      :optionButton="true"
      :infoButton="true"
      :enableDanmu="true"
      :chapterButton="true"
      :disableMutedConfirm="true"
      danmuBar="danmu-controlbar"
    />
  </div>
</template>

Main Properties

| Property | Type | Description | Default | |---------|------|-------------|---------| | murl | String/Object/Array | Media URL parameter, supports dynamic switching | - | | fluid | Boolean | Enable fluid layout (adaptive to container width) | false | | autoplay | Boolean | Auto-play on load | false | | disableMutedConfirm | Boolean | Disable muted playback confirmation | false | | enableDanmu | Boolean | Enable danmaku (bullet comments) | false | | snapshotButton | Boolean | Show screenshot button | false | | optionButton | Boolean | Show settings button | false | | infoButton | Boolean | Show info button | false | | chapterButton | Boolean | Show chapter button | false | | recordButton | Boolean | Show record button | false | | segmentButton | Boolean | Show segment button | false | | localPlayback | Boolean | Enable local file playback | false | | sendDanmu | Function | Callback function for sending danmaku | - | | thumbnails | Object | Thumbnail configuration object | - | | logo | Object | Logo watermark configuration object | - | | poster | String | Video poster image URL | - | | timeFormat | String | Time format: 's' = seconds, 'ms' = milliseconds | 's' | | castButton | Boolean | Show cast button | false | | zoomButton | Boolean | Show magnifier button | false | | annotationButton | Boolean | Show annotation/hotspot button | false | | annotation | Object | Annotation/hotspot configuration data | - | | annotations | Object | Annotation/hotspot configuration data (alias for annotation) | - | | watermark | Array | Watermark configuration array | - | | watermarks | Array | Watermark configuration array (alias for watermark) | - | | translateApi | String | Translation API endpoint | - | | defVolume | Number | Default volume percentage (0-100) | 61.25 | | hideControlbarTimeout | Number | Control bar auto-hide timeout (milliseconds) | 10000 | | Others | - | See zwplayer constructor parameters | - |

Thumbnail configuration example:

thumbnails: {
  url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
  width: 160,
  height: 90,
  row: 9,
  col: 9,
  total: 74
}

Events

| Event Name | Description | Callback Parameters | |-----------|-------------|---------------------| | onready | Player initialization complete | - | | onmediaevent | Media playback event (play, pause, ended, etc.) | event object, containing type and other properties |

Method Calls

const player = this.$refs.zwplayerRef

// Basic playback control
player.play()                    // play
player.pause()                   // pause
player.seekTime(120)             // seek to 120 seconds
player.stop()                    // stop

// Subtitles
player.addSubtitle('/subtitles/zh.vtt', '1')
player.removeSubtitle('1')

// Danmaku
player.appendDanmu({ border: '1px solid #ccc', text: 'Hello!', color: '#ff6b6b' })

// Chapters
player.setChapters([{ title: "Chapter 1", time: 0, duration: 50 }])

// Info
player.getDuration()
player.getCurrentTime()

For more methods, see zwplayer API documentation.

Other Versions

Vue 2.x

npm install zwplayer-vue2x --save

Documentation: zwplayer-vue2x

Related Resources

Official Documentation

• ZWPlayer Official Website
• Vue Framework Integration Guide
• Configuration Parameters
• API Methods
• Events

Example Projects

• Vue 3 Example (Gitee)
• Vue 3 Example (GitHub)
• Vue 2 Example (Gitee)
• Vue 2 Example (GitHub)

License

MIT License. ZWPlayer core library is completely free to use.

Technical Support

• Email: [email protected]
• QQ: 893366640
• WeChat: zwplayerX
• Official Account: zwplayer

基于 Vue 3.x 的 zwplayer 组件封装，提供简单易用的视频播放能力。

关于 zwplayer

zwplayer（Zero Web Player）是一款秉持"智能傻瓜式"设计理念的网页播放器，致力于将开发者的使用成本降至无限接近于零。

核心特点

✅ 零费用成本 - 完全免费，永久免费，无需支付任何费用

✅ 零学习成本 - 提供统一简洁的 API，智能引擎自动处理所有流媒体技术细节

✅ 零升级成本 - API 永久固化，版本升级仅需替换文件

✅ 零风险成本 - 代码纯净，无广告、无统计、无联网后门

✅ 零部署成本 - 不依赖第三方库和 CDN，私网、内网均可使用

主要功能

• 广泛协议支持：HLS、DASH、HTTP-FLV、HTTP-TS、WS、WebRTC（WHEP/ARTC/BRTC/TRTC）
• 特色协议：支持 RTSP 网页播放（无需插件）
• 本地文件播放：支持直接播放用户设备上的本地视频/音频文件
• 智能字幕：支持双字幕、字幕搜索、字幕翻译、章节搜索、拖拽加载本地字幕/章节文件
• 丰富功能：弹幕、进度条预览、画面调节、截图、音量增益、AB循环、录制、音频提取等
• 直播优化：超低延时直播、直播追帧、多码流切换
• 灵活模式：画中画、网页全屏、自动小窗口、强制锁定模式

v3.3.0 新增功能

• 投屏：支持通过浏览器 Presentation API / AirPlay 投射到外部设备
• 水印：支持多水印、图片水印、文字水印、动态游走水印，兼容旧版 logo 配置
• 播放列表：支持 XML 格式播放列表，多集分组管理，自动播放下一集
• 视频交互热区（标注）：可视化拖拽设计视频交互热区，支持表单、测验、投票等交互节点
• 逐帧步进：通过键盘方向键逐帧精确控制播放
• 字幕翻译：可设置翻译 API，支持实时字幕翻译面板
• 音量增强：通过 Web Audio API 实现超过 100% 的音量增益
• 时间格式：支持秒和毫秒两种时间显示格式
• 放大镜：全新重写的放大镜功能

在线工具

ZWPlayer 提供 8 个免费在线工具，无需注册，即开即用：

| # | 工具 | 说明 | 链接 | |---|------|------|------| | 1 | 在线播放器 | 全协议在线试播与本地文件预览，支持 WebRTC/RTSP/HLS/DASH/FLV 等所有协议 | videoplayer | | 2 | 代码生成器 | 可视化配置播放器 UI 皮肤、自动播放策略、字幕挂载与视频热区，一键导出集成代码 | generator | | 3 | 交互标注编辑器 | 可视化拖拽设计视频交互热区，支持表单、测验、投票等交互节点 | annotation | | 4 | 字幕编辑器 | 在线创建、翻译和导出 SRT、VTT、BCC、JSON 等格式字幕 | subtitle | | 5 | 章节编辑器 | 可视化创建和导出视频章节标记数据 | chapter | | 6 | 缩略图生成器 | 快速生成视频雪碧图（Sprite Sheet）和 ZWMAP JSON 配置 | thumbnail | | 7 | 播放列表编辑器 | 可视化管理和导出播放列表数据，支持分组和自动播放 | playlist | | 8 | 水印编辑器 | 可视化配置图片水印、文字水印、动态游走水印和铺满水印 | watermark |

更多详情请访问：

• zwplayer 官网
• 在线体验
• Vue 框架集成指南

使用说明

安装

npm install zwplayervue3 --save

安装注意事项

⚠️ 重要：本组件依赖 zwplayer 核心库，安装时请注意以下事项：

1. 自动配置：npm install 会自动执行 postinstall 脚本，该脚本会：

   • 创建 public 目录（如果不存在）
   • 将 zwplayer 核心库复制到 public/zwplayer 目录

2. 核心库必须发布：public/zwplayer 目录必须随项目一起发布到生产环境

   • 确保该目录完整包含所有 zwplayer 相关文件
   • 不要在部署时忽略此目录

3. 动态加载机制：zwplayer 采用动态加载机制

   • 支持无缝升级，无需修改业务代码
   • 升级时只需替换 public/zwplayer 目录中的文件即可

4. 内网/私网部署：zwplayer 不依赖 CDN，完全支持内网和离线环境部署

组件注册

全局注册

在 src/main.js 中添加：

import { createApp } from 'vue'
import App from './App.vue'
import ZwModule from 'zwplayervue3'

createApp(App)
  .use(ZwModule)
  .mount('#app')

全局注册后，可在项目任何组件中使用 <zwplayer> 组件。

局部注册

在组件中单独注册：

import { zwplayer } from 'zwplayervue3'

export default {
  name: 'MyComponent',
  components: {
    zwplayer
  },
  data() {
    return {
      movieUrl: 'https://d2zihajmogu5jn.cloudfront.net/elephantsdream/ed_hd.mp4',
      playerOpen: true
    }
  },
  methods: {
    onPlayerReady() {
      console.log('player ready event.')
    },
    onPlayerMediaEvent(event) {
      console.log('media event:', event.type)
    },
    sendDanmu(danmu) {
      console.log('sendDanmu:', danmu)
    }
  }
}

组件使用

基础使用示例

<template>
  <div class="player-container">
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      nodeid="main-player"
      :murl="movieUrl"
      @onready="onPlayerReady"
      @onmediaevent="onPlayerMediaEvent"
      :snapshotButton="true"
      :optionButton="true"
      :infoButton="true"
      :enableDanmu="true"
      :chapterButton="true"
      :disableMutedConfirm="true"
      danmuBar="danmu-controlbar"
    />
  </div>
</template>

弹幕功能示例

<template>
  <div>
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      :murl="movieUrl"
      :enableDanmu="true"
      :sendDanmu="sendDanmu"
      :disableMutedConfirm="true"
      @onready="onPlayerReady"
    />
    <div class="danmubar" id="danmu-controlbar"></div>
  </div>
</template>

<script>
import { zwplayer } from 'zwplayervue3'

export default {
  name: 'DanmuExample',
  components: { zwplayer },
  data() {
    return {
      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
      playerOpen: true,
      player: null
    }
  },
  methods: {
    onPlayerReady() {
      this.player = this.$refs.zwplayerRef
      if (this.player && this.player.appendDanmu) {
        this.player.appendDanmu({ border: '1px solid #ccc', text: '欢迎来到 zwplayer！', color: '#ff6b6b' })
      }
    },
    sendDanmu(danmuText) {
      if (!danmuText || !this.player) return
      this.player.appendDanmu({ border: '1px solid #ccc', text: danmuText })
    }
  }
}
</script>

<style scoped>
.danmubar {
  height: 50px;
  background-color: #232323;
  padding: 8px;
  box-sizing: border-box;
}
.danmubar :deep(.zwp_danmu-controlbar) {
  width: 60%;
}
</style>

主要属性说明

| 属性名称 | 类型 | 说明 | 默认值 | |---------|------|------|--------| | murl | String/Object/Array | 媒体地址参数，支持动态切换 | - | | fluid | Boolean | 是否启用流式布局（自适应容器宽度） | false | | autoplay | Boolean | 是否自动播放 | false | | disableMutedConfirm | Boolean | 禁用静音确认 | false | | enableDanmu | Boolean | 是否启用弹幕功能 | false | | snapshotButton | Boolean | 是否显示截图按钮 | false | | optionButton | Boolean | 是否显示设置按钮 | false | | infoButton | Boolean | 是否显示信息按钮 | false | | chapterButton | Boolean | 是否显示章节按钮 | false | | recordButton | Boolean | 是否显示录制按钮 | false | | segmentButton | Boolean | 是否显示分段按钮 | false | | localPlayback | Boolean | 是否启用本地播放功能 | false | | sendDanmu | Function | 发送弹幕的回调函数 | - | | thumbnails | Object | 缩略图配置对象 | - | | logo | Object | Logo水印配置对象 | - | | poster | String | 视频封面图地址 | - | | timeFormat | String | 时间格式：'s'=秒，'ms'=毫秒 | 's' | | castButton | Boolean | 是否显示投屏按钮 | false | | zoomButton | Boolean | 是否显示放大镜按钮 | false | | annotationButton | Boolean | 是否显示标注/热区按钮 | false | | annotation | Object | 标注/热区配置数据 | - | | annotations | Object | 标注/热区配置数据（annotation 别名） | - | | watermark | Array | 水印配置数组 | - | | watermarks | Array | 水印配置数组（watermark 别名） | - | | translateApi | String | 翻译 API 端点 | - | | defVolume | Number | 默认音量百分比 (0-100) | 61.25 | | hideControlbarTimeout | Number | 控制栏自动隐藏等待时间（毫秒） | 10000 | | 其它 | - | 请参考 zwplayer 播放器构造函数参数 | - |

缩略图配置对象（thumbnails）示例：

thumbnails: {
  url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
  width: 160,    // 每个小缩略图的宽度
  height: 90,    // 每个小缩略图的高度
  row: 9,        // 缩略图总行数
  col: 9,        // 缩略图总列数
  total: 74      // 缩略图总数
}

事件

| 事件名称 | 说明 | 回调参数 | |---------|------|---------| | onready | 播放器初始化完成 | - | | onmediaevent | 媒体事件（播放、暂停、结束等） | event对象，包含type等属性 |

方法调用

通过 ref 引用调用播放器方法：

const player = this.$refs.zwplayerRef

// 播放控制
player.play()                    // 播放
player.pause()                   // 暂停
player.seekTime(120)             // 跳转到指定秒数
player.stop()                    // 停止

// 字幕
player.addSubtitle('/subtitles/zh.vtt', '1')  // 添加字幕轨道
player.removeSubtitle('1')                     // 移除字幕轨道

// 弹幕
player.appendDanmu({ border: '1px solid #ccc', text: '这是一条弹幕', color: '#ff6b6b' })

// 章节
player.setChapters([{ title: "章节1", desc: "章节1描述", time: 0, duration: 50 }])

// 获取信息
player.getDuration()               // 获取视频总时长
player.getCurrentTime()            // 获取当前播放时间

更多方法请参考 zwplayer API 文档。

示例项目

• Gitee: https://gitee.com/chenfanyu/zwplayervue3-demo
• GitHub: https://github.com/chenfanyu/zwplayervue3-demo

其他版本

Vue 2.x

npm install zwplayer-vue2x --save

详细文档：zwplayer-vue2x

相关资源

官方文档

• ZWPlayer 官网
• Vue 框架集成指南
• 配置参数文档
• API 方法文档
• 事件文档

示例项目

• Vue 3 示例 (Gitee)
• Vue 3 示例 (GitHub)
• Vue 2 示例 (Gitee)
• Vue 2 示例 (GitHub)

许可证

本组件遵循 MIT 许可证。ZWPlayer 核心库完全免费使用。

技术支持

如有问题或建议，请通过以下方式联系：

• 邮箱：[email protected]
• QQ：893366640
• 微信：zwplayerX
• 公众号：zwplayer