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.
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
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:
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:
<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.
Import a fileNow, 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!)
<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 jobsYou can monitor what's going on with your import job created in the previous step.
<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 dataWhen 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,shapeIn 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 httpNow, 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
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>
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.