Transcoder, redimensionner ou filigraner des vidéos

🤖/video/encode encode des vidéos et des GIF animés, les redimensionne et y applique des filigranes.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "text_overlay_default": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "empty",
      "ffmpeg_stack": "v7",
      "ffmpeg": {
        "codec:a": "copy",
        "vf": "drawtext=text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
      },
      "result": true
    },
    "text_overlay_custom": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "empty",
      "ffmpeg_stack": "v7",
      "ffmpeg": {
        "codec:a": "copy",
        "vf": "drawtext=font='Times New Roman':text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
      },
      "result": true
    }
  }
}

Exemple d’utilisation

{
  "steps": {
    "hevc_encoded": {
      "preset": "hevc",
      "robot": "/video/encode",
      "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 EN (English) 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 EN (English) 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 EN (English).

  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.

• resize_strategy

  crop | fit | fillcrop | min_fit | pad | stretch(par défaut : "pad")

  Consultez les stratégies de redimensionnement disponibles.

• zoom

  boolean(par défaut : true)

  Si ce paramètre est défini sur false, les vidéos plus petites ne seront pas étirées aux largeur et hauteur souhaitées. Pour en savoir plus sur l’effet du zoom avec votre stratégie de redimensionnement préférée, consultez la liste des stratégies de redimensionnement disponibles.

• crop

  object | string

  Indiquez un objet contenant les coordonnées des coins supérieur gauche et inférieur droit du rectangle à extraire par recadrage de la ou des vidéos d’origine. Les valeurs peuvent être des entiers pour des valeurs absolues en pixels ou des chaînes pour des valeurs en pourcentage.

  Par exemple :

  {
    "x1": 80,
    "y1": 100,
    "x2": "60%",
    "y2": "80%"
  }
  

  Cette opération recadrera la zone allant de (80, 100) à (600, 800) dans une vidéo de 1000×1000 pixels, soit un rectangle de 520 px de largeur et de 700 px de hauteur. Si crop est défini, les paramètres width et height sont ignorés, et resize_strategy est automatiquement défini sur crop.

  Vous pouvez également utiliser de la même manière une chaîne JSON représentant un tel objet avec des coordonnées :

  "{\"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer>}"
  

• background

  string(par défaut : "#00000000")

  La couleur d’arrière-plan de la vidéo obtenue, au format "rrggbbaa" (rouge, vert, bleu, alpha), lorsque ce paramètre est utilisé avec la stratégie de redimensionnement "pad". La couleur par défaut est le noir.

• rotate

  0 | 90 | 180 | 270 | 360 | false

  Force la rotation de la vidéo selon le nombre entier de degrés indiqué. Actuellement, seuls les multiples de 90 sont pris en charge. Nous corrigeons automatiquement l’orientation de nombreuses vidéos lorsque la caméra fournit cette information. Cette option n’est utile que pour les vidéos nécessitant une rotation parce que l’orientation n’a pas été détectée par la caméra. Si vous définissez rotate sur false, aucune rotation n’est effectuée, même si les métadonnées contiennent de telles instructions.

• hint

  boolean(par défaut : false)

  Active l’ajout de pistes d’indication aux fichiers mp4 pour le streaming RTP/RTSP.

• turbo

  boolean(par défaut : false)

  Découpe la vidéo en plusieurs fragments afin que chacun puisse être encodé en parallèle, avant que tous les fragments encodés ne soient réassemblés pour former la vidéo de sortie. Cela mobilise des emplacements prioritaires de Jobs supplémentaires et peut s’avérer contre-productif pour les très petits fichiers vidéo.

• chunk_duration

  string | number

  Permet de spécifier la durée de chaque fragment lorsque turbo est défini sur true. Vous pouvez ainsi bénéficier de cette fonctionnalité tout en utilisant moins d’emplacements prioritaires de Jobs. Par exemple, plus chaque fragment est long, moins de Jobs d’encodage sont nécessaires.

• watermark_url

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

  URL d’une image PNG à superposer à cette image. Vous pouvez également fournir le filigrane via un autre Assembly Step.

• watermark_position

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

  Position à laquelle le filigrane est placé.

  Vous pouvez également spécifier un tableau de valeurs possibles, par exemple [ "center", "left", "bottom-left", "bottom-right" ], auquel cas une valeur sera sélectionnée au hasard.

  Ce réglage place le filigrane dans le coin spécifié. Pour appliquer un décalage précis en pixels au filigrane, vous devrez ajouter des marges à l’image elle-même.

• watermark_x_offset

  string | number(par défaut : 0)

  Le décalage sur l’axe x, en pixels, à appliquer à la position du filigrane définie par watermark_position.

  Les valeurs peuvent être positives ou négatives et produisent des résultats différents selon le paramètre watermark_position. Les valeurs positives rapprochent le filigrane du centre de l’image, tandis que les valeurs négatives l’en éloignent.

• watermark_y_offset

  string | number(par défaut : 0)

  Le décalage sur l’axe y, en pixels, à appliquer à la position du filigrane définie par watermark_position.

  Les valeurs peuvent être positives ou négatives et produisent des résultats différents selon le paramètre watermark_position. Les valeurs positives rapprochent le filigrane du centre de l’image, tandis que les valeurs négatives l’en éloignent.

• watermark_size

  string

  Taille du filigrane, en pourcentage, par exemple "50%". La façon dont le filigrane est redimensionné dépend fortement du paramètre watermark_resize_strategy.

• watermark_resize_strategy

  area | fit | stretch(par défaut : "fit")

  Pour expliquer le fonctionnement des stratégies de redimensionnement, supposons que la taille cible de notre vidéo soit de 800×800 pixels et que celle de notre image de filigrane soit de 400×300 pixels. Supposons également que le paramètre watermark_size soit défini sur "25%".

  Avec la stratégie de redimensionnement "fit", le filigrane est mis à l’échelle de façon à ce que son côté le plus long occupe 25 % du côté correspondant de la vidéo. L’autre côté est mis à l’échelle en respectant le rapport d’aspect de l’image de filigrane. Dans notre exemple, la largeur est le côté le plus long, et 25 % de la dimension correspondante de la vidéo représenteraient 200 px. Le filigrane serait donc redimensionné à 200×150 pixels. Si le paramètre watermark_size était défini sur "50%", le filigrane serait redimensionné à 400×300 pixels (il conserverait donc simplement sa taille d’origine).

  Avec la stratégie de redimensionnement "stretch", l’image de filigrane est étirée (c’est-à-dire redimensionnée sans respecter son rapport d’aspect) de façon à ce que chacun de ses côtés occupe 25 % du côté correspondant de la vidéo. Puisque notre vidéo mesure 800×800 pixels, pour une taille de filigrane de 25 %, le filigrane serait redimensionné à 200×200 pixels. Il paraîtrait étiré en hauteur, car, si le rapport d’aspect était respecté, il serait plutôt redimensionné à 200×150 pixels.

  Avec la stratégie de redimensionnement "area", le filigrane est redimensionné (tout en respectant son rapport d’aspect) pour couvrir "xx%" de la surface de la vidéo. La valeur de watermark_size sert à définir le pourcentage de surface.

• watermark_start_time

  string | number(par défaut : 0)

  Délai en secondes depuis le début de la vidéo avant l’apparition du filigrane. Par défaut, le filigrane s’affiche immédiatement.

• watermark_duration

  string | number(par défaut : -1)

  Durée d’affichage du filigrane, en secondes. Ce paramètre peut être utilisé avec watermark_start_time pour créer de jolis effets. La valeur par défaut est -1.0, ce qui signifie que le filigrane s’affiche pendant toute la durée de la vidéo.

• watermark_opacity

  string | number(par défaut : 1)

  Opacité du filigrane. Les valeurs valides sont comprises entre 0 (invisible) et 1.0 (visibilité totale).

• segment

  boolean(par défaut : false)

  Divise le fichier en plusieurs parties destinées au HTTP Live Streaming⁠ d’Apple.

• segment_duration

  string | number(par défaut : 10)

  Indique la durée de chaque segment HTTP. Ce paramètre est facultatif, et sa valeur par défaut, recommandée par Apple, est 10. Ne modifiez pas cette valeur sans bonne raison.

• segment_prefix

  string(par défaut : "")

  Préfixe utilisé pour nommer les fichiers. Par exemple, le préfixe "segment_" produirait des fichiers nommés "segment_0.ts", "segment_1.ts", etc. Ce paramètre est facultatif et utilise par défaut le nom de base du fichier d’entrée. Consultez également le paramètre associé segment_name.

• segment_name

  string(par défaut : "")

  Nom utilisé pour le segment final. Les variables disponibles sont ${segment_prefix}, ${segment_number} et ${segment_id} (qui est un UUIDv4 sans tirets).

• segment_time_delta

  string | number

  Delta à appliquer à la durée des segments. Ce paramètre est facultatif et permet d’ajuster finement les limites des segments.

Démonstrations

Articles de blog associés