De nombreux fichiers contiennent des informations intéressantes sur leur contenu. C’est ce que l’on appelle les « métadonnées ». Transloadit extrait automatiquement ces métadonnées pour tous les fichiers téléversés, importés et traités.

Chaque fichier disposera au minimum d’informations telles que les suivantes :

{
  "id": "ae52b7f8c1b3426e8c29ea0a9daf8306",
  "name": "straw-apple.jpg",
  "basename": "straw-apple",
  "ext": "jpg",
  "size": 92230,
  "mime": "image/jpeg",
  "type": "image",
  "field": "test_file",
  "url": "http://tmp.maynard.transloadit.com/upload/1324a798a99fce7f5f8289a95a74f02b.jpg",
  "original_id": "4af24fb2595f44809f3adc2f77bc9bfa",
  "meta": {
    // …
  }
}

Les informations que nous pouvons extraire dépendent du fichier multimédia, de son type, mais aussi de l’appareil ou de la personne qui l’a produit. S’il s’agit d’un iPhone, le fichier contient probablement latitude pour la géolocalisation. Parmi les clés plus courantes figurent height et duration.

Pour découvrir les informations que nous pouvons extraire des fichiers que vous nous soumettrez, vous pouvez essayer l’une de nos démonstrations (English) et examiner notre réponse après y avoir téléversé un fichier.

id: Un ID aléatoire et unique utilisé en interne par Transloadit pour suivre le fichier.
name: Le nom du fichier. Transloadit modifiera l’extension utilisée pour ce champ si le fichier est converti dans un autre format lors du traitement.
basename: Le nom du fichier sans son extension.
ext: L’extension du fichier. Peut valoir null lorsqu’aucune extension n’a été déterminée, ou une chaîne vide pour un nom sans extension.
size: La taille du fichier, en octets.
mime: Le type MIME déterminé pour ce fichier.
type: Une catégorie abstraite décrivant le fichier. Les valeurs connues sont "audio", "document", "image", "office", "pdf", "swf", "video", "xls", ou null lorsqu’aucune catégorie n’a été détectée. Les applications qui exploitent ces données devraient accepter d’autres chaînes afin de maintenir la compatibilité avec de futures catégories.
field: Le nom du champ de formulaire utilisé pour envoyer ce fichier.
url: Une URL permettant de télécharger le fichier, ou null lorsqu’aucune URL de distribution n’est disponible. Les URL temporaires sur nos serveurs expirent après quelques heures ; exportez les fichiers vers un système de stockage pour une utilisation ultérieure. /transloadit/store attribue à url/ssl_url une URL signée du Smart CDN, ou null en l’absence de clé. Conservez le Workspace, asset_id et version_id renvoyés pour disposer d’une référence durable, sous réserve des conditions d’accès et de conservation. /transloadit/import accepte asset_id avec un version_id facultatif, ou un path modifiable. Ni une URL temporaire ni l’id du fichier de traitement ne constituent une référence durable à Storage.
original_id: L’ID unique du fichier téléversé d’origine à partir duquel ce fichier a été généré. Il permet de déterminer quel fichier d’un téléversement de plusieurs fichiers a servi à générer un fichier donné, après plusieurs Steps de traitement.
meta: Un objet contenant des métadonnées supplémentaires extraites du fichier, comme indiqué ci-dessous. Les balises de date répétées peuvent être renvoyées sous forme de listes de leurs valeurs d’origine. Vérifiez le type de la valeur avant de l’utiliser comme un horodatage unique.

Métadonnées des images

Bien que cela dépende du fichier concerné, les fichiers dont le champ type vaut image peuvent généralement contenir des données telles que les suivantes dans la propriété meta :

