提供高质量且同步准确的字幕,是专业视频流媒体的重要环节。在 HLS 生态中,WebVTT(网页视频文本轨道)是字幕与隐藏式字幕的标准格式。传统字幕通常使用单个完整文件,而 HLS 一般要求把字幕分段,并通过主播放列表引用,因此视频工程师会面对一系列独特挑战。
本指南深入介绍通过 M3U8 分发多语言 WebVTT 的架构,涵盖主播放列表配置、VTT 分段,以及常见同步和显示问题的排查方法。
理解 HLS 架构中的 WebVTT
为 HLS 流添加字幕时,并不是简单地把单个 `.vtt` 文件附加到视频播放器标签。HLS 会把字幕视为独立媒体轨道。这种模块化方式让播放器只在需要时获取字幕文本,从而尽量减少带宽消耗,并可在不同语言之间无缝切换。
标准的多语言部署架构包括:
- 主播放列表(`master.m3u8`):使用
#EXT-X-MEDIA标签声明可用的字幕轨道,并使用SUBTITLES属性在#EXT-X-STREAM-INF中将它们与视频变体关联起来。 - 字幕播放列表(例如 `subs_en.m3u8`):包含 WebVTT 分段文件的媒体播放列表,其中带有完整时间戳和 `#EXTINF` 时长标签。
- WebVTT 分段文件(`.vtt`):实际的文本片段,通常按视频分片的时长切分。
配置主播放列表
多语言字幕分发的核心在于主播放列表。#EXT-X-MEDIA 标签用于定义替代媒体,包括音频和字幕。下面分析一种可靠的英语和西班牙语字幕实现。
#EXTM3U
#EXT-X-VERSION:4
# Subtitle Definitions
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",URI="subs/en/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Spanish",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="es",URI="subs/es/prog_index.m3u8"
# Video Variants
#EXT-X-STREAM-INF:BANDWIDTH=1500000,RESOLUTION=854x480,SUBTITLES="subs"
video/480p/prog_index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=3000000,RESOLUTION=1280x720,SUBTITLES="subs"
video/720p/prog_index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=6000000,RESOLUTION=1920x1080,SUBTITLES="subs"
video/1080p/prog_index.m3u8
解析 #EXT-X-MEDIA 属性
- TYPE=SUBTITLES:明确表示此媒体是一条字幕轨道。
- GROUP-ID="subs":把字幕与视频变体连接起来的唯一标识符。
SUBTITLES="subs"是#EXT-X-STREAM-INF标签中的属性,其值必须与该 ID 完全一致。 - DEFAULT=YES/NO:表示用户尚未选择时,是否应默认播放此轨道。同一组中只能有一条轨道设为 DEFAULT=YES。
- AUTOSELECT=YES:允许播放器根据系统语言偏好自动选择这条轨道。
- LANGUAGE="en":使用 RFC 5646 语言标签,这对原生播放器的语言菜单至关重要。
强制字幕
设置 FORCED=YES 表示该轨道包含主要音频中外语对白所需的必要翻译,例如以英语为主的电影里出现的精灵语。即使全局关闭字幕,强制字幕也会自动显示。
构建字幕播放列表
字幕播放列表与视频媒体播放列表非常相似,其中包含一系列 WebVTT 分段。
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:6.000,
seq_1.vtt
#EXTINF:6.000,
seq_2.vtt
#EXTINF:6.000,
seq_3.vtt
#EXT-X-ENDLIST
强烈建议让字幕分段与视频分片对齐,例如视频分片为 6 秒时,字幕分段也应为 6 秒。虽然 HLS 规范并未强制要求,但不对齐可能导致部分播放器出现卡顿和解析错误,例如 Safari 的原生播放器或早期版本的 hls.js。
WebVTT 分段规则
WebVTT 分段并不是对文本文件随意切割。每个分段本身都必须是有效的 WebVTT 文件。
WEBVTT
X-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000
00:00:01.500 --> 00:00:03.200
Hello, and welcome to our stream.
00:00:04.000 --> 00:00:05.500
This is an example of WebVTT.
关键的 X-TIMESTAMP-MAP
X-TIMESTAMP-MAP 标头对于同步 VTT 文件与视频流至关重要。它把 WebVTT 本地时间映射到 MPEG-TS 呈现时间戳(PTS)。
如果字幕不同步、随时间逐渐偏移,或根本不显示,应首先检查X-TIMESTAMP-MAP。确保MPEGTS值准确对应视频分片第一帧的 PTS。
排查字幕分发问题
构建 HLS 字幕分发时难免会遇到边界情况。以下是最常见的问题及解决方法。
- 播放器菜单中没有字幕:验证
GROUP-ID(在#EXT-X-MEDIA标签中)是否与SUBTITLES(在#EXT-X-STREAM-INF标签中)一致。这里的拼写错误会断开字幕与视频的关联。 - 字幕出现但不同步:检查
X-TIMESTAMP-MAP。如果使用分片 MP4(fMP4)而不是 TS 分片,同步机制可能转而依赖 ISO 基础媒体文件格式中的 baseMediaDecodeTime。 - 加载字幕时出现 CORS 错误:JavaScript 播放器通过 XHR/Fetch 加载 WebVTT 文件,因此会受到 CORS 限制。确保 CDN 或源站服务器为 `.vtt` 文件返回
Access-Control-Allow-Origin: *标头。更多信息请参阅我们的完整 CORS 指南。 - 字幕提示重叠:如果一条字幕提示从一个分段开始、到下一个分段才结束,分段工具必须正确复制或切分该提示,以防出现渲染错误。请确保使用 Shaka Packager、FFmpeg 或 Bento4 等专业打包工具。
使用 FFmpeg 生成字幕
在自动化工作流中,FFmpeg 是从单个完整文件生成 WebVTT 分段的行业标准工具。
ffmpeg -i input.mp4 -i input.vtt \
-c:v copy -c:a copy -c:s webvtt \
-hls_time 6 \
-hls_playlist_type vod \
-hls_segment_filename "output_%03d.vtt" \
master.m3u8
这条命令会把输入的视频和字幕正确切分为 6 秒的分段,自动生成播放列表,并插入必要的时间戳映射。