Extraire des vignettes de vidéos

Le Robot 🤖/video/thumbs extrait un nombre quelconque d’images de vidéos pour les utiliser comme aperçus.

Exemple d’utilisation

{
  "steps": {
    "thumbnailed": {
      "count": 3,
      "ffmpeg_stack": "v7",
      "robot": "/video/thumbs",
      "smart": true,
      "smart_max_candidates": 12,
      "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.

• count

  string | number(par défaut : 8)

  Le nombre de vignettes à extraire. Comme certaines vidéos ont des durées incorrectes, le nombre réel de vignettes générées peut, dans de rares cas, être inférieur. Le nombre maximal de vignettes que nous autorisons actuellement est de 999.

  Lorsque smart vaut false, les vignettes sont prises à intervalles réguliers. Par exemple, une valeur de 3 produit des vignettes à 25 %, 50 % et 75 % de la durée de la vidéo. Avec smart: true, il s’agit plutôt du nombre de vignettes sélectionnées parmi l’ensemble des images candidates.

  Pour extraire des vignettes à des horodatages précis, utilisez le paramètre offsets.

• offsets

  Array<string | number> | Array<string> | null

  Un tableau de décalages représentant des secondes de la durée du fichier, par exemple [ 2, 45, 120 ]. Des durées en millisecondes peuvent également être utilisées à l’aide de valeurs décimales. Par exemple, un décalage de 1250 millisecondes serait représenté par 1.25. Les décalages peuvent aussi être des valeurs en pourcentage, comme [ "2%", "50%", "75%" ].

  Lorsque smart vaut false, offsets a priorité sur count. Demandez des horodatages compris dans la durée de la vidéo. Si FFmpeg ne produit aucune image à un décalage demandé, le Robot peut réessayer sans positionnement par horodatage et renvoyer à la place une image proche du début. Il n’ignore pas simplement le décalage, et l’extraction peut tout de même échouer si aucune image n’est disponible.

  Lorsque smart vaut true, la sélection intelligente ignore offsets et utilise count pour faire son choix parmi ses propres horodatages candidats. Si aucune image candidate de la sélection intelligente ne peut être extraite, le Robot revient à l’extraction standard, où offsets a priorité. Utilisez smart: false pour extraire systématiquement les horodatages indiqués.

  Utilisez null pour laisser count et smart déterminer la sélection des horodatages.

• format

  jpeg | jpg | png(par défaut : "jpeg")

  Le format de la vignette extraite. Les valeurs prises en charge sont "jpg", "jpeg" et "png". Même si vous indiquez le format "jpeg", les vignettes obtenues auront l’extension de fichier "jpg".

• width

  string | number | null

  La largeur de la vignette, en pixels. Omettez ce paramètre ou utilisez null pour conserver la largeur d’origine de la vidéo.

• height

  string | number | null

  La hauteur de la vignette en pixels, plafonnée de la même manière que width. Omettez ce paramètre ou utilisez null pour conserver la hauteur d’origine.

• resize_strategy

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

  L’une des stratégies de redimensionnement disponibles.

• background

  string(par défaut : "#000000ff")

  La couleur d’arrière-plan des vignettes obtenues, 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 opaque.

• rotate

  0 | 90 | 180 | 270 | 360(par défaut : 0)

  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 celle-ci est fournie par la caméra. Cette option n’est utile que pour les vidéos nécessitant une rotation parce que leur orientation n’a pas été détectée par la caméra.

• input_codec

  string

  Indique le codec d’entrée à utiliser pour décoder la vidéo. Cela est utile pour les vidéos dotées de codecs particuliers qui nécessitent des décodeurs spécifiques.

• smart

  boolean(par défaut : false)

  Lorsqu’il est défini sur true, ce paramètre active la sélection intelligente de vignettes par IA. Au lieu de renvoyer des vignettes à intervalles réguliers, le Robot analyse les images candidates et sélectionne les plus attrayantes visuellement.

  L’IA évalue les images selon les critères suivants :

  • Netteté visuelle (en évitant les images floues ou sombres)
  • Qualité de la composition
  • Présence et expressions des visages
  • Action et mouvement (en évitant les images de transition)
  • Intérêt visuel global

  Les frais de traitement habituels de /video/thumbs s’appliquent toujours. L’analyse des images par IA utilise un modèle de vision dédié à faible coût avec le niveau de raisonnement low, ainsi que des copies d’aperçu limitées à 512 pixels sur le côté le plus long. Les vignettes renvoyées conservent les dimensions et le format demandés. L’analyse est facturée séparément au coût du fournisseur sous-jacent, majoré d’une marge Transloadit de 50 %. Vous n’avez pas besoin de fournir d’informations d’identification IA.

  Le mode intelligent génère ses propres horodatages candidats régulièrement espacés ; utilisez smart: false avec offsets lorsque vous avez besoin d’horodatages précis. Les vignettes intelligentes sélectionnées sont renvoyées dans l’ordre chronologique, et non dans l’ordre des scores. Examinez meta.thumb_offset, meta.smart_score et meta.smart_reasons lorsque vous évaluez la sélection.

  Si l’évaluation par IA échoue, le Robot sélectionne les images candidates extraites dans l’ordre chronologique et enregistre un motif de repli. En l’absence d’images candidates, il tente une extraction standard. Ces deux replis ajoutent un avertissement à l’Assembly. Une Assembly terminée ne garantit pas une image d’affiche représentative ou adaptée à la publication ; vérifiez que les résultats existent et appliquez la politique de vérification de votre application.

• smart_max_candidates

  string | number(par défaut : 20)

  La taille maximale de l’ensemble des images candidates lorsque smart vaut true. Le Robot analyse jusqu’à trois images candidates par vignette demandée, dans la limite de cette valeur, mais il n’analysera jamais moins d’images candidates que la valeur count demandée.

  Un nombre plus élevé peut donner de meilleurs résultats, mais augmente le temps de traitement et le coût de l’IA. Avec les valeurs par défaut count: 8 et smart_max_candidates: 20, le Robot analyse 20 images et renvoie les 8 meilleures dans l’ordre chronologique.

  Relever cette limite au-delà de trois fois count n’élargit pas l’ensemble des images candidates. Par exemple, avec count: 1, le Robot analyse au plus trois images candidates.

  Ce paramètre n’est utilisé que lorsque smart vaut true.

Démonstrations

Articles de blog associés