Middleware - running a Transcoder for Media Transformation

Since version 4.1.0, our Middleware allows to process each downloaded media by means of a user defined command. This enables to transform the downloaded files in order to make them compatible with your system. 

For example, using this feature you'll be able to use a tool such as ffmpeg or ImageMagick to transcode images, audios and videos.

How to Configure it

You need to edit the env.xml file from your Middleware. To do so, locate the transcoders section that looks like this:

<New class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg></Arg>
  <Arg>transcoders</Arg>
  <Arg><![CDATA[
]]></Arg>
</New>
If you're upgrading from a previous version you can edit your current env.xml and add the section. 
Inside the CDATA brackets, you need to add each transformation you want to perform, detailing one per line with the following format:
<source_extension>,<target_extension>,<command>
where 
  • source_extension defines the extension of the downloaded file that must be processed using command. This parameter is case insensitive.
  • target_extension defines the extension for the generated file.
  • command is the full path of the command being called for each downloaded file having source_extension as file extension. 
    • This command 
      • will receive two arguments: the incoming file and the file where it must write the output (command input_file destination_file).
      • must return a 0 status code on success or a code different than 0 otherwise
For example in Linux or OSX, if you want to convert PNG and GIF files to JPG using ImageMagick's convert, you can add the following:
<New class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg></Arg>
  <Arg>transcoders</Arg>
  <Arg><![CDATA[
png,jpg,/usr/bin/convert
gif,jpg,/usr/bin/convert
]]></Arg>
</New>

as you can see in the example, you need to declare each input format in a separate line.

Following the example for a given downloaded media file, the middleware will call something like

/usr/bin/convert /tmp/media/https/foo/4645d1dc5f523182d5d1a6812071f3c17f974953.png /tmp/media/https/foo/4645d1dc5f523182d5d1a6812071f3c17f974953.png_pKBXqg.jpg

How it works 

The conversion happens during the Data Source synchronization process. When the data for a specific data source is downloaded, the middleware looks for downloaded media having one of the declared extensions and calls the configured command (if it hasn't been previously processed). 

If the command is successful the destination file that's passed as second argument to the command will be used as the media file path that will be written in the corresponding field (localMainMediaPath or similar) of the file or table (depending on you integration mode). 


Troubleshooting

In case the conversion is unsuccessful (for example: the execution failed) the middleware will treat the content as if it wasn't downloaded (field will be empty).

You can check for the error message to understand better what's happening:

  • Couldn't find the configured software:
    code 072:
    Failed to download https://s3-assets0.flowics.com/web/uploads/production/generic-resources/asset/53115/versioned_efb3e1d0211f8dff706ba53ca066e383.png
    due to: Cannot run program "usr/bin/onvert" (in directory "/run/user/1000/middleware/media/https/s3-assets0.flowics.com"):
    error=2, No such file or directory
  • The conversion failed:
    code 072:
    Failed to download https://s3-assets0.flowics.com/web/uploads/production/generic-resources/asset/53115/versioned_efb3e1d0211f8dff706ba53ca066e383.png
    due to: transcoding failed
  • Format problem at the env.xml:
    Failed loading transcoder configuration:
     - on line 1: field is incomplete: 'x'
    Dying. Please review your 'env.xml'.



Was this article helpful?