API

Every media item in AdmiralCloud is linked to a format. A format can be of type video, audio, image or document. Except for the original formats (which are linked to uploaded media items) every format contains a command structure that defines how this format transcodes or converts the original media. This can be a format to transcode an original video to MP4 or to HLS or a RGB image into CYMK.

AdmiralCloud provided a huge number of curated, managed formats so most of the time there is no need to create your own format. AdmiralCloud also provided microservices which can do conversion of the fly – please checkout Smartcropping Service

Command structure

Every custom format must be based on one of our managed blueprint formats. These formats define available parameters in the settings object. The actual format command must be set in settings parameters.

Again, custom format can have all command parameters from blueprint AND allowedParameters (which take precedence). Take a look at this example:

// blueprint settings
{
   "parameters":{
      "width":640
   },
   "allowedParameters":[
      {
         "command":"width",
         "regex":"^\\d{2,5}$",
         "mediaTypes":[
            "audio"
         ]
      },
      {
         "command":"height",
         "regex":"^\\d{2,5}$",
         "mediaTypes":[
            "audio"
         ]
      }
   ]
}

// custom format
{
   "parameters":{
      "width":1920,
      "height":1080,
      "notAllowedParameter":true
   }
}

// Result command, notAllowedParameter will be ignored
{ width: 1920, height: 1080 }

IPTC-Data

By default AdmiralCloud removes all metadata from images for data protection reasons. A source field (iptc:source) will be automatically re-added with the name of the customer as defined in the customer account. Also the field xmp:CreatorTool will be set to “AdmiralCloud”.

You can define other fields in your format that should be added during transcoding as well as updated after those metadata change. To do so, you have to set settings.metadata in your format.

[
  { "metaTitle": "meta_exif_camera_model" },
  { "metaTitle": "meta_exif_camera_model", "type": "exif", "key": "model" },
  { "metaTitle": "tags", "key": "Keywords", "languages": ["de", "uni"] } // languages is optional,
  { "metaTitle": "license" },
  { "metaTitle": "instructions" }
]

Field	Type	Required	Description
metaTitle	String	yes	The field as defined in our metadata fields. The will automatically be mapped to the proper IPTC or EXIF field. If you want more control, use type and key. SPECIAL CASES: Using “tags” as value -> Tags are set as keywords, all languages are used. If you set languages array only tags in those languages are added. Using “license” as value -> license_rightsUsageTerms are determined from license metadata and added as xmp:usageterms Using instructions as value -> If you set value as property of this object this value is used. Otherwise start, end and types are determined from license and added as instructions
type	String		Optional type – can be exif or iptc
key	String		Optional key to use as IPTC or EXIF field
language			If set metadata in this language is preferred. Otherwise “uni” will be used.

Please note, that the metadata must exist, otherwise the field will remain empty/will not be written to the file.

Reference