Getting Started With the VidiCore API (Starter/Team Editions)

The purpose of this guide is to get you familiarized with the VidiCore 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 VidiCore 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, you can find tutorial videos on our youtube channel. Before you go there I suggest you take a look at how you should configure your S3 bucket for VidiCore 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 VidiCore API, either the admin account, or another account created for you. The VidiCore 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 VidiCore API can be accessed through an SDK, e.g., in .NET or Java. However, for this guide we make RESt API requests directly to VidiCore 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 you can find more guides on our knowledge base.

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 VidiCore API documentation to get an overview of the entities and the VidiCore data model, especially if you’re not familiar with VidiCore and the data model.

Create a shape

When importing a file to VidiCore, 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 VidiCore API instance several presets were created as part of the process. Under the hood a request was made to your API instance:

CODE

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

You can view all your shapes by making a GET request to

CODE

https://<your-chosen-name>.myvidispine.com/API/shape-tag/

All details for a shape is given by a GET request to

CODE

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:

CODE

<?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:

CODE

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

Create a custom metadata field

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

CODE

https://<your-chosen-name>.myvidispine.com/API/metadata-field/legal_copyright

with body

CODE

<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:

CODE

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 VidiCore to create a proxy version. When importing a file, VidiCore 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:

CODE

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:

CODE

<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:

CODE

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:

CODE

<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

CODE

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)

CODE

<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. VidiCore 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

CODE

https://<your-chosen-name>.myvidispine.com/API/item/VX-6?content=uri&methodType=AUTO

This will return:

CODE

<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 VidiCore Development Toolkit (VDT), where you can find a framework with pre-built UI components to quickly get you up to speed.

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.