zwplayer Subtitle Usage Guide

1. Overview

Subtitles are used for playing back recorded files, displaying text content of the video’s audio track. zwplayer provides a complete subtitle system, supporting simultaneous display of two subtitle tracks (dual subtitle feature), runtime style customization, full-text search and jump, machine translation, and loop playback by subtitle intervals, offering users a flexible and powerful subtitle viewing experience.

Subtitle Display Example

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

Subtitle Control Example

Users can manage all subtitle functions via the CC menu on the player control bar:

2. Subtitle Menu (CC Menu)

Click the CC button on the player control bar to open the subtitle menu panel. The menu contains the following functional areas:

3. Adding Subtitles

zwplayer provides three ways to load subtitles:

3.1 Add via Menu

Click the “Add Subtitle File” button in the CC menu and select local subtitle files in the pop-up file selector (multi-select supported). Supported formats: .srt, .vtt, .bcc, .json.

3.2 Add Dynamically via API

Use the addSubtitle(url, pos, title) method to dynamically add subtitle tracks at runtime:

// Set main subtitle (pos is '1')
player.addSubtitle('https://example.com/movie_zh.srt', '1', '中文字幕');

// Set secondary subtitle (pos is '2')
player.addSubtitle('https://example.com/movie_en.srt', '2', 'English');

• url: Subtitle file address (supports HTTP/HTTPS URL or local file object)
• pos: Subtitle track identifier. '1' for Main Subtitle, '2' for Secondary Subtitle. Other values or omitting will only add to the subtitle list, available for manual selection in the menu
• title: Subtitle name (displayed in the menu)

3.3 Add via Initialization Configuration

Pass in the subtitles parameter when creating the player. Supports URL strings, arrays, or object arrays:

// Single subtitle
subtitles: 'https://cdn.example.com/subtitles/movie.vtt'

// Multiple subtitles (pos assigned automatically in array order)
subtitles: ['movie_zh.srt', 'movie_en.srt']
// Equivalent to addSubtitle('movie_zh.srt', '1') and addSubtitle('movie_en.srt', '2')

// Object format: customizable title and pos
subtitles: [
    { url: 'movie_zh.srt', title: '中文', pos: '1' },
    { url: 'movie_en.srt', title: 'English', pos: '2' },
    { url: 'movie_jp.srt', title: '日本語' }
    // Subtitles without specified pos are only added to the list, available for manual assignment in the menu
]

pos Assignment Rules:

Backward Compatibility: The original addSubtitle(url, '1') / addSubtitle(url, '2') usage remains fully unaffected.

Supported Subtitle Formats

• JSON: zwplayer custom format
• SRT: Format adopted by most video sites
• VTT: Web video subtitle standard format
• BCC: Bilibili subtitle format (JSON format)

4. Dual Subtitle Selection

zwplayer supports displaying two different language subtitle tracks simultaneously. Method to enable dual subtitle mode:

1. Ensure ≥2 subtitle tracks are loaded
2. Open the CC menu and enable the “Dual Subtitles” toggle
3. The menu automatically switches to dual-column layout, with Main Subtitle on the left and Secondary Subtitle on the right
4. Click to select the desired subtitle tracks in each column

After disabling the dual toggle, the menu reverts to single-column list mode.

5. Subtitle Settings

Click “Subtitle Settings” in the CC menu to open the subtitle style settings panel. The top of the panel features two tabs: Main Subtitle / Secondary Subtitle, allowing independent style adjustment for each track.

5.1 Font Size

Set independently for each track, providing 5 levels:

5.2 Color

Set independently for each track, providing 12 preset colors:

White, Light Gray, Dark Gray, Yellow, Orange, Red, Green, Cyan, Blue, Purple, Pink, Black

5.3 Stroke

Set independently for each track, providing 4 stroke styles:

5.4 Position

Global setting (applies to Main Subtitle), positioned via a 6-grid selector:

5.5 Other Options

The bottom of the settings panel provides a “Restore Defaults” button to reset all options with one click.

6. Subtitle Search

Click “Subtitle Search” in the CC menu to open the subtitle search panel.

How to Use

1. Enter keywords in the search input box, matching results update in real-time
2. In Dual Subtitle Mode: The top of the panel displays All / Main / Sec filter buttons to filter by subtitle track
3. Single-click a search result → Jump to the corresponding timestamp
4. During playback, the search result for the currently displaying subtitle will be automatically highlighted

Locate in Full List & Search Suspend

After locating a subtitle from search results, you often need to view its context (neighboring subtitles) or perform cross-line range looping based on it. The panel provides a “Locate + Suspend / Resume” mechanism for seamless switching:

• 📍 Locate Button: After entering a keyword, each search result shows a locate button on its left (visible only in the search results list). Click it to switch the panel to the full subtitle list, auto-scroll to that subtitle and place it near the top of the viewport, while the keyword stays highlighted for easy identification in context.
• Suspended State: After locating, the panel enters “suspended” mode — a “↩ Resume search for ‘keyword’” button appears in the status bar at the bottom, indicating that the full list is shown but your search term is still retained. You can freely scroll through context, perform cross-line range looping, etc.
• Resume Search: After finishing operations in the full list, click the “Resume search” button in the status bar. The panel re-runs the filter on the latest subtitle data and returns to the search results list to continue searching.
• Exit Suspend: While suspended, clearing the search box (click ✕ or delete text) returns directly to a clean full list, exiting the suspended state.

💡 Design Note: The locate + suspend mechanism lets you freely switch between “precisely locating a subtitle” and “doing cross-line operations in the full list” without losing your search context.

Search Scope

The search traverses all loaded subtitle items, performing keyword matching on the subtitle text content, displaying timestamps and context.

7. Subtitle Looping

In the subtitle search panel, each search result has a Loop Button on the right. Clicking it causes the player to loop playback within the time range of that subtitle item. Click again to cancel looping.

Cross-line Range Looping: In the full list (or the full list after locating in suspended mode), consecutively clicking the loop buttons of two subtitles aggregates them into a loop block; the player then loops across the entire range spanning multiple subtitles. Clicking the loop button at either endpoint of the range adjusts or releases the range.

Notes

• Subtitle looping and chapter looping share the same playback slot; only one loop can be active at a time
• If the progress bar is manually dragged outside the loop range while a subtitle loop is active, the loop will automatically disengage
• Cross-line range looping is not supported in the search results list: Search matches are usually non-contiguous, and cross-line expansion would point to subtitles outside the list, so each result in the search list only supports single-line looping. For range looping, use the 📍 locate button to switch to the full list first
• Range looping is not supported in Dual “All” mode: Cross-track ranges cause confusion in dual-subtitle mixing, so under the “All” track filter (whether in search results or full list), only single-line looping is supported. For range looping, switch to the “Main” or “Sec” single track

8. Subtitle Translation

Click “Subtitle Translation” in the CC menu to open the subtitle translation panel. After configuring the translateApi parameter, this button appears automatically. Users can select a target language to translate the current subtitles, with the result overlaid as the Secondary Subtitle. For detailed configuration, please refer to Parameter Configuration → translateApi.

8.1 Translation Service Protocol

Users can implement their own translation server based on the following protocol and configure the service address into the player via the translateApi parameter.

The player sends a POST request to the translation service, encoded as multipart/form-data, containing the following fields:

The translation service should return a JSON formatted response with the following structure:

{
  "success": true,
  "data": {
    "content": "1\n00:00:15,000 --> 00:00:17,951\n在左边我们可以看到……\n\n2\n00:00:18,166 --> 00:00:20,083\n在右边我们可以看到……\n\n3\n00:00:20,119 --> 00:00:21,962\n……那些摇头晃脑的家伙\n\n",
    "format": "srt",
    "totalSubtitles": 3,
    "filename": "subtitle.translated.srt"
  }
}

Example failure response: { "success": false, "error": "Unsupported target language" }

Default request timeout is 30 seconds.

9. HLS Embedded Subtitle Preloading

When playing HLS streams, the player automatically detects embedded Closed Captions tracks carried in the MANIFEST and downloads subtitle segment files locally in advance. Through this preloading mechanism, even if the video has not reached the corresponding position, users can search all subtitle content in the subtitle search panel or pre-translate unplayed sections via the translation panel.

Preloaded subtitle tracks are automatically added to the CC subtitle menu for direct user switching.

10. 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

Subtitle Element Attribute (body) Description

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

11. Other Format Descriptions

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

12. Code Example

The following example demonstrates how to load dual 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
});

// Delayed subtitle loading in a timer event
setTimeout(function() {
    if (window.mainplayer) {
        // Set first subtitle (Main Subtitle)
        window.mainplayer.addSubtitle('http://example.com/data/movies.en.srt', '1', 'English');

        // Set second subtitle (Secondary Subtitle)
        window.mainplayer.addSubtitle('http://example.com/data/movies.zh.srt', '2', '中文字幕');
    }
}, 1000);
</script>

13. Notes

1. It is recommended to load subtitles after the video has finished loading to ensure the best user experience
2. Except for the body attribute, all other attributes in JSON format can be omitted
3. Subtitle track identifiers ('1', '2') are used to distinguish the display positions of dual subtitles
4. The subtitle translation feature requires configuring the translateApi parameter; without configuration, the translation button will not appear in the menu. Users can implement their own translation server according to the protocol
5. Subtitle looping and chapter looping share the same playback slot; only one loop can be active at a time. Manually seeking outside the loop range will automatically disengage the loop
6. Online Tool: You can use the Online Subtitle Editor to create, translate, and export SRT, VTT, and other format subtitles