width: La largeur du média en pixels. Pour une vidéo dont le rapport d’affichage diffère du rapport en pixels, il s’agit de la largeur d’affichage prévue.
height: La hauteur du média en pixels.
aspect_ratio: Le rapport largeur/hauteur de l’image, soit sa largeur divisée par sa hauteur. Vaudra 0 si, pour une raison quelconque, la hauteur de l’image est de 0.
date_recorded: La date et l’heure auxquelles le média a été enregistré. Un horodatage unique et valide sous forme de chaîne est normalisé au format YYYY/MM/DD HH:MM:SS. Lorsqu’un fuseau horaire est présent, l’horodatage est converti en UTC/GMT et se termine par GMT. Les horodatages sous forme de chaînes qui ne peuvent pas être analysés deviennent null. Les horodatages numériques et les listes de balises de date répétées conservent leurs valeurs d’origine.
date_file_created: L’horodatage de création indiqué par les métadonnées du média, lorsqu’il est disponible.
date_file_modified: L’horodatage de modification indiqué par le système de fichiers ou les métadonnées intégrées au média.
title: Le titre de cette image, par exemple "Tree".
keywords: Les mots-clés extraits des métadonnées du fichier : une chaîne, un nombre fini ou un tableau dont les éléments peuvent être des chaînes, des nombres finis ou des booléens. Par exemple, ["tree", "nature"]. Le champ peut être absent ou valoir null. Vérifiez son type avant de le parcourir ; les éléments du tableau ne sont pas nécessairement des chaînes.
description: Une description de cette image, par exemple "This tree is very old.".
location: Le lieu où cette image a été prise, généralement la rue, par exemple "Zingster Str. 32". Les valeurs de métadonnées de type chaîne ou numérique sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
creator: Les métadonnées relatives au créateur extraites du fichier. Les valeurs scalaires d’origine, y compris les listes de ces valeurs, sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
author: L’auteur de la prise de vue. Certains appareils photo renseignent ce champ plutôt que creator.
copyright: Le champ de métadonnées relatif aux droits d’auteur.
copyright_notice: Les métadonnées de la mention de droits d’auteur extraites du fichier. Les valeurs scalaires d’origine sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
city: La ville où cette image a été prise, par exemple "Berlin".
state: L’État où cette image a été prise, par exemple "Berlin".
country: Le pays où cette image a été prise, par exemple "Germany".
country_code: Le code de pays enregistré dans les métadonnées de l’image, par exemple "de" ou 528. Les valeurs de type chaîne ou numérique sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
aperture: Le réglage d’ouverture pour cette image, par exemple 5.7.
exposure_compensation: La correction d’exposition pour cette image, par exemple "+4/3".
exposure_mode: Le mode d’exposition pour cette image, par exemple "Auto".
exposure_time: Le temps d’exposition pour cette image, par exemple "1/30".
flash: Les réglages du flash pour cette image, par exemple "Off, Did not fire".
focal_length: La distance focale pour cette image, par exemple "55.0 mm".
f_number: Le nombre d’ouverture pour cette image, par exemple 5.6.
iso: La valeur ISO pour cette image, par exemple 800.
light_value: L’indice de lumination pour cette image, par exemple 6.9.
metering_mode: Le mode de mesure de l’exposition pour cette image, par exemple "Multi-segment".
shutter_speed: La vitesse d’obturation pour cette image, par exemple "1/32".
white_balance: Le réglage de la balance des blancs pour cette image, par exemple "Manual". Les valeurs de métadonnées de type chaîne ou numérique sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
device_name: Le nom de l’appareil qui a enregistré le média, par exemple "iPhone 3GS".
device_vendor: Le fabricant de l’appareil qui a enregistré le média, par exemple "Apple". Les valeurs de métadonnées de type chaîne ou numérique sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
device_software: La version du logiciel de l’appareil qui a enregistré le média, par exemple "3.1.2".
latitude: La latitude à laquelle le média a été enregistré, par exemple 52.5374.
longitude: La longitude à laquelle le média a été enregistré, par exemple 13.4034.
thumb_index: L’indice de la miniature actuelle, à partir de 0. Cette clé n’est présente que pour les résultats de 🤖/video/thumbs.
thumb_offset: Le décalage temporel de la miniature actuelle, en secondes. Cette clé n’est présente que pour les résultats de 🤖/video/thumbs.
frame_count: Le nombre d’images dans un fichier GIF animé. Vaut 1 par défaut pour tous les autres types d’images.
colorspace: L’espace colorimétrique détecté du média, par exemple "sRGB" ou "Gray". L’espace colorimétrique d’une vidéo est disponible lorsqu’il est détecté et que l’extraction des métadonnées est activée ; il ne nécessite pas output_meta.colorspace: true. Le réglage output_meta: false désactive l’extraction des métadonnées.
has_clipping_path: Vaut true si l’image contient un tracé de détourage, false sinon.
average_color: À ne pas confondre avec la couleur dominante, qui correspond à la couleur de pixel la plus fréquente et dont les cas d’utilisation sont limités. La couleur moyenne est calculée en réduisant d’abord l’image d’entrée à 1 pixel.
has_transparency: Indique si l’image comporte des zones transparentes. Définissez output_meta.has_transparency sur true pour demander une inspection de la transparence. Des valeurs connues comme valant faux, telles que false pour les images JPEG, peuvent être renvoyées même lorsque cette option est omise ou vaut false. Définir output_meta lui-même sur false permet d’ignorer l’extraction de métadonnées supplémentaires ; les vérifications de base du type et de la taille du fichier peuvent tout de même être effectuées.
dominant_colors: Renvoie un tableau contenant jusqu’à 10 couleurs dominantes de l’image sous forme de valeurs hexadécimales. Omettez output_meta.dominant_colors pour ignorer cette extraction. Fournir cette propriété, même avec la valeur false, demande l’extraction et peut entraîner des frais d’utilisation supplémentaires lorsque des couleurs sont renvoyées. Définir output_meta lui-même sur false désactive l’extraction de métadonnées supplémentaires ; les vérifications de base du type et de la taille du fichier peuvent tout de même être effectuées.

