zwplayervue3

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 Multi-Track Subtitles with Real-Time API Translation: Pioneering HLS embedded caption pre-download and extraction technology, seamlessly combined with SRT/VTT/BCC external subtitles (multi-track loading with free primary/secondary track assignment); native translation API integration for dynamic bilingual display; global index-based line search with instant seeking; per-track runtime style customization and per-line loop playback — perfectly empowering foreign language learning, knowledge-payment, and cross-border content scenarios
• 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

What's New in v3.3.1

• Audio Tracks: Multi-language audio track switching + TTS subtitle-to-speech
• VR / 360° Panoramic Playback: Interactive panoramic video with drag/touch/keyboard controls, live view settings panel, and auto-detection of 2:1 panoramic videos
• Control Bar Polish: Streamlined control bar UI with refined time progress, speed controller, and playback indicators

What's New in v3.3.2

• Bumper Ads: Pre-roll/post-roll ad insertion with configurable skip strategies (force view, immediate skip, countdown skip), click-through landing pages, and clean ad playback UI
• Playback Modes: mode config enables four forms — standard video, preview (hover to peek), music (vinyl cover + lyrics + spectrum), and auto (auto-switch between video/audio in mixed playlists)
• Cross-Video Subtitle Search: Search subtitles by keyword across all videos in a playlist — instantly locate which episode a line appears in and jump to the exact timestamp
• DASH Embedded Subtitle Pre-Download: Automatically pre-download DASH embedded subtitles (stpp/wvtt) for full-text search, translation, and export — zero config required
• Unified UI Redesign: Pull-up thumbnail strip for precise seeking, modern control bar, home→sub-page settings menu, mobile Bottom Sheets, number-key percentage seeking

Online Tools

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

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

Thumbnail configuration example:

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

Events

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: 893366640@qq.com
• 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 网页播放（无需插件）
• 本地文件播放：支持直接播放用户设备上的本地视频/音频文件
• 智能多轨字幕与实时 API 翻译：创新引入 HLS 内嵌字幕预下载提取技术，无缝融合 SRT/VTT/BCC 外挂字幕（多轨加载、主/副轨自由分配）；原生对接翻译 API 实现动态双语，配合全局无感索引定位台词秒级跳转；逐轨运行时样式调节与逐条循环——完美赋能外语学习、知识付费与跨国出海场景
• 丰富功能：弹幕、进度条预览、画面调节、截图、音量增益、AB循环、录制、音频提取等
• 直播优化：超低延时直播、直播追帧、多码流切换
• 灵活模式：画中画、网页全屏、自动小窗口、强制锁定模式

v3.3.0 新增功能

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

v3.3.1 新增功能

• 多音轨：多语言音轨动态切换，支持 TTS 字幕转配音
• VR / 360° 全景播放：交互式全景视频，支持鼠标拖拽/触摸/键盘控制，内置视角设置面板，自动检测 2:1 全景视频
• 控制条优化：简洁化控制条界面，优化时间进度条、倍速控制器与播放状态指示

v3.3.2 新增功能

• 贴片广告：片前/片后插入宣传片，支持强制观看、立即可跳、倒计时可跳三种跳过策略，支持点击跳转落地页，广告界面清爽不打扰
• 播放模式：通过 mode 配置一键切换四种形态——标准视频、预览模式（悬停即播）、音乐模式（唱片封面 + 歌词 + 频谱）、自动模式（混合列表视频/音频自动切换）
• 跨视频字幕搜索：在播放列表中跨视频搜索字幕关键词，快速定位台词出现在哪一集的什么时间，点击直达
• DASH 内嵌字幕预下载：自动预下载 DASH 内嵌字幕（stpp/wvtt），搜索、翻译、导出全面可用，零配置即生效
• 界面统一改版：上拉缩略图条精确定位画面、现代化控制栏、首页→子页设置菜单、移动端 Bottom Sheet、数字键百分比跳转

在线工具

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

更多详情请访问：

• 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>

主要属性说明

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

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

事件

方法调用

通过 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 核心库完全免费使用。

技术支持

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

• 邮箱：893366640@qq.com
• QQ：893366640
• 微信：zwplayerX
• 公众号：zwplayer