zwplayer-vue2x 1.0.35 → 1.1.0

package/README.md

@@ -1,73 +1,99 @@
 # zwplayer-vue2x
 
-基于 Vue 2.x 的 zwplayer 组件封装，提供简单易用的视频播放能力。
+Vue 2.x wrapper component for zwplayer, providing easy-to-use video playback capabilities.
 
-## 关于 zwplayer
+**[English](#english) | [中文](#中文)**
 
-`zwplayer`（Zero Web Player）是一款秉持"智能傻瓜式"设计理念的网页播放器，致力于将开发者的使用成本降至无限接近于零。
+---
 
-### 核心特点
+<a id="english"></a>
 
-✅ **零费用成本** - 完全免费，永久免费，无需支付任何费用
+Vue 2.x wrapper component for zwplayer, providing easy-to-use video playback capabilities.
 
-✅ **零学习成本** - 提供统一简洁的 API，智能引擎自动处理所有流媒体技术细节
+## About zwplayer
 
-✅ **零升级成本** - API 永久固化，版本升级仅需替换文件
+`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
 
-✅ **零部署成本** - 不依赖第三方库和 CDN，私网、内网均可使用
+- **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
 
-- **广泛协议支持**：HLS、DASH、HTTP-FLV、HTTP-TS、WS、WebRTC（WHEP/ARTC/BRTC/TRTC）
-- **特色协议**：支持 RTSP 网页播放（无需插件）
-- **本地文件播放**：支持直接播放用户设备上的本地视频/音频文件
-- **智能字幕**：支持双字幕、字幕搜索、章节搜索、拖拽加载本地字幕、章节文件
-- **丰富功能**：弹幕、进度条预览、画面调节、截图、音量增益、AB循环、录制、音频提取等
-- **直播优化**：超低延时直播、直播追帧、多码流切换
-- **灵活模式**：画中画、网页全屏、自动小窗口、强制锁定模式
+- **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
 
-更多详情请访问：
-1. [zwplayer 官网](https://www.zwplayer.cn) 
-2. [在线体验](https://www.zwplayer.cn/videoplayer.html)
-3. [vue框架使用](https://www.zwplayer.cn/docs/support/guide-vue-framework.html)
-3. [vue框架使用](https://www.zwplayer.cn/docs/support/guide-vue-framework.html)
-4. 调用示例项目：
+### 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/zh/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/zh/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/zh/tools/annotation/) |
+| 4 | **Subtitle Editor** | Create, translate, and export subtitles in SRT, VTT, BCC, JSON, and other formats online | [subtitle](https://www.zwplayer.com/zh/tools/subtitle/) |
+| 5 | **Chapter Editor** | Visually create and export video chapter marker data | [chapter](https://www.zwplayer.com/zh/tools/chapter/) |
+| 6 | **Thumbnail Generator** | Quickly generate video sprite sheets and ZWMAP JSON configuration | [thumbnail](https://www.zwplayer.com/zh/tools/thumbnail/) |
+| 7 | **Playlist Editor** | Visually manage and export playlist data, with group and auto-play support | [playlist](https://www.zwplayer.com/zh/tools/playlist/) |
+| 8 | **Watermark Editor** | Visually configure image watermarks, text watermarks, animated roaming watermarks, and tiled watermarks | [watermark](https://www.zwplayer.com/zh/tools/watermark/) |
+
+For more details, please visit:
+1. [zwplayer Official Website](https://www.zwplayer.cn)
+2. [Online Demo](https://www.zwplayer.cn/videoplayer.html)
+3. [Vue Framework Integration Guide](https://www.zwplayer.cn/docs/support/guide-vue-framework.html)
+4. Example projects:
    - **Gitee**: https://gitee.com/chenfanyu/zwplayer-vue2x-demo
    - **GitHub**: https://github.com/chenfanyu/zwplayer-vue2x-demo
-   
 
-## 使用说明
+## Getting Started
 
-### 安装
+### Installation
 
 ```bash
 npm install zwplayer-vue2x --save
 ```
 
-#### 安装注意事项
+#### Installation Notes
 
-⚠️ **重要**：本组件依赖 `zwplayer` 核心库，安装时请注意以下事项：
+**Important**: This component depends on the `zwplayer` core library. Please note the following during installation:
 
-1. **自动配置**：`npm install` 会自动执行 `postinstall` 脚本，该脚本会：
-   - 创建 `public` 目录（如果不存在）
-   - 将 `zwplayer` 核心库复制到 `public/zwplayer` 目录
+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. **核心库必须发布**：`public/zwplayer` 目录必须随项目一起发布到生产环境
-   - 确保该目录完整包含所有 zwplayer 相关文件
-   - 不要在部署时忽略此目录
+2. **Core Library Must Be Deployed**: The `public/zwplayer` directory must be deployed along with your project to production
 
-3. **动态加载机制**：zwplayer 采用动态加载机制
-   - 支持无缝升级，无需修改业务代码
-   - 升级时只需替换 `public/zwplayer` 目录中的文件即可
+3. **Dynamic Loading Mechanism**: zwplayer uses a dynamic loading mechanism, supporting seamless upgrades without modifying your application code
 
-4. **内网/私网部署**：zwplayer 不依赖 CDN，完全支持内网和离线环境部署
-### 组件注册
+4. **Intranet / Offline Deployment**: zwplayer does not depend on CDNs and fully supports intranet and offline environments
 
-#### 全局注册
+### Component Registration
 
-在 `src/main.js` 中添加：
+#### Global Registration
+
+Add in `src/main.js`:
 
 ```javascript
 import Vue from 'vue'
@@ -81,11 +107,11 @@ new Vue({
 }).$mount('#app')
 ```
 
-全局注册后，可在项目任何组件中使用 `<zwplayer>` 组件。
+After global registration, you can use the `<zwplayer>` component anywhere in your project.
 
-#### 局部注册
+#### Local Registration
 
-在组件中单独注册：
+Register in a single component:
 
 ```javascript
 import { zwplayer } from 'zwplayer-vue2x'
@@ -110,15 +136,12 @@ export default {
     },
     sendDanmu(danmu) {
       console.log('sendDanmu:', danmu)
-      // 调用websocket等方法将弹幕实际发送出去
     }
   }
 }
 ```
 
-### 组件使用
-
-在模板中使用组件：
+### Component Usage
 
 ```html
 <template>
