beta

Générer une miniature d’aperçu

🤖/file/preview génère une miniature pour tout fichier téléversé afin d’en prévisualiser le contenu, à la manière des miniatures affichées par les gestionnaires de fichiers de bureau.

L’objectif de ce Robot est de générer une image d’aperçu pertinente pour n’importe quel fichier, de sorte que la miniature obtenue mette en valeur le contenu du fichier. Le but n’est pas de présenter le média d’origine sans perte dans un format réduit. Il s’agit plutôt de maximiser les chances qu’une personne reconnaisse le média d’un coup d’œil, tout en obtenant un résultat visuellement agréable et cohérent avec les autres aperçus. Le processus de génération dépend du type de fichier. Par exemple, le Robot peut extraire la pochette des fichiers multimédias et des images des vidéos, générer une forme d’onde pour les fichiers audio et prévisualiser le contenu des documents et des images. Le paramètre strategy répertorie les stratégies disponibles et détermine leur ordre de repli.

Avec la configuration de stratégies par défaut, une icône générique sert de solution de repli lorsqu’aucune miniature propre au fichier ne peut être générée. Le style d’icône par défaut with-text inclut l’extension du fichier ; icon_style et icon_text_content contrôlent son apparence.

Les paramètres par défaut produisent des aperçus fixes aux dimensions et au format configurés, pour une intégration dans l’interface de votre application. La stratégie facultative clip produit des aperçus animés à l’aide de clip_format. Les images d’aperçu sont optimisées par défaut afin de réduire leur taille de fichier tout en conservant leur qualité visuelle.

Exemple d’utilisation

Générer une miniature d’aperçu pour n’importe quel fichier téléversé :

{
  "steps": {
    "previewed": {
      "format": "png",
      "height": 400,
      "robot": "/file/preview",
      "use": ":original",
      "width": 300
    }
  }
}

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.
format
avif | gif | jpeg | jpg | png | webp(par défaut : "png")
Le format de sortie de la miniature générée. Si un court clip vidéo est généré avec la stratégie clip, son format est défini par clip_format.
quality
string | number
Qualité de compression des aperçus fixes, de 1 à 100. Lorsque ce paramètre est spécifié, le redimensionnement final de l’image encode directement dans le format demandé avec cette qualité et supprime les métadonnées intégrées. Omettez-le pour conserver le comportement d’encodage par défaut. Les clips animés utilisent leurs propres paramètres d’encodage. Si optimize est activé, l’optimisation s’exécute après cet encodage.
width
number(par défaut : 300)
Largeur de la miniature, en pixels.
height
number(par défaut : 200)
Hauteur de la miniature, en pixels.
resize_strategy
crop | fit | fillcrop | min_fit | pad | stretch(par défaut : "pad")
Pour obtenir les dimensions souhaitées de la miniature d’aperçu, le Robot peut devoir redimensionner l’image générée. Cela se produit par exemple lorsque les dimensions d’une image extraite d’une vidéo ne correspondent pas aux paramètres width et height choisis.

Pour plus de détails, consultez la liste des stratégies de redimensionnement disponibles.
background
string(par défaut : "#ffffffff")
Le code hexadécimal de la couleur utilisée pour remplir l’arrière-plan (utilisé uniquement pour la stratégie de redimensionnement pad). Le format est #rrggbb[aa] (rouge, vert, bleu, alpha). Utilisez #00000000 pour un remplissage transparent.
zoom
boolean(par défaut : true)
Si la valeur est false, les images plus petites ne seront pas étirées jusqu’aux valeurs width et height souhaitées. C’est utile si vous voulez conserver les dimensions d’origine de l’image et vous contenter de limiter la sortie à une taille maximale. Pour en savoir plus sur l’effet du zoom selon la stratégie de redimensionnement de votre choix, consultez la liste des stratégies de redimensionnement disponibles.

Notez que ce paramètre n’affecte que les stratégies qui produisent une image fixe. Les clips animés générés par la stratégie clip ne sont pas concernés.
strategy
object
Définition du processus de génération de miniatures par catégorie de fichier. Chaque clé sélectionne une catégorie de fichier et sa valeur est un tableau ordonné de stratégies :

Catégorie de fichier Stratégies disponibles
audio artwork, waveform, icon
video artwork, frame, clip, icon
image image, embedded-preview, icon
document page, icon
archive icon
webpage render, icon
unknown icon

artwork extrait l’image de couverture intégrée, waveform dessine une forme d’onde audio, frame extrait une image de la vidéo et clip crée un aperçu vidéo animé. Pour les images, image redimensionne l’original et embedded-preview extrait un aperçu intégré lorsqu’il est disponible. page effectue le rendu de la première page du document, render capture une page web et icon génère une icône correspondant au type de fichier.

