Ajouter des sous-titres aux vidéos

🤖/video/subtitle ajoute des sous-titres et des sous-titres codés aux vidéos.

Exemple d’utilisation

{
  "steps": {
    "captioned": {
      "ffmpeg_stack": "v7",
      "preset": "empty",
      "robot": "/video/subtitle",
      "style": "social",
      "subtitles_type": "burned",
      "use": {
        "steps": [
          {
            "as": "video",
            "name": ":original"
          },
          {
            "as": "subtitles",
            "name": "transcript"
          }
        ]
      }
    },
    "transcript": {
      "format": "json",
      "provider": "aws",
      "robot": "/speech/transcribe",
      "source_language": "en-US",
      "use": ":original"
    }
  }
}

Paramètres

• interpolate

  boolean | Record<string, boolean>

  Détermine si les Assembly Variables sont interpolées pour chaque champ d’instruction.

  Par défaut, la plupart des champs d’instruction des Robots interpolent les Assembly Variables. Définissez ce paramètre sur false pour traiter tous les champs d’instruction comme du texte littéral, ou définissez le chemin d’un champ individuel sur false pour traiter uniquement ce champ comme du texte littéral. Pour les champs propres à un Robot qui sont littéraux par défaut, définissez ce paramètre sur true ou définissez le chemin de ce champ sur true pour réactiver l’interpolation.

  Utilisez des noms de champs tels que path, ou des chemins avec points tels que ffmpeg.vf pour les objets imbriqués.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Permet de spécifier un ensemble de métadonnées dont le calcul est plus coûteux en puissance CPU et qui sont donc désactivées par défaut afin que le traitement de vos Assemblies reste rapide.

  Pour les images, vous pouvez ajouter "has_transparency": true dans cet objet pour déterminer si l’image contient des parties transparentes, et "dominant_colors": true pour extraire de l’image un tableau de codes couleur hexadécimaux.

  Pour les images, vous pouvez également ajouter "blurhash": true pour extraire une chaîne BlurHash⁠ — une représentation compacte d’un espace réservé pour l’image, utile pour afficher un aperçu flou pendant le chargement de l’image complète.

  Pour les images, "thumbhash": true extrait plutôt un ThumbHash⁠ encodé en base64 dans meta.thumbhash, accompagné de meta.has_alpha (qui indique si un canal alpha existe, même lorsque l’image est entièrement opaque). Il décrit les pixels orientés selon les données EXIF et utilise la première image des images animées. L’extraction est effectuée au mieux : les images de plus de 40 mégapixels, les formats non pris en charge ou un décodage échoué ou limité ne produisent aucun espace réservé. Une extraction réussie ajoute des frais de métadonnées équivalents à 20 % des octets de ce fichier. Aucun supplément ThumbHash ne s’applique lorsque l’option est désactivée ou lorsqu’aucun hash n’est produit.

  Définissez cette option sur le Step qui produit l’image, par exemple /upload/handle pour les originaux téléversés ou /image/resize pour les sorties traitées. La définir uniquement sur /transloadit/store ne déclenche pas l’extraction : le stockage conserve les métadonnées du Step producteur. Transloadit Storage conserve un hash généré avec sa version immuable et le renvoie dans les résultats stockés et lors des lectures natives de ressources. Les téléversements directs vers S3 ne génèrent pas d’espaces réservés. Un espace réservé contient des informations sur l’image : protégez-le donc avec les mêmes contrôles d’accès que l’image complète.

  Pour les vidéos, vous pouvez ajouter le paramètre "colorspace": true pour extraire l’espace colorimétrique de la vidéo de sortie.

  Pour les vidéos, vous pouvez également ajouter "interlaced": true pour détecter si la vidéo est entrelacée. Cette option combine l’indicateur ffprobe peu coûteux field_order avec une passe d’échantillonnage idet limitée sur les premières images de la source, et expose interlaced, field_order ainsi qu’un objet de diagnostic interlace_detection sous file.meta. Cette opération est coûteuse en calcul et facturée en conséquence.

  Pour l’audio, vous pouvez ajouter "mean_volume": true pour obtenir une valeur unique représentant le volume moyen du fichier audio.

  Vous pouvez également définir cette option sur false pour ignorer l’extraction des métadonnées et accélérer le transcodage.

