Parameter Configuration

1. Player Interface Description

To facilitate the explanation of the subsequent parameters, the figure below shows a screenshot of a player instance:

2. Configuration Overview

When creating a zwplayer object, we need to pass a JS object to the zwplayer constructor as a parameter. A sample JS object for a constructor parameter with relatively complete attributes is shown below (subsequent new versions may add members due to feature enhancements, but will not remove or modify the property names defined in previous versions, ensuring the stabilization of the existing API for seamless replacement and upgrades).

new ZWPlayer({
  // Basic Configuration
  playerElm: '#player-holder',
  url: 'https://example.com/video.mp4',
  videostyle: "width:100%;height:100%;",
  poster: 'https://example.com/poster.jpg',
  fluid: true,
  ratio: '16:9',
  // Playback Control
  autoplay: true,
  muted: false,
  reconnect: true,
  isLive: false,
  // Control Bar Display Buttons
  infoButton: true,
  speedButton: true,
  optionButton: true,
  snapshotButton: true,
  useProgressTooltip: true,
  chapterButton: true,
  enableDanmu: true,
  fixedControlbar: true,
  defVolume: 61.25,
  hideControlbarTimeout: 10000,
  // Advanced Features
  enableDanmu: true,
  castButton: true,
  zoomButton: true,
  annotationButton: true,
  thumbnails: {
    url: "http://example.com/thumbnail.jpg",
    width: 128,
    height: 72,
    row: 7,
    col: 7,
    total: 43
  },
  chapters: 'http://example.com/chapters.json',
  annotations: 'http://example.com/annotations/movie_annotation.json',
  subtitles: 'http://example.com/subtitles/movie.vtt',
  playlistButton: true,
  playlist: {
    url: 'http://example.com/playlist/my_playlist.json'
  },
  logo: {
    icon: 'logo.png',
    dock: 'left',
    x: '5%',
    y: '5%',
    width: '30%',
    height: '30%',
    opacity: 70
  },
  
  // Feature Restrictions
  disablePlayBtn: false,
  disableSeek: false,
  disableFullscreenWin: false,
  disablePicInPic: false,
  disableVolumeControl: false,
  autoSmallWindow: true,
  lostFocusPause: true,
  
  // Callback Functions
  onready: function() {
    console.log("Player ready");
  },
  onmediaevent: function(event) {
    // Handle media events
  },
  sendDanmu: function(text) {
    // Send Danmu
  }
});

Except for playerElm and url, which are required, all parameters for the zwplayer constructor are optional. Please set them according to specific needs.

3. Basic Configuration

3.1 *playerElm - Player Container

• Type: string | DomObject
• Default Value: None
• Required
• Description: Used to specify the docking element for the player. It should be the ID of a DIV or a DOM object of DIV type. If a string parameter is passed, it can be with or without the “#” prefix; both will be treated as the element’s ID. If it is a DOM object, that DOM object must be of DIV type. If the passed playerElm is not an existing DOM, zwplayer will attempt to create a new DIV DOM element to serve as the docking point for the player.
• Example: 'mse' or '#mse' or document.getElementById('mse')

new ZWPlayer({
    playerElm: '#mse',
    ...
});

3.2 *url - Source Address

• Type: string | Object

• Default Value: None

• Required

• Description: The access address of the media stream. The following input methods are supported:

  • String URL: Directly pass the video address (MP4, HLS, FLV, DASH, WebRTC, etc.).
  • JS Object: Pass an object containing rich configurations to simultaneously set video, thumbnails, chapters, annotations, subtitles, playlists, etc. Please see Source Address URL Details.

// Method 1: Simple String
new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4'
});

// Method 2: JS Object (Supports configuring multiple resources simultaneously)
new ZWPlayer({
    playerElm: '#mse',
    url: {
      src: 'https://example.com/video.mp4',
      thumbnails: 'https://example.com/thumbnails/movie_thumbnail.json',
      chapters: 'https://example.com/chapters/movie_chapter.json',
      annotations: 'https://example.com/annotations/movie_annotation.json',
      subtitles: 'https://example.com/subtitles/movie.vtt'
    }
});

