Subtitle Settings

1. Overview

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

Subtitle Display Example

The image below shows the effect of zwplayer presenting dual subtitles simultaneously:

Dual subtitle display example

Subtitle Control Example

Users can enable or disable either subtitle track through 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 websites
VTT: Web video subtitle standard format
BCC: Bilibili subtitle format (JSON format)

3. JSON Subtitle Format Description

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": "Entering the 21st century"
        },
        {
            "from": 8.79,
            "to": 12.68,
            "sid": 2,
            "location": 2,
            "content": "China becomes an important role on the world stage"
        },
        {
            "from": 14.79,
            "to": 18.68,
            "sid": 3,
            "location": 2,
            "content": "China is one of the most populous countries in the world"
        }
    ]
}

File-level Attribute Description

Attribute Name	Description	Required
font_size	Font size (relative size). Calculation method: Scale video to 1024×576, 32-pixel font size is 1. Actual font size is calculated based on this value so that subtitle size changes synchronously when the video playback window changes.	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 font has outline	Optional
type	Subtitle type (not used for actual rendering)	Optional
lang	Subtitle language (e.g., zh, zh-TW, en)	Optional
version	Production tool version (not used for actual rendering)	Optional
body	Specific subtitle content (JS array)	Required

Subtitle Element Attribute (body) Description

Each subtitle element is an object contained in the body array with the following attributes:

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 Descriptions

SRT and VTT files are standard subtitle file formats, and zwplayer also fully supports loading these files. For detailed format specifications of these subtitle files, please refer to 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 element ID or DOM object
});

// Delay loading subtitles in timer event
setTimeout(function() {
    if (window.mainplayer) {
        // Get subtitle URL (in actual applications may be obtained via Ajax)
        var subtitleURL_korean = 'http://example.com/data/movies.en.srt';
        
        // Set first subtitle
        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 second subtitle
        window.mainplayer.addSubtitle(subtitleURL_japan, '2');
    }
}, 1000);
</script>

6. Notes

It is recommended to load subtitles after the video has loaded to ensure the best user experience
Except for the body attribute, other attributes in the JSON format can be omitted
Subtitle track identifiers ('1', '2') are used to distinguish display positions for dual subtitles

Catalog Navigation