@@ -144,87 +167,158 @@ export default {
 </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.cn/docs/support/guide-configuration.html) | - |
+
+**Thumbnail configuration example:**
 
-#### 1. 基础使用
+```javascript
+thumbnails: {
+  url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
+  width: 160,    // width of each thumbnail
+  height: 90,    // height of each thumbnail
+  row: 9,        // total rows
+  col: 9,        // total columns
+  total: 74      // total number of thumbnails
+}
+```
 
-最简单的播放器配置，展示基本功能：
+**Logo watermark configuration example:**
 
-```html
-<template>
-  <div class="demo">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-      :snapshotButton="true"
-      :optionButton="true"
-      :infoButton="true"
-      :localPlayback="true"
-      :recordButton="true"
-      :segmentButton="true"
-      :autoplay="false"
-      :enableDanmu="true"
-      :chapterButton="true"
-      :fluid="true"
-      :disableMutedConfirm="true"
-      danmuBarId="danmu-controlbar"
-    />
-  </div>
-</template>
+```javascript
+logo: {
+  icon: 'https://cdn.zwplayer.cn/logo.png',  // logo image URL
+  dock: 'right',                             // dock position (left/right/top/bottom)
+  x: '5%',                                   // X offset
+  y: '5%',                                   // Y offset
+  width: '10%',                              // logo width
+  height: '10%',                             // logo height
+  opacity: 70                                // opacity (0-100)
+}
+```
 
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
+### Events
 
-export default {
-  name: 'BasicDemo',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      playerOpen: true
-    }
+| Event Name | Description | Callback Parameters |
+|-----------|-------------|---------------------|
+| onready | Player initialization complete event | - |
+| onmediaevent | Media playback event (play, pause, ended, etc.) | event object, containing `type` and other properties |
+
+```javascript
+methods: {
+  onPlayerReady() {
+    console.log('Player is ready')
+    const player = this.$refs.zwplayerRef
   },
-  methods: {
-    onPlayerReady() {
-      console.log('播放器已准备就绪')
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    }
+  onPlayerMediaEvent(event) {
+    console.log('Media event:', event.type)
+    // event.type: play, pause, ended, timeupdate, etc.
   }
 }
-</script>
 ```
 
-#### 2. 弹幕功能
+### 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')  // add subtitle track
+player.removeSubtitle('1')                     // remove subtitle track
+
+// Danmaku
+player.appendDanmu({
+  border: '1px solid #ccc',
+  text: 'Hello!',
+  color: '#ff6b6b'
+})
+
+// Chapters
+player.setChapters([{
+  title: "Chapter 1",
+  desc: "Chapter 1 description",
+  time: 0,
+  duration: 50
+}])
+
+// Info
+player.getDuration()               // get total duration
+player.getCurrentTime()            // get current playback time
+```
 
-展示播放器弹幕功能，支持实时弹幕发送和接收：
+### Complete Example
 
 ```html
 <template>
-  <div class="demo">
+  <div class="video-player">
     <zwplayer
       v-if="playerOpen"
       ref="zwplayerRef"
+      nodeid="main-player"
       :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
+      :poster="poster"
+      :logo="logo"
+      :thumbnails="thumbnails"
       :autoplay="false"
-      :sendDanmu="sendDanmu"
-      :enableDanmu="true"
       :fluid="true"
+      :enableDanmu="true"
+      :snapshotButton="true"
+      :optionButton="true"
+      :infoButton="true"
+      :chapterButton="true"
+      :recordButton="true"
+      :localPlayback="true"
+      :sendDanmu="sendDanmu"
       :disableMutedConfirm="true"
       danmuBarId="danmu-controlbar"
+      @onready="onPlayerReady"
+      @onmediaevent="onPlayerMediaEvent"
     />
 
-    <!-- 弹幕控制条 -->
     <div class="danmubar" id="danmu-controlbar"></div>
+
+    <div class="controls">
+      <button @click="play">Play</button>
+      <button @click="pause">Pause</button>
+      <button @click="snapshot">Screenshot</button>
+      <button @click="addSubtitle">Add Subtitle</button>
+    </div>
   </div>
 </template>
 
@@ -232,315 +326,289 @@ export default {
 import { zwplayer } from 'zwplayer-vue2x'
 
 export default {
-  name: 'DanmuDemo',
+  name: 'VideoPlayer',
   components: {
     zwplayer
   },
   data() {
     return {
       movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
+      poster: 'https://www.zwplayer.cn/zwplayer-preview.png',
       playerOpen: true,
-      player: null
+      player: null,
+      logo: {
+        icon: 'https://cdn.zwplayer.cn/logo.png',
+        dock: 'right',
+        x: '5%',
+        y: '5%',
+        width: '10%',
+        height: '10%',
+        opacity: 70
+      },
+      thumbnails: {
+        url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
+        width: 160,
+        height: 90,
+        row: 9,
+        col: 9,
+        total: 74
+      }
     }
   },
   methods: {
     onPlayerReady() {
+      console.log('Player is ready')
       this.player = this.$refs.zwplayerRef
-
-      // 添加测试弹幕
-      setTimeout(() => {
-        if (this.player && this.player.appendDanmu) {
-          const testDanmu1 = {
-            border: '1px solid #ccc',
-            text: '欢迎来到 zwplayer 弹幕演示！',
-            color: '#ff6b6b'
-          }
-          this.player.appendDanmu(testDanmu1)
-        }
-      }, 3000)
     },
     onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
+      console.log('Media event:', event.type)
+    },
+    play() {
+      this.player.play()
+    },
+    pause() {
+      this.player.pause()
+    },
+    snapshot() {
+      this.player.snapshot()
+    },
+    addSubtitle() {
+      this.player.addSubtitle('/subtitles/zh.vtt', '1')
     },
     sendDanmu(danmuText) {
-      console.log('发送弹幕:', danmuText)
-
       if (!danmuText) return
-
-      const danmu = {
+      this.player.appendDanmu({
         border: '1px solid #ccc',
         text: danmuText
-      }
-
-      // 将弹幕添加到播放器
-      if (this.player && this.player.appendDanmu) {
-        this.player.appendDanmu(danmu)
-      }
+      })
     }
   }
 }
 </script>
 
 <style scoped>
+.video-player {
+  max-width: 1280px;
+  margin: 0 auto;
+}
+
 .danmubar {
   height: 50px;
   background-color: #232323;
   padding: 8px;
   box-sizing: border-box;
 }
+
+.controls {
+  margin-top: 20px;
+  text-align: center;
+}
+
+.controls button {
+  margin: 0 10px;
+  padding: 8px 16px;
+  background-color: #409eff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.controls button:hover {
+  background-color: #66b1ff;
+}
 </style>
 ```
 
-#### 3. 字幕功能
+## Other Versions
 
-展示播放器字幕功能，支持多语言字幕切换：
+### Vue 3.x
 
-```html
-<template>
-  <div class="demo">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-      :autoplay="false"
-      :fluid="true"
-      :disableMutedConfirm="true"
-    />
-  </div>
-</template>
+```bash
+npm install zwplayervue3 --save
+```
 
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
+Documentation: [zwplayervue3](https://www.zwplayer.cn/guide-vue-framework.html)
 
-export default {
-  name: 'SubtitleDemo',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      playerOpen: true
-    }
-  },
-  methods: {
-    onPlayerReady() {
-      const player = this.$refs.zwplayerRef
-
-      // 添加多个字幕轨道
-      setTimeout(() => {
-        if (player) {
-          player.addSubtitle('/subtitles/zh.vtt', '1')
-          player.addSubtitle('/subtitles/en.vtt', '2')
-        }
-      }, 1000)
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    }
-  }
-}
-</script>
-```
+## Related Resources
 
-#### 4. 缩略图预览
+### Official Documentation
+- [ZWPlayer Official Website](https://www.zwplayer.cn)
+- [Online Demo](https://www.zwplayer.cn/videoplayer.html)
+- [Vue Framework Integration Guide](https://www.zwplayer.cn/docs/support/guide-vue-framework.html)
+- [Configuration Parameters](https://www.zwplayer.cn/docs/support/guide-configuration.html)
+- [API Methods](https://www.zwplayer.cn/docs/support/guide-api.html)
+- [Events](https://www.zwplayer.cn/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)
 
-```html
-<template>
-  <div class="demo">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-      :thumbnails="thumbnails"
-      :enableDanmu="true"
-      :chapterButton="true"
-      :fluid="true"
-      :disableMutedConfirm="true"
-      :autoplay="false"
-    />
-  </div>
-</template>
+## License
 
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
+MIT License. ZWPlayer core library is completely free to use.
 
-export default {
-  name: 'ThumbnailDemo',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      playerOpen: true,
-      thumbnails: {
-        url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
-        width: 160,
-        height: 90,
-        row: 9,
-        col: 9,
-        total: 74
-      }
-    }
-  },
-  methods: {
-    onPlayerReady() {
-      console.log('播放器已准备就绪')
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    }
-  }
-}
-</script>
+## Technical Support
+
+- Email: 893366640@qq.com
+- QQ: 893366640
+- WeChat: zwplayerX
+- Official Account: zwplayer
+
+---
+
+<a id="中文"></a>
+
+基于 Vue 2.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/) |
+
+更多详情请访问：
+1. [zwplayer 官网](https://www.zwplayer.cn)
+2. [在线体验](https://www.zwplayer.cn/videoplayer.html)
+3. [Vue 框架使用](https://www.zwplayer.cn/docs/support/guide-vue-framework.html)
+4. 调用示例项目：
+   - **Gitee**: https://gitee.com/chenfanyu/zwplayer-vue2x-demo
+   - **GitHub**: https://github.com/chenfanyu/zwplayer-vue2x-demo
+
+## 使用说明
+
+### 安装
+
+```bash
+npm install zwplayer-vue2x --save
 ```
 
-#### 5. 章节分段
+#### 安装注意事项
 
-展示播放器章节分段功能：
+⚠️ **重要**：本组件依赖 `zwplayer` 核心库，安装时请注意以下事项：
 
-```html
-<template>
-  <div class="demo">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-      :chapterButton="true"
-      :autoplay="false"
-      :fluid="true"
-      :disableMutedConfirm="true"
-    />
-  </div>
-</template>
+1. **自动配置**：`npm install` 会自动执行 `postinstall` 脚本，该脚本会：
+   - 创建 `public` 目录（如果不存在）
+   - 将 `zwplayer` 核心库复制到 `public/zwplayer` 目录
 
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
+2. **核心库必须发布**：`public/zwplayer` 目录必须随项目一起发布到生产环境
+   - 确保该目录完整包含所有 zwplayer 相关文件
+   - 不要在部署时忽略此目录
 
-export default {
-  name: 'ChapterDemo',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      playerOpen: true
-    }
-  },
-  methods: {
-    onPlayerReady() {
-      const player = this.$refs.zwplayerRef
-
-      setTimeout(() => {
-        if (player) {
-          const chapters = [{
-              title: "分段1",
-              desc: "分段1描述",
-              time: 0,
-              duration: 50,
-              thumb: null
-            },
-            {
-              title: "分段2",
-              desc: "分段2描述",
-              time: 50,
-              duration: 100,
-              style: {
-                background: "blue"
-              },
-              image: null
-            },
-            {
-              title: "分段3",
-              desc: "分段3描述",
-              time: 100,
-              duration: 200,
-              style: {
-                background: "green"
-              },
-              image: null
-            }
-          ]
-          player.setChapters(chapters)
-        }
-      }, 1000)
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    }
-  }
-}
-</script>
+3. **动态加载机制**：zwplayer 采用动态加载机制
+   - 支持无缝升级，无需修改业务代码
+   - 升级时只需替换 `public/zwplayer` 目录中的文件即可
+
+4. **内网/私网部署**：zwplayer 不依赖 CDN，完全支持内网和离线环境部署
+
+### 组件注册
+
+#### 全局注册
+
+在 `src/main.js` 中添加：
+
+```javascript
+import Vue from 'vue'
+import App from './App.vue'
+import ZwModule from 'zwplayer-vue2x'
+
+Vue.use(ZwModule)
+
+new Vue({
+  render: h => h(App),
+}).$mount('#app')
 ```
 
-#### 6. 截图功能
+全局注册后，可在项目任何组件中使用 `<zwplayer>` 组件。
 
-展示播放器截图功能，支持一键截取当前播放画面：
+#### 局部注册
 
-```html
-<template>
-  <div class="demo">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-      :snapshotButton="true"
-      :fluid="true"
-      :autoplay="false"
-      :disableMutedConfirm="true"
-    />
-  </div>
-</template>
+在组件中单独注册：
 
-<script>
+```javascript
 import { zwplayer } from 'zwplayer-vue2x'
 
 export default {
-  name: 'ScreenshotDemo',
+  name: 'MyComponent',
   components: {
     zwplayer
   },
   data() {
     return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
+      movieUrl: 'https://d2zihajmogu5jn.cloudfront.net/elephantsdream/ed_hd.mp4',
       playerOpen: true
     }
   },
   methods: {
     onPlayerReady() {
-      console.log('播放器已准备就绪')
+      console.log('player ready event.')
     },
     onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
+      console.log('media event:', event.type)
+    },
+    sendDanmu(danmu) {
+      console.log('sendDanmu:', danmu)
     }
   }
 }
-</script>
 ```
 
-#### 7. 流式播放
+### 组件使用
 
-展示播放器的流式布局功能，播放器会自适应容器宽度：
+在模板中使用组件：
 
 ```html
 <template>
-  <div class="demo">
+  <div class="player-container">
     <zwplayer
       v-if="playerOpen"
       ref="zwplayerRef"
@@ -553,96 +621,13 @@ export default {
       :infoButton="true"
       :enableDanmu="true"
       :chapterButton="true"
+      danmuBarId="danmu-controlbar"
       :fluid="true"
       :autoplay="false"
       :disableMutedConfirm="true"
     />
   </div>
 </template>
-
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
-
-export default {
-  name: 'FluidDemo',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      playerOpen: true
-    }
-  },
-  methods: {
-    onPlayerReady() {
-      console.log('播放器已准备就绪')
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    }
-  }
-}
-</script>
-```
-
-#### 8. Logo水印
-
-展示播放器Logo水印功能，支持自定义Logo位置、大小和透明度：
-
-```html
-<template>
-  <div class="demo">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-      :autoplay="false"
-      :logo="logo"
-      :poster="poster"
-      :fluid="true"
-      :disableMutedConfirm="true"
-    />
-  </div>
-</template>
-
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
-
-export default {
-  name: 'LogoDemo',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      playerOpen: true,
-      poster: 'https://www.zwplayer.cn/zwplayer-preview.png',
-      logo: {
-        icon: 'https://cdn.zwplayer.cn/logo.png',
-        dock: 'right',
-        x: '5%',
-        y: '5%',
-        width: '10%',
-        height: '10%',
-        opacity: 70
-      }
-    }
-  },
-  methods: {
-    onPlayerReady() {
-      console.log('播放器已准备就绪')
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    }
-  }
-}
-</script>
 ```
 
 ### 主要属性说明
@@ -665,6 +650,17 @@ export default {
 | 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.cn/docs/support/guide-configuration.html) | - |
 
 **缩略图配置对象（thumbnails）示例：**
@@ -705,31 +701,11 @@ logo: {
 | onready | 播放器初始化完成事件 | - |
 | onmediaevent | 媒体播放事件（播放、暂停、结束等） | event对象，包含type等属性 |
 
-**使用示例：**
-
-```javascript
-methods: {
-  onPlayerReady() {
-    console.log('播放器已准备就绪')
-    // 可以在这里进行播放器初始化后的操作
-    const player = this.$refs.zwplayerRef
-    // 例如：添加字幕、设置章节等
-  },
-  onPlayerMediaEvent(event) {
-    console.log('媒体事件:', event.type)
-    // event.type 可能的值：play, pause, ended, timeupdate 等
-  }
-}
-```
-
 ### 方法调用
 
 通过 `ref` 引用调用播放器方法：
 
-**基础方法：**
-
 ```javascript
