This is a step-by-step guide for getting started with the Vidispine API as-a-Service on Vidinet. The purpose of this guide is to get you familiarized with the Vidispine API, and help you create your first item, shape and metadata-field, import and transcode a file, and finally retrieve the transcoded version of the file through the API.


Before you begin

Before you begin you need to launch a new Vidispine instance in Vidinet. Don't worry, won't take more time than getting yourself a nice cup of coffee. If you're not at all familiar with Vidinet we have a Vidispine API launch guide in our blog. Before you go there I suggest you take a look at how you should configure your S3 bucket for Vidispine API usage


For the API call described in this articles we also make the following assumptions: 

  • Default header should be content-type: application/xml
  • Default authentication is basic authentication
  • You have the credentials for access to your Vidispine API, either the admin account, or another account created for you. The Vidispine API editions on Vidinet does not have a default password, instead it’s selected when creating the instance. Ask your admin, unless you are the admin.

Introduction

The Vidispine API can be accessed through an SDK, e.g., in .NET or Java. However, for this guide we make RESt API requests directly to Vidispine instead of going through SDKs. Directly calling the API is our favourite method for debugging and/or playing. There are thousands of tools out there, but some that we regularly use here are:

Postman: comes with an easy to use user interface, ability to save requests, and create test scripts.

cURL: The expert's tool and the Swiss army knife of HTTP requests. Command-line tool.

HTTPie: Another command-line tool but more straightforward to use than cURL. It requires Python though. There is no one-click installer, but there are several blog posts with easy step-by-step guides.

You can of course also use your favorite browser - easy to use, but quite limited in terms of HTTP details.


Before you start the next step of this guide, you should head over to the Vidispine API documentation to get an overview of the entities and the Vidispine data model, especially if you’re not familiar with Vidispine and the data model.


Create a shape

When importing a file to Vidispine, you might want to create proxy (low-res) versions of your content. To enable this, you must create a shape to hold the item. The easiest way to start is to use the built-in shape tag settings, see API documentation on Shape Tag. When you launched your Vidispine API instance several presets were created as part of the process. Under the hood a request was made to your API instance:
https://<your-chosen-name>.myvidispine.com/APIinit/preset-templates
 
You can view all your shapes by making a GET request to 
https://<your-chosen-name>.myvidispine.com/API/shape-tag/
 
All details for a shape is given by a GET request to 
https://<your-chosen-name>.myvidispine.com/API/shape-tag/__mp4

where <__mp4> is the shape-tag you want to investigate. All pre-created shape tag names begin with __ and cannot be overwritten. The above call should generate the following answer:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <name>__mp4</name>
    <format>mp4</format>
    <audio>
        <codec>aac</codec>
        <bitrate>128000</bitrate>
        <channel>0</channel>
        <channel>1</channel>
        <stream>2</stream>
    </audio>
    <video>
        <scaling>
            <width>512</width>
        </scaling>
        <codec>h264</codec>
        <bitrate>2000000</bitrate>
        <framerate>
            <numerator>1</numerator>
            <denominator>25</denominator>
        </framerate>
        <preset>high</preset>
    </video>
</TranscodePresetDocument>


If you want to use another transcoder service, e.g., AWS Elemental MediaConvert, you also need to create MediaConvert specific shape tags for that service. For AWS Elemental MediaConvert the API call would be a PUT to:

https://<your-chosen-name>.myvidispine.com/APIinit/preset-mediaconvert-templates


Create a custom metadata field

When building a media repository using Vidispine you need to master how to create metadata fields. Here's an example creating the text field "legal_copyright". Make a PUT request to:

https://<your-chosen-name>.myvidispine.com/API/metadata-field/legal_copyright
 with body 
<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <type>string</type>
</MetadataFieldDocument> 
Note: Custom metadata fields must have the format prefix_name (with the underscore in between). Read more on creating metadata fields, allowed types etc in the metadata example in the API documentation. 

You can view metadata fields in your system by making a GET request to: 
https://<your-chosen-name>.myvidispine.com/API/metadata-field/

 Import a file

Now, let's import a file with one custom metadata field and tell Vidispine to create a proxy version. When importing a file, Vidispine needs to be able to reach the local (or remote) source file (as file:/// or http://). The below example shows importing "NASA1.mov" from the local harddrive setting the system metadata tag "title" to "Nasa1", and setting the custom metadata tag "legal_copyright" to "http://www.nasa.gov". Also, we will add the command tag=__mp4 to the URL to create an mp4-proxy-version of the file. Make a POST to: 
https://<your-chosen-name>.myvidispine.com/API/import?URL=file:///C:/Vidispine/Demovideos/NASA1.mov&tag=__mp4
     (Note the forwardslash in the Windows file path!) 