Pour chaque fichier, le Robot tente d’utiliser la première stratégie pour générer la miniature. Si ce processus échoue (par exemple parce qu’aucune image de couverture n’est disponible dans un fichier vidéo), la stratégie suivante est essayée. Ce processus se répète jusqu’à ce qu’une miniature soit générée ou que la liste soit épuisée. Choisir la stratégie icon comme dernière entrée fournit un mécanisme de repli qui garantit qu’une stratégie appropriée est toujours disponible.

Par défaut, le paramètre prend la définition suivante :
```
{
  "archive": [
    "icon"
  ],
  "audio": [
    "artwork",
    "waveform",
    "icon"
  ],
  "document": [
    "page",
    "icon"
  ],
  "image": [
    "image",
    "embedded-preview",
    "icon"
  ],
  "unknown": [
    "icon"
  ],
  "video": [
    "artwork",
    "frame",
    "icon"
  ],
  "webpage": [
    "render",
    "icon"
  ]
}
```
artwork_outer_color
string
La couleur utilisée dans les parties extérieures du dégradé de l’illustration.
artwork_center_color
string
La couleur utilisée au centre du dégradé de l’illustration.
waveform_center_color
string(par défaut : "#000000ff")
La couleur utilisée au centre du dégradé de la forme d’onde. Le format est #rrggbb[aa] (rouge, vert, bleu, alpha). Utilisée uniquement si la stratégie waveform pour les fichiers audio est appliquée.
waveform_outer_color
string(par défaut : "#000000ff")
La couleur utilisée dans les parties extérieures du dégradé de la forme d’onde. Le format est #rrggbb[aa] (rouge, vert, bleu, alpha). Utilisée uniquement si la stratégie waveform pour les fichiers audio est appliquée.
waveform_height
string | number(par défaut : 100)
Hauteur de la forme d’onde, en pixels. Utilisée uniquement si la stratégie waveform pour les fichiers audio est appliquée. Elle peut servir à faire en sorte que la forme d’onde n’occupe qu’une partie de la miniature d’aperçu.
waveform_width
string | number(par défaut : 300)
Largeur de la forme d’onde, en pixels. Utilisée uniquement si la stratégie waveform pour les fichiers audio est appliquée. Elle peut servir à faire en sorte que la forme d’onde n’occupe qu’une partie de la miniature d’aperçu.
icon_style
square | with-text(par défaut : "with-text")
Le style de l’icône générée si la stratégie icon est appliquée. Le style par défaut, with-text, comprend une icône indiquant le type de fichier et, en dessous, une zone de texte dont le contenu peut être contrôlé par le paramètre icon_text_content et correspond par défaut à l’extension du fichier (par ex. MP4, JPEG). Le style square ne comprend qu’une variante carrée de l’icône indiquant le type de fichier. Voici des exemples d’aperçus générés pour un fichier texte avec les différents styles :

Style with-text :

Style square :
icon_text_color
string(par défaut : "#a2a2a2")
La couleur du texte utilisé dans l’icône. Le format est #rrggbb[aa]. Ce paramètre n’est utilisé que si la stratégie icon est appliquée.
icon_text_font
string(par défaut : "Roboto")
La famille de polices du texte utilisé dans l’icône. Ce paramètre n’est utilisé que si la stratégie icon est appliquée. Voici la liste de toutes les polices prises en charge.
icon_text_content
extension | none(par défaut : "extension")
Le contenu de la zone de texte des icônes générées. Ce paramètre n’est utilisé que si le paramètre icon_style est défini sur with-text. La valeur par défaut, extension, ajoute l’extension du fichier (par ex. MP4, JPEG) à l’icône. La valeur none laisse la zone de texte vide tout en réservant de l’espace pour une superposition de texte personnalisée, par exemple à l’aide de HTML dans votre application.
optimize
boolean(par défaut : true)
Indique si l’image d’aperçu générée doit être optimisée afin de réduire sa taille de fichier tout en conservant sa qualité visuelle. Si cette option est activée, l’image sera optimisée à l’aide de 🤖/image/optimize.
optimize_priority
compression-ratio | conversion-speed(par défaut : "conversion-speed")
Indique si la vitesse de conversion ou le taux de compression est prioritaire lors de l’optimisation des images. Ce paramètre n’est utilisé que si optimize est activé. Veuillez consulter la documentation de 🤖/image/optimize pour plus de détails.
optimize_progressive
boolean(par défaut : false)
Indique si les images doivent être entrelacées, ce qui permet à l’image résultante de se charger progressivement dans les navigateurs. Utilisé uniquement si optimize est activé. Pour plus de détails, veuillez consulter la documentation de 🤖/image/optimize.
clip_format
apng | avif | gif | webp(par défaut : "webp")
Le format d’image animée du clip vidéo généré. Ce paramètre n’est utilisé que si la stratégie clip est appliquée aux fichiers vidéo.

