Cette page explique comment ajouter des sous-titres générés automatiquement à votre sortie à l'aide de l'API Transcoder. Cette fonctionnalité vous permet de générer des sous-titres à partir de pistes audio, même si la langue n'est pas connue, et de traduire des sous-titres dans différentes langues.
Pour configurer cette fonctionnalité, vous devez fournir des métadonnées supplémentaires sur vos éléments d'entrée à l'aide du champ attributes dans chaque élément du tableau inputs de la configuration de votre tâche. Ce champ aide l'API Transcoder à comprendre les langues présentes dans vos pistes audio et comment les traiter.
Avant de commencer
Cette page suppose que vous avez suivi les étapes de la section Avant de commencer.
Limites
Cette fonctionnalité présente les limites suivantes :
Pays acceptés
Cette fonctionnalité est disponible sur us-central1 et europe-west4.
Format de sortie
Les sous-titres générés automatiquement doivent être au format WebVTT (webvtt).
Modifier l'assemblage de listes
Cette fonctionnalité n'est pas compatible avec l'utilisation d'un editList pour assembler plusieurs extraits vidéo.
Exemples de configuration
Les exemples suivants montrent comment configurer les sous-titres automatiques pour différents cas d'utilisation.
Mappage fourni par l'utilisateur
Cette méthode permet de contrôler directement la piste d'entrée à utiliser pour générer les sous-titres.
Mapper explicitement les pistes d'entrée aux flux de sous-titres de sortie
Cet exemple montre comment utiliser le champ mapping dans chaque textStream pour contrôler précisément la piste audio d'entrée utilisée pour générer les sous-titres en anglais et en français.
{
"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/"
}
}
}
Le flux vtt-stream-english est généré à partir de la piste 1 de input0 en raison du mappage explicite. Le flux vtt-stream-french est généré à partir de la piste 2 de input0.
Mappage par défaut par l'API Transcoder
Ces exemples s'appuient sur l'API pour déduire la piste audio à utiliser en fonction du attributes fourni dans le inputs. Les autres parties de la configuration (muxStreams, manifests, output) sont supposées être similaires à l'exemple complet.
Piste audio unique dans une langue connue
Si votre vidéo d'entrée comporte une piste audio (par exemple, la piste 1) et que vous savez qu'elle est en anglais (en-US), vous pouvez générer des sous-titres en anglais. Vous pouvez également demander des sous-titres dans d'autres langues, comme le français (fr-FR). L'API traduira alors la transcription en anglais.
{
"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"
}
}
]
}
Le flux de sous-titres en anglais (vtt-stream-english) est généré directement à partir de la piste audio 1 définie, car les codes de langue correspondent. La piste de sous-titres en français (vtt-stream-french) est produite en transcrivant d'abord l'audio en anglais de la piste 1, puis en traduisant le texte obtenu en français.
Plusieurs pistes audio avec des langues connues
Lorsque votre fichier d'entrée contient plusieurs pistes audio dans différentes langues (par exemple, Français sur la piste 1 et anglais sur la piste 2), vous pouvez spécifier les langues pour chaque piste.
{
"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"
}
}
]
}
Dans cette configuration, les sous-titres vtt-stream-english sont générés à partir de la piste audio 2 et les sous-titres vtt-stream-french sont générés à partir de la piste audio 1, en fonction des codes de langue fournis dans le attributes.
La langue de sortie ne correspond à aucune piste audio d'entrée
Si la langue des sous-titres demandée ne correspond à aucune langue de piste définie, l'API utilise la première piste audio disponible pour la transcription et la traduction.
{
"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"
}
}
]
}
Comme aucune piste audio en hindi n'est définie, les sous-titres vtt-stream-hindi sont générés en transcrivant la première piste audio (piste 1, en français), puis en traduisant la transcription en hindi.
Piste audio unique avec plusieurs langues
Si une même piste audio comporte plusieurs langues, listez-les toutes dans le tableau 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"
}
}
]
}
Les trois flux VTT (anglais, français et hindi) sont générés à partir de la piste audio 1. L'API transcrira l'audio multilingue et fournira chaque flux de sortie dans la langue unique spécifiée par le champ languageCode.
L'API transcrit l'audio, en détectant potentiellement plusieurs langues dans la piste 1. Pour chaque textStream de sortie, il génère des sous-titres uniquement dans la langue spécifiée par le champ languageCode de ce flux.
Détection de la langue sur une piste audio spécifique
Utilisez detectLanguages": true lorsque la langue d'une piste spécifique est inconnue.
{
"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"
}
}
]
}
L'API détecte d'abord la ou les langues présentes dans la piste audio 1. Il génère ensuite les sous-titres en anglais, y compris la traduction si la langue détectée n'est pas l'anglais.
Détection de la langue sur la piste audio par défaut
Si la langue et le numéro de piste sont inconnus, l'API utilise par défaut la première piste 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"
}
}
]
}
L'API analyse la première piste audio pour détecter la ou les langues, puis génère les sous-titres en anglais, en les traduisant si nécessaire.
Spécifier la langue de la piste audio par défaut
Si vous connaissez la langue, mais pas le numéro de piste spécifique, l'API suppose que la première piste audio disponible correspond à la langue fournie.
{
"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"
}
}
]
}
Les sous-titres en anglais (vtt-stream-english) sont générés à partir de la première piste audio de l'entrée, en partant du principe que cette piste est en anglais.
Questions fréquentes
Que se passe-t-il si je spécifie à la fois languages et detectLanguages dans le même trackDefinition ?
Vous ne pouvez spécifier qu'un seul champ languages ou detectLanguages dans un même trackDefinition. Si vous fournissez les deux dans la même définition, la configuration sera non valide et une erreur s'affichera.
Comment l'API choisit-elle la piste audio à utiliser si plusieurs trackDefinitions correspondent à la langue d'un textStream ?
Si le tableau inputs.attributes.trackDefinitions contient plusieurs trackDefinitions susceptibles de correspondre au languageCode d'un textStream demandé, l'API utilisera la piste audio du trackDefinition correspondant en premier dans l'ordre du tableau. Cela ne s'applique que lorsque vous n'utilisez pas le champ mapping explicite dans textStream.