with body:   
<MetadataDocument
    xmlns=”http://xml.vidispine.com/schema/vidispine”>
    <timespan start=”-INF” end=”+INF”>
        <field>
            <name>title</name>
            <value>Nasa1</value>
        </field>
        <field>
            <name>legal_copyright</name>
            <value>www.nasa.gov</value>
        </field>
    </timespan>
</MetadataDocument> 

 

The above API call triggers a file import. The file import creates one shape for the original file and one shape for the proxy version, as well as a set of thumbnail URL's. The return data from the POST contains the job-id (e.g., VX-20) which you can use to monitor the job and determine the ItemID (in this case VX-6) created for your imported item.


Monitoring jobs

You can monitor what's going on with your import job created in the previous step. 
Make a GET request to:
https://<your-chosen-name>.myvidispine.com//API/job/VX-20

This will return a document with details on all steps performed and their outcome. In this case, the job is finished with success. And we can see that the imported item got the ItemID VX-6: 
<JobDocument
    xmlns="http://xml.vidispine.com/schema/vidispine">
    <jobId>VX-20</jobId>
    <user>admin</user>
    <started>2015-05-28T11:39:23.572Z</started>
    <status>FINISHED</status>
    <type>PLACEHOLDER_IMPORT</type>
    <priority>MEDIUM</priority>
    <currentStep>
        <description>Importing sidecar files.</description>
        <number>16</number>
        <status>FINISHED</status>
    </currentStep>
    <data>
        <key>item</key>
        <value>VX-6</value>
    </data>
    <totalSteps>16</totalSteps>
    <log>
    ...
  </log>
</JobDocument>
   Note: The XML is somewhat shortened

View Item data

When the import job has finished, you can see the complete result by: Make a GET request to 
https://<your-chosen-name>.myvidispine.com//API/item/VX-6?content=metadata,thumbnail,shape
 In the return document there should be two shapes, in this case VX-8 for the low-res and VX-7 for the original. There's also a set of thumbnails. In the metadata section you will find the custom field legal_copyright with the value provided when importing the file. Example (thumbnails section shortened) 
<ItemDocument
    xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-6">
    <metadata><span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>
        <revision>VX-28,VX-27,VX-30,VX-32,VX-34,VX-33</revision>
        <timespan start="-INF" end="+INF">
            <field uuid="24044ded-ee16-477a-990c-159a3ae0d3b3" user="admin" timestamp="2012-03-29T16:24:11.350+02:00" change="VX-27">
                <name>legal_copyright</name>
                <value uuid="ec273429-53b8-4220-a081-79c0447f4dbc" user="admin" timestamp="2012-03-29T16:24:11.350+02:00" change="VX-27">www.nasa.gov</value>
            </field>
        </timespan>
    </metadata>
    <thumbnails>...</thumbnails>
    <shape>
        <id>VX-8</id>
        <essenceVersion>0</essenceVersion>
        <tag>__mp4</tag>
        <mimeType>video/mp4</mimeType>
        <containerComponent>...</containerComponent>
        <audioComponent>...</audioComponent>
        <videoComponent>...</videoComponent>
    </shape>
    <shape>
        <id>VX-7</id>
        <essenceVersion>0</essenceVersion>
        <tag>original</tag>
        <mimeType>video/quicktime</mimeType>
        <containerComponent>...</containerComponent>
        <audioComponent>...</audioComponent>
        <videoComponent>...</videoComponent>
    </shape>
</ItemDocument> 


 Access proxy version over http

Now, let's access the proxy version of our uploaded file. Vidispine supports creating 5-minute temporary URL's for streaming files through the API without authentication. The following command creates unique URLs for all available versions (shapes) of an item: Make a GET to  
https://<your-chosen-name>.myvidispine.com/API/item/VX-6?content=uri&methodType=AUTO

 This will return: 
<ItemDocument
    xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-6">
    <files>
        <uri>http://localhost:8080/APInoauth/storage/VX-1/file/VX-24/0.5103167573574195/VX-24.mp4</uri>
        <uri>http://localhost:8080/APInoauth/storage/VX-1/file/VX-23/0.16017109612757396/VX-23.mov</uri>
    </files>
</ItemDocument> 

The URLs will be valid for 5 minutes. 

So, where do I go from here?

For more details on what you can do with the API, check out our the API documentation, this is the Holy Bible for the API. If you want to dive directly into front-end development, we suggest you take a look at our Vidispine Development Toolkit (VDT), where you can find a framework with pre-built UI components to quickly get you up to speed. A tip here would be to run through the four part mini-tutorial on how to build media applications using the Vidispine Development Toolkit and Vidispine API.


 In the knowledge base of our Support Forum, i.e., this website, you can find a lot of useful tips and tricks, questions and answers, how-to's et cetera, which can guide you even further. You can also sign-up to the Support Forum (this website) to get help directly from our support team.