CloudConvert Integration [VC 21.3 GEN]

Vidispine supports using CloudConvert as an alternative to the Vidispine transcoder.

How to use

1. Create a CloudConvert resource on Vidispine, containing your CloudConvert API key:

   POST /resource/cloudconvert

   <ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
     <cloudconvert>
       <apiKey>your-api-key</apiKey>
     </cloudconvert>
   </ResourceDocument>

2. Start the jobs with job metadata useCloudConvert=true.

   POST /item/(item-id)/transcode?jobmetadata=useCloudConvert=true

Source file access

By default, Vidispine will upload the source file to CloudConvert. However, it’s also possible to let CloudConvert fetch them directly.

Firstly, make sure the source files are publicly available:

• If the files are on S3 or Azure, set the configuration property useS3Proxy or useAzureProxy to true;

• If not, a public address of the Vidispine server is needed in the CloudConvert resource:

  <ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <cloudconvert>
      <apiKey>your-api-key</apiKey>
      <publicAddress>http://public-address:8080</publicAddress>
    </cloudconvert>
  </ResourceDocument>

  Otherwise, the address from the configuration property apiNoauthUri will be used.

Then, set the job metadata cloudConvertInputMethod=download or add the global setting in the CloudConvert resource:

<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <cloudconvert>
    <apiKey>your-api-key</apiKey>
    <publicAddress>http://public-address:8080</publicAddress>
    <inputMethod>download</inputMethod>
  </cloudconvert>
</ResourceDocument>

Conversion parameters

When transcoding, CloudConvert specific options can be specified in the <muxerSetting> of the shape tag. For example:

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>jpg</format>
  <video>
    <codec>jpg</codec>
  </video>
  <audio/>
  <muxerSetting>
    <key>converteroptions[resize]</key>
    <value>300x300</value>
  </muxerSetting>
  <muxerSetting>
    <key>converteroptions[quality]</key>
    <value>80</value>
  </muxerSetting>
</TranscodePresetDocument>

CloudConvert callback

After a job has been started, Vidispine will always try to poll CloudConvert for the job status. In order for Vidispine to receive notifications from CloudConvert, the publicAddress of the Vidispine server should be set:

<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <cloudconvert>
    <apiKey>your-api-key</apiKey>
    <publicAddress>http://public-address:8080</publicAddress>
  </cloudconvert>
</ResourceDocument>

If not set, then the apiNoauthUri will be used. The one resource that must be accessible to CloudConvert is the callback resource.

Enable CloudConvert using JavaScript

JavaScript can be used to determine if CloudConvert should be used in a job. The script will be evaluated if the job metadata useCloudConvert is not set. CloudConvert will be used only if the script returns a string true.

<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <cloudconvert>
    <apiKey>your-api-key</apiKey>
    <script><![CDATA[
        ...
 ]]></script>
  </cloudconvert>
</ResourceDocument>

The available objects are: job and the commonly available objects