Attribute and Interface Description
Updated: 2026-01-19 14:30:07
Player Properties
| Name | Type | Default | Description | PC Compatible | Mobile Compatible |
|---|---|---|---|---|---|
| wrap | String / HTMLElement | / | DOM element to load the player, supports passing an element or element selector (only loads on the first element). | ✔ | ✔ |
| vid | String | / | Unique video ID on the cloud video platform. | ✔ | ✔ |
| width | Number / String | 100% | Player width, supports pixel values and percentages, e.g., 200 or 100%. | ✔ | ✔ |
| height | Number / String | / | Player height, supports pixel values, percentages, and auto-adaptation, e.g., 100, 40%. When the value is auto or empty, the height is automatically calculated based on the video aspect ratio (only effective on PC). |
✔ | ✔ |
| autoplay | Boolean | / | Whether to autoplay. Note: Most browsers currently restrict autoplay; this parameter may be ineffective. |
✔ | ✔ |
| loop | Boolean | false | Whether to enable loop playback. | ✔ | ✔ |
| forceH5 | Boolean | / | Whether to use the H5 player by default when using multi-terminal code. Note: Flash will still be used if the browser does not support H5. |
✔ | ✘ |
| flash | Boolean | false | Whether to use the Flash player by default. | ✔ | ✘ |
| hideSwitchPlayer | Boolean | false | Whether to hide the H5 and Flash player switch button. | ✔ | ✘ |
| playsafe | String/Function | / | Authorization credential required for playing encrypted videos. See: Play Encrypted Video. Function usage: playsafe: function(vid, next) { $.ajax({ url: 'token API', type: "POST", data: obj, }).done(function(res) { next(res.data.token); }); }, |
✔ | ✔ |
| playsafeUrl | String | / | URL for obtaining the credential to play encrypted videos. Use either this or the playsafe parameter. |
✔ | ✔ |
| disposable | Boolean | false | If the disposable parameter was passed when generating the playsafe token, the token is valid for one use. Switching quality will cause playback failure. Set this parameter to true if the token request included disposable. Note: Requires playsafe <Function> or playsafeUrl |
✔ | ✘ |
| sign | String | / | Signature required for playing encrypted videos on mobile. See: Play Encrypted Video. | ✘ | ✔ |
| ts | Number | / | Timestamp required for playing encrypted videos on mobile. | ✘ | ✔ |
| viewerInfo | Object | / | Custom viewer information. When set, the viewer information is attached to the playback behavior logs reported by the player. See: Viewer Information Setting and Statistics. | ✔ | ✔ |
| video_align | String | / | Alignment of the video image within the player. Default is center. Values: {top, bottom, left, right}. | ✔ | ✔ |
| loading_bg_img | String | / | URL for the video poster image. | ✔ | ✔ |
| cover_display | String | scaleToFill | Cover image display mode: scaleToFill (fill), scaleAspectFit (fit), scaleAspectFill (fill with aspect ratio). | ✔ | ✔ |
| cover_opacity | Number | 70 | Cover image mask opacity, range: [0,100]. | ✔ | ✘ |
| showHd | Boolean | true | Whether to display the quality selection button. | ✔ | ✔ |
| show_rate | Number | / | Maximum selectable quality. Values: {1,2}. 1 shows only smooth, 2 allows smooth and HD. | ✔ | ✔ |
| showAuto | Boolean | true | Whether to display the "Auto" option in the quality selection. | ✔ | ✘ |
| df | Number | - | Default playback quality. Values: {0,1,2,3}, corresponding to Auto, Smooth, HD, Super HD. | ✔ | ✔ |
| speed | Boolean/Array | true | When the speed parameter is a boolean, it indicates whether to show the speed toggle button. When it is an array, it represents the selectable playback speeds. No limit on the number of speeds. Recommended range: (0,3]. PC default: [2, 1.5, 1.2, 0.5], Mobile default: [1, 1.5, 2]. | ✔ | ✔ |
| showLine | Boolean | true | Whether to display the line selection button. | ✔ | ✔ |
| volume | Number | 0.75 | Default volume level, range: (0,1). The player remembers the last volume. | ✔ | ✔ |
| allowFullscreen | Boolean | true | Whether to allow fullscreen playback. When false, hides the fullscreen button (the fullscreen API remains available). Note: Not supported on mobile v1. |
✔ | ✔ |
| fullscreenProxy | Boolean | false | Whether to use a fullscreen proxy. When true, clicking fullscreen does not call the fullscreen API but triggers the window.onFullscreenProxy(vid, toFullscreen) event, allowing developers to handle fullscreen themselves. Suitable for overlaying custom elements in fullscreen mode. | ✔ | ✘ |
| full_page_screen | Boolean | false | Whether to display the web page fullscreen button. Requires configuring the window.onFullPageScreen event callback for handling. | ✔ | ✘ |
| pictureInPicture | Boolean | false | Whether to display the picture-in-picture button in the control bar. Note: Only effective when playing non-encrypted videos. |
✔ | ✘ |
| screenshot | Boolean | false | Whether to display the video screenshot button. | ✔ | ✘ |
| skinLocation | Number | 1 | Player control bar display position: 0 hidden, 1 inside video area, 2 outside video area. Note: Mobile v1 uses ban_ui: true instead of skinLocation: 0 |
✔ | ✔ |
| hideRepeat | Boolean | false | Whether to hide the replay button after playback ends. | ✔ | ✔ |
| ban_seek | String | off | Whether to disable progress bar dragging. Values: {on, off}. Note: Behavior may vary across Android browsers; this parameter may not work. |
✔ | ✔ |
| ban_seek_by_limit_time | String | off | Whether to prevent dragging the progress bar to positions beyond the played range. Values: {on, off}. When on, dragging is only allowed within the already played range (forward dragging). | ✔ | ✔ |
| cacheLimitTime | Boolean | false | Whether to cache the maximum played duration. Used with ban_seek_by_limit_time. When set, the draggable area for the same video is limited to the historical maximum watch time. Note: Not supported on mobile v1. |
✔ | ✔ |
| banSeekDeviation | Number | / | When ban_seek is set, this parameter limits the maximum seek time. Unit: seconds. | ✔ | ✔ |
| ban_preview_video | String | off | Whether to disable the thumbnail preview when hovering over the progress bar. Values: {on, off}. When on, the preview thumbnail is not displayed. | ✔ | ✘ |
| keyboardSeekTime | Number | 15000 | Time to seek forward/backward per keyboard arrow key press. Unit: milliseconds. | ✔ | ✘ |
| watchStartTime | Number | / | Playback start time, indicating the second from which the video starts playing. The value must be less than the video duration. | ✔ | ✔ |
| watchEndTime | Number | / | Playback end time, indicating the second at which the video stops playing. When set, progress bar dragging is limited to the range between start and end time. The value must be greater than watchStartTime and less than the video duration. If less than watchStartTime, watchStartTime becomes invalid. | ✔ | ✔ |
| start | Number | / | Truncates a portion of the video as an independent video. E.g., if the original video is 60 seconds and start=20, the video displays as 40 seconds starting from the 20th second. Usually used with the end parameter (sub-video feature). | ✔ | ✔ |
| end | Number | / | Truncates a portion of the video as an independent video. E.g., if the original video is 60 seconds, start=20, end=50, the video displays as 30 seconds playing from the 20th to the 50th second. | ✔ | ✔ |
| preview | Boolean | false | Whether to use preview mode. Playback stops after the preview duration, which can be configured in the admin console. | ✔ | ✔ |
| previewDuration | Number | / | Preview duration. Optional parameter, unit: seconds. If not provided and preview is enabled, the default preview duration from the admin console is used. Note: 1. For non-encrypted videos, the system displays the preview based on this parameter. 2. For encrypted videos, the actual preview duration is determined by the shorter of: the actual video encoding length and this parameter. It is recommended not to exceed the admin console's preview duration to avoid issues. |
✔ | ✔ |
| history_video_duration | Number | 5 | Default duration threshold for enabling resume playback. Videos longer than this value (in minutes) will have resume playback enabled. Playback time points are not recorded during the first and last 10 seconds of the video. | ✔ | ✔ |
| ban_history_time | String | off | Whether to disable the resume playback feature. Values: {on, off}. on: disable, off: enable. | ✔ | ✔ |
| historyTimeType | String | local | Values: "local" or "remote". Storage method for resume playback records. "local" stores in localStorage, "remote" stores on the polyv server. Note: When configured as "remote", subsequent records are not stored locally. If both exist, the remote value is read first. | ✔ | ✔ |
| preloadDataSize | Number | 15000 | Amount of data to preload. The number of segments loaded depends on the actual video duration and quality. Range: [500, 60000], unit: KB. Note: Only effective for HLS videos (encrypted videos) on PC. |
✔ | ✘ |
| preloadDurationLength | Number | / | Maximum video preload duration. Unit: seconds. | ✔ | ✘ |
| url | String | / | URL for a third-party video resource. Cannot be set simultaneously with vid. | ✔ | ✔ |
| logo | Object | / | Player logo configuration parameters. See: Player Logo. | ✔ | ✔ |
| teaser_show | Number | / | Whether to play the teaser: 0 no, 1 yes. The teaser can be set in the admin console. | ✔ | ✔ |
| teaser_time | Number | / | Teaser display duration. | ✔ | ✔ |
| teaser_url | String | / | Teaser URL. Video supports only mp4 format. | ✔ | ✔ |
| teaserSkip | Boolean | false | Whether to display the skip teaser button. Note: Due to video layering issues, this parameter may not work on some mobile browsers. |
✔ | ✔ |
| tail_show | Number | / | Whether to play the tail: 0 no, 1 yes. The tail can be set in the admin console. | ✔ | ✔ |
| tail_time | Number | / | Tail display duration. | ✔ | ✔ |
| tail_url | String | / | Tail URL. Video supports only mp4 format. | ✔ | ✔ |
| tailSkip | Boolean | / | Whether to display the skip tail button. | ✔ | ✔ |
| ban_ad | Boolean | false | Whether to disable ad playback. | ✔ | ✔ |
| ban_ad_time | Boolean | false | Whether to hide the ad countdown. | ✔ | ✔ |
| adMatter | Array | / | Ad configuration parameters. See: Ad Settings. | ✔ | ✔ |
| adSkip | Boolean | false | Whether to display the skip ad button. | ✔ | ✔ |
| rightMenu | Array | / | Player right-click menu configuration. Example: rightMenu: [{rightName: 'Right-click menu display name', rightUrl: 'Menu click redirect URL', callback: function(){console.log('hi')}},{rightName: 'Right-click menu two',rightUrl: '', callback: function(){console.log('hello')}}] | ✔ | ✘ |
| lang | String | zh_CN | Player language. Supports Chinese and English. Values: {zh_CN, en}. | ✔ | ✔ |
| priorityMode | String | video | Default mode: video or audio. Values: {video, audio}. Note: Only videos with an additional audio track can switch between video and audio modes. |
✔ | ✔ |
| videoMode | Boolean | true | When false, enables audio mode. Note: Only effective on PC. Audio mode is enabled even for videos without an additional audio track. Note: Not supported on mobile v1. |
✔ | ✔ |
| audioMode | Boolean | true | Whether to enable audio mode (only effective if the source video supports audio). | ✔ | ✔ |
| is_interaction | String | on | Whether to display quiz questions set in the admin console during video playback. Values: {on, off}. See: Quiz Popup Feature. | ✔ | ✘ |
| ban_record_interaction_right_answer | String | off | Whether to prevent the player from caching quiz submission records. Values: {on, off}. When set to "on", the quiz must be retaken each time the video is played. | ✔ | ✘ |
| title_of_right_answer_explain | String | / | Prompt text when a quiz answer is correct. | ✔ | ✘ |
| title_of_wrong_answer_explain | String | / | Prompt text when a quiz answer is incorrect. | ✔ | ✘ |
| pptEnable | Boolean | false | Whether to enable the courseware three-screen playback mode. See: Courseware Three-Screen Playback. | ✔ | ✘ |
| mainScreen | String | ppt | Main screen in three-screen playback mode. Values: {ppt, video}. | ✔ | ✘ |
| subWidth | Number | 355 | Default width of the secondary screen in three-screen playback mode. | ✔ | ✘ |
| subHeight | Number | 200 | Default height of the secondary screen in three-screen playback mode. | ✔ | ✘ |
| pptVisible | Boolean | true | Whether to display the PPT on initialization in three-screen playback mode. | ✔ | ✘ |
| srtBackground | String | / | Subtitle background color, hexadecimal. E.g., '#333333'. | ✔ | ✘ |
| srt_caption_txt_size | Number | 20 | Subtitle font size, range: [20, 40], unit: px. | ✔ | ✘ |
| srt_caption_txt_height | Number | 20 | Height of the subtitle from the bottom of the player, unit: px. | ✔ | ✘ |
| srt_caption_base_width | Number | 1280 | Subtitle font size scales with player size. This value is the base width of the player. | ✔ | ✘ |
| srt_caption_base_height | Number | 720 | Subtitle font size scales with player size. This value is the base height of the player. | ✔ | ✘ |
| showSrt | Boolean | true | Whether to enable subtitle display. | ✔ | ✔ |
| defaultSubtitle | String | - | Default subtitle parameter, must match the string set in the admin console (subtitle file name). | ✔ | ✘ |
| useSingleSubtitleStyle | Boolean | true | Whether the single subtitle style responds to admin console settings. | ✔ | ✘ |
| code | String | / | Custom code value for the marquee. See: Authorized Playback and Video Marquee. | ✔ | ✔ |
| marqueeCheck | Boolean | / | When true, checks if the marquee has been tampered with and reports error 016. Note: Not supported on mobile v1. |
✔ | ✔ |
| ignoreIE | Boolean | false | Whether to disable the HTML5 player in IE browsers (including compatibility mode of 360, QQ, etc.). | ✔ | ✘ |
| player_id | String | / | Player ID. When set, uses the settings of the corresponding player. Note: This feature requires additional activation. |
✔ | ✘ |
| preventKeyboardEvent | Boolean | false | Whether to block keyboard events. When true, blocks them. | ✔ | ✘ |
| videoKeyframes | Array | / | Custom keyframe settings. When set, these keyframe settings are used, ignoring admin console settings. Can also be passed via changeVid. See: videoKeyframes. | ✔ |
Custom Tracking Settings
const videoKeyframes = [{
// 打点出现时间
keytime: 80,
// 打点提示内容
keycontent: 'test111',
// 打点跳转按钮文案,可选
btnDesc: 'text',
// 打点跳转按钮跳转链接，可选
btnHref: 'https://www.example.com/'
}]
Player Interface
The API needs to be called after the player initialization is complete, for example:
player.on('s2j_onPlayerInitOver',function(e) {
player.j2s_seekVideo(100);
});
API List
| Name | Parameters & Type | Return Value & Type | Description | Compatibility: PC | Compatibility: Mobile |
|---|---|---|---|---|---|
| j2s_pauseVideo | / | / | Pause playback. | ✔ | ✔ |
| j2s_resumeVideo | / | / | Resume playing the current video. | ✔ | ✔ |
| j2s_stopVideo | / | / | Stop playing the current video and display the end screen. | ✔ | ✔ |
| j2s_seekVideo | (Number) | / | Seek to a specific time for playback. Parameter unit: seconds. | ✔ | ✔ |
| j2s_getDuration | / | Number | Get the total duration of the video. Return value unit: seconds. | ✔ | ✔ |
| j2s_getCurrentTime | / | Number | Get the current playback time of the video. Return value unit: Mobile: seconds (integer) PC: seconds (with decimal point, needs to be converted using parseInt()) |
✔ | ✔ |
| getMaxCurrentTime | / | Number | Get the maximum time the video has been played. Return value unit: seconds. Must be used with ban_seek_by_limit_time.Note: Not supported on mobile v1. |
✔ | ✔ |
| j2s_realPlayVideoTime | / | Number | Get the actual played duration of the current video, excluding ads, intro, pauses, credits, etc. | ✔ | ✔ |
| j2s_getFlowCount | / | Number | Get the data consumed by the current video playback. Unit: bytes. Only supported by the Flash player. | ✔ | ✘ |
| j2s_setVolume | (Number) | / | Set the video playback volume. Value range: (0,1). | ✔ | ✔ |
| j2s_realPlayStatus | / | Object | Get the real-time playback status. Returns a JSON format string containing the following fields:pid Unique ID generated for each playback action, also included in backend viewing logs.vid Video ID.playduration Current playback duration.timestamp Current timestamp.sign Signature. Please consult technical support for the calculation method. |
✔ | ✔ |
| changeVid | (Object) | / | Switch to the next video. See: Video Switching | ✔ | ✔ |
| switchBitrate | (Number) | / | Switch video quality. Parameter values {0,1,2,3} correspond to Auto, Smooth, HD, and Ultra HD respectively. | ✔ | ✔ |
| getCurrentLevel | / | (Number) | Return the current video quality level. Return values as above. | ✔ | ✔ |
| toggleFullscreen | / | / | Toggle fullscreen/exit fullscreen. | ✔ | ✘ |
| toggleFullPageScreen | (String) | / | Toggle web page fullscreen. Requires prior setting of webPageFullScreen and fullScreenOrientation parameters.Web page fullscreen orientation: portrait for portrait, landscape for landscape. If no parameter is passed, the initialized orientation parameter is used.Note: Not supported on mobile v1. |
✘ | ✔ |
| changeRepeat | (Boolean) | / | When the parameter value is true, hide the replay button after the video ends. |
✔ | ✔ |
| switchMain | (String) | / | When using a three-part courseware split-screen, switch the PPT or video to the main screen. Values: {ppt, player}. | ✔ | ✘ |
| setMode | (String) | / | Switch audio/video mode. Values: {video, audio}. Note: Only videos with an additional audio track can switch audio/video modes. |
✔ | ✔ |
| getCurrentMode | / | String | Return the current playback mode: video for video mode, audio for audio mode. |
✔ | ✔ |
| toFlash | / | / | Switch to the Flash player. Only callable from the PC H5 player. | ✔ | ✘ |
| toHTML5 | / | / | Switch to the H5 player. Only callable from the Flash player. | ✔ | ✘ |
| on | (String, Function) | / | Bind an event listener. | ✔ | ✔ |
| destroy | / | / | Destroy the player instance. | ✔ | ✔ |
| getScreenshotData(type, encoderOptions); | type (optional): Used to set the image format, default is image/png. Type: 'image/png' | 'image/webp' | 'image/jpeg'encoderOptions (optional): When the specified image format is image/jpeg or image/webp, you can select the image quality from a range of 0 to 1. If the value is out of range, the default value 0.92 will be used. Other parameters are ignored. |
If the interface call is normal, returns a string containing a data URI; if the interface call is abnormal, returns an object containing a property error, whose value is the exception's message, type is string. Object format example: { "error": "xxx" }. |
Get screenshot data of the current video frame. Requires setting the player parameter allowGetScreenshotData to true. |
✔ | ✔ |
| getVideoInfo | / | Object | Get basic video information. Returns an object containing video resolution and other info. Currently only supports getting video resolution. It is recommended to call this interface after the s2j_onPlayerInitOver event is triggered. |
✘ | ✔ |
| changeRate | (Number) | / | Switch playback speed. Optional values: [2, 1.5, 1.2, 0.5] | ✔ | ✔ |
| getCurrentRate | / | Number | Return the current playback speed. | ✔ | ✔ |
Player Events
| Name | Description | Compatibility: PC | Compatibility: Mobile |
|---|---|---|---|
| s2j_onPlayerInitOver | Triggered when the player initialization is complete. Player methods can only be called after this event. Returns the vid parameter. | ✔ | ✔ |
| s2j_onReadyPlay | Triggered when enough data has been loaded to start playing the video. Returns the vid parameter. | ✔ | ✘ |
| s2j_onPlayStart | Triggered when the video starts playing for the first time. Returns the vid parameter. | ✔ | ✔ |
| s2j_onVideoPlay | Triggered when the video starts playing for the first time or resumes from pause. Returns the vid parameter. | ✔ | ✔ |
| s2j_onVideoPause | Triggered when the video is paused. Returns the vid parameter. | ✔ | ✔ |
| s2j_onVideoSeek | Triggered when the video progress is dragged. Returns the start and end seek time points and the vid parameter. | ✔ | ✔ |
| s2j_onPlayOver | Triggered when the current video finishes playing. Returns the vid parameter. | ✔ | ✔ |
| s2j_volumeChange | Triggered when the audio volume changes. Returns the vid parameter and the changed volume. | ✔ | ✘ |
| s2j_onFullScreen | Triggered when the player enters fullscreen. Returns the vid parameter. Note: On mobile, only effective in web fullscreen. |
✘ | ✔ |
| s2j_onNormalScreen | Triggered when the player exits fullscreen. Returns the vid parameter. Note: On mobile, only effective in web fullscreen. |
✘ | ✔ |
| s2j_onPlayerError | Triggered when a playback error occurs. Returns the vid parameter. | ✔ | ✔ |
| HTML5Load | Triggered when switching from Flash to H5 player. | ✔ | ✘ |
| flashLoad | Triggered when switching from H5 player to Flash player on PC. | ✔ | ✘ |
| serverError | Triggered when a business logic error occurs, such as authorization verification failure or domain whitelist/blacklist validation failure. Returns the event name and error code. | ✔ | ✔ |
| onChangeMode | Triggered when the audio/video mode is switched. Returns the vid parameter, the mode after switching, and the mode before switching. | ✔ | ✔ |
| onFullscreenProxy | When the fullscreenProxy parameter is set to true, clicking the fullscreen button does not call the fullscreen API but triggers the window.onFullscreenProxy(vid, toFullscreen) event. The caller handles fullscreen themselves, suitable for overlaying custom elements in fullscreen mode. |
✔ | ✘ |
| onFullPageScreen | When full_page_screen is set to true, clicking the web fullscreen button triggers the window.onFullPageScreen(vid, currentStatus) event. The caller handles web fullscreen themselves. window.onFullPageScreen = function (vid, currentStatus) {}) |
✔ | ✘ |
| adSkip | Returns the type of skipped ad, consistent with the set ad type. Triggered when an ad is skipped. Can be used to distinguish VIP users and whether the ad can truly be skipped. |
✔ | ✘ |
| teaserSkip | Triggered when clicking to skip the teaser. | ✔ | ✘ |
| onTimeupdate | Triggered during video playback and seek. Returns the current playback progress in real-time (in seconds, with decimal points). | ✔ | ✘ |
| toggleClickPlay | Triggered when the user actively plays/pauses via the UI. Returns a Boolean indicating whether it is paused. | ✔ | ✔ |
Note: Due to historical reasons, the event return parameters of the three web-based players (Flash, PC H5, and Mobile H5) have not yet been aligned. The table above is based on the PC H5 player.
Subscribe via the player instance's on method:
function fn(params) {
console.log('播放器数据初始化完毕：',params);
}
player.on('s2j_onPlayerInitOver', fn);
Unsubscribe using the off method of the player instance:
player.off('s2j_onPlayerInitOver', fn);