// Method 3: Pass ZWMAP Playlist JSON URL (auto-detected)
new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/playlist/my_playlist.json'
});

// Method 4: Pass ZWMAP Playlist JSON object directly (no hosted file needed)
new ZWPlayer({
    playerElm: '#mse',
    url: {
      zwp_protocol: 'ZWMAP/1.0',
      zwp_type: 'playlist',
      title: 'My Playlist',
      groups: [
        {
          name: 'Group One',
          items: [
            { name: 'Video 1', url: 'https://example.com/video1.mp4' }
          ]
        }
      ]
    }
});

Playlist

The url parameter supports two ways to provide a playlist:

1. JSON File URL: Point to a .json file conforming to the ZWMAP protocol. The player auto-detects and loads it.
2. Inline JSON Object: Pass the ZWMAP playlist object directly as the url parameter — no hosted file needed. Ideal for dynamically generated playlists.

The player automatically detects zwp_type: "playlist" and loads it in playlist mode — no extra configuration needed. The player renders the grouped list UI, supports auto-play next, remembers playback progress, and enables favorites.

The playlist JSON must conform to the ZWMAP playlist type (zwp_type: "playlist"), supporting grouped structures and associated resources for each video item.

ZWMAP Playlist JSON Example:

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "zwp_version": "1.0",
  "id": "demo_list_001",
  "title": "Demo Playlist",
  "autoPlayNext": true,
  "groups": [
    {
      "id": "g1",
      "name": "Tutorial Videos",
      "expanded": true,
      "items": [
        {
          "id": "v1",
          "name": "Lesson 1: Basics",
          "url": "https://cdn.example.com/video/lesson1.mp4",
          "type": "mp4",
          "poster": "https://cdn.example.com/poster/lesson1.jpg",
          "subtitle": "https://cdn.example.com/sub/lesson1.vtt",
          "chapter": "https://cdn.example.com/chapter/lesson1.json",
          "annotation": "https://cdn.example.com/annotation/lesson1.json",
          "thumbnails": "https://cdn.example.com/thumbnail/lesson1.json"
        },
        {
          "id": "v2",
          "name": "Lesson 2: Advanced Content",
          "url": "https://cdn.example.com/video/lesson2.mp4",
          "type": "mp4",
          "subtitle": [
            "https://cdn.example.com/sub/lesson2_zh.vtt",
            "https://cdn.example.com/sub/lesson2_en.vtt"
          ]
        }
      ]
    },
    {
      "id": "g2",
      "name": "Live Channels",
      "expanded": false,
      "items": [
        {
          "id": "live1",
          "name": "CCTV-1",
          "url": "https://live.example.com/cctv1.flv",
          "type": "flv",
          "isLive": true
        }
      ]
    }
  ]
}

Playlist Field Description:

Video Item (VideoItem) Fields:

3.3 videostyle - Player Style

• Type: string
• Default Value: None
• Description: CSS set on the player’s built-in Video object; must be a compliant CSS description statement.
• Example: "width:100%;height:100%;"

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4',
    videostyle: "width:100%;height:100%;",
});

3.4 poster - Poster

• Type: String
• Default Value: None
• Description: Sets the poster, which is the image displayed in the video area of the player when the player is stopped.

3.5 fluid - Fluid Layout

• Type: Boolean
• Default Value: false
• Description: Sets to fluid layout, allowing the player’s width to follow the size changes of the parent element, and the height to change according to the ratio of height to width in the configuration items (if player width and height are not set, it is calculated based on internal default values). The aspect ratio calculation algorithm is as follows:
  • If the ratio attribute is set, the ratio attribute value is the aspect ratio.
  • If the ratio attribute is not set, the ratio of width to height is calculated by calculating the ratio of width and height.
  • If width and height attributes are not set, the aspect ratio defaults to 16:9.

