# zwplayer-react

React wrapper component for zwplayer, providing easy-to-use video playback capabilities.

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

---

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

React 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)
- [Online Demo](https://www.zwplayer.com/tools/videoplayer/)

## Getting Started

### Installation

```bash
npm install zwplayer-react --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 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 Usage

```jsx
import React, { useRef } from 'react';
import { ZwPlayer } from 'zwplayer-react';

function App() {
  const playerRef = useRef(null);

  const handlePlayerReady = () => {
    console.log('Player ready');
  };

  const handlePlayerMediaEvent = (event) => {
    console.log('Media event:', event.type);
  };

  return (
    <ZwPlayer
      ref={playerRef}
      murl="https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4"
      onready={handlePlayerReady}
      onmediaevent={handlePlayerMediaEvent}
      snapshotButton={true}
      optionButton={true}
      infoButton={true}
      enableDanmu={true}
      chapterButton={true}
      fluid={true}
      autoplay={false}
      disableMutedConfirm={true}
    />
  );
}

export default App;
```

### Danmaku Example

```jsx
import React, { useRef } from 'react';
import { ZwPlayer } from 'zwplayer-react';

function DanmuDemo() {
  const playerRef = useRef(null);

  const handlePlayerReady = () => {
    const player = playerRef.current;
    if (player && player.appendDanmu) {
      player.appendDanmu({
        border: '1px solid #ccc',
        text: 'Welcome to zwplayer!',
        color: '#ff6b6b'
      });
    }
  };

  const handleSendDanmu = (danmuText) => {
    if (!danmuText) return;
    const player = playerRef.current;
    if (player && player.appendDanmu) {
      player.appendDanmu({ border: '1px solid #ccc', text: danmuText });
    }
  };

  return (
    <div>
      <ZwPlayer
        ref={playerRef}
        murl="https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4"
        onready={handlePlayerReady}
        enableDanmu={true}
        sendDanmu={handleSendDanmu}
        fluid={true}
        disableMutedConfirm={true}
        danmuBarId="danmu-controlbar"
      />
      <div id="danmu-controlbar" style={{ height: 50, backgroundColor: '#232323', padding: 8 }}></div>
    </div>
  );
}

export default DanmuDemo;
```

### 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) | - |

### Events

| Event Name | Description | Callback Parameters |
|-----------|-------------|---------------------|
| onready | Player initialization complete | player instance |
| onmediaevent | Media playback event (play, pause, ended, etc.) | event object |

### Method Calls

```jsx
const player = playerRef.current;

// 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()
```

### Example Project

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

## Other Versions

### Vue 2.x

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

### Vue 3.x

```bash
npm install zwplayervue3 --save
```

## Related Resources

### Official Documentation
- [ZWPlayer Official Website](https://www.zwplayer.com)
- [Online Demo](https://www.zwplayer.com/tools/videoplayer/)
- **[React Framework Guide](https://www.zwplayer.com/docs/support/guide-react-framework.html)** — Complete React integration tutorial
- [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)

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

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

更多详情请访问：
- [zwplayer 官网](https://www.zwplayer.com)
- [在线体验](https://www.zwplayer.com/tools/videoplayer/)

## 使用说明

### 安装

```bash
npm install zwplayer-react --save
```

#### 安装注意事项

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

1. **自动配置**：`npm install` 会自动执行 `postinstall` 脚本，将 `zwplayer` 核心库复制到 `public/zwplayer` 目录

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

3. **动态加载机制**：zwplayer 采用动态加载机制，升级时只需替换 `public/zwplayer` 目录中的文件

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

### 组件使用

```jsx
import React, { useRef } from 'react';
import { ZwPlayer } from 'zwplayer-react';

function App() {
  const playerRef = useRef(null);

  return (
    <ZwPlayer
      ref={playerRef}
      murl="https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4"
      onready={() => console.log('Player ready')}
      onmediaevent={(e) => console.log('Media event:', e.type)}
      snapshotButton={true}
      optionButton={true}
      infoButton={true}
      enableDanmu={true}
      chapterButton={true}
      fluid={true}
      autoplay={false}
      disableMutedConfirm={true}
    />
  );
}
```

### 弹幕功能示例

```jsx
import React, { useRef } from 'react';
import { ZwPlayer } from 'zwplayer-react';

function DanmuDemo() {
  const playerRef = useRef(null);

  const handlePlayerReady = () => {
    const player = playerRef.current;
    if (player && player.appendDanmu) {
      player.appendDanmu({
        border: '1px solid #ccc',
        text: '欢迎来到 zwplayer！',
        color: '#ff6b6b'
      });
    }
  };

  const handleSendDanmu = (danmuText) => {
    if (!danmuText) return;
    const player = playerRef.current;
    if (player && player.appendDanmu) {
      player.appendDanmu({ border: '1px solid #ccc', text: danmuText });
    }
  };

  return (
    <div>
      <ZwPlayer
        ref={playerRef}
        murl="https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4"
        onready={handlePlayerReady}
        enableDanmu={true}
        sendDanmu={handleSendDanmu}
        fluid={true}
        disableMutedConfirm={true}
        danmuBarId="danmu-controlbar"
      />
      <div id="danmu-controlbar" style={{ height: 50, backgroundColor: '#232323', padding: 8, boxSizing: 'border-box' }}></div>
    </div>
  );
}
```

### 主要属性说明

| 属性名称 | 类型 | 说明 | 默认值 |
|---------|------|------|--------|
| 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/docs/support/guide-configuration.html) | - |

### 事件

| 事件名称 | 说明 | 回调参数 |
|---------|------|---------|
| onready | 播放器初始化完成 | player 实例 |
| onmediaevent | 媒体事件（播放、暂停、结束等） | event 对象 |

### 方法调用

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

```jsx
const player = playerRef.current;

// 播放控制
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/docs/support/guide-api.html)。

### 示例项目

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

## 其他版本

### Vue 2.x

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

### Vue 3.x

```bash
npm install zwplayervue3 --save
```

## 相关资源

### 官方文档
- [ZWPlayer 官网](https://www.zwplayer.com)
- [在线体验](https://www.zwplayer.com/tools/videoplayer/)
- **[React 框架使用指南](https://www.zwplayer.com/zh/docs/support/guide-react-framework.html)** — 完整的 React 集成教程
- [配置参数文档](https://www.zwplayer.com/docs/support/guide-configuration.html)
- [API 方法文档](https://www.zwplayer.com/docs/support/guide-api.html)
- [事件文档](https://www.zwplayer.com/docs/support/guide-events.html)

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

## 许可证

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

## 技术支持

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