=== ZW Player Video Embed ===
Contributors: zwplayer
Donate link: https://www.zwplayer.com/
Tags: video player, live streaming, hls, dash, html5
Requires at least: 5.8
Tested up to: 6.9
Requires PHP: 7.0
Stable tag: 3.3.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Professional HTML5 video player with VR/360° panoramic playback, multi-audio-track switching, subtitles, chapters, annotations, watermarks, playlists, magnifier, casting, and 6 online editing tools.

== Description ==

ZW Player Video Embed is a professional-grade HTML5 video player WordPress plugin supporting all major video formats and streaming protocols. It provides a complete video publishing workflow with companion online editing tools — no coding required.

Perfect for: live streaming, online courses, video portfolios, surveillance feeds, interactive training, and media publishing.

= Codec & Protocol Support =

**Video Codecs**: H.264, H.265/HEVC, AV1
**Audio Codecs**: MP3, Opus
**VOD Protocols**: HLS, DASH, HTTP-FLV, HTTP-MP4
**Live Protocols**: HTTP-FLV, WebSocket-FLV, HLS, DASH, TS, WebRTC, RTSP

= Player Features =

* VR / 360° panoramic video playback with interactive controls
* Multi-audio-track switching with TTS subtitle-to-speech
* Screenshot and video recording
* Segmented loop playback
* Picture-in-picture (PIP) and auto mini player
* Multi-quality switching
* Playback speed control
* Local file playback (no upload needed)
* Volume gain (up to 4x)
* Keyboard shortcuts
* Multi-language UI

= Subtitle System =

