# zwplayervue3

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

**[English](#english) | [中文](#中文)**

---

<a id="english"></a>

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](https://www.zwplayer.com/tools/videoplayer/) |
| 2 | **Code Generator** | Visually configure player UI skins, autoplay policies, subtitle attachment, and video hotspots; one-click export of integration code | [generator](https://www.zwplayer.com/tools/generator/) |
| 3 | **Annotation Editor** | Visual drag-and-drop design of interactive video hotspots, supporting form, quiz, vote, and other interactive nodes | [annotation](https://www.zwplayer.com/tools/annotation/) |
| 4 | **Subtitle Editor** | Create, translate, and export subtitles in SRT, VTT, BCC, JSON, and other formats online | [subtitle](https://www.zwplayer.com/tools/subtitle/) |
| 5 | **Chapter Editor** | Visually create and export video chapter marker data | [chapter](https://www.zwplayer.com/tools/chapter/) |
| 6 | **Thumbnail Generator** | Quickly generate video sprite sheets and ZWMAP JSON configuration | [thumbnail](https://www.zwplayer.com/tools/thumbnail/) |
| 7 | **Playlist Editor** | Visually manage and export playlist data, with group and auto-play support | [playlist](https://www.zwplayer.com/tools/playlist/) |
| 8 | **Watermark Editor** | Visually configure image watermarks, text watermarks, animated roaming watermarks, and tiled watermarks | [watermark](https://www.zwplayer.com/tools/watermark/) |

For more details, please visit:
- [zwplayer Official Website](https://www.zwplayer.com)
- [Vue Framework Integration Guide](https://www.zwplayer.com/docs/support/guide-vue-framework.html)

## Getting Started

### Installation

```bash
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`:

```javascript
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:

```javascript
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

```html
<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](https://www.zwplayer.com/docs/support/guide-configuration.html) | - |

**Thumbnail configuration example:**

```javascript
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

```javascript
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](https://www.zwplayer.com/docs/support/guide-api.html).

## Other Versions

### Vue 2.x

```bash
npm install zwplayer-vue2x --save
```

Documentation: [zwplayer-vue2x](https://www.zwplayer.com/docs/support/guide-vue-framework.html)

## Related Resources

### Official Documentation
- [ZWPlayer Official Website](https://www.zwplayer.com)
- [Vue Framework Integration Guide](https://www.zwplayer.com/docs/support/guide-vue-framework.html)
- [Configuration Parameters](https://www.zwplayer.com/docs/support/guide-configuration.html)
- [API Methods](https://www.zwplayer.com/docs/support/guide-api.html)
- [Events](https://www.zwplayer.com/docs/support/guide-events.html)

### Example Projects
- [Vue 3 Example (Gitee)](https://gitee.com/chenfanyu/zwplayervue3-demo)
- [Vue 3 Example (GitHub)](https://github.com/chenfanyu/zwplayervue3-demo)
- [Vue 2 Example (Gitee)](https://gitee.com/chenfanyu/zwplayer-vue2x-demo)
- [Vue 2 Example (GitHub)](https://github.com/chenfanyu/zwplayer-vue2x-demo)

## License

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

## Technical Support

- Email: 893366640@qq.com
- QQ: 893366640
- WeChat: zwplayerX
- Official Account: zwplayer

---

<a id="中文"></a>

基于 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](https://www.zwplayer.com/zh/tools/videoplayer/) |
| 2 | **代码生成器** | 可视化配置播放器 UI 皮肤、自动播放策略、字幕挂载与视频热区，一键导出集成代码 | [generator](https://www.zwplayer.com/zh/tools/generator/) |
| 3 | **交互标注编辑器** | 可视化拖拽设计视频交互热区，支持表单、测验、投票等交互节点 | [annotation](https://www.zwplayer.com/zh/tools/annotation/) |
| 4 | **字幕编辑器** | 在线创建、翻译和导出 SRT、VTT、BCC、JSON 等格式字幕 | [subtitle](https://www.zwplayer.com/zh/tools/subtitle/) |
| 5 | **章节编辑器** | 可视化创建和导出视频章节标记数据 | [chapter](https://www.zwplayer.com/zh/tools/chapter/) |
| 6 | **缩略图生成器** | 快速生成视频雪碧图（Sprite Sheet）和 ZWMAP JSON 配置 | [thumbnail](https://www.zwplayer.com/zh/tools/thumbnail/) |
| 7 | **播放列表编辑器** | 可视化管理和导出播放列表数据，支持分组和自动播放 | [playlist](https://www.zwplayer.com/zh/tools/playlist/) |
| 8 | **水印编辑器** | 可视化配置图片水印、文字水印、动态游走水印和铺满水印 | [watermark](https://www.zwplayer.com/zh/tools/watermark/) |

更多详情请访问：
- [zwplayer 官网](https://www.zwplayer.com/zh)
- [在线体验](https://www.zwplayer.com/zh/videoplayer.html)
- [Vue 框架集成指南](https://www.zwplayer.com/zh/docs/support/guide-vue-framework.html)

## 使用说明

### 安装

```bash
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` 中添加：

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

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

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

#### 局部注册

在组件中单独注册：

```javascript
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)
    }
  }
}
```

### 组件使用

#### 基础使用示例

```html
<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>
```

#### 弹幕功能示例

```html
<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 播放器构造函数参数](https://www.zwplayer.com/zh/docs/support/guide-configuration.html) | - |

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

```javascript
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` 引用调用播放器方法：

```javascript
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 文档](https://www.zwplayer.com/zh/docs/support/guide-api.html)。

### 示例项目

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

## 其他版本

### Vue 2.x

```bash
npm install zwplayer-vue2x --save
```

详细文档：[zwplayer-vue2x](https://www.zwplayer.com/zh/docs/support/guide-vue-framework.html)

## 相关资源

### 官方文档
- [ZWPlayer 官网](https://www.zwplayer.com/zh)
- [Vue 框架集成指南](https://www.zwplayer.com/zh/docs/support/guide-vue-framework.html)
- [配置参数文档](https://www.zwplayer.com/zh/docs/support/guide-configuration.html)
- [API 方法文档](https://www.zwplayer.com/zh/docs/support/guide-api.html)
- [事件文档](https://www.zwplayer.com/zh/docs/support/guide-events.html)

### 示例项目
- [Vue 3 示例 (Gitee)](https://gitee.com/chenfanyu/zwplayervue3-demo)
- [Vue 3 示例 (GitHub)](https://github.com/chenfanyu/zwplayervue3-demo)
- [Vue 2 示例 (Gitee)](https://gitee.com/chenfanyu/zwplayer-vue2x-demo)
- [Vue 2 示例 (GitHub)](https://github.com/chenfanyu/zwplayer-vue2x-demo)

## 许可证

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

## 技术支持

如有问题或建议，请通过以下方式联系：
- 邮箱：893366640@qq.com
- QQ：893366640
- 微信：zwplayerX
- 公众号：zwplayer
