Many files contain interesting information about their contents. This is called “metadata”. Transloadit automatically extracts this metadata for all uploaded, imported, and processed files.

At the very minimum, each file will have the information such as:

{
  "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": {
    // …
  }
}

The information we can extract depends on the media file, its type, but also who produced it. If it was an iPhone, there’s probably latitude in there for geo-positioning. More common keys include height, and duration.

To see what information we can extract from files that you will throw at us, you could try one of our demos and inspect our response after uploading a file there.

id: A random and unique ID used internally by Transloadit to track the file.
name: The name of the file. Transloadit will change the extension used for this field if the file undergoes processing into a different format.
basename: The name of the file without the extension.
ext: The extension of the file.
size: The size of the file, in bytes.
mime: The determined MIME type for this file.
type: An abstract category describing the file. Known values are "audio", "document", "image", "office", "pdf", "swf", "video", "xls", or null when no category was detected. Consumers should accept other strings so future categories remain compatible.
field: The name of the form field used to submit this file.
url: A URL from which the file can be downloaded, or null when no delivery URL is available. Temporary URLs on our servers expire after a few hours; export files to storage for later use. Private-storage results from /transloadit/store return null for both url and ssl_url. Keep the returned Workspace, asset_id, and version_id for a durable reference, subject to access and retention. /transloadit/import accepts asset_id with an optional version_id, or a mutable path. Neither a temporary URL nor the processing file’s id is a durable Storage reference.
original_id: The unique ID of the original upload file from which this file was generated. This is useful to determine which file of a multi-file upload was used to generate a given file, after several Steps of processing.
meta: An object containing additional metadata extracted from the file, as shown below.

Image Metadata

Although it depends on the file at hand, files whose type is image can typically contain data such as the following inside the meta property:

width: The width of the media in pixels. For video whose display ratio differs from its pixel ratio, this is the intended display width.
height: The height of the media in pixels.
aspect_ratio: The aspect ratio of the image, which is its width divided by its height. Will be 0 if for some reason the image height is 0.
date_recorded: The date and time at which the media was recorded, in the format YYYY/MM/DD HH:MM:SS TZ, such as "2010/06/30 22:16:06 GMT".
date_file_created: The creation timestamp reported by the media metadata, when available.
date_file_modified: The file-system modification time for the media file.
title: The title of this image, such as "Tree".
keywords: Keywords extracted from the file’s metadata: a string, a finite number, or an array whose entries can be strings, finite numbers, or booleans. For example, ["tree", "nature"]. The field may be absent or null. Check its type before iterating; array entries are not necessarily strings.
description: A description of this image, such as "This tree is very old.".
location: The location at which this image was taken, which is usually the street, such as "Zingster Str. 32".
creator: The creator that took the image.
author: The author that took the image. Some cameras populate this field as opposed to creator.
copyright: The copyright metadata field.
copyright_notice: The copyright notice metadata field.
city: The city in which this image was taken, such as "Berlin".
state: The state in which this image was taken, such as "Berlin".
country: The country in which this image was taken, such as "Germany".
country_code: The country code of the country in which this image was taken, such as "de".
aperture: The aperture setting for this image, such as 5.7.
exposure_compensation: The exposure compensation for this image, such as "+4/3".
exposure_mode: The exposure mode for this image, such as "Auto".
exposure_time: The exposure time for this image, such as "1/30".
flash: The flash settings for this image, such as "Off, Did not fire".
focal_length: The focal length for this image, such as "55.0 mm".
f_number: The f-number for this image, such as 5.6.
iso: The ISO value for this image, such as 800.
light_value: The light value for this image, such as 6.9.
metering_mode: The metering mode for this image, such as "Multi-segment".
shutter_speed: The shutter speed for this image, such as "1/32".
white_balance: The white balance setting for this image, such as "Manual".
device_name: The name of the device that recorded the media, such as "iPhone 3GS".
device_vendor: The manufacturer of the device that recorded the media, such as "Apple".
device_software: The software version of the device that recorded the media, such as "3.1.2".
latitude: The latitude at which the media was recorded, such as 52.5374.
longitude: The longitude at which the media was recorded, such as 13.4034.
thumb_index: The index of the current thumbnail starting at 0. This key is only present for results of 🤖/video/thumbs.
thumb_offset: The offset for the current thumbnail, in seconds. This key is only present for results of 🤖/video/thumbs.
frame_count: The number of frames in an animated GIF file. This is 1 by default for all other image types.
colorspace: The detected media colorspace, such as "sRGB" or "Gray". Video colorspace is available when detected while metadata extraction is enabled; it does not require output_meta.colorspace: true. Setting output_meta: false disables metadata extraction.
has_clipping_path: Is true if the image contains a clipping path, false otherwise.
average_color: Not to be confused with dominant color, that counts a single most occurring pixel color and has limited use cases. The average color is calculated by first scaling the input image to 1 pixel.
has_transparency: Whether the image has transparent areas. Set output_meta.has_transparency to true to request transparency inspection. Known-false values, such as false for JPEG images, can be returned even when this option is omitted or false. Setting output_meta itself to false skips additional metadata extraction; basic file type and size checks can still run.
dominant_colors: Returns an array of up to 10 dominant image colors as hexadecimal values. Omit output_meta.dominant_colors to skip this extraction. Supplying the property, including false, requests extraction and can incur additional usage charges when colors are returned. Setting output_meta itself to false disables additional metadata extraction; basic file type and size checks can still run.

