En esta página se explica cómo añadir subtítulos generados automáticamente a tu contenido de salida con la API Transcoder. Esta función te permite generar subtítulos a partir de pistas de audio, aunque no se sepa el idioma, y traducir subtítulos a varios idiomas.
Para configurar esta función, debe proporcionar metadatos adicionales sobre los recursos de entrada mediante el campo attributes de cada elemento de la matriz inputs en la configuración del trabajo. Este campo ayuda a la API Transcoder a entender los idiomas presentes en tus pistas de audio y cómo procesarlos.
Antes de empezar
En esta página se presupone que has completado los pasos de la sección Antes de empezar.
Limitaciones
Esta función tiene las siguientes limitaciones:
Ubicaciones admitidas
Esta función está disponible en us-central1 y europe-west4.
Formato de salida
Los subtítulos generados automáticamente deben estar en formato WebVTT (webvtt).
Editar la unión de listas
Esta función no permite usar un editList para unir varios clips de vídeo.
Ejemplos de configuración
En los siguientes ejemplos se muestra cómo configurar los subtítulos automáticos en varios casos prácticos.
Asignación proporcionada por el usuario
Este método ofrece un control directo, ya que especifica exactamente qué pista de entrada se debe usar para generar los subtítulos.
Asigna explícitamente las pistas de entrada a las secuencias de subtítulos de salida
En este ejemplo se muestra cómo usar el campo mapping de cada textStream para controlar con precisión qué pista de audio de entrada se usa para generar los subtítulos en inglés y francés.
{
"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/"
}
}
}
El flujo vtt-stream-english se genera a partir de la pista 1 de input0 debido a la asignación explícita. El flujo vtt-stream-french se genera a partir de la pista 2 de input0.
Asignación predeterminada por la API Transcoder
Estos ejemplos se basan en la API para inferir qué pista de audio se debe usar en función del attributes proporcionado en el inputs. Se da por hecho que el resto de la configuración (muxStreams, manifests y output) es similar al ejemplo completo.
Una sola pista de audio en un idioma conocido
Si el vídeo de entrada tiene una pista de audio (por ejemplo, la pista 1) y sabes que está en inglés (en-US), puedes generar subtítulos en inglés. También puedes solicitar subtítulos en otros idiomas, como el francés (fr-FR), y la API traducirá la transcripción en inglés.
{
"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"
}
}
]
}
El flujo de subtítulos en inglés (vtt-stream-english) se genera directamente a partir de la pista de audio 1 definida, ya que los códigos de idioma coinciden. La pista de subtítulos en francés (vtt-stream-french) se genera transcribiendo primero el audio en inglés de la pista 1 y, a continuación, traduciendo el texto resultante al francés.
Varias pistas de audio con idiomas conocidos
Si tu archivo de entrada contiene varias pistas de audio en distintos idiomas (por ejemplo, francés en la pista 1 e inglés en la pista 2), puede especificar los idiomas de cada pista.
{
"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"
}
}
]
}
En esta configuración, los subtítulos vtt-stream-english se generan a partir de la pista de audio 2 y los subtítulos vtt-stream-french se generan a partir de la pista de audio 1, en función de los códigos de idioma proporcionados en el attributes.
El idioma de salida no coincide con ninguna pista de audio de entrada
Si el idioma de los subtítulos solicitado no coincide con ninguno de los idiomas de las pistas definidos, la API usará la primera pista de audio disponible para la transcripción y la traducción.
{
"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"
}
}
]
}
Como no se ha definido ninguna pista de audio en hindi, los subtítulos vtt-stream-hindi se generan transcribiendo la primera pista de audio (la pista 1, en francés) y, a continuación, traduciendo la transcripción al hindi.
Una sola pista de audio con varios idiomas
Si una sola pista de audio contiene varios idiomas, indícalos todos en la matriz 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"
}
}
]
}
Las tres secuencias VTT (inglés, francés e hindi) se generan a partir de la pista de audio 1. La API transcribirá el audio en varios idiomas y proporcionará cada flujo de salida en el idioma especificado en el campo languageCode.
La API transcribe el audio y puede detectar varios idiomas en la pista 1. Por cada salida textStream, genera subtítulos solo en el idioma especificado en el campo languageCode de ese flujo.
Detección de idioma en una pista de audio específica
Usa detectLanguages": true cuando no se sepa el idioma de una pista específica.
{
"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"
}
}
]
}
La API primero detecta los idiomas presentes en la pista de audio 1. A continuación, genera los subtítulos en inglés, incluida la traducción si el idioma detectado no es el inglés.
Detección de idioma en la pista de audio predeterminada
Si se desconocen tanto el idioma como el número de pista, la API usará de forma predeterminada la primera pista de audio disponible.
{
"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"
}
}
]
}
La API analiza la primera pista de audio para detectar los idiomas y, a continuación, genera los subtítulos en inglés, traduciéndolos si es necesario.
Especificar el idioma de la pista de audio predeterminada
Si conoces el idioma, pero no el número de pista específico, la API asume que la primera pista de audio disponible coincide con el idioma proporcionado.
{
"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"
}
}
]
}
Los subtítulos en inglés (vtt-stream-english) se generan a partir de la primera pista de audio de la entrada, partiendo de la base de que esta pista está en inglés.
Preguntas frecuentes
¿Qué ocurre si especifico tanto languages como detectLanguages en el mismo trackDefinition?
Solo puedes especificar uno de los campos languages o detectLanguages en un mismo trackDefinition. Si se proporcionan ambos en la misma definición, la configuración no será válida y se producirá un error.
¿Cómo elige la API la pista de audio que debe usar si hay varias trackDefinitions que coinciden con el idioma de un textStream?
Si tienes varios trackDefinitions en la matriz inputs.attributes.trackDefinitions que podrían coincidir con el languageCode de un textStream solicitado, la API usará la pista de audio del trackDefinition primero que coincida en el orden de la matriz. Esto solo se aplica si no usas el campo mapping explícito en textStream.