3.6 ratio - Aspect Ratio

• Type: Number | String
• Default Value: 16:9
• Description: Sets the aspect ratio of the player, in the format “width:height”, e.g., “16:9”. Takes effect when fluid layout is enabled.

3.7 width - Width

• Type: Number | String
• Default Value: None
• Description: Player width. If a number type parameter is passed, the player internally defaults to adding the unit px; if a string type parameter is passed, it is directly assigned to the player container’s width style attribute.

3.8 height - Height

• Type: Number | String
• Default Value: None
• Description: Player height. If a number type parameter is passed, the player internally defaults to adding the unit px; if a string type parameter is passed, it is directly assigned to the player container’s height style attribute.

3.9 lang - Language Setting

• Type: String

• Default Value: Automatically detected based on browser interface language; if Chinese, it is Chinese; otherwise, it is English.

• Description: Sets the interface language of the player. Supports multi-language localization, affecting all text content such as the player control bar, prompt messages, and menus.

• Supported Languages:

  • 'zh-CN' or 'zh': Simplified Chinese
  • 'en-US' or 'en': English

4. Playback Control

4.1 autoplay - Auto Play

• Type: Boolean
• Default Value: false
• Description: Whether to start playback automatically. If set to false, the player must click the play button to start playback.
• Note: Under the restrictions of the latest browsers, auto-play on new pages needs to be combined with muted set to true.
• Feature: zwplayer has a built-in auto-detection function. If this parameter is set to true, when the player attempts to open audio playback and fails, it will automatically set the player to muted to start playback. Subsequently, the user needs to click the Unmute prompt button to turn on the sound.
• Reference: ZWPlayer Auto-Play Complete Guide: Solving Mute Issues and Scenario-Based Configuration

4.2 disableMutedConfirm - Disable Auto-Play Mute Confirmation Modal

• Type: Boolean
• Default Value: true
• Description: Whether to disable the mute confirmation modal triggered by the browser’s auto-play policy.
• Detailed Behavior: When the player’s autoplay attribute is set to true, zwplayer will attempt to start playback automatically. However, modern browser auto-play policies usually require video with sound to play only after user interaction with the page. To cope with this policy and provide a seamless experience, zwplayer has a built-in auto-detection mechanism:

• · Detection and Fallback: If auto-play with sound fails due to browser policy, the player will automatically set the video to muted state and start playback.

• · User Prompt (Default Behavior): Subsequently, the player will pop up a modal prompt explaining to the user: “Due to browser restrictions, the video is playing muted. Please click the screen to turn on the sound.” This prompt requires the user to manually click to close it, ensuring the user is aware of the current silent state and avoiding confusion.

The disableMutedConfirm attribute is used to control the display of this prompt:

• · When set to false (default value), the modal prompt described above will display normally.
• · When set to true, this modal prompt will be disabled. Even if playback switches to muted due to policy restrictions, no prompt requiring interaction will pop up.

Applicable Scenario Recommendations:

• · Set to true: Suitable for scenarios pursuing ultimate immersive, uninterrupted experience, such as background videos, advertisements, or video displays without audio. Developers need to inform users of the muted state via UI or other means themselves.
• · Keep false (default): Suitable for general video playback scenarios where it is necessary to clearly inform the user of the current state and avoid user confusion due to sudden silence, such as news, education, and main site players, which can effectively improve the clarity of user experience.

4.3 muted - Mute

• Type: Boolean
• Default Value: false
• Description: Whether the player starts muted. In current H5 browsers, if auto-play is set but mute is not set, automatic playback may fail to start without user interaction.

4.4 reconnect - Reconnect on Disconnect

