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.

Au minimum, chaque fichier disposera 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 ce qui l’a produit. Si le fichier provient d’un iPhone, il contient probablement latitude pour le géopositionnement. Parmi les clés plus courantes figurent height et duration.

Pour voir quelles informations 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 identifiant 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 l’extension.
ext: L’extension du fichier. Peut valoir null lorsqu’aucune extension n’a été déterminée, ou être 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 consommatrices devraient accepter d’autres chaînes afin de préserver la compatibilité avec les futures catégories.
field: Le nom du champ de formulaire utilisé pour soumettre ce fichier.
url: Une URL à partir de laquelle le fichier peut être téléchargé, ou null lorsqu’aucune URL de distribution n’est disponible. Les URL temporaires sur nos serveurs expirent au bout de quelques heures ; exportez les fichiers vers un stockage pour une utilisation ultérieure. Les résultats de /transloadit/store en stockage privé renvoient null à la fois pour url et ssl_url. Conservez le Workspace, l’asset_id et le version_id renvoyés pour disposer d’une référence durable, sous réserve des règles d’accès et de rétention. /transloadit/import accepte un 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 de stockage.
original_id: L’identifiant 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 été utilisé pour 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 illustré 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 type est 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 de son rapport de 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 égale à 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 impossibles à analyser 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 les métadonnées du système de fichiers ou par celles 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".
creator: Le créateur qui a pris l’image.
author: L’auteur qui a pris l’image. Certains appareils photo renseignent ce champ plutôt que creator.
copyright: Le champ de métadonnées relatif aux droits d’auteur.
copyright_notice: Le champ de métadonnées relatif à la mention de droits d’auteur.
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 du pays où cette image a été prise, par exemple "de".
aperture: Le réglage de l’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 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".
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".
device_software: La version logicielle 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 vignette actuelle, à partir de 0. Cette clé n’est présente que pour les résultats de 🤖/video/thumbs (English).
thumb_offset: Le décalage de la vignette actuelle, en secondes. Cette clé n’est présente que pour les résultats de 🤖/video/thumbs (English).
frame_count: Le nombre d’images dans un fichier GIF animé. Cette valeur est 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 de la vidéo est disponible lorsqu’il est détecté alors que l’extraction des métadonnées est activée ; il ne nécessite pas output_meta.colorspace: true. Définir 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 prend en compte uniquement la couleur de pixel la plus fréquente et dont les cas d’utilisation sont limités. La couleur moyenne est calculée en redimensionnant 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 vérification de la transparence. Des valeurs dont on sait qu’elles correspondent au booléen faux, comme false pour les images JPEG, peuvent être renvoyées même lorsque cette option est omise ou vaut false. Lorsque output_meta lui-même est défini sur false, l’extraction de métadonnées supplémentaires est ignorée ; les vérifications de base du type et de la taille du fichier peuvent toujours être exécuté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 ne pas effectuer cette extraction. Fournir la propriété, y compris 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 toujours être exécutées.

Métadonnées des vidéos

Bien que cela dépende du fichier concerné, les fichiers dont le type est 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 de son rapport de 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 sur l’ensemble des canaux, 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 le déplacement à une position donnée, 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 ne montre 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 une logique conditionnelle simple entre vidéo entrelacée et vidéo progressive.
interlace_detection: Détails de diagnostic fournis par le 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 la présence d’un objet non nul avant d’en lire les propriétés.
colorspace: L’espace colorimétrique détecté du média, par exemple "sRGB" ou "Gray". L’espace colorimétrique de la vidéo est disponible lorsqu’il est détecté alors que l’extraction des métadonnées est activée ; il ne nécessite pas output_meta.colorspace: true. Définir 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 impossibles à analyser 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 les métadonnées du système de fichiers ou par celles 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".
device_software: La version logicielle 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 n’acheminer que 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 type est 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 sur l’ensemble des canaux, 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: De nombreuses applications qui produisent de l’audio écrivent des informations supplémentaires dans le fichier audio, telles que artist, year, album, genre.
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 ne montre pas que la mesure a été effectuée.