跳到主要内容
HLS 进阶

如何为 M3U8 流添加多语言 WebVTT 字幕

这是一份关于在 HTTP 实时流(HLS)中集成多语言 WebVTT 字幕的全面进阶指南。你将了解准确的 #EXT-X-MEDIA 配置、分段技术和调试策略,从而在现代播放器与平台上可靠地分发字幕。

提供高质量且同步准确的字幕,是专业视频流媒体的重要环节。在 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 秒的分段,自动生成播放列表,并插入必要的时间戳映射。