• Type: Boolean
• Default Value: None
• Description: Whether the player reconnects on failure. true means automatic reconnection after playback disconnection. When receiving live streams, it is recommended to set this to true, so that if there is a network failure or server failure, the player will automatically reconnect.

4.5 isLive - Live Stream Flag

• Type: Boolean
• Default Value: None
• Description: Specifies whether the program source is a live-type stream. Live streams cannot seek progress or adjust playback rate. This is very useful in specific situations where a VOD source needs to be disguised as a live program. Defaults to the player automatically detecting whether it is a live source.

5. Streaming Protocol Configuration

5.1 streamtype - Stream Protocol Type

• Type: String

• Default Value: None

• Description: Manually specify the stream protocol type. Supports: httpflv, hls, dash, mpegts, webrtc. This parameter must be specified when the live stream address has no file extension.

• Feature: zwplayer determines the stream protocol through the live stream address extension. The corresponding relationship is as follows:

  File Extension	Corresponding Protocol	Description
  flv	http-flv	HTTP-FLV streaming protocol
  m3u8	HLS	HTTP Live Streaming protocol
  mpd	DASH	Dynamic Adaptive Streaming over HTTP protocol
  rtc	Webrtc	Web Real-Time Communication protocol
  ts	mpegts	MPEG Transport Stream protocol

However, if the live stream address does not contain an extension, zwplayer will be unable to determine which protocol to use to play the stream. In this case, you must manually specify the stream type.

5.2 useFlv - FLV Priority

• Type: Boolean
• Default Value: false
• Description: zwplayer supports multi-protocol type live program source objects (using a JS object as the url parameter). A live program source may contain multiple types of streams. For example, a multi-protocol live source may simultaneously include webrtc, http-flv, hls, dash, and other transmission protocol types. If this parameter is set to true, when zwplayer detects that the program source type contains an http-flv stream, it will prioritize using the flv stream for playback; otherwise, zwplayer will make an automatic decision to select the transmission type with the lowest latency for playback.

5.3 useOldFlv - Enable FLV Old Interface

• Type: Boolean
• Default Value: false
• Description: When playing Flv type live streams, whether to use the old playback interface. Using the old Flv playback interface, zwplayer will not be able to play video streams containing H265/HEVC. This is only for testing compatibility and defaults to false. In new Chrome browsers (and some Safari browsers), zwplayer supports live sources containing H265.

5.4 hasAudio - Contains Audio Stream

• Type: Boolean
• Default Value: None
• Description: Specifies whether the stream to be played contains an audio stream. If omitted, the player automatically determines whether the URL to be played contains an audio stream. If the URL to be played actually does not contain an audio stream, but hasAudio is set to true, the player will keep searching for the audio stream in the stream before starting playback. If not found, the player will wait indefinitely. For streams from some surveillance cameras, this parameter can be set to false, so the player will not search for audio streams, and playback will start faster.

5.5 hasVideo - Contains Video Stream

• Type: Boolean
• Default Value: None
• Description: Specifies whether the stream to be played contains a video stream. If omitted, the player automatically determines whether the URL to be played contains a video stream. If the URL to be played actually does not contain a video stream, but hasVideo is set to true, the player will keep searching for the video stream in the stream before starting playback. If not found, the player will wait indefinitely.

5.6 xmc_url - Media Gateway Address

• Type: String
• Default Value: None
• Description: xmc_url is the media gateway address. xmc stands for External Media Coprocessor (abbreviated as: Media Gateway). Some common streaming protocols, such as RTSP, UDP, RTP, etc., cannot be played by current browsers’ H5 video playback because current H5 cannot support raw sockets, so it cannot implement the retrieval of these protocol streams. One solution is to use an external server to convert the protocol to HTTP or WebRTC protocol, so that the H5 player can play RTSP, UDP, RTP streams. Using xmc, zwplayer supports playing RTSP, UDP, and other live streams in the browser, which is very helpful for playing RTSP streams output by most current surveillance device manufacturers. The co-processing protocol supported by zwplayer uses the WebSocket protocol. For details, please refer to Playing RTSP Streams.

