`zwplayer` Subtitle Usage Guide

1. Overview

Subtitles are used for the playback of recorded files, displaying the text content of the audio track of the video file. zwplayer supports displaying two subtitle tracks simultaneously (dual subtitle feature), providing users with a more flexible subtitle viewing experience.

Subtitle Display Example

The image below demonstrates the effect of zwplayer displaying dual subtitles simultaneously:

Dual Subtitle Display Example

Subtitle Control Example

Users can enable or disable any subtitle track via the “CC” menu on the player control bar:

Subtitle Control Menu

2. Adding Subtitles

To add subtitle support, you need to call the addSubtitle method of zwplayer. It is recommended to load subtitles after the player has finished loading the video.

Supported Subtitle Formats

JSON: zwplayer custom format
SRT: Format used by most video sites
VTT: Standard Web video subtitle format
BCC: Bilibili subtitle format (JSON format)

3. JSON Subtitle Format Specification

Sample File

{
    "font_size": 0.4,
    "font_color": "#FFFFFF",
    "background_alpha": 0.5,
    "background_color": "#9C27B0",
    "Stroke": "none",
    "type": "AIsubtitle",
    "lang": "zh",
    "version": "v1.4.0.4",
    "body": [
        {
            "from": 7.26,
            "to": 8.79,
            "sid": 1,
            "location": 2,
            "content": "进入21世纪"
        },
        {
            "from": 8.79,
            "to": 12.68,
            "sid": 2,
            "location": 2,
            "content": "中国成为世界舞台上的重要角色"
        },
        {
            "from": 14.79,
            "to": 18.68,
            "sid": 3,
            "location": 2,
            "content": "中国是世界人口最多的国家之一"
        }
    ]
}

File-level Attribute Description

Attribute Name	Description	Required
font_size	Font size (relative size). Calculation method: Scale the video to 1024×576, where a 32-pixel font size equals 1. The actual font size is calculated based on this value, ensuring subtitle size scales synchronously when the video playback window changes size.	Optional
font_color	Font color (HTML color value)	Optional
background_alpha	Font background transparency (1 is opaque, 0 is fully transparent)	Optional
background_color	Font background color	Optional
Stroke	Whether the font has a stroke	Optional
type	Subtitle type (not used in actual rendering)	Optional
lang	Subtitle language (e.g., zh, zh-TW, en)	Optional
version	Creation tool version (not used in actual rendering)	Optional
body	Subtitle specific content (JS array)	Required

Subtitle Element Attribute (body) Description

Each subtitle element is an object contained in the body array and has the following properties:

Attribute Name	Description	Required
from	Subtitle start time (relative to media time, unit: seconds)	Required
to	Subtitle end time (relative to media time, unit: seconds)	Required
sid	Subtitle element ID	Optional
location	Subtitle display position	Optional
content	Subtitle text content	Required

4. Other Format Specifications

SRT and VTT files are standard subtitle file formats, and zwplayer also fully supports loading these files. For detailed specifications of these subtitle files, please refer to the relevant technical documentation.

5. Code Example

The following example demonstrates how to load subtitles in zwplayer:

<script language="javascript">
window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#player-holder', // Can be an element ID or DOM object
});

// Delay loading subtitles in a timer event
setTimeout(function() {
    if (window.mainplayer) {
        // Get subtitle URL (might be obtained via Ajax in actual applications)
        var subtitleURL_korean = 'http://example.com/data/movies.en.srt';
        
        // Set the first subtitle track
        window.mainplayer.addSubtitle(subtitleURL_korean, '1');
        
        // If providing dual subtitles, use the following code (otherwise delete or comment out)
        var subtitleURL_japan = 'http://example.com/data/movies.zh.srt';
        // Set the second subtitle track
        window.mainplayer.addSubtitle(subtitleURL_japan, '2');
    }
}, 1000);
</script>

6. Notes

It is recommended to load subtitles after the video has finished loading to ensure the best user experience.
Except for the body property, all other properties in the JSON format can be omitted.
Subtitle track identifiers (‘1’, ‘2’) are used to distinguish the display positions of dual subtitles.
Online Tool: Use the Online Subtitle Editor to create, translate, and export SRT, VTT, and other subtitle formats.

zwplayer Subtitle Usage Guide