Video Metadata

Although it depends on the file at hand, files whose type is video can typically contain data such as the following inside the meta property:

width: The width of the media in pixels. For video whose display ratio differs from its pixel ratio, this is the intended display width.
height: The height of the media in pixels.
framerate: The frame rate of the video, such as 29.5.
video_bitrate: The video bit rate of the video, such as 500000.
video_codec: The video codec of the video, such as "ffh264".
audio_bitrate: The audio bit rate in bits per second across all channels, such as 128000.
audio_samplerate: The audio sample rate in hertz, such as 44100.
audio_channels: The number of audio channels, typically 2 for stereo.
audio_codec: The audio codec, such as "faad". See the supported audio codecs.
seekable: Whether the format of the video supports seeking, such as true.
interlaced: Whether the video appears to use interlaced scanning: true for interlaced videos or false for progressive videos. Set output_meta.interlaced to true to request detection. This key may be present as null when detection was not requested or when requested detection was inconclusive. Field presence alone does not show that detection ran.
field_order: The field order reported by FFprobe, such as "tt", "bb", "tb", "bt", or "progressive". Set output_meta.interlaced to true to request the detection that populates this diagnostic field. This key may be present as null when detection was not requested or the field order was unavailable. Use interlaced for simple interlaced/progressive branching.
interlace_detection: Diagnostic details from Transloadit’s interlace detector. This object can include sampled_frames, tff, bff, progressive, undetermined, confidence, method, and ffprobe_field_order. Set output_meta.interlaced to true to request detection. This key may be present as null when detection was not requested; check for a non-null object before reading its properties.
colorspace: The detected media colorspace, such as "sRGB" or "Gray". Video colorspace is available when detected while metadata extraction is enabled; it does not require output_meta.colorspace: true. Setting output_meta: false disables metadata extraction.
date_recorded: The date and time at which the media was recorded, in the format YYYY/MM/DD HH:MM:SS TZ, such as "2010/06/30 22:16:06 GMT".
date_file_created: The creation timestamp reported by the media metadata, when available.
date_file_modified: The file-system modification time for the media file.
device_name: The name of the device that recorded the media, such as "iPhone 3GS".
device_vendor: The manufacturer of the device that recorded the media, such as "Apple".
device_software: The software version of the device that recorded the media, such as "3.1.2".
latitude: The latitude at which the media was recorded, such as 52.5374.
longitude: The longitude at which the media was recorded, such as 13.4034.

For example, you can detect interlaced video in an import or upload Step and route only those files to a follow-up Step:

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

Audio Metadata

Although it depends on the file at hand, files whose type is audio can typically contain data such as the following inside the meta property:

duration: The length of the audio file in seconds.
audio_bitrate: The audio bit rate in bits per second across all channels, such as 128000.
audio_samplerate: The audio sample rate in hertz, such as 44100.
audio_channels: The number of audio channels, typically 2 for stereo.
audio_codec: The audio codec, such as "faad". See the supported audio codecs.
artist: Many applications that produce audio write additional information into the audio file such as artist, year, album, genre.
mean_volume: The mean volume of the audio file. Set output_meta.mean_volume to true to request measurement. This key may be present as null when measurement was not requested or the value was unavailable. Field presence alone does not show that measurement ran.