6. Control Bar Display Configuration

6.1 controlbar - Player Control Bar

• Type: Boolean
• Default Value: true
• Description: Whether to display the player control bar. To facilitate user operation, the player will have a playback control bar containing various buttons, such as play, pause, full screen, etc. In certain application scenarios, if the playback control bar is not needed, this parameter can be set to false. Note that since the native playback control bar of the H5 browser’s video tag is not satisfactory, zwplayer has built a custom playback control bar that presents a consistent appearance across all browsers. The various buttons on the custom playback control bar support configuration to control whether they are displayed.

6.2 nativecontrols - Native Playback Control Bar

• Type: Boolean
• Default Value: false
• Description: Whether to use the browser’s native playback control bar. If true, the native playback control bar of the browser’s video element is used. The appearance of the native playback control bar may differ in different browsers. If you want users to see a consistent appearance across different browsers, please do not set this attribute to true. When set to false, zwplayer creates a custom playback control bar to control playback and disables the native playback control bar. Using the native playback control bar is not recommended.

6.3 infoButton - Media Info Button

• Type: Boolean
• Default Value: false
• Description: Whether to display the media info button on the playback control bar. The playback info button is used to display information related to the currently playing media.

6.4 speedButton - Playback Rate Control Button

• Type: Boolean
• Default Value: false
• Description: Whether to display the playback rate control button on the playback control bar. Playback rate control is only effective for VOD programs. If it is a live program, even if set to true, the player will not display the playback rate control button.

6.5 optionButton - Player Settings Button

• Type: Boolean
• Default Value: false
• Description: Whether to display the player settings button on the playback control bar. If true, a settings button will appear on the playback control bar. When the mouse moves over the settings button, a settings menu will pop up. Currently configurable settings include image rotation, loop playback control, and video chroma adjustment. Future versions may have richer settings functions.

6.6 snapshotButton - Image Capture Button

• Type: Boolean
• Default Value: false
• Description: Whether to display the image capture button on the playback control bar. Clicking the image capture button allows users to capture the currently playing video image with one click.

6.7 enableDanmu - Danmu Feature

• Type: Boolean
• Default Value: false
• Description: Whether to enable the built-in Danmu (bullet comments) display function. Danmu, as an interactive control function for current video playback, is already supported by major video websites. Using zwplayer’s Danmu function can also achieve the same functionality as major video websites. If this item is not set, the zwplayer player cannot display Danmu.

6.8 useProgressTooltip - Progress Bar Preview Display

• Type: Boolean
• Default Value: false
• Description: Whether to enable tooltips on the playback progress bar. If enabled, when the user moves the mouse over the playback progress bar, an event tooltip will appear following the mouse pointer. For video-on-demand programs, if there are thumbnails, this parameter must be set to true.

6.9 autoSmallWindow - Auto Small Window

• Type: Boolean
• Default Value: false
• Description: Automatically switch to pop-up small window playback when the window scroll is about to hide the player. When the page is long and has a scroll bar, if the user scrolls the page, it may cause zwplayer to be scrolled out of the page and hidden. If this parameter is set to true, when this happens, zwplayer automatically switches to small window playback. Note: The small window is different from Picture-in-Picture. Picture-in-Picture is a small video window floating on top of all windows on the current desktop, while small window playback is a small video window only inside the current browser tab, not floating out.

6.10 fixedControlbar - Fixed Control Bar

• Type: Boolean
• Default Value: true
• Description: Whether to always display the player control bar. If set to false, the control bar automatically hides after the timeout set by hideControlbarTimeout.

6.11 timeFormat - Time Display Format

• Type: String
• Default Value: 's'
• Description: Controls the display precision of the time code on the player control bar. 's' displays to seconds (e.g., 01:30), 'ms' displays to milliseconds (e.g., 01:30.500). Suitable for scenarios requiring precise time positioning, such as subtitle editing, video annotation, etc.

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4',
    timeFormat: 'ms'  // Display millisecond precision: 00:01:30.500
});

