CloudConvert Integration

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

Important

  • It is not possible to transcode using the Vidispine transcoder and CloudConvert at the same time.
  • Thumbnails and posters will not be generated during the transcode of video using CloudConvert

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

Using cloudconvert API V2

New in version 5.7.4.

To setup a cloudconvert resource using the V2 API, add a version=2 property to the resource definition. And if the resource is using a sandbox account, add a <isSandbox>true<isSandbox>` element to the definition:

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

By default, VidiCore will try to select a v1 resource (version=1, or not set) for all cloudconvert jobs, unless the configuration cloudConvertVersion is set to 2.

There is also a cloudConvertSandbox that be set globally to make VidiCore select a sandbox resource by default.

These two options can also be configured on a per-job basis, using the cloudConvertVersion=2 and cloudConvertSandbox=true/false job metadata.