字幕设置

1. 概述

字幕用于录播文件的播放，显示视频文件声音轨道的文字内容。zwplayer 支持同时呈现两路字幕（双字幕功能），为用户提供更灵活的字幕观看体验。

字幕显示示例

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

双字幕显示示例

字幕控制示例

用户可以通过播放器控制条上的"CC"菜单来开启或关闭任意一路字幕：

字幕控制菜单

2. 添加字幕

要添加字幕支持，需要调用 zwplayer 的 addSubtitle 方法。建议在播放器加载完视频后再加载字幕。

支持的字幕格式

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

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

文件级属性说明

属性名	说明	是否必须
font_size	字体尺寸（相对尺寸），计算方式：将视频缩放为1024×576，32像素字体尺寸为1，实际的字体尺寸根据这个值计算出来的，以便于字幕尺寸在视频播放窗口发生变化时同步变化。	可选
font_color	字体颜色（HTML颜色值）	可选
background_alpha	字体背景透明度（1为不透明，0为全透明）	可选
background_color	字体背景颜色	可选
Stroke	字体是否勾边	可选
type	字幕类型（实际渲染用不到）	可选
lang	字幕语言（如：zh、zh-TW、en）	可选
version	制作工具版本（实际渲染用不到）	可选
body	字幕具体内容（JS数组）	必须

字幕元素属性(body)说明

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

属性名	说明	是否必须
from	字幕开始时间（相对于媒体时间，单位：秒）	必须
to	字幕结束时间（相对于媒体时间，单位：秒）	必须
sid	字幕元素ID	可选
location	字幕呈现位置	可选
content	字幕文本内容	必须

4. 其他格式说明

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

5. 代码示例

以下示例演示如何在 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) {
        // 获取字幕URL（实际应用中可能通过Ajax获取）
        var subtitleURL_korean = 'http://example.com/data/movies.en.srt';
        
        // 设置第一字幕
        window.mainplayer.addSubtitle(subtitleURL_korean, '1');
        
        // 如果提供双字幕，请使用以下代码（否则删除或注释）
        var subtitleURL_japan = 'http://example.com/data/movies.zh.srt';
        // 设置第二字幕
        window.mainplayer.addSubtitle(subtitleURL_japan, '2');
    }
}, 1000);
</script>

6. 注意事项

建议在视频加载完成后再加载字幕，以确保最佳用户体验
除 body 属性外，JSON 格式的其他属性均可省略
字幕轨道标识（'1'、'2'）用于区分双字幕显示位置

目录导航