Parameter Configuration

1. Player Interface Description

To facilitate the explanation of subsequent parameters, the screenshot below shows an instance of the player interface:

ZWPlayer main interface showing the complete player interface, including playback control buttons, status display area, progress bar, playback progress indicator, player control bar, player control bar buttons, preview thumbnails, large play button, etc.

2. Configuration Overview

When creating a zwplayer object, we need to pass a JS object as a parameter to the zwplayer constructor. A sample constructor parameter JS object with relatively complete attributes is as follows (subsequent new versions may add members due to feature enhancements, but will not reduce or modify property names defined in previous versions, ensuring API solidity 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,
  // Advanced features
  enableDanmu: true,
  thumbnails: {
    url: "http://example.com/thumbnail.jpg",
    width: 128,
    height: 72,
    row: 7,
    col: 7,
    total: 43
  },
  chapters: 'http://example.com/chapters.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 danmaku
  }
});

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

3. Basic Configuration

3.1 *playerElm - Player Container

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

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

3.2 *url - Source Address

Type: string | ObjectArray
Default: None
Required
Description: The access URL of the media stream. To enable the player to support powerful features while reducing the number of parameters, this url parameter can not only be a simple string type but also a JS object type. Please see Detailed Source URL Explanation.

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4'	// Please replace with actual address
});

3.3 videostyle - Player Style

Type: string
Default: None
Description: CSS applied to the built-in Video object of the player. Must be valid CSS description statements.
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: None
Description: Sets the poster, which is the image displayed in the player video area when the player is stopped.

3.5 fluid - Fluid Layout

Type: Boolean
Default: false
Description: Setting to fluid layout allows the player width to follow the parent element's width changes, and the height changes according to the aspect ratio configured in the configuration items (when player width and height are not set, internal default values are used for calculation). The aspect ratio calculation algorithm is as follows:

If the ratio property is set, the ratio property value is the aspect ratio.
If the ratio property is not set, the aspect ratio is calculated from the width and height values.
If width and height properties are not set, the default aspect ratio is 16:9.

3.6 ratio - Aspect Ratio

Type: Number | String
Default: 16:9
Description: Sets the aspect ratio of the player, in the format "width:height", such as "16:9". Takes effect when fluid layout is enabled.

3.7 width - Width

Type: Number | String
Default: None
Description: Player width. If a number type parameter is passed, the player internally adds the unit px by default. If a string type parameter is passed, it is directly assigned to the player container width style property.

3.8 height - Height

Type: Number | String
Default: None
Description: Player height. If a number type parameter is passed, the player internally adds the unit px by default. If a string type parameter is passed, it is directly assigned to the player container height style property.

3.9 lang - Language Setting

Type: String
Default: Automatically detected based on browser interface language. If Chinese, it will be Chinese; otherwise, English.
Description: Sets the interface language of the player. Supports multi-language localization, affecting all text content in the player control bar, prompt messages, menus, etc.
Supported Languages:

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

4. Playback Control

4.1 autoplay - Autoplay

Type: Boolean
Default: false
Description: Whether to automatically start playback. If set to false, the player must click the play button to start playing.
Note: Under the latest browser restrictions, autoplay on a new page needs to be used in conjunction with muted set to true.
Feature: zwplayer has built-in automatic detection functionality. If this parameter is set to true, when the player tries to open audio playback and fails, it will automatically set the player to mute to start playback. Subsequently, users need to click the Enable Sound prompt button to turn on the sound.
Reference: ZWPlayer Autoplay Complete Guide: Solving Silent Issues and Scenario-based Configuration

4.2 disableMutedConfirm - Disable Autoplay Mute Confirmation Dialog

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

· Detection and Degradation: If autoplay with sound fails due to browser policy, the player will automatically set the video to mute state and start playing.
· User Prompt (Default Behavior): Subsequently, the player will pop up a modal prompt box explaining to the user: "Due to browser restrictions, the video is playing muted. Please click the screen to enable sound." This prompt box requires the user to manually click to close, ensuring the user is aware of the current silent state to avoid confusion.

The disableMutedConfirm property controls the display of this prompt box:

· When set to false (default), the above modal prompt box will display normally.
· When set to true, this modal prompt box will be disabled. Even if muted playback is triggered due to policy restrictions, no interactive prompts will pop up.

Suggested usage scenarios:

· Set to true: Suitable for scenarios pursuing ultimate immersive, uninterrupted experiences, such as background videos, advertisements, or video displays that don't require audio. Developers need to inform users of the mute state through UI or other means.
· Keep false (default): Suitable for general video playback scenarios where it's necessary to clearly inform users of the current state to avoid confusion caused by sudden silence, such as news, education, main site players, etc., which can effectively improve user experience clarity.

4.3 muted - Mute

Type: Boolean
Default: false
Description: Whether the player starts muted. Current H5 browsers, if set to autoplay but not set to mute, may not be able to automatically start playback without user interaction.

4.4 reconnect - Reconnect

Type: Boolean
Default: None
Description: Whether the player should automatically reconnect after 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: None
Description: Specifies whether the program source is a live stream type. Live streams cannot drag progress or adjust playback speed. This is very useful for disguising a recorded source as a live program in specific situations. By default, the player automatically detects whether it is a live source.

5. Streaming Protocol Configuration

5.1 streamtype - Stream Protocol Type

Type: String
Default: None
Description: Manually specifies the stream protocol type, supports: httpflv, hls, dash, mpegts, webrtc. This parameter must be specified when the live stream address has no extension.

Feature: zwplayer determines the stream protocol through the live stream address extension, with the following correspondence:

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 not be able to determine which protocol to use to play the stream. In this case, the stream type must be manually specified.

5.2 useFlv - FLV Priority

Type: Boolean
Default: false
Description: zwplayer supports multi-protocol type live program source objects (using JS objects as url parameters). A live program source may contain multiple types of streams. For example, a multi-protocol live source may simultaneously contain webrtc, http-flv, hls, dash, and other transmission protocol types. If this parameter is set to true, zwplayer will prioritize using the flv stream when it detects http-flv streams in the source type; otherwise zwplayer will make automatic decisions, selecting the transmission type with the shortest latency to play.

5.3 useOldFlv - Enable FLV Legacy Interface

Type: Boolean
Default: false
Description: When playing Flv type live streams, whether to use the legacy playback interface. Using the legacy 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. On newer Chrome browsers (some Safari browsers), zwplayer supports live sources containing H265.

5.4 hasAudio - Contains Audio Stream

Type: Boolean
Default: 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 audio streams in the stream before starting playback. If not found, the player will keep waiting. For streams from certain surveillance cameras, this parameter can be set to false, so the player will not search for audio streams and will start playback faster.

5.5 hasVideo - Contains Video Stream

Type: Boolean
Default: 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 video streams in the stream before starting playback. If not found, the player will keep waiting.

5.6 xmc_url - Media Gateway Address

Type: String
Default: None
Description: xmc_url is the media gateway address. xmc stands for External Media Coprocessor. Some common streaming protocols, such as rtsp, udp, rtp, cannot be played through the current browser's H5 video playback because current H5 does not support raw sockets, so these protocol streams cannot be obtained. One solution is to use an external server to convert the protocol to http or webrtc, so H5 players can play rtsp, udp, rtp streams. Using xmc, zwplayer supports playing rtsp, udp and other live streams in the browser. This is helpful for playing rtsp streams output by cameras from most surveillance device manufacturers. The coprocessor 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: true
Description: Whether to display the player control bar, i.e., display the player control bar. For user convenience, players usually have a playback control bar with various buttons such as play, pause, fullscreen, etc. In some application scenarios, a control bar is not needed, and this parameter can be set to false. Note that since the H5 browser's video tag's built-in player control bar is not satisfactory, zwplayer has built a custom player control bar that presents a consistent appearance across all browsers. Various buttons on the custom player control bar support configuration for whether to display.

6.2 nativecontrols - Native Player Control Bar

Type: Boolean
Default: false
Description: Whether to use the browser's native player control bar. If true, the browser video element's native player control bar is used. The native player control bar may look different in different browsers. If you need users to see a consistent appearance across different browsers, please do not set this property to true. When set to false, zwplayer will create a custom playback control bar to control playback while disabling the native playback control bar. Using the native playback control bar is not recommended.

