标签本身不包含时间戳,时间信息严格位于关联的WebVTT(.vtt)文件中,其首行须为WEBVTT,每条字幕块含绝对时间戳HH:MM:SS.mmm --> HH:MM:SS.mmm及文本,毫秒必须三位、箭头前后各两个空格,文件需UTF-8无BOM编码且服务器返回text/vtt MIME类型。

track元素本身不写时间戳,时间戳在.vtt文件里
直接往 <track></track> 标签上加时间戳是无效的——它只负责声明轨道,不承载时间信息。所有时间控制逻辑都落在关联的 WebVTT 文件中。你看到的“00:01:23.456 --> 00:01:25.789”这类格式,必须出现在 subtitles_zh.vtt 这类文件里,而不是 HTML 中。
常见错误现象:<track datetime="00:01:23.456"></track> 或 <track data-start="123456"></track> —— 浏览器完全忽略这些自定义属性,<track></track> 标准属性列表里根本没有 datetime 或 start。
-
kind、src、srclang、label、default是仅有的合法属性 -
src指向的 .vtt 文件必须可访问(注意 CORS,尤其本地开发时用 file:// 协议会失败) - 服务器需返回正确 MIME 类型:
text/vtt;Nginx/Apache 配置漏掉这行,Chrome 就静默拒载
WebVTT 时间戳格式必须严格到毫秒位
哪怕一个空格错位,Chrome 或 Firefox 就跳过整条 cue(字幕块)。标准格式是:HH:MM:SS.mmm --> HH:MM:SS.mmm,中间两个空格,毫秒必须三位。
错误示例:00:01:02.5 --> 00:01:04.50(毫秒位数不齐)、00:01:02.500 -->00:01:04.500(箭头前少空格)、00:01:02,500 --> 00:01:04,500(逗号代替点)—— 全部失效。
立即学习“前端免费学习笔记(深入)”;
- 首行必须是纯
WEBVTT,不能带 BOM、不能有注释、不能空行前置 - 时间戳不支持相对值(如 +2s),只接受绝对时间点
- 同一文件内时间轴必须严格递增,不能交叉或倒流,否则首个违规 cue 后全部丢弃
动态注入字幕时,时间戳对齐依赖 video.textTracks
如果你用 JS 动态添加字幕(比如加载用户选择的语言),不能只靠 video.addTextTrack() 就完事。浏览器不会自动解析你传入的字符串里的时间戳——你得手动创建 VTTCue 实例,并显式设置 startTime、endTime 和 text。
例如:
const track = video.addTextTrack('subtitles', '中文', 'zh');
const cue = new VTTCue(12.345, 14.678, '你好,世界');
track.addCue(cue);
这里 12.345 和 14.678 就是秒级浮点数时间戳,对应视频播放位置。若从 WebVTT 字符串解析,必须自己做正则提取并转成数字,new VTTCue() 不接受字符串格式时间。
-
VTTCue构造函数参数单位是秒(非毫秒),传12345会被当 12 秒 345 秒处理 - 动态添加后,需确保
track.mode = 'showing',否则 cue 不渲染 - 若视频已播放,新 cue 可能因时间已过而被跳过;建议先
video.pause(),注入后再video.play()
流媒体(HLS/DASH)里 track 的时间戳根本不起作用
在 hls.js 或 dash.js 场景下,<track src="xxx.vtt"></track> 声明的外挂字幕和流内字幕是两套系统。流协议自带的字幕轨道(如 HLS 的 EXT-X-MEDIA:TYPE=SUBTITLES)由 JS 播放器解析后,手动注入 video.textTracks,此时时间戳精度要求更高:首帧偏差 >100ms 就可能丢失同步。
容易被忽略的关键点:
- 流媒体字幕 PTS(Presentation Time Stamp)常比音视频轨晚 200ms,不能直接把 VTT 里的时间戳原样塞进
VTTCue;需减去该偏移量再注入 - hls.js 的
subtitleTrack切换后,旧 track 的mode必须设为'disabled',否则多个 active cue 冲突导致文字重叠 - WebVTT 文件若含
NOTE或注释行,某些版本 dash.js 会解析失败——生产环境务必删净
真正精确定位教学,不是调对一个标签,而是盯住时间戳从服务端生成、文件编码、HTTP 响应、JS 注入到最终渲染的每一步精度损失。毫秒级偏差,在用户眼里就是字幕“卡顿”或“错位”。



















