zwplayer 字幕使用说明

1. 概述

字幕用于录播文件的播放，显示视频声音轨道的文字内容。zwplayer 提供完整的字幕系统，支持同时呈现两路字幕（双字幕功能）、运行时样式自定义、全文检索与跳转、机器翻译以及按字幕区间的循环播放，为用户提供灵活且强大的字幕观看体验。

字幕显示示例

下图展示了 zwplayer 同时呈现双字幕的效果：

字幕控制示例

用户可以通过播放器控制条上的 CC 菜单来管理所有字幕功能：

2. 字幕菜单（CC 菜单）

点击播放器控制条上的 CC 按钮，即可打开字幕菜单面板。菜单包含以下功能区域：

3. 添加字幕

zwplayer 提供三种方式加载字幕：

3.1 通过菜单添加

在 CC 菜单中点击 “添加字幕文件” 按钮，在弹出的文件选择器中选择本地字幕文件（支持多选）。支持格式：.srt、.vtt、.bcc、.json。

3.2 通过 API 动态添加

使用 addSubtitle(url, pos, title) 方法在运行时动态添加字幕轨道：

// 设置主字幕（pos 为 '1'）
player.addSubtitle('https://example.com/movie_zh.srt', '1', '中文字幕');

// 设置副字幕（pos 为 '2'）
player.addSubtitle('https://example.com/movie_en.srt', '2', 'English');

• url：字幕文件地址（支持 HTTP/HTTPS URL 或本地文件对象）
• pos：字幕轨道标识，'1' 为主字幕、'2' 为副字幕。其他值或不传则仅加入字幕列表，可在菜单中手动选择
• title：字幕名称（在菜单中显示）

3.3 通过初始化配置

在创建播放器时通过 subtitles 参数传入。支持 URL 字符串、数组或对象数组：

// 单个字幕
subtitles: 'https://cdn.example.com/subtitles/movie.vtt'

// 多个字幕（按数组顺序自动分配 pos）
subtitles: ['movie_zh.srt', 'movie_en.srt']
// 等同于 addSubtitle('movie_zh.srt', '1') 和 addSubtitle('movie_en.srt', '2')

// 对象格式：可自定义 title 和 pos
subtitles: [
    { url: 'movie_zh.srt', title: '中文', pos: '1' },
    { url: 'movie_en.srt', title: 'English', pos: '2' },
    { url: 'movie_jp.srt', title: '日本語' }
    // 未指定 pos 的字幕仅加入列表，可在菜单中手动选择
]

pos 赋值规则：

向后兼容：原有 addSubtitle(url, '1') / addSubtitle(url, '2') 用法完全不受影响。

支持的字幕格式

• JSON：zwplayer 自定义格式
• SRT：大多数视频网站采用的格式
• VTT：Web 视频字幕标准格式
• BCC：Bilibili 字幕格式（JSON 格式）

4. 双语字幕选择

zwplayer 支持同时显示两路不同语言的字幕。开启双语模式的方法：

1. 确保已加载 ≥2 条字幕轨道
2. 打开 CC 菜单，开启 “双语字幕” 开关
3. 菜单自动切换为双列布局，左侧为 主字幕、右侧为 副字幕
4. 分别在两列中点击选择要显示的字幕轨道

关闭双语开关后，菜单恢复为单列列表模式。

5. 字幕设置

在 CC 菜单中点击 “字幕设置”，打开字幕样式设置面板。面板顶部有 主字幕 / 副字幕 两个 Tab，可分别调整每路字幕的样式。

5.1 字号

每路字幕独立设置，提供 5 档：

5.2 颜色

每路字幕独立设置，提供 12 种预设颜色：

白色、浅灰、深灰、黄色、橙色、红色、绿色、青色、蓝色、紫色、粉色、黑色

5.3 勾边

每路字幕独立设置，提供 4 种勾边样式：

5.4 位置

全局设置（作用于主字幕），通过 6 宫格选择器定位：

5.5 其他选项

设置面板底部提供 “恢复默认” 按钮，一键重置所有选项。

6. 字幕搜索

在 CC 菜单中点击 “字幕搜索”，打开字幕搜索面板。

使用方法

1. 在搜索输入框中输入关键词，匹配结果实时更新
2. 双语模式下：面板顶部显示 全部 / 主 / 副 三个范围筛选按钮，可按字幕轨道过滤
3. 单击搜索结果 → 跳转到对应时间点
4. 播放过程中，搜索结果会自动高亮当前正在显示的字幕条目

行级定位与搜索态挂起

在搜索结果中定位某条字幕后，常常需要查看它的上下文（前后相邻的字幕），或基于它做跨行段落循环。面板提供「定位 + 挂起 / 恢复」机制，让这两种操作无缝衔接：

• 📍 定位按钮：输入关键词后，每条搜索结果左侧会出现一个定位按钮（仅在搜索结果列表中显示）。点击它，面板会切换到全量字幕列表，自动滚动到该条字幕并置于可视区顶部，同时关键词会持续高亮，方便在上下文中识别。
• 挂起状态：定位后面板进入「挂起态」——底部状态栏会出现一个 「↩ 恢复对「关键词」的搜索」 按钮，表示当前显示的是全量列表，但你的搜索词仍被保留。此时可自由滚动浏览上下文、进行跨行段落循环等操作。
• 恢复搜索：在全量列表中完成操作后，点击状态栏的「恢复搜索」按钮，面板会基于最新的字幕数据重新执行过滤，回到搜索结果列表，继续检索下一条。
• 解除挂起：挂起状态下，清空搜索框（点 ✕ 或删除文本）会直接回到纯净的全量列表，挂起状态解除。

