本页介绍了如何使用 Transcoder API 将自动生成的字幕添加到输出中。借助此功能，您可以根据音轨生成字幕，即使不知道音轨的语言，也可以将字幕翻译成各种语言。
您可以通过在作业配置的 inputs 数组中的每个项内使用 attributes 字段来提供有关输入素材资源的额外元数据，从而配置此功能。此字段有助于 Transcoder API 了解音轨中包含的语言以及如何处理这些语言。
准备工作
本页面假设您已完成准备工作中的步骤。
限制
此功能具有以下限制：
支持的位置
us-central1 和 europe-west4 支持此功能。
输出格式
自动生成的字幕的输出格式必须为 WebVTT (webvtt)。
修改列表拼接
此功能不支持使用 editList 将多个视频片段拼接在一起。
配置示例
以下示例展示了如何针对各种用例配置自动字幕。
用户提供的映射
此方法通过精确指定用于生成字幕的输入轨道来提供直接控制。
将输入轨道显式映射到输出字幕流
此示例展示了如何使用每个 textStream 中的 mapping 字段来精确控制使用哪个输入音轨生成英语和法语字幕。
{
"config": {
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"inputTrack": 1,
"languages": [
"en-US"
]
},
{
"inputTrack": 2,
"languages": [
"fr-FR"
]
}
]
}
}
],
"editList": [
{
"key": "atom0",
"inputs": [
"input0"
]
}
],
"elementaryStreams": [
{
"key": "video-stream0",
"videoStream": {
"h264": {
"frameRate": 30,
"widthPixels": 1280,
"heightPixels": 720,
"bitrateBps": 3200000,
"frameRateConversionStrategy": "DOWNSAMPLE"
}
}
},
{
"key": "audio-stream0",
"audioStream": {
"codec": "aac",
"bitrateBps": 64000,
"sampleRateHertz": 48000,
"channelCount": 2,
"channelLayout": [
"fl",
"fr"
]
}
},
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English",
"mapping": [
{
"atomKey": "atom0",
"inputKey": "input0",
"inputTrack": 1
}
]
}
},
{
"key": "vtt-stream-french",
"textStream": {
"codec": "webvtt",
"languageCode": "fr-FR",
"displayName": "French",
"mapping": [
{
"atomKey": "atom0",
"inputKey": "input0",
"inputTrack": 2
}
]
}
}
],
"muxStreams": [
{
"container": "fmp4",
"elementaryStreams": [
"video-stream0"
],
"fileName": "video-only.m4s",
"key": "hd-video-only",
"segmentSettings": {
"segmentDuration": "6s"
}
},
{
"container": "fmp4",
"elementaryStreams": [
"audio-stream0"
],
"fileName": "audio-only.m4s",
"key": "audio-only",
"segmentSettings": {
"segmentDuration": "6s"
}
},
{
"key": "text-vtt-english",
"container": "vtt",
"elementaryStreams": [
"vtt-stream-english"
],
"segmentSettings": {
"individualSegments": true,
"segmentDuration": "6s"
}
},
{
"key": "text-vtt-french",
"container": "vtt",
"elementaryStreams": [
"vtt-stream-french"
],
"segmentSettings": {
"individualSegments": true,
"segmentDuration": "6s"
}
}
],
"manifests": [
{
"fileName": "manifest.m3u8",
"muxStreams": [
"hd-video-only",
"audio-only",
"text-vtt-english",
"text-vtt-french"
],
"type": "HLS"
}
],
"output": {
"uri": "gs://your-bucket/output/"
}
}
}
由于存在显式映射，因此 vtt-stream-english 流是从 input0 的轨道 1 生成的。vtt-stream-french 流是从 input0 的轨道 2 生成的。
Transcoder API 的默认映射
这些示例依赖于 API，以根据 inputs 中提供的 attributes 推断要使用的音轨。配置的其他部分（muxStreams、manifests、output）应与完整示例类似。
具有已知语言的单音轨
如果输入视频只有一条音轨（例如轨道 1），并且您知道该音轨是英语 (en-US)，则可以生成英文字幕。您还可以请求其他语言（例如法语 [fr-FR]）的字幕，API 会翻译英语转写内容。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"inputTrack": 1,
"languages": [
"en-US"
]
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English"
}
},
{
"key": "vtt-stream-french",
"textStream": {
"codec": "webvtt",
"languageCode": "fr-FR",
"displayName": "French"
}
}
]
}
英语字幕流 (vtt-stream-english) 直接从定义的音轨 1 生成，因为语言代码匹配。法语字幕流 (vtt-stream-french) 的生成方式是：先转写轨道 1 中的英语音频，然后将生成的文本翻译为法语。
具有已知语言的多个音轨
当输入文件包含多种不同语言的音轨时（例如，轨道 1 为法语，轨道 2 为英语），您可以为每个轨道指定语言。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"inputTrack": 1,
"languages": ["fr-FR"]
},
{
"inputTrack": 2,
"languages": ["en-US"]
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English"
}
},
{
"key": "vtt-stream-french",
"textStream": {
"codec": "webvtt",
"languageCode": "fr-FR",
"displayName": "French"
}
}
]
}
在此配置中，系统会根据 attributes 中提供的语言代码，从音轨 2 生成 vtt-stream-english 字幕，从音轨 1 生成 vtt-stream-french 字幕。
输出语言与任何输入音轨都不匹配
如果请求的字幕语言与任何已定义的轨道语言都不匹配，API 会使用第一个可用的音轨进行转写和翻译。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"inputTrack": 1,
"languages": ["fr-FR"]
},
{
"inputTrack": 2,
"languages": ["en-US"]
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-hindi",
"textStream": {
"codec": "webvtt",
"languageCode": "hi-IN",
"displayName": "Hindi"
}
}
]
}
由于未定义印地语音轨，因此 vtt-stream-hindi 字幕是通过转写第一个音轨（轨道 1，法语），然后将转写内容翻译成印地语生成的。
包含多种语言的单个音轨
如果单个音轨包含多种语言，请在 languages 数组中列出所有这些语言。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"inputTrack": 1,
"languages": ["en-US", "fr-FR"]
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English"
}
},
{
"key": "vtt-stream-french",
"textStream": {
"codec": "webvtt",
"languageCode": "fr-FR",
"displayName": "French"
}
},
{
"key": "vtt-stream-hindi",
"textStream": {
"codec": "webvtt",
"languageCode": "hi-IN",
"displayName": "Hindi"
}
}
]
}
所有三个 VTT 字幕流（英语、法语和印地语）均从音轨 1 生成。该 API 将转写混合语言音频，并以 languageCode 字段指定的单一语言提供每个输出流。
该 API 会转写音频，并可能会检测到轨道 1 中的多种语言。对于每个输出 textStream，它仅生成相应视频流的 languageCode 字段中指定的语言的字幕。
检测特定音轨的语言
如果特定轨道的语言未知，请使用 detectLanguages": true。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"inputTrack": 1,
"detectLanguages": true
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English"
}
}
]
}
API 首先检测音轨 1 中存在的语言。然后，系统会生成英文字幕，如果检测到的语言不是英语，则会进行翻译。
检测默认音轨的语言
如果语言和轨道号均未知，API 会默认使用第一个可用的音轨。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"detectLanguages": true
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English"
}
}
]
}
API 会分析第一个音轨以检测语言，然后生成英文字幕，并在必要时进行翻译。
指定默认音轨的语言
如果您知道语言，但不知道具体轨道号，API 会假定第一个可用的音轨与所提供的语言相匹配。
{
"inputs": [
{
"key": "input0",
"uri": "gs://input-bucket/input.mp4",
"attributes": {
"trackDefinitions": [
{
"languages": ["en-US"]
}
]
}
}
],
"elementaryStreams": [
{ "key": "video-stream0", "videoStream": { ... } },
{ "key": "audio-stream0", "audioStream": { ... } },
{
"key": "vtt-stream-english",
"textStream": {
"codec": "webvtt",
"languageCode": "en-US",
"displayName": "English"
}
}
]
}
英语字幕 (vtt-stream-english) 是根据输入的第一个音轨生成的，前提是该音轨为英语。
常见问题解答
如果我在同一 trackDefinition 中同时指定了 languages 和 detectLanguages，会发生什么情况？
您只能在单个 trackDefinition 中指定 languages 字段或 detectLanguages 字段中的一个。在同一定义中同时提供这两者是一种无效的配置，会导致错误。
如果多个 trackDefinitions 与 textStream 的语言相匹配，API 如何选择要使用的音轨？
如果 inputs.attributes.trackDefinitions 数组中有多个 trackDefinitions 可能与所请求 textStream 的 languageCode 相匹配，API 将使用数组顺序中第一个匹配的 trackDefinition 中的音轨。仅当您未在 textStream 中使用显式 mapping 字段时，此设置才适用。