Vidinet services [VC 21.3.1 GEN]

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/vidinet/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>

Configuring a service

New in version 21.3.

Some VidiNet services require configuration before they can be used. Such as service specific metadata-fields, shape-tags or task definitions. The required configuration can be applied automatically by invoking the configure endpoint of the VidiNet resource. Invoking the endpoint will pull the configuration from VidiNet and apply it. A pre-check can be performed to inspect what will happen before applying the actual configuration:

GET /resource/vidinet/VX-1/configuration/pre-check
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceConfigurationResultDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <serviceName>MyVidiNetService</serviceName>
  <serviceId>bac7d4ac-69a8-4b52-b421-79f4dfb3177f</serviceId>
  <configurationVersion>1.0.0</configurationVersion>
  <preCheck>true</preCheck>
  <executedSteps>
      <order>1</order>
      <description>Create/Update metadata-field: vidinet_service_metadata_field</description>
      <resource>/metadata-field/vidinet_service_metadata_field</resource>
      <result>The API call will be executed.</result>
      <success>true</success>
  </executedSteps>
</ServiceConfigurationResultDocument>

After inspecting the results of the pre-check, the configuration can be applied with:

PUT /resource/vidinet/VX-1/configuration
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceConfigurationResultDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <serviceName>MyVidiNetService</serviceName>
  <serviceId>bac7d4ac-69a8-4b52-b421-79f4dfb3177f</serviceId>
  <configurationVersion>1.0.0</configurationVersion>
  <preCheck>false</preCheck>
  <executedSteps>
      <order>1</order>
      <description>Create/Update metadata-field: vidinet_service_metadata_field</description>
      <resource>/metadata-field/vidinet_service_metadata_field</resource>
      <result>The API call was executed successfully.</result>
      <success>true</success>
  </executedSteps>
</ServiceConfigurationResultDocument>

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. For more information on how to analyze using a Vidinet service, please refer to the Vidinet service documentation.

POST /item/VX-74/shape/VX-79/analyze?resourceId=VX-3&jobmetadata=template%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.

Training custom models using VidiNet Cognitive Services

New in version 21.3.

You can use VidiNet Cognitive Services to train your own models which can be used for detection in an analyze job. Please refer to the knowledge base for detailed instructions on how to get started with custom training.

Creating a highlight reel using Nablet Shrynk

New in version 5.4.

Nablet Shrynk is an AI technology that analyses the content of a video file and assigns an interest factor for each frame in the video. Once the analysis has been completed a highlight reel can be rendered for any desired output length. In order to perform the analysis, you need a GPU enabled transcoding service in Vidinet.

Analyze a shape with default parameters:

POST /item/VX-123/shape/VX-456/analyze
Content-Type: application/xml

<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <highlighter>
    <model>football</model>
  </highlighter>
</AnalyzeJobDocument>

When the analysis has finished, start a render job:

POST /item/VX-123/shape/VX-456/highlight-render?tag=__mp4&duration=300

Using Nablet Heightscreen to crop a video into portrait mode

New in version 5.4.

Oftentimes content is filmed in landscape mode, which is not suitable for every device. Nablet Heighscreen uses AI to determine the areas of highest interest in the video. Once an analysis has been completed for a specific aspect ratio, a job can be started to render the asset in portrait mode. A GPU enabled transcoder service is needed in order to perform the analysis.

POST /item/VX-123/shape/VX-456/analyze
Content-Type: application/xml

<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <smartcrop>
    <aspect>9:16</aspect>
  </smartcrop>
</AnalyzeJobDocument>

When the analysis has finished, start a render job:

POST /item/VX-123/shape/VX-456/smartcrop-render?tag=__mp4&aspect=9_16

Using Interra Baton to perform quality control on your material

New in version 5.6.

Baton QC is an industry standard for performing quality control on media content. It supports the basic checks for black frames, freezes all the way up to advanced features such as PSE checks. We have built an integration available in VidiNet, which means you only have to add the service in your VidiNet dashboard. The service is automatically attached to your VidiCore instance (provided it is running in VidiNet), and we also attach some select Baton test plans to get you started. Each test plan is added to VidiCore as an analyze preset. The following test plans are provided out of the box:

Generic - Has all the basic checks enabled, such as black/freeze frames, blockiness, RGB color gamut and signal level checks.
GenericHDR - Same as the Generic plan, but made for HDR content.
GenericPSE - Same as the Generic plan, but with PSE checks enabled.
XDCAM_HD_422_MXF_1080i50 - Has specific checks for validating XDCAM HD content.
AS-11_UK_DPP_HD - Has all the checks for validating AS-11 UK DPP files.

To start a validation, we use a standard ANALYZE job, and provide a Baton test plan as the preset:

POST /item/VX-123/shape/VX-456/analyze?preset=Generic

VidiCore will see that the preset is a Baton test plan and delegate the job to Baton instance running in the cloud. Once the job has finished, the Baton reports are stored in the bulky metadata of the shape. We can then extract the files by asking for the bulky metadata as a file. Looking at the resulting bulky metadata, we get the following result:

GET /item/VX-123/shape/VX-456/metadata/bulky

<?xml version="1.0"?>
<URIListDocument>
    <uri>baton_error_Generic</uri>
    <uri>baton_report_files</uri>
    <uri>baton_summary_Generic</uri>
</URIListDocument>

The baton_error_Generic contains a parsed version of the Baton XML report, which can be used to display the errors in a player for example. The baton_summary_Generic key contains a summary of the number of errors, warnings and informational messages from the analysis. Finally, the baton_report_files contain the binary data from the PDF and XML reports. If we look at what this key contains, we can see the following:

GET /item/VX-123/shape/VX-456/metadata/bulky/baton_report_files

<?xml version="1.0"?>
<BulkyMetadataDocument id="VX-456">
    <field start="-INF" end="+INF" itemTrack="">
        <key>baton_report_files</key>
        <maps>
            <map>
                <entry key="filename">baton_VX-123_VX-456_Generic.xml</entry>
                <entry key="content">...</entry>
                <entry key="type">xml</entry>
                <entry key="test-plan">Generic</entry>
                <entry key="created">2021-04-09T13:19:48.164Z</entry>
            </map>
            <map>
                <entry key="filename">baton_VX-123_VX-456_Generic.pdf</entry>
                <entry key="content">...</entry>
                <entry key="type">pdf</entry>
                <entry key="test-plan">Generic</entry>
                <entry key="created">2021-04-09T13:19:48.405Z</entry>
            </map>
        </maps>
    </field>
</BulkyMetadataDocumen

The actual file data has been removed from the above snippet to save space. Using the bulky-data-as-file endpoint we can now get the actual fle content using the following call:

GET /item/VX-123/shape/VX-456/metadata/bulky/baton_report_files/as-file?extraMapValues=type=pdf

The extraMapValues is used to filter which <map> to extract the file from. In this case we use the type entry and specify that we want the map which has a “type” entry with a value of “pdf”.