* Multi-track subtitle management with free primary/secondary track assignment
* Supports URL, VTT, SRT, BCC formats and drag-and-drop loading
* Built-in translation panel supporting 13 target languages
* HLS embedded Closed Captions pre-build with full-text search
* Per-track settings for font size, color, outline, position, and background opacity
* Subtitle loop for language learning scenarios
* Subtitle download (SRT export)
* Companion [online subtitle editor](https://www.zwplayer.com/tools/subtitle/) with AI speech recognition

= Chapter Navigation =

* Video segment navigation with JSON/VTT format support
* Color-coded progress bar markers
* Built-in search panel with keyword jump
* Companion [online chapter editor](https://www.zwplayer.com/tools/chapter/)

= Thumbnail Preview =

* Progress bar hover preview via sprite sheets
* Companion [online thumbnail generator](https://www.zwplayer.com/tools/thumbnail/)

= Logo & Watermark =

* **Logo / Station Badge**: Image logo with configurable position, dock, size, and opacity
* **Watermark System**: Supports image and text types with three behavior modes:
  * Static — fixed position display
  * Dynamic / Marquee — moving watermark for anti-screen-recording
  * Tile — dense coverage for copyright protection
* Text watermarks support template variables (e.g., `{user_name}`, `{sys_time}`)
* Backward compatible with legacy `logo` parameter
* Companion [online watermark editor](https://www.zwplayer.com/tools/watermark/)

= Interactive Annotations (ZWMAP Protocol) =

* 13 node types: hotspot, text, image, button, choice, quiz, form, vote, card, webview, map, countdown, speed controller
* 3-phase animation system with 18 effects
* Color-coded progress bar visualization
* Event-driven action chains
* Mandatory/no-skip and pause-on-show for educational scenarios
* Session variable system
* Companion [online annotation editor](https://www.zwplayer.com/tools/annotation/) with timeline-based visual editing

= Playlist =

* Multi-level grouping (Group → Item) based on ZWMAP protocol
* Per-item configuration for video URL, poster, subtitles, chapters, thumbnails, annotations, and watermarks
* Auto-save playback progress per item with resume on next visit
* Auto-play next item with configurable behavior
* Favorites and play history with localStorage persistence
* Real-time search with keyword highlighting
* Dual-panel and single-panel adaptive layouts
* "Up Next" preview panel
* Companion [online playlist editor](https://www.zwplayer.com/tools/playlist/)

= Magnifier & Screen Casting =

* **Magnifier**: Canvas-based circular magnifier with 1.5x–4x zoom levels and `Z` hotkey toggle
* **Screen Casting**: Google Cast and AirPlay support via native browser APIs

= ZWMAP Data Protocol =

ZWMAP/1.0 (ZWPlayer Media Application Protocol) defines a standardized JSON data exchange format for six modules: thumbnails, subtitles, chapters, playlists, annotations, and watermarks. All companion online editors generate ZWMAP-compliant data that can be directly loaded by the player, enabling a seamless "online editor → export data → WordPress publish" zero-code workflow.

= WordPress Integration =

1. **Gutenberg Block** — Visual editor with advanced settings panels for all features
2. **Shortcode** — `[zwplviem url="video-url" ...]` with full attribute support
3. **Classic Editor Button** — One-click insert
4. **Multiple Instances** — Support for multiple players on a single page
5. **JSON Configuration** — Advanced setups via JSON attributes

= Online Tool Ecosystem =

Six companion web-based editors generate ZWMAP-compliant JSON data that can be directly used in Gutenberg blocks or shortcodes:

1. [Thumbnail Generator](https://www.zwplayer.com/tools/thumbnail/)
2. [Chapter Editor](https://www.zwplayer.com/tools/chapter/)
3. [Subtitle Editor](https://www.zwplayer.com/tools/subtitle/)
4. [Playlist Editor](https://www.zwplayer.com/tools/playlist/)
5. [Annotation Editor](https://www.zwplayer.com/tools/annotation/)
6. [Watermark Editor](https://www.zwplayer.com/tools/watermark/)

= Framework & Platform Support =

* **WordPress Plugin**: Full support for all v3.3.1 features via Gutenberg block and shortcode
* **Vue 2 / Vue 3**: npm package `zwplayervue3`
* **React**: Native integration via `useRef` + `useEffect` hooks
* **UMD Module**: Compatible with CommonJS, AMD, and browser global imports

== Installation ==

1. Upload to /wp-content/plugins/zw-player-video-embed/
2. Activate in WordPress 'Plugins' screen
3. Use Gutenberg block or shortcode [zwplviem url="your-video-url"]

== Frequently Asked Questions ==

= What formats are supported? =

H.264/H.265/AV1 video, MP3/Opus audio. Protocols: HLS, DASH, FLV, MP4, WebRTC, RTSP.

= Can I use it for live streaming? =

Yes. Enable "Live Stream" mode or add isLive="true" to shortcode.

= How to add multiple qualities? =

Use JSON in URL field: [{"name":"1080p","url":"hd.mp4","default":true},{"name":"720p","url":"sd.mp4"}]

= Does it support picture-in-picture? =

Yes, including auto mini player when scrolling.

= How to add subtitles? =

Use the `subtitles` attribute with a JSON array: `[zwplviem url="video.mp4" subtitles='[{"url":"https://example.com/en.vtt","name":"English"},{"url":"https://example.com/zh.srt","name":"中文"}]']`. You can also use the legacy `subtitle1` and `subtitle2` attributes for backward compatibility. The player supports VTT, SRT, BCC formats and drag-and-drop loading. Use the [online subtitle editor](https://www.zwplayer.com/tools/subtitle/) to create subtitle files.

= How to configure chapter navigation? =

Use the `chapters` attribute with a JSON URL or inline JSON array: `[zwplviem url="video.mp4" chapters="https://example.com/chapters.json"]` or `[zwplviem url="video.mp4" chapters='[{"title":"Intro","time":0,"duration":30},{"title":"Main","time":30,"duration":120}]']`. Use the [online chapter editor](https://www.zwplayer.com/tools/chapter/) to create chapter data.

= How to add a watermark? =

Use the `watermarks` attribute: `[zwplviem url="video.mp4" watermarks='[{"type":"text","text":"{user_name}","behavior":"marquee"}]']`. Supports static, dynamic (marquee), and tile modes. Use the [online watermark editor](https://www.zwplayer.com/tools/watermark/) for visual editing.

= How to use interactive annotations? =

Use the `annotations` attribute with a ZWMAP JSON URL or inline data: `[zwplviem url="video.mp4" annotations="https://example.com/annotations.json"]`. The annotation system supports 13 node types including hotspot, button, quiz, and form. Use the [online annotation editor](https://www.zwplayer.com/tools/annotation/) for timeline-based visual editing.

= What is the ZWMAP protocol? =

ZWMAP/1.0 (ZWPlayer Media Application Protocol) is a standardized JSON data format used by all six online editing tools. Data exported from any editor can be directly loaded by the player via shortcode attributes, enabling a zero-code workflow.

= How to add a logo or station badge? =

Use the `logo` attribute with an image URL or JSON config: `[zwplviem url="video.mp4" logo="https://example.com/logo.png"]` for simple usage, or `[zwplviem url="video.mp4" logo='{"icon":"logo.png","dock":"right","x":"5%","y":"5%","width":"15%","opacity":70}']` for advanced positioning.

= How to enable thumbnail preview on the progress bar? =

Set `useProgressTooltip="true"` and provide thumbnail data: `[zwplviem url="video.mp4" useProgressTooltip="true" thumbnails="https://example.com/thumbnails.json"]`. Use the [online thumbnail generator](https://www.zwplayer.com/tools/thumbnail/) to create sprite sheets and configuration.

== Screenshots ==

1. Gutenberg block editor
2. Player with custom poster
3. Live streaming interface
4. Picture-in-picture mode
5. Multi-quality selector
6. Mobile responsive view

== External Services & Third-Party Libraries ==

This plugin includes minified JavaScript libraries for video playback. Below are the sources and licenses for each library:

= ZWPlayer Core (zwplayer.js) =
This is the main player library developed by ZW Player Team.
Documentation: https://www.zwplayer.com/
License: Proprietary - The minified zwplayer.js is provided for use within this plugin. Source code is not publicly available.

= DASH.js (dash.all.min.js) =
A JavaScript library for playing DASH (Dynamic Adaptive Streaming over HTTP) content.
Source: https://github.com/Dash-Industry-Forum/dash.js
License: BSD-3-Clause
Version included: 4.x

Note: This library may reference XML schemas (schemas.xmlsoap.org) for MPD manifest parsing. No user data is transmitted to external servers during normal playback.

= HLS.js (hls.min.js, hls.light.min.js) =
A JavaScript library for playing HLS (HTTP Live Streaming) content in browsers.
Source: https://github.com/video-dev/hls.js
License: Apache-2.0
Version included: 1.x

= FLV.js (flv.min.js, flv.live.js) =
A JavaScript library for playing FLV (Flash Video) content via HTTP-FLV or WebSocket-FLV streaming.
Source: https://github.com/bilibili/flv.js
License: Apache-2.0

= MPEGTS.js (mpeg.min.js) =
A JavaScript library for playing MPEG-TS streams.
Source: https://github.com/xqq/mpegts.js
License: Apache-2.0

= Build Tools =
No build tools are required for this plugin. All JavaScript files are pre-built and included as-is. The libraries above are used directly without additional compilation.

== Changelog ==

= 3.3.3 =
* Added: VR / 360° panoramic video playback with interactive drag/touch/keyboard controls, live view settings panel, and auto-detection of 2:1 panoramic videos
* Added: Multi-audio-track switching with TTS subtitle-to-speech support
* Updated: Streamlined control bar UI with refined time progress, speed controller, and playback indicators
* Updated: ZWPlayer core library to v3.3.1

= 3.3.2 =
* Added: ZWMAP/1.0 unified data protocol for standardized JSON data exchange across six modules
* Added: Interactive annotation system with 13 node types (hotspot, text, image, button, choice, quiz, form, vote, card, webview, map, countdown, speed controller)
* Added: 3-phase annotation animation system with 18 effects and event-driven action chains
* Added: Watermark system with static, dynamic (marquee), and tile modes; image/text types with template variables
* Added: Multi-track subtitle management with free primary/secondary track assignment
* Added: Built-in subtitle translation panel supporting 13 target languages
* Added: HLS embedded Closed Captions pre-build with full-text search and export
* Added: Per-track subtitle settings (font size, color, outline, position, background opacity)
* Added: Subtitle loop for language learning scenarios
* Added: Playlist with multi-level grouping (Group → Item), per-item feature configuration
* Added: Playlist auto-save progress, auto-play next, favorites, search, and "Up Next" panel
* Added: Progress bar thumbnail preview via sprite sheets
* Added: Chapter navigation with JSON/VTT formats, color-coded progress markers, and search panel
* Added: Magnifier with 1.5x–4x zoom and Z hotkey toggle
* Added: Screen casting (Google Cast and AirPlay) via native browser APIs
* Added: Six companion online editors (thumbnail, chapter, subtitle, playlist, annotation, watermark)
* Added: New config options (defVolume, hideControlbarTimeout, timeFormat, translateApi, subtitleDownload, iosWebFullscreen)
* Updated: ZWPlayer core library to v3.3.0 with full backward compatibility
* Updated: Enhanced Gutenberg block with advanced settings panels for all new features

= 3.3.0 =
* Added: Dual subtitle support (URL, VTT, SRT, BCC formats)
* Added: Chapter navigation with JSON or URL configuration
* Added: Progress bar thumbnail preview
* Added: Logo / station badge with position and opacity control
* Added: Dynamic watermark with marquee and timed display
* Added: Interactive annotations (ZWMAP protocol)
* Added: Enhanced Gutenberg block with advanced settings panel
* Updated: ZWPlayer core library (performance improvements)
* Updated: Player UI styles and icon font

= 2.0 =
* Added: H.265/HEVC and AV1 support
* Added: WebRTC and RTSP streaming
* Added: Video recording and segmented playback
* Added: Auto mini player
* Improved: Gutenberg block UI
* Fixed: Text domain issues

= 1.0 =
* Initial release with HLS, DASH, FLV support

== Upgrade Notice ==

= 3.3.3 =
Feature update: VR/360° panoramic video playback, multi-audio-track switching with TTS subtitle-to-speech support, streamlined control bar UI, and ZWPlayer core v3.3.1. Recommended for all users.

= 3.3.2 =
Major feature update: ZWMAP protocol, interactive annotations (13 node types), watermark system, multi-track subtitles with translation, playlist management, magnifier, screen casting, and six online editing tools. Full backward compatible. Recommended for all users.

= 2.0 =
Major update with new codecs and recording features. Recommended for all users.