Veuillez consulter les MDN Web Docs pour des informations détaillées sur les formats d’image et leurs caractéristiques. Le GIF bénéficie d’une large prise en charge logicielle, mais ne prend en charge qu’une palette de couleurs limitée. L’APNG prend en charge diverses profondeurs de couleur, mais sa compression sans perte produit des images volumineuses pour les vidéos. L’AVIF offre une compression efficace, mais la prise en charge de l’animation varie selon les navigateurs. Le WebP offre un équilibre entre petite taille de fichier et qualité visuelle, et c’est le format de clip par défaut.
clip_offset
string | number(par défaut : 1)
La position de départ, en secondes, à laquelle le clip est découpé. Ce paramètre n’est utilisé que si la stratégie clip est appliquée aux fichiers vidéo. Pour les vidéos volumineuses, seules certaines portions du fichier peuvent être importées afin d’améliorer la vitesse. Un décalage situé en dehors des données multimédias disponibles peut empêcher la génération du clip.
clip_duration
string | number(par défaut : 5)
La durée en secondes du clip vidéo généré. Ce paramètre n’est utilisé que si la stratégie clip est appliquée aux fichiers vidéo. Sachez qu’une durée de clip plus longue entraîne aussi une taille de fichier plus importante, ce qui peut être indésirable pour des aperçus.
clip_framerate
string | number(par défaut : 5)
La fréquence d’images du clip vidéo généré. Ce paramètre n’est utilisé que si la stratégie clip est appliquée aux fichiers vidéo. Sachez qu’une fréquence d’images plus élevée paraît plus fluide, mais entraîne aussi une taille de fichier plus importante, ce qui peut être indésirable pour des aperçus.
clip_loop
boolean(par défaut : true)
Indique si l’image animée générée doit boucler indéfiniment (true) ou s’arrêter après avoir lu l’animation une fois (false). Ce paramètre n’est utilisé que si la stratégie clip est appliquée aux fichiers vidéo.

Aperçus de médias à la demande avec Smart CDN 17 juin 2024
Generating meaningful file previews (English) 14 janvier 2025

Générer une miniature d’aperçu

Exemple d’utilisation

Paramètres

`interpolate`

`output_meta`

`user_meta`

`result`

`queue`

`force_accept`

`ignore_errors`

`use`

`format`

`quality`

`width`

`height`

`resize_strategy`

`background`

`zoom`

`strategy`

`artwork_outer_color`

`artwork_center_color`

`waveform_center_color`

`waveform_outer_color`

`waveform_height`

`waveform_width`

`icon_style`

`icon_text_color`

`icon_text_font`

`icon_text_content`

`optimize`

`optimize_priority`

`optimize_progressive`

`clip_format`

`clip_offset`

`clip_duration`

`clip_framerate`

`clip_loop`

Catégorie de fichier	Stratégies disponibles
`audio`	`artwork`, `waveform`, `icon`
`video`	`artwork`, `frame`, `clip`, `icon`
`image`	`image`, `embedded-preview`, `icon`
`document`	`page`, `icon`
`archive`	`icon`
`webpage`	`render`, `icon`
`unknown`	`icon`

Générer une miniature d’aperçu

Exemple d’utilisation

Paramètres

interpolate

output_meta

user_meta

result

queue

force_accept

ignore_errors

use

format

quality

width

height

resize_strategy

background

zoom

strategy

artwork_outer_color

artwork_center_color

waveform_center_color

waveform_outer_color

waveform_height

waveform_width

icon_style

icon_text_color

icon_text_font

icon_text_content

optimize

optimize_priority

optimize_progressive

clip_format

clip_offset

clip_duration

clip_framerate

clip_loop

Articles de blog associés

`interpolate`

`output_meta`

`user_meta`

`result`

`queue`

`force_accept`

`ignore_errors`

`use`

`format`

`quality`

`width`

`height`

`resize_strategy`

`background`

`zoom`

`strategy`

`artwork_outer_color`

`artwork_center_color`

`waveform_center_color`

`waveform_outer_color`

`waveform_height`

`waveform_width`

`icon_style`

`icon_text_color`

`icon_text_font`

`icon_text_content`

`optimize`

`optimize_priority`

`optimize_progressive`

`clip_format`

`clip_offset`

`clip_duration`

`clip_framerate`

`clip_loop`