zwplayer-react

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

English | 中文

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

Getting Started

Installation

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

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

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

Events

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

Method Calls

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

npm install zwplayer-vue2x --save

Vue 3.x

npm install zwplayervue3 --save

Related Resources

Official Documentation

• ZWPlayer Official Website
• Online Demo
• React Framework Guide — Complete React integration tutorial
• Configuration Parameters
• API Methods
• Events

License

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

Technical Support

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

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

更多详情请访问：

• zwplayer 官网
• 在线体验

使用说明

安装

npm install zwplayer-react --save

安装注意事项

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

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

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

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

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

组件使用

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}
    />
  );
}

弹幕功能示例

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 播放器构造函数参数 | - |

事件

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

方法调用

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

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 文档。

示例项目

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

其他版本

Vue 2.x

npm install zwplayer-vue2x --save

Vue 3.x

npm install zwplayervue3 --save

相关资源

官方文档

• ZWPlayer 官网
• 在线体验
• React 框架使用指南 — 完整的 React 集成教程
• 配置参数文档
• API 方法文档
• 事件文档

示例项目

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

许可证

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

技术支持

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

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