6.3 infoButton - Media Info Button

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

6.4 speedButton - Playback Speed Control Button

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

6.5 optionButton - Player Settings Button

Type: Boolean
Default: 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. Current settings include image rotation, loop playback control, and video chrominance adjustment. Future versions may have richer setting functions.

6.6 snapshotButton - Snapshot Button

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

6.7 enableDanmu - Danmaku Function

Type: Boolean
Default: false
Description: Whether to enable the built-in danmaku display function. Danmaku, as an interactive control function for current video playback, is supported by major video websites. Using zwplayer's danmaku function can achieve the same functionality as major video websites. If this item is not set, the zwplayer player cannot display danmaku.

6.8 useProgressTooltip - Progress Bar Preview Display

Type: Boolean
Default: false
Description: Whether to enable tooltips on the playback progress bar. If enabled, when the user moves the mouse over the playback progress bar, event tips will display with 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: false
Description: When window scrolling is about to hide the player, automatically switch to pop-up small window playback. When the page is long with a scrollbar, if the user scrolls the page, it will cause zwplayer to be scrolled out of the page and hidden. If this parameter is set to true, when this situation occurs, zwplayer will automatically switch to small window playback. Note: Small window is different from picture-in-picture. Picture-in-picture is a video small window floating above all windows on the current desktop, while small window playback is a video small window only within the current browser tab, not floating out.

6.10 fixedControlbar - Fixed Control Bar Display

Type: Boolean
Default: true
Description: Whether to always display the playback control bar. If set to false, the control bar disappears after 10 seconds of playback.

6.11 localPlayback - Local File Playback

Type: Boolean
Default: false
Description: Whether to enable local video/audio file playback functionality. When set to true, the player will display a file selection button, allowing users to select local files by clicking the button or directly drag and drop files onto the player area to play.
Feature characteristics:

Supports drag and drop upload: Users can directly drag video/audio files into the player area
File selection button: Displays a file icon, clicks to open the file selection dialog
Intelligent MIME type detection: Automatically identifies file formats to ensure accurate playback
Supported formats: MP4, WebM, MOV, MKV, M4V, OGG, FLAC, WAV, M4A, MP3, OPUS, and other browser natively supported formats
Prompt interface: When no video is loaded, displays friendly prompt information to guide users to select files

6.12 segmentButton - Segment Selection Function

Type: Boolean
Default: false
Description: Whether to enable the segment selection function button. This function allows users to select specific segments in the video for loop playback; if a segment is selected during recording, only the content of that segment will be recorded.
Feature characteristics:

Drag segmentation: Can drag segment start and end time points via sliders on the progress bar for convenient operation
Time markers: Display segment start and end times in millisecond precision
Live stream restriction: Only available in non-live mode (when isLive is true, segment selection function is not activated)
Segment loop: Supports loop playback within selected segments

Usage scenarios: Suitable for teaching videos, meeting recordings, and other scenarios requiring focused viewing of specific time period content

6.13 recordButton - Recording Function

Type: Boolean
Default: false
Description: Whether to enable video recording functionality. When set to true, the player control bar will display a record button, allowing users to record the currently playing video content or extract audio only.
Feature characteristics:

Record button: Displays record icon, click to start/stop recording
Recording settings: Provides recording configuration options in the options menu, including: Always Ask, Full Recording, Audio Only
Status indicator: The button displays different states during recording. Red dot indicator for full recording, 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 recording file is automatically downloaded and saved locally

Technical requirements: Chrome engine browsers are recommended; some browsers may have limited support.

7. Feature Restriction Configuration

7.1 disablePlayBtn - Disable Play Button

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

7.2 disableSeek - Disable Progress Bar Dragging

Type: Boolean
Default: false
Description: Whether to disable dragging the progress bar during playback. In certain application scenarios where users are required to watch an entire program forcibly without being able to fast forward or rewind during playback, this parameter should be set to true.

7.3 disableFullscreenWin - Disable Web Fullscreen

Type: Boolean
Default: 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 webpage and scales with the webpage; in normal fullscreen, the player occupies the entire screen and is at the topmost layer of the occupied screen.