• user_meta

  Record<string, any>(par défaut : {})

  Ajoute des métadonnées JSON personnalisées à chaque fichier émis sans modifier son contenu. Les objets et tableaux imbriqués sont pris en charge.

  L’héritage dépend du Robot. Les valeurs sont fusionnées avec la valeur user_meta existante du fichier de sortie ; le Step actuel remplace les clés de premier niveau correspondantes. Attribuez explicitement les clés requises lorsqu’un Robot crée de nouvelles sorties.

  Dans les Steps de traitement, ${file.*} désigne la première entrée et ${result.*} le fichier émis. Les valeurs sont évaluées pour chaque sortie après l’exécution du Robot, avant l’extraction ultérieure des métadonnées et le stockage temporaire. Sur :original, les valeurs sont évaluées pour chaque téléversement avant l’extraction des métadonnées.

  Les Steps en aval lisent ${file.user_meta.key}. Consultez Métadonnées personnalisées pour un exemple complet et les règles d’héritage.

• result

  boolean(par défaut : false)

  Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON

• queue

  batch

  Définir la file d’attente sur « batch » abaisse manuellement la priorité des Jobs de ce Step afin d’éviter de consommer des emplacements prioritaires de Jobs pour des Jobs qui n’ont pas besoin d’un temps d’attente nul dans la file

• force_accept

  boolean(par défaut : false)

  Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.

  Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode, par exemple, ignorera volontiers les images en entrée.

  Avec le paramètre force_accept défini sur true, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.

