Vidinet services

Vidinet services can be registered as resources and then be used directly by Vidispine, if supported natively, or from custom JavaScript steps.

Adding a service

Add a Vidinet service by creating a new vidinet resource. The resource document may differ for different services, so please refer to the vidinet dashboard for more information on how the service should be defined.

POST /resource/
Content-Type: application/xml

<?xml version="1.0"?>
<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <vidinet>
    <url>http://transcoder.example.com:8888/</url>
    <endpoint>http://transcoder.example.com:8888/</endpoint>
    <type>TRANSCODER</type>
  </vidinet>
</ResourceDocument>

Vidispine checks the status of services continuously in the background. As such, if the configuration is correct you will see that the transcoder shows up as ONLINE in a few seconds.

GET /resource/VX-8
<?xml version="1.0"?>
<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-8</id>
  <vidinet>
    <url>http://transcoder.example.com:8888/</url>
    <endpoint>http://transcoder.example.com:8888/</endpoint>
    <type>TRANSCODER</type>
    <state>ONLINE</state>
  </vidinet>
</ResourceDocument>

Import using Vidinet

When importing files the import job uses the Vidispine transcoder to detect the type of media that is being imported, and if requested, to transcode the imported media.

To use Vidinet transcoder service instead of a local transcoder on import, specify the Vidinet TRANSCODER resource when initiating the import. For example:

POST /import?uri=file:///srv/testdata/sample.mov&tag=__mp4&resourceId=VX-8

After the file has been transferred to a storage, the file will be media checked and transcoded using Vidinet. Once a media check or transcode has been requested from Vidinet, the state of the job will change to VIDINET_JOB, and the job will no longer occupy a job slot, until Vidinet has completed and the job will resume.

Make sure that files are imported to or exist on a storage that is compatible with the Vidinet service in question. This is typically either an S3 bucket or an Azure blob storage, see the Vidinet service documentation for more detail.

Transcoding using Vidinet

If a Vidinet TRANSCODER resource is specified when initiating an item transcode, then the transcode will be performed using that Vidinet service. For example:

POST /item/VX-74/transcode?tag=__mp4&resourceId=VX-8

The transcode job will execute as normal, but the transcode will be handed off to Vidinet instead of being sent to a local transcoder. Once this happens the state of the job will change to VIDINET_JOB, and no longer occupy a job slot, until Vidinet has completed the transcode.

Cost estimation

To retrieve the estimated cost of performing the above transcode using Vidinet, the cost API can be used. Simply prefix the path with cost/ and execute the request:

POST /cost/item/VX-74/transcode?tag=__mp4&resourceId=VX-8
<CostEstimateDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>dGVzdA==</id>
  <url>http://localhost:8080/API/cost/estimate/dGVzdA==</url>
</CostEstimateDocument>

The estimate may not be immediately available, in which case the estimate will be shown as pending.

GET http://localhost:8080/API/cost/estimate/dGVzdA==
<CostEstimateDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>dGVzdA==</id>
  <url>http://localhost:8080/API/cost/estimate/dGVzdA==</url>
  <state>PENDING</state>
  <service>
    <resource>VX-8</resource>
    <type>TRANSCODER</type>
    <state>ONLINE</state>
  </service>
</CostEstimateDocument>

Once the cost has been estimated:

GET http://localhost:8080/API/cost/estimate/dGVzdA==
<CostEstimateDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>dGVzdA==</id>
  <url>http://localhost:8080/API/cost/estimate/dGVzdA==</url>
  <state>FINISHED</state>
  <service>
    <resource>VX-8</resource>
    <type>TRANSCODER</type>
    <state>ONLINE</state>
    <cost unit="USD">1.2</cost>
  </service>
</CostEstimateDocument>

Quality control using Vidinet

Quality control using Vidinet services can be performed by specifying a Vidinet QC resource when starting a shape analysis job.

POST /item/VX-74/shape/VX-79/analyze?resourceId=VX-3&jobmetadata=auroraTemplate%3DQuality%20Test
Content-Type: application/xml

<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine"/>
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <jobId>VX-345</jobId>
  <user>admin</user>
  <started>2017-09-08T14:59:49.131Z</started>
  <status>READY</status>
  <type>ANALYZE</type>
  <priority>MEDIUM</priority>
</JobDocument>

Once the job has finished, the result of the analysis can be found in the bulky metadata of the shape.

A cost estimate can be retrieved, just like for transcodes, using the cost API.

Using Vidinet services from JavaScript

Vidinet services that are not natively supported can be used from JavaScript, for example by creating a custom job with one or more steps that interact with the Vidinet service using the Vidinet JavaScript functions.

For example:

POST /task-definition/jobtype/MYCOMPANY_CUSTOM_VIDINET_JOB?id=26000
PUT  /task-definition/jobtype/MYCOMPANY_CUSTOM_VIDINET_JOB/step/100
Content-Type: application/xml

<TaskDefinitionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <description>A custom JavaScript step</description>
  <script><![CDATA[
var item = ...;
var instruction = "...";

job.vidinetJob("TEST", instruction, {
    item: itemId
});
]]></script>
  <step>100</step>
  <dependency>
    <previous>false</previous>
    <allPrevious>true</allPrevious>
  </dependency>
  <jobType>MYCOMPANY_CUSTOM_VIDINET_JOB</jobType>
  <critical>false</critical>
</TaskDefinitionDocument>

For more information on how to execute jobs for a service in Vidinet, please refer to the Vidinet service documentation.

Transcoding using AWS Elemental MediaConvert

The AWS Elemental MediaConvert integration is currently in developer preview. This means that syntax may change somewhat for the final implementation.

New in version 4.15.

You can use Elemental MediaConvert to transcode your files using Vidinet. To start with you need to buy the service in Vidinet and add it to your Vidispine server instance. please refer to the Vidinet service documentation on how to do that.

<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1</id>
  <vidinet>
    <url>vidinet://e1423727-...:...@42a73b4c-8974-4402-a237-17b80bd11350</url>
    <name>My AWS MediaConvert</name>
    <endpoint>https://services.vidinet.net</endpoint>
    <type>ELEMENTAL_MEDIACONVERT</type>
    <state>ONLINE</state>
    <scheme>s3</scheme>
  </vidinet>
</ResourceDocument>

You then need a new shape-tag with the new mediaconvert element. To install the system default shape-tags that use Elastic MediaConvert you call:

PUT /APIinit/preset-mediaconvert-templates

Once the vidinet resource is in place and a shape-tag contains the mediaconvert element you can use it as any other shape-tag for transcoding.

 <TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <description>
     BROADCAST, XDCAM, MXF, MPEG2 HD422, WAV, 16x9 DAR, 1920x1080p, 23.98 Hz, 50 Mbps CBR
   </description>
   <name>
     __mediaconvert_Broadcast_Xdcam_Mxf_Mpeg2_Wav_16x9_1920x1080p_24Hz_50Mbps
   </name>
   <audio/>
   <video/>
   <mediaconvert>
     <outputSetting>
         { "Type": "SYSTEM", "Category": "BROADCAST-XDCAM", ... }
     </outputSetting>
   </mediaconvert>
 </TranscodePresetDocument>

Transcoding using this preset would then cause the transcode to be executed using the Vidinet Elemental MediaConvert service:

POST /item/VX-46/transcode?tag=__mediaconvert_Broadcast_Xdcam_Mxf_Mpeg2_Wav_16x9_1920x1080p_24Hz_50Mbps

The following requirements apply when using MediaConvert:

  • The input and output storages needs to be S3 buckets.
  • The buckets must be accessible to the AWS Elemental MediaConvert service as detailed in the Vidinet service documentation.

Transcoding using Bitmovin

New in version 5.0.

You can use the Bitmovin service in Vidinet to transcode your files. To start with you need to buy the service in Vidinet and add it to your Vidispine server instance. Please refer to the Vidinet service documentation on how to do that.

<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1</id>
  <vidinet>
    <url>vidinet://g6d23345-...:...@4b916a24-393d-4ff6-85ac-76e3fb082dd9</url>
    <name>My Bitmovin transcoder</name>
    <endpoint>https://services.vidinet.net</endpoint>
    <type>BITMOVIN</type>
    <state>ONLINE</state>
    <scheme>s3</scheme>
  </vidinet>
</ResourceDocument>

Once the vidinet resource is in place you can use any normal shape-tag for transcoding. Please see the Vidinet service documentation for current restrictions, as they are subject to change with upcoming updates to the Vidinet system.

The following requirements apply when using Bitmovin:

  • The input and output storages needs to be S3 buckets.
  • The buckets must be accessible to the Bitmovin service as detailed in the Vidinet service documentation.

Analyzing using Vidinet Cognitive Services

New in version 5.0.

You can use Vidinet Cognitive Services to analyze your files and populate them with cognitive metadata. To start you need to buy a cognitive service in the Vidinet store and add it to your Vidispine server instance. Please refer to the Vidinet service documentation on how to do that.

<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1</id>
  <vidinet>
    <url>vidinet://e1423727-...:...@42a73b4c-8974-4402-a237-17b80bd11350</url>
    <name>My AWS Rekognition service</name>
    <endpoint>https://services.vidinet.net</endpoint>
    <type>COGNITIVE_SERVICES</type>
    <state>ONLINE</state>
    <scheme>s3</scheme>
  </vidinet>
</ResourceDocument>

Once the Vidinet resource is in place you can trigger an analysis on an item:

POST /item/VX-46/analyze?resourceId=VX-1
<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine"/>

Or, on a specific shape:

POST /item/VX-46/shape/VX-47/analyze?resourceId=VX-1
<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine"/>

The following requirements apply when using AWS based Cognitive Services:

  • The media storage needs to be an S3 bucket.
  • The buckets must be accessible to the AWS Cognitive service as detailed in the Vidinet service documentation.