-// 获取播放器实例
 const player = this.$refs.zwplayerRef
 
 // 播放控制
@@ -738,11 +714,6 @@ player.pause()                   // 暂停
 player.seekTime(120)             // 跳转到指定秒数
 player.stop()                    // 停止
 
-```
-
-**高级方法：**
-
-```javascript
 // 字幕相关
 player.addSubtitle('/subtitles/zh.vtt', '1')  // 添加字幕轨道
 player.removeSubtitle('1')                     // 移除字幕轨道
@@ -762,160 +733,15 @@ player.setChapters([{
   duration: 50
 }])
 
-
 // 获取信息
 player.getDuration()               // 获取视频总时长
 player.getCurrentTime()            // 获取当前播放时间
-
 ```
 
-### 完整示例
-
-结合所有功能的完整组件示例：
-
-```html
-<template>
-  <div class="video-player">
-    <zwplayer
-      v-if="playerOpen"
-      ref="zwplayerRef"
-      nodeid="main-player"
-      :murl="movieUrl"
-      :poster="poster"
-      :logo="logo"
-      :thumbnails="thumbnails"
-      :autoplay="false"
-      :fluid="true"
-      :enableDanmu="true"
-      :snapshotButton="true"
-      :optionButton="true"
-      :infoButton="true"
-      :chapterButton="true"
-      :recordButton="true"
-      :localPlayback="true"
-      :sendDanmu="sendDanmu"
-      :disableMutedConfirm="true"
-      danmuBarId="danmu-controlbar"
-      @onready="onPlayerReady"
-      @onmediaevent="onPlayerMediaEvent"
-    />
-
-    <div class="danmubar" id="danmu-controlbar"></div>
-
-    <div class="controls">
-      <button @click="play">播放</button>
-      <button @click="pause">暂停</button>
-      <button @click="snapshot">截图</button>
-      <button @click="addSubtitle">添加字幕</button>
-    </div>
-  </div>
-</template>
-
-<script>
-import { zwplayer } from 'zwplayer-vue2x'
-
-export default {
-  name: 'VideoPlayer',
-  components: {
-    zwplayer
-  },
-  data() {
-    return {
-      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
-      poster: 'https://www.zwplayer.cn/zwplayer-preview.png',
-      playerOpen: true,
-      player: null,
-      logo: {
-        icon: 'https://cdn.zwplayer.cn/logo.png',
-        dock: 'right',
-        x: '5%',
-        y: '5%',
-        width: '10%',
-        height: '10%',
-        opacity: 70
-      },
-      thumbnails: {
-        url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
-        width: 160,
-        height: 90,
-        row: 9,
-        col: 9,
-        total: 74
-      }
-    }
-  },
-  methods: {
-    onPlayerReady() {
-      console.log('播放器已准备就绪')
-      this.player = this.$refs.zwplayerRef
-    },
-    onPlayerMediaEvent(event) {
-      console.log('媒体事件:', event.type)
-    },
-    play() {
-      this.player.play()
-    },
-    pause() {
-      this.player.pause()
-    },
-    snapshot() {
-      this.player.snapshot()
-    },
-    addSubtitle() {
-      this.player.addSubtitle('/subtitles/zh.vtt', '1')
-    },
-    sendDanmu(danmuText) {
-      if (!danmuText) return
-      this.player.appendDanmu({
-        border: '1px solid #ccc',
-        text: danmuText
-      })
-    }
-  }
-}
-</script>
-
-<style scoped>
-.video-player {
-  max-width: 1280px;
-  margin: 0 auto;
-}
-
-.danmubar {
-  height: 50px;
-  background-color: #232323;
-  padding: 8px;
-  box-sizing: border-box;
-}
-
-.controls {
-  margin-top: 20px;
-  text-align: center;
-}
-
-.controls button {
-  margin: 0 10px;
-  padding: 8px 16px;
-  background-color: #409eff;
-  color: white;
-  border: none;
-  border-radius: 4px;
-  cursor: pointer;
-}
-
-.controls button:hover {
-  background-color: #66b1ff;
-}
-</style>
-```
-
-
 ## 其他版本
 
 ### Vue 3.x
 
-如果你使用 Vue 3.x，请安装 `zwplayervue3`：
-
 ```bash
 npm install zwplayervue3 --save
 ```