7.4 disablePicInPic - Disable Picture-in-Picture

Type: Boolean
Default: 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 functionality. If supported and available for calling, a picture-in-picture control button will appear on the player control bar. Clicking this button will switch the current video to picture-in-picture mode. In picture-in-picture mode, when the user minimizes the current browser, the picture-in-picture window will still remain on the screen and will not disappear.

7.5 disableVolumeControl - Disable Volume Control Button

Type: Boolean
Default: false
Description: Whether to disable the volume control button. If set to true, the playback 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 up and down arrow keys. On smartphones, since most phones can already control volume via the phone's own volume buttons, this parameter can be set to true.

7.6 lostFocusPause - Lose Focus Pause

Type: Boolean
Default: None
Description: Pause playback when window loses focus. Current mainstream browsers on PC platforms use tabs to support multi-page access. Users can switch between different pages through tabs; only the current frontmost page gets focus, while other pages lose focus and are positioned behind. You can set this parameter to true to make zwplayer pause playback when its page loses focus, and resume playback when the page regains focus.

8. Media Info Configuration

8.1 thumbnails - Progress Bar Preview Parameters

Type: Object
Default: None
Description: Progress bar preview parameters. Preview images are pre-captured video thumbnails used to display preview images of the video at different times when the user moves the mouse over the progress bar. Only valid for on-demand programs. This parameter is a js object. A valid thumbnails parameter is as follows:

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

For details, please see Progress Bar Preview Parameters Description

8.2 chapters - Chapter Markers Info

Type: String | Array
Default: None
Description: Program chapter marker information. The chapters parameter can be a string or an already parsed js array. If chapters is a string starting with http or https, zwplayer will treat this parameter as a chapter URL and automatically download from remote when loading; if chapters starts with the character "[", it will be parsed as a JSON array; if chapters starts with WEBVTT, it will be treated as a WEBVTT file. It is not recommended to set this parameter during player initialization. The recommended approach is to load it lazily via the setChapters method after the player starts playing. Since chapter information contains a lot of content, for details please see Chapter Markers Setup Description

8.3 logo - Logo Parameters

Type: String | Object
Default: None
Description: Sets the logo. If a string is input, the string identifies the URL of the logo image. For more control over the logo, an object is recommended. The object format is as follows:

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

For details, please see Logo Setup Description

9. Event Callback Configuration

9.1 onmediaevent - Media Event Callback

Type: Function
Default: None
Description: Player media event callback function. This parameter must be a js function. The function prototype is as follows:
```
function onmediaevent(event)
```
Where event is the event parameter. This parameter is a js object. Event types can be distinguished via event.type. Possible event types include 'play', 'pause', 'seeked', 'ended', 'error', etc.

9.2 onready - Player Ready Event Callback

Type: Function
Default: None
Description: Event callback triggered when player creation is ready. Function prototype is as follows:
```
function onready()
```

9.3 sendDanmu - Send Danmaku Function

Type: Function
Default: None
Description: Send danmaku function. Function prototype is as follows:
```
function sendDanmu(text)
```
zwplayer has a built-in danmaku input interface. This danmaku input interface only handles input and is not responsible for sending. Danmaku input through this interface must provide a send function to be sent out. The implementation of the danmaku send function is completed by the user. Since zwplayer is not bound to any danmaku backend server, developers need to implement their own danmaku server or use third-party danmaku servers. This function accepts a UTF-8 string parameter, which is actually a json string containing danmaku content, style, and other setting information.
For details, please see Danmaku Setup Description

10. Other Configuration

10.1 videoElm

Type: String | DomObject
Default: None
Description: The ID of the video element (VIDEO) for the player or a Video type DOM object. If the passed parameter is not an actual Video object ID or DOM object, the zwplayer player will automatically create a VIDEO object; if it already exists, zwplayer will use this existing DOM object to play video. This parameter is recommended only when a custom player UI is needed; otherwise, this parameter can be ignored.

10.2 logframe

Type: Boolean
Default: None
Description: Whether to print logs frame by frame. When using zwplayer's WebAssembly core technology, setting this parameter to true will cause zwplayer to print logs frame by frame. This parameter is temporarily not supported.

Catalog Navigation