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¶
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>
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
oruseAzureProxy
totrue
;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.