6.12 defVolume - Default Volume

• Type: Number
• Default Value: 61.25
• Description: The default volume percentage when the player starts, range 0–100. The player will remember this value; user adjustments via the interface will override this default value.

6.13 hideControlbarTimeout - Control Bar Auto-Hide Timeout

• Type: Number
• Default Value: 10000
• Description: The timeout for the control bar to auto-hide, in milliseconds. When fixedControlbar is set to false, the player automatically hides the control bar after no user operation for this duration. Default is 10 seconds.

6.14 castButton - Cast Button

• Type: Boolean
• Default Value: false
• Description: Whether to display the cast button on the playback control bar. The casting feature uses the browser’s native Cast API (such as Chromecast, AirPlay) to cast the current video to supported devices for playback. The button only appears when the browser supports the casting protocol.

6.15 zoomButton - Magnifier Button

• Type: Boolean
• Default Value: false
• Description: Whether to display the magnifier button on the playback control bar. Once enabled, users can click the magnifier button to enter zoom mode, using the mouse wheel or dragging to magnify local details of the video image. Suitable for teaching demonstrations, medical imaging, and other scenarios requiring detail observation.

6.16 annotationButton - Annotation Edit Button

• Type: Boolean
• Default Value: Defaults to true when annotations property is configured, otherwise false
• Description: Whether to display the annotation edit button on the playback control bar. This button is used to open the online annotation editor to visually edit interactive annotations for the current video. This button only appears when the annotations parameter is configured, and can be disabled by explicitly setting it to false.

6.17 localPlayback - Local File Playback

• Type: Boolean
• Default Value: false
• Description: Whether to enable local video/audio file playback. When set to true, the player will display a file selection button. Users can click the button to select local files or drag and drop files directly into the player area to play.
• Feature Highlights:
  • Drag and Drop Upload: Users can directly drag video/audio files into the player area.
  • File Selection Button: Displays a file icon; clicking opens the file selection dialog.
  • Smart MIME Type Detection: Automatically recognizes file formats to ensure accurate playback.
  • Supported Formats: MP4, WebM, MOV, MKV, M4V, OGG, FLAC, WAV, M4A, MP3, OPUS, and other formats natively supported by browsers.
  • Prompt Interface: When no video is loaded, displays a friendly prompt message to guide the user to select a file.

6.18 segmentButton - Segment Selection Feature

• Type: Boolean
• Default Value: false
• Description: Whether to enable the segment selection feature button. This feature allows users to select specific segments of the video for loop playback; if a segment is selected during recording, only that segment’s content will be recorded.
• Feature Highlights:
  • Drag Segmentation: Drag segment start and end points via sliders on the progress bar, convenient to operate.
  • Time Markers: Display segment start and end times with millisecond precision.
  • Live Restriction: Only available in non-live mode (segment selection feature is not active when isLive is true).
  • Segment Loop: Supports loop playback within the selected segment.
• Usage Scenarios: Suitable for teaching videos, meeting recordings, etc., where specific time periods need focused viewing.

6.19 recordButton - Recording Feature

• Type: Boolean
• Default Value: false
• Description: Whether to enable the video recording feature. When set to true, the player control bar will display a recording button. Users can record the currently playing video content or extract only the audio.
• Feature Highlights:
  • Recording Button: Displays a recording icon; click to start/stop recording.
  • Recording Settings: Provides recording configuration options in the settings menu. Options include: Always Ask, Full Recording, Audio Only.
  • Status Indicator: The button shows different states during recording; a red dot indicator for full recording, a green dot indicator for audio-only recording.
  • Recording Format: Full recording format is MP4, audio-only recording format is M4A.
  • Recording Save: After stopping recording, the file is automatically downloaded and saved locally.