💡 设计要点：定位 + 挂起机制让你在「精准定位某条字幕」和「在全量列表中做跨行操作」之间自由切换，而不会丢失搜索上下文。

搜索范围

搜索会遍历已加载的所有字幕条目，对字幕文本内容进行关键词匹配，结果显示时间戳和上下文内容。

7. 字幕循环

在字幕搜索面板中，每条搜索结果右侧都有一个 循环按钮。点击后，播放器将在该字幕条目的时间区间内循环播放，再次点击取消循环。

跨行段落循环：在全量列表（或挂起态定位后的全量列表）中，连续点击两条字幕的循环按钮，可将它们聚合成一个循环块，播放器会在跨越多条字幕的整段区间内循环。再次点击区间端点的循环按钮可调整或解除区间。

注意事项

• 字幕循环与章节循环共用同一播放槽位，同时只能有一个循环生效
• 如果正在播放字幕循环期间手动拖动进度条到循环区间外，循环将自动解除
• 搜索结果列表中不支持跨行段落循环：搜索命中条目通常不连续，跨行扩展会指向列表外的字幕，因此搜索结果列表中每条仅支持单句循环。如需段落循环，请先用 📍 定位按钮切到全量列表
• 双语「全部」模式下不支持段落循环：双语混合时跨轨区间会混乱，因此「全部」轨道筛选下（无论搜索结果还是全量列表）仅支持单句循环。如需段落循环，请切换到「主」或「副」单轨

8. 字幕翻译

在 CC 菜单中点击 “字幕翻译”，打开字幕翻译面板。配置 translateApi 参数后该按钮自动出现，用户可选择目标语言将当前字幕翻译为对应语言，翻译结果作为副字幕叠加显示。详细配置请参阅 参数配置 → translateApi。

8.1 翻译服务协议

用户可根据以下协议自行实现翻译服务端，并通过 translateApi 参数将服务地址配置到播放器中。

播放器向翻译服务发送 POST 请求，编码为 multipart/form-data，包含以下字段：

翻译服务应返回 JSON 格式的响应，结构如下：

{
  "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"
  }
}

失败响应示例：{ "success": false, "error": "Unsupported target language" }

请求超时时间默认 30 秒。

9. HLS 内嵌字幕预加载

9.1 背景与原理

HLS 流的内嵌字幕（Closed Captions）采用分段传输机制，每个字幕条目被切分为多个小片段随视频流逐段下载。这意味着传统播放器只能边播边获取当前播放位置附近的字幕片段，无法一次性获取完整字幕文件，导致字幕搜索和翻译功能在 HLS 场景下难以使用。

ZWPlayer 通过预构建机制解决这一限制：播放器在检测到 HLS MANIFEST 中的内嵌字幕轨后，会主动逐个下载所有字幕分段，并将它们拼接为完整的字幕文件。即使视频尚未播放到对应位置，用户也可以对全部字幕内容进行全文检索和翻译。

9.2 预加载的字幕管理

预加载完成后，HLS 内嵌字幕将获得与外挂字幕完全一致的待遇：

• 自动加入 CC 菜单：预构建的字幕轨道自动出现在字幕选择列表中，用户可一键切换为主字幕或副字幕
• 全文搜索：在字幕搜索面板中可对全部字幕条目进行关键词检索，单击跳转到对应时间点
• 字幕翻译：可通过翻译面板将未播放部分的字幕内容提前翻译为目标语言
• 统一处理：HLS 内嵌字幕与外挂字幕在搜索、翻译、设置等功能中采用相同的数据结构，无需区分处理

9.3 字幕导出与二次利用

配合 subtitleDownload 配置，用户可将预构建的 HLS 内嵌字幕导出为 SRT 文件下载到本地，便于后续重新编辑、翻译或与其他视频复用。

对于内容平台和在线教育场景，这一机制意味着无需为 HLS 视频单独准备外挂字幕文件，即可在播放器中直接利用内嵌字幕完成搜索、翻译和导出的完整工作流。

10. JSON 字幕格式说明

示例文件

{
    "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": "中国是世界人口最多的国家之一"
        }
    ]
}

文件级属性说明

字幕元素属性(body)说明

每个字幕元素为一个对象，包含在 body 数组中，具有以下属性：

11. 其他格式说明

SRT 与 VTT 文件是标准的字幕文件格式，zwplayer 也全面支持加载这些文件。关于这些字幕文件的详细格式说明，请参考相关技术文档。

12. 代码示例

以下示例演示如何在 zwplayer 中加载双语字幕：

<script language="javascript">
window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#player-holder', // 可以是元素ID或DOM对象
});

// 在时钟事件中延时加载字幕
setTimeout(function() {
    if (window.mainplayer) {
        // 设置第一字幕（主字幕）
        window.mainplayer.addSubtitle('http://example.com/data/movies.en.srt', '1', 'English');

        // 设置第二字幕（副字幕）
        window.mainplayer.addSubtitle('http://example.com/data/movies.zh.srt', '2', '中文字幕');
    }
}, 1000);
</script>

13. 注意事项

1. 建议在视频加载完成后再加载字幕，以确保最佳用户体验
2. 除 body 属性外，JSON 格式的其他属性均可省略
3. 字幕轨道标识（'1'、'2'）用于区分双字幕显示位置
4. 字幕翻译功能需要配置 translateApi 参数，未配置时翻译按钮不会出现在菜单中；用户可根据协议自行实现翻译服务端
5. 字幕循环与章节循环共用同一播放槽位，同时只能有一个循环生效；手动 seek 到循环区间外会自动解除循环
6. 在线工具：可通过 在线字幕编辑工具 创建、翻译和导出 SRT、VTT 等格式字幕