• ignore_errors

  boolean | Array<meta | execute>(par défaut : [])

  Ignore les erreurs pendant certaines phases du traitement.

  Si vous définissez cette valeur sur ["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.

  Si vous définissez cette valeur sur ["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.

  Définir cette valeur sur true équivaut à ["meta", "execute"] : les erreurs seront alors ignorées dans les deux phases.

• use

  string | Array<string> | Array<object> | object

  Indique quel(s) Step(s) utiliser comme entrée.

  • Vous pouvez choisir n’importe quel nom pour les Steps, sauf ":original" (réservé aux téléversements des utilisateurs gérés par Transloadit)
  • Vous pouvez fournir plusieurs Steps en entrée à l’aide de tableaux :

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Vous pouvez également étiqueter les Steps d’entrée avec as pour transmettre une intention sémantique aux Robots :

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Astuce

  C’est probablement tout ce que vous devez savoir sur use, mais vous pouvez consulter les cas d’utilisation avancés.

• ffmpeg

  object

  Un objet de paramètres à transmettre à FFmpeg. Si un préréglage est utilisé, les options spécifiées sont fusionnées par-dessus celles du préréglage. Pour connaître les options disponibles, consultez la documentation de FFmpeg⁠. Les options spécifiées ici ont priorité sur celles du préréglage.

• ffmpeg_stack

  v6 | v7 | v8 | string(par défaut : "v6.0.0")

  Sélectionne la version de la pile FFmpeg à utiliser pour l’encodage. Nous recommandons actuellement d’utiliser « v7 ». Les versions exactes « v6.0.0 », « v7.0.0 » et « v8.0.0 » sont des valeurs héritées qui restent acceptées pour assurer la rétrocompatibilité. Les valeurs « v5.x », dépréciées, sont également acceptées.

• width

  string | number | null

  Largeur de la nouvelle vidéo, en pixels.

  Si la valeur n’est pas spécifiée et que le paramètre preset est disponible, la largeur fournie par preset sera appliquée.

• height

  string | number | null

  Hauteur de la nouvelle vidéo, en pixels.

  Si la valeur n’est pas spécifiée et que le paramètre preset est disponible, la hauteur fournie par preset sera appliquée.

• preset

  android | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video | 195 de plus ↓

  Convertit une vidéo selon des paramètres préconfigurés.

  Vous pouvez utiliser ici la valeur 'empty' si vous spécifiez vos propres paramètres FFmpeg à l’aide du Robot, ou si vous ne souhaitez pas que Transloadit définisse de paramètres d’encodage.

• subtitles_type

  burned | external | burn(par défaut : "external")

  Détermine si les sous-titres sont ajoutés à la vidéo sous forme de flux distinct (valeur "external"), que vous pouvez ensuite activer ou désactiver dans votre lecteur vidéo, ou s’ils doivent être incrustés directement dans la vidéo (valeur "burned" ou "burn") afin de faire partie du flux vidéo.

• style

  social

  Applique une apparence prédéfinie aux sous-titres incrustés : texte en police Poppins très grasse, contour épais et ombre noire douce. Les sous-titres JSON s’affichent en majuscules dans le tiers inférieur. Par défaut, la taille de la police des sous-titres JSON est calculée à partir du côté le plus court de la vidéo et ajustée pour que chaque sous-titre tienne dans la largeur de sécurité, de préférence sur une ligne et au maximum sur deux. Les mots ne sont jamais coupés. Chaque sous-titre passe de 85 % à sa taille finale en 120 millisecondes, puis ses mots restent en place tandis que la mise en évidence change de couleur. Le fichier de transcription est conservé. Les paramètres de style existants prennent le pas sur le préréglage ; une valeur explicite du paramètre font_size désactive l’ajustement automatique. Les fichiers ASS conservent leurs propres styles. Avec les données JSON horodatées provenant de /speech/transcribe, le mot actif est mis en évidence jusqu’au début du mot ou du sous-titre suivant ; les autres mots utilisent font_color. Les virgules et les points en fin de mot sont omis dans les sous-titres JSON de style social ; les points d’interrogation et d’exclamation sont conservés. La mise en évidence et le regroupement des mots nécessitent une entrée JSON.

• highlight_color

  string | string(par défaut : "FFD60A")

  La couleur d’accentuation du mot actif dans les sous-titres JSON. S’applique uniquement aux sous-titres JSON incrustés. Avec "style": "social", le mot précédent reste surligné pendant les courtes pauses jusqu’au début du mot ou du sous-titre suivant. Sans le style social, font_color est utilisé pour l’ensemble du sous-titre pendant les pauses.

  Utilisez le format "rgb", "rrggbb" ou "aarrggbb", éventuellement précédé de #. Les couleurs à trois chiffres sont étendues à six chiffres. Les couleurs sans alpha sont entièrement opaques. Pour les couleurs à huit chiffres, les deux premiers chiffres définissent la transparence ("00" correspond à une opacité totale, "ff" à une transparence totale).

• max_words_per_caption

  string | number(par défaut : 3)

  Le nombre maximal visé de mots JSON horodatés affichés dans un sous-titre. Les sous-titres sont coupés plus tôt aux signes de ponctuation de fin de phrase ou aux pauses de plus de 0,4 seconde. Avec "style": "social", un mot grammatical anglais en fin de sous-titre, comme « by », « to » ou « the », passe au sous-titre suivant lorsque c’est possible. Les expressions courtes comme « line of code » peuvent rester groupées, et un mot isolé en fin de phrase peut rejoindre le sous-titre précédent. Ces ajustements autorisent au maximum un mot supplémentaire par sous-titre, sans franchir les fins de phrase ni les pauses longues. Les sous-titres d’un seul mot sont conservés lorsque la limite est de 1. Un sous-titre reste visible jusqu’au début du suivant lorsque la pause ne dépasse pas 0,4 seconde, et disparaît à la fin de son dernier mot lors des pauses plus longues. Ne modifie pas les segments SRT, VTT ou ASS.

• border_style

  box | outline | shadow(par défaut : "outline")

  Définit le style des sous-titres. Utilisez le paramètre border_color pour définir la couleur de la bordure.

• border_color

  string | string(par défaut : "000000")

  La couleur de la bordure des sous-titres. La valeur par défaut est le noir opaque. S’applique uniquement aux sous-titres incrustés.

  Utilisez le format "rgb", "rrggbb" ou "aarrggbb", éventuellement précédé de #. Les couleurs à trois chiffres sont étendues à six chiffres. Les couleurs sans alpha sont entièrement opaques. Pour les couleurs à huit chiffres, les deux premiers chiffres définissent la transparence ("00" correspond à une opacité totale, "ff" à une transparence totale).

• font

  string

  La famille de polices à utiliser. Inclut également la graisse et le style de la police. La police par défaut est Arial. Avec "style": "social", la police par défaut est Poppins, avec sa graisse ExtraBold pour les sous-titres JSON. Une police définie explicitement prend le pas sur le style.

  Vous trouverez ici la liste de toutes les polices prises en charge.

• font_color

  string | string(par défaut : "FFFFFF")

  La couleur du texte des sous-titres. S’applique uniquement aux sous-titres incrustés.

  Utilisez le format "rgb", "rrggbb" ou "aarrggbb", éventuellement précédé de #. Les couleurs à trois chiffres sont étendues à six chiffres. Les couleurs sans alpha sont entièrement opaques. Pour les couleurs à huit chiffres, les deux premiers chiffres définissent la transparence ("00" correspond à une opacité totale, "ff" à une transparence totale).

• font_size

  string | number

  Définit la taille du texte dans l’espace de coordonnées des sous-titres de 288 pixels, mis à l’échelle selon la hauteur de la vidéo. La valeur par défaut est 16. Avec "style": "social", la valeur par défaut est 54. Pour les sous-titres JSON de style social, l’omission de cette valeur adapte cette valeur par défaut au côté le plus court de la vidéo, l’augmente de 18 % pour les vidéos au format portrait et réduit les sous-titres au besoin pour qu’ils tiennent sur deux lignes au maximum. Avant cet ajustement, les majuscules de Poppins mesurent environ 7,5 % du côté le plus court, ou environ 9 % pour les vidéos au format portrait. Une valeur explicite conserve le dimensionnement relatif à la hauteur et désactive l’ajustement automatique.

• bold

  boolean

  Indique si le texte des sous-titres doit être en gras. S’applique uniquement aux sous-titres incrustés. La valeur par défaut est false. Avec "style": "social", la valeur par défaut est true ; une valeur explicite de false prend le pas sur le style.

• italic

  boolean(par défaut : false)

  Indique si le texte des sous-titres doit être en italique. S’applique uniquement aux sous-titres incrustés.

• outline_width

  string | number | null

  Définit la largeur du contour du texte dans l’espace de coordonnées des sous-titres de 288 pixels, mis à l’échelle selon la hauteur de la vidéo. Les chaînes numériques telles que "4" sont également acceptées. S’applique uniquement aux sous-titres incrustés avec les styles de bordure "outline" ou "box". Si ce paramètre est omis ou vaut null, la largeur par défaut est utilisée (2 avec "style": "social", proportionnelle à la taille finale ajustée de la police pour les sous-titres JSON de style social).

• position

  bottom | bottom-left | bottom-right | center | left | right | top | 2 de plus ↓(par défaut : "bottom")

  Définit la position des sous-titres. Avec "style": "social", la position basse par défaut place les sous-titres JSON dans le tiers inférieur, avec un espace supplémentaire en bas pour les vidéos au format portrait. Une valeur explicite prend le pas sur le style.

• language

  string | null

  Définit la langue du flux de sous-titres à l’aide d’un code de langue à trois lettres (par exemple "eng", "deu", "spa"). Utilisé uniquement si les sous-titres sont externes. Lorsque vous ajoutez plusieurs flux de sous-titres, définissez une langue différente pour chaque flux afin que les lecteurs vidéo puissent proposer un choix de langue.

• name

  string | null

  Définit un nom lisible pour la piste de sous-titres (par exemple "English", "Deutsch", "Español"). Utilisé uniquement si les sous-titres sont externes. Ce nom est affiché à côté de la langue dans les menus de sous-titres des lecteurs vidéo.

• keep_subtitles

  boolean(par défaut : false)

  Indique si les sous-titres existants dans le fichier d’entrée doivent être conservés ou remplacés par les nouveaux sous-titres. Utilisé uniquement si les sous-titres sont externes. Définissez ce paramètre sur true lorsque vous enchaînez plusieurs Steps /video/subtitle pour ajouter plusieurs flux de sous-titres (par exemple dans différentes langues) à la même vidéo.

Démonstrations

Articles de blog associés