• Technical Requirements: It is recommended to use Chrome engine browsers; some browsers may have limited support.

7. Function Restriction Configuration

7.1 disablePlayBtn - Disable Play Button

• Type: Boolean
• Default Value: false
• Description: Whether to disable the play button. In certain application scenarios, users are required to forcefully watch a program and are not allowed to pause during playback. In this case, set this parameter to true. If set to true, during video playback, users cannot pause playback by clicking the video, pressing the Space key, or clicking the play/pause button on the player toolbar.

7.2 disableSeek - Disable Progress Bar Seeking

• Type: Boolean
• Default Value: false
• Description: Whether to disable dragging the progress bar during playback. In certain application scenarios, users are required to forcefully watch an entire program and are not allowed to move forward or backward during playback. In this case, set this parameter to true.

7.3 disableFullscreenWin - Disable Web Fullscreen

• Type: Boolean
• Default Value: false
• Description: Whether to disable web fullscreen. If set to true, the web fullscreen button on the player control bar will not appear, and users cannot enter web fullscreen mode. The difference between web fullscreen and normal fullscreen is that in web fullscreen, the player only fills the current web page and zooms with the page; in normal fullscreen, the player occupies the entire screen and is located at the topmost layer of the occupied screen.

7.4 disablePicInPic - Disable Picture-in-Picture

• Type: Boolean
• Default Value: false
• Description: Whether to disable the Picture-in-Picture function. If not explicitly specified to disable Picture-in-Picture, the player will automatically detect whether the current browser supports Picture-in-Picture. If supported and available, a Picture-in-Picture control button will appear on the player control bar. Clicking this button switches the current video to Picture-in-Picture mode. In Picture-in-Picture mode, if the user minimizes the current browser, the Picture-in-Picture window will remain on the screen and will not disappear.

7.5 disableVolumeControl - Disable Volume Control Button

• Type: Boolean
• Default Value: false
• Description: Whether to disable the volume control button. If set to true, the volume control button will not appear on the player control bar. On PC platforms, users cannot control volume via mouse or toggle mute, but can still control volume via the up and down arrow keys. On smartphones, since most phones can already control volume via the phone’s physical volume buttons, this parameter can be set to true.

7.6 lostFocusPause - Pause on Lost Focus

• Type: Boolean
• Default Value: None
• Description: Pause playback when the window loses focus. Current mainstream browsers on the PC platform use tabs to support multi-page access. Users can switch different pages through tabs. Only the page currently at the front gets focus; other pages lose focus and remain at the back. You can set this parameter to true to let zwplayer pause playback when its page loses focus and restart playback when the page regains focus.

8. Media Information Configuration

8.1 thumbnails - Progress Bar Preview Image Parameters

• Type: Object | String
• Default Value: None
• Description: Progress bar preview image parameters. The preview image is a pre-captured video thumbnail used to display preview frames of the video at different times when the user moves the mouse over the progress bar. It is only effective for VOD programs. The following three input methods are supported:

Method 1: Pass Object Directly

{
  "url": "https://cdn.zwplayer.com/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg",
  "width": 160,
  "height": 90,
  "row": 9,
  "col": 9,
  "total": 74
}

Method 2: Pass ZWMAP JSON Object

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "thumbnail",
  "zwp_version": "1.0",
  "thumbnail": {
    "url": "thumbnail.jpg",
    "width": 160,
    "height": 90,
    "col": 10,
    "row": 10,
    "total": 100
  }
}

Method 3: Pass JSON URL Address

thumbnails: 'http://example.com/thumbnails/movie_thumbnail.json'

Additionally, it supports dragging and dropping the thumbnail JSON file and sprite image directly onto the player for loading. The player will automatically match the video and thumbnails by filename. For details, please see Progress Bar Preview Image Parameter Description

8.2 chapters - Chapter Annotation Information

• Type: String | Array | Object