Métadonnées des vidéos

Bien que cela dépende du fichier concerné, les fichiers dont le champ type vaut video peuvent généralement contenir des données telles que les suivantes dans la propriété meta :

width: La largeur du média en pixels. Pour une vidéo dont le rapport d’affichage diffère du rapport en pixels, il s’agit de la largeur d’affichage prévue.
height: La hauteur du média en pixels.
framerate: La fréquence d’images de la vidéo, par exemple 29.5.
video_bitrate: Le débit vidéo de la vidéo, par exemple 500000.
video_codec: Le codec vidéo de la vidéo, par exemple "ffh264".
audio_bitrate: Le débit audio en bits par seconde, tous canaux confondus, par exemple 128000.
audio_samplerate: La fréquence d’échantillonnage audio en hertz, par exemple 44100.
audio_channels: Le nombre de canaux audio, généralement 2 pour la stéréo.
audio_codec: Le codec audio, par exemple "faad". Consultez les codecs audio pris en charge.
seekable: Indique si le format de la vidéo permet de se déplacer dans la vidéo, par exemple true.
interlaced: Indique si la vidéo semble utiliser un balayage entrelacé : true pour les vidéos entrelacées ou false pour les vidéos progressives. Définissez output_meta.interlaced sur true pour demander la détection. Cette clé peut être présente avec la valeur null lorsque la détection n’a pas été demandée ou lorsque la détection demandée n’a pas permis de conclure. La seule présence du champ n’indique pas que la détection a été effectuée.
field_order: L’ordre des trames indiqué par FFprobe, par exemple "tt", "bb", "tb", "bt" ou "progressive". Définissez output_meta.interlaced sur true pour demander la détection qui renseigne ce champ de diagnostic. Cette clé peut être présente avec la valeur null lorsque la détection n’a pas été demandée ou que l’ordre des trames n’était pas disponible. Utilisez interlaced pour distinguer simplement les vidéos entrelacées des vidéos progressives dans votre logique.
interlace_detection: Des détails de diagnostic provenant du détecteur d’entrelacement de Transloadit. Cet objet peut inclure sampled_frames, tff, bff, progressive, undetermined, confidence, method et ffprobe_field_order. Définissez output_meta.interlaced sur true pour demander la détection. Cette clé peut être présente avec la valeur null lorsque la détection n’a pas été demandée ; vérifiez qu’il s’agit d’un objet non nul avant de lire ses propriétés.
colorspace: L’espace colorimétrique détecté du média, par exemple "sRGB" ou "Gray". L’espace colorimétrique d’une vidéo est disponible lorsqu’il est détecté et que l’extraction des métadonnées est activée ; il ne nécessite pas output_meta.colorspace: true. Le réglage output_meta: false désactive l’extraction des métadonnées.
date_recorded: La date et l’heure auxquelles le média a été enregistré. Un horodatage unique et valide sous forme de chaîne est normalisé au format YYYY/MM/DD HH:MM:SS. Lorsqu’un fuseau horaire est présent, l’horodatage est converti en UTC/GMT et se termine par GMT. Les horodatages sous forme de chaînes qui ne peuvent pas être analysés deviennent null. Les horodatages numériques et les listes de balises de date répétées conservent leurs valeurs d’origine.
date_file_created: L’horodatage de création indiqué par les métadonnées du média, lorsqu’il est disponible.
date_file_modified: L’horodatage de modification indiqué par le système de fichiers ou les métadonnées intégrées au média.
device_name: Le nom de l’appareil qui a enregistré le média, par exemple "iPhone 3GS".
device_vendor: Le fabricant de l’appareil qui a enregistré le média, par exemple "Apple". Les valeurs de métadonnées de type chaîne ou numérique sont préservées ; vérifiez le type avant d’utiliser des méthodes de chaîne.
device_software: La version du logiciel de l’appareil qui a enregistré le média, par exemple "3.1.2".
latitude: La latitude à laquelle le média a été enregistré, par exemple 52.5374.
longitude: La longitude à laquelle le média a été enregistré, par exemple 13.4034.

