Metadata Handling

Extract Metadata

The API allows you to easily extract metadata from files without the need for any special options or configurations.

However, to customize the output and ensure it aligns with your coding style or requirements, you can specify a key format for the metadata fields as follows:

  • original: The keys are returned as they appear in the raw metadata.
  • capital_first: The first letter of each key is capitalized, and the rest of the key is lowercase (e.g., Title, Author, Date Created).
  • snake_lowercase: Keys are transformed to lowercase and separated by underscores (snake_case). For example, Title becomes title, and Date Created becomes date_created.
  • snake_uppercase: Similar to snake_lowercase, but with all letters in uppercase (e.g., Title becomes TITLE, and Date Created becomes DATE_CREATED).
  • lowercase_nospaces: Keys are converted to lowercase, and all spaces are removed. For example, Date Created becomes datecreated.
  • lowercase_with_spaces: Keys are converted to lowercase, but spaces between words are preserved (e.g., Date Created becomes date created).
  • uppercase_nospaces: Keys are converted to uppercase, and spaces are removed (e.g., Date Created becomes DATECREATED).
  • uppercase_with_spaces: Keys are converted to uppercase, and spaces between words are retained (e.g., Date Created becomes DATE CREATED).

Following are a few examples:

Option Output
original "MIMEType":"video/x-msvideo","VideoCodec":"MP42"
capital_first "Mime Type":"video/x-msvideo","Video Codec":"MP42"
snake_lowercase "mime_type":"video/x-msvideo","video_codec":"MP42"
snake_uppercase "MIME_TYPE":"video/x-msvideo","VIDEO_CODEC":"MP42"
lowercase_nospaces "mimetype":"video/x-msvideo","videocodec":"MP42"
lowercase_with_spaces "mime type":"video/x-msvideo","video codec":"MP42"
uppercase_nospaces "MIMETYPE":"video/x-msvideo","VIDEOCODEC":"MP42"
uppercase_with_spaces "MIME TYPE":"video/x-msvideo","VIDEO CODEC":"MP42" 

{
    "conversion": [{
        "category": "metadata",
        "target": "json",
        "options": {
            "keys_format": "snake_lowercase"
        }
    }]
}

Output Mode

For advanced users or scenarios where more detailed information is required, you can use the output_mode option.

When enabled, this option returns a more comprehensive metadata output, including additional details such as whether a particular metadata field is editable, its formatted key, and its current value. 

                        
                            "conversion": [{
                                "category": "metadata",
                                "target": "json",
                                "options": {
                                    "output_mode": "expert",
                                    "keys_format": "original"
                                }
                            }]

The output will provide detailed information for each metadata key in the following format:


"WhiteBalance": {
"editable": true,
"key_formatted": "white_balance",
"value": "Auto"
},
"FocusMode": {
    "editable": true,
    "key_formatted": "focus_mode",
    "value": "AF-A"
}

Remove Metadata

In some cases, you may want to remove all metadata from a file, such as for privacy reasons or to reduce file size.

This can be easily achieved using the clear_all option. When set to true, this option will remove all possible metadata from the file, ensuring that no sensitive or unnecessary information remains.

Please be aware that not all metadata can be removed from a file, and the effectiveness of the clear_all option may depend on the file type and the nature of the metadata.

While most user-defined or embedded metadata (such as author names, creation dates, and custom tags) can be successfully removed, some types of metadata are deeply embedded in the file and may not be fully cleared. 


{
    "conversion": [{
        "category": "metadata",
        "target": "metadata",
        "options": {
            "clear_all": "true"
        }
    }]
}

Edit Metadata

In addition to removing metadata, you can also change or add custom metadata to a file by using the metadata property.

This feature allows you to specify new metadata fields or update existing ones, providing flexibility for managing and customizing the information associated with a file.

To add or modify metadata, simply include a metadata property in your request, along with the key-value pairs for the metadata you want to modify or add.

This can be useful for updating document properties, adding copyright information, or appending other relevant details.

Please note that the metadata to be added or updated must be expressed in CamelCase, such as CustomMetadata, FocusMode, WhiteBalance, etc.

The following is an example that clears all removable metadata and adds new metadata.


{
    "conversion": [{
        "category": "metadata",
        "target": "metadata",
        "options": {
            "clear_all": "true",
            "Copyright": "(C) My Name",
            "Title": "My New Book"
        }
    }]
}

Errors and Warnings

If a metadata field cannot be written or updated, the system will return the warning code 20002.

This warning indicates that the requested metadata modification could not be applied, typically due to the field being read-only or restricted by the file format.

In such cases, you should verify the field's properties (e.g. whether it is editable) or check if the file format supports modification of that specific metadata.