• Default Value: None

• Description: Program chapter annotation information. Supports the following input methods:

  • URL String: Starts with http or https, zwplayer will automatically download and parse from remote.
  • JSON String: Starts with [, it will be parsed as a JSON array.
  • WEBVTT String: Starts with WEBVTT, parsed according to WEBVTT format.
  • ZWMAP JSON Object: Directly pass a ZWMAP protocol object containing zwp_type: “chapter”.
  • JS Array: Pass an already parsed chapter array.

  Also supports the chapter (singular) property name; the player will automatically normalize it internally.

  It is not recommended to set this parameter during player initialization. The recommended method is to use the setChapters method for delayed loading after the player starts playback. For details, please see Chapter Annotation Settings Description

• Chapter Search Feature: After loading chapters, click the “Chapter Search” button in the player settings menu to open the chapter search panel. Enter keywords to filter matching chapter entries in real-time. Clicking a search result jumps to the corresponding time point. Supports searching by chapter title and description content.

• Loop Playback by Chapter: In the chapter search panel, there is a loop button on the right side of each chapter entry. Clicking it causes the player to loop playback within the time range of that chapter; clicking

8.3 chapterButton - Chapter Menu Button

• Type: Boolean
• Default: none (automatically enabled when chapters are loaded)
• Description: Controls whether the chapter menu button appears near the control bar time display area. When set to false, progress bar chapter markers are still displayed normally; only the menu button is hidden. Chapter data loading is not affected by this parameter.

8.4 annotations - Interactive Annotation Information

• Type: String | Array | Object
• Default Value: None
• Description: Interactive video annotation information. Supports URL string, ZWMAP JSON object, or annotation array. For details, see Annotation Settings

8.5 subtitles - External Subtitles

• Type: String | Array

• Default Value: None

• Description: External subtitle configuration. Supports the following input methods:

  • URL String: Subtitle file URL (supports VTT, SRT, BCC formats).
  • Array: An array of subtitle track objects.

  Also supports the subtitle (singular) property name. It is recommended to use the addSubtitle method for delayed loading after playback starts.

8.6 translateApi - Subtitle Translation Service URL

• Type: String
• Default Value: None
• Description: The API endpoint URL for subtitle translation service. When set, a translate button will appear in the subtitle settings menu. For details, see Subtitle Settings

8.7 logo - Station Logo

• Type: String | Object
• Default Value: None
• Description: Station logo configuration. If a string is provided, it is treated as the logo image URL. For more control, use an object:

{
    icon: 'http://example.com/vod/logo.png',
    dock: 'left',
    x: '5%',
    y: '5%',
    width: '20%',
    height: '20%',
    opacity: 70
}

For details, see Logo Settings

8.8 watermarks - Watermark Parameters

• Type: String | Array | Object

• Default Value: None

• Description: Video watermark configuration. Supports image watermarks, text watermarks, dynamic roaming watermarks, and tile watermarks. Commonly used for branding, copyright notices, and anti-screen-recording protection. Supports the following input methods:

  • URL String: Starts with http or https, pointing to a ZWMAP JSON file. The player will automatically download and parse it.
  • ZWMAP JSON Object: A protocol object containing zwp_type: "watermark".
  • Watermark Array: Directly pass a watermark entries array.

  You can also use the setWatermarks method for delayed loading after the player starts playback.

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    watermarks: [
        {
            type: 'image',
            icon: 'https://example.com/watermark.png',
            dock: 'bottom-right',
            x: '5%',
            y: '5%',
            width: 120,
            opacity: 40
        },
        {
            type: 'text',
            text: '{user_id} {sys_time}',
            font_size: 14,
            font_color: 'rgba(255,255,255,0.3)',
            behavior: 'dynamic',
            dock: 'center'
        }
    ],
    variables: {
        user_id: '138****1234'
    }
});

For detailed watermark data structure and behavior modes, see Watermark Setup