Par exemple, vous pouvez détecter les vidéos entrelacées dans un Step d’importation ou de téléversement et acheminer uniquement ces fichiers vers un Step suivant :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "output_meta": {
        "interlaced": true
      }
    },
    "only_interlaced": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.meta.interlaced}", "==", "true"]]
    }
  }
}

Métadonnées audio

Bien que cela dépende du fichier concerné, les fichiers dont le champ type vaut audio peuvent généralement contenir des données telles que les suivantes dans la propriété meta :

duration: La durée du fichier audio en secondes.
audio_bitrate: Le débit audio en bits par seconde, tous canaux confondus, par exemple 128000.
audio_samplerate: La fréquence d’échantillonnage audio en hertz, par exemple 44100.
audio_channels: Le nombre de canaux audio, généralement 2 pour la stéréo.
audio_codec: Le codec audio, par exemple "faad". Consultez les codecs audio pris en charge.
artist: Les informations sur l’artiste enregistrées dans les métadonnées du média. Les balises répétées sont renvoyées sous forme de liste. Les noms d’apparence numérique et les mots true et false peuvent être reçus sous forme de nombres ou de booléens JSON, y compris dans les listes. Vérifiez le type avant d’utiliser des méthodes de chaîne ou de parcourir une liste.
mean_volume: Le volume moyen du fichier audio. Définissez output_meta.mean_volume sur true pour demander la mesure. Cette clé peut être présente avec la valeur null lorsque la mesure n’a pas été demandée ou que la valeur n’était pas disponible. La seule présence du champ n’indique pas que la mesure a été effectuée.

Métadonnées des documents Office

Les fichiers dont le champ type vaut office peuvent inclure ces champs dans meta, lorsqu’ils sont présents dans les propriétés enregistrées du fichier. Ces nombres sont indiqués par l’application ayant servi à créer le document ; Transloadit ne les recalcule pas à partir de son contenu, ils peuvent donc être absents ou obsolètes.

page_count: Le nombre de pages. Pour les documents Office, il provient des propriétés enregistrées du fichier.
word_count: Le nombre de mots enregistré dans les propriétés d’un document Office.
character_count: Le nombre de caractères enregistré dans les propriétés d’un document Office.