This is a step-by-step guide for getting started with the Vidispine and the Vidispine .NET SDK. The purpose of this guide is to let you familiarize yourself with the system, and help you programmatically 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. You can download the SDK in the Software Download section (login/signup needed), under respective Vidispine API version.

Before you start

The Vidispine .NET SDK is a powerful building block for developing video applications and services using .NET. However, Vidispine can be controlled by other means as well. For debugging and/or playing around it is good to be able to send REST API requests directly. There are thousands of tools out there, but some that have been proven to work very well are:

Postman: comes with an easy to use user interface, ability to save requests.
cURL: expert's tool and the Swiss army knife of HTTP requests. Command-line tool.
HTTPie: also a command-line tool but easier to use than cURL. Requires python. There is no one-click installer, but there are several blog posts with easy step-by-step guides.
Your favourite browser. Easy to use, but quite limited in terms of HTTP details.

Create a shape

When importing a file to Vidispine you might want to create proxy (lowres) 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 builtin shape tag settings, see shape tag in the API documentation. The example below uses HTTPie to set up the presets. At your command line http://localhost:8080/APIinit/preset-templates. You can view all your shapes by making a GET request to http://localhost:8080/API/shape-tag/, e.g., by using your browser. All details for a shape is given by a GET request to http://localhost:8080/API/shape-tag/original.

Create a custom metadata field

Now we are ready to use the SDK. When building an database with Vidispine you will need to master how to create metadata fields. Here's an example creating the text field "legal_copyright":

var rootResource = new VidispineResource("http://localhost:8080/API/").Authenticate("admin", "admin");
var metadatafieldResource = rootResource.MetadataField;
metadatafieldResource.Name("legal_copyright").PutMetadataField.CallXmlObj(new {
	type = MetadataFieldTypeType.@string
});

The first line simply creates a resource with the Vidispine API endpoint and the credentials. The second line references the metadata field subresource. The third line references a specific metadata field (although not created yet), then selects the PutMetadataField method, which is about to create the metadata field. Finally, the CallXmlObj does the actual call. The REST call takes XML or JSON as input which contains more information about the metadata-field. here we use CallXmlObj, which takes a .NET anonymous object and converts this to XML.

Note: custom metadata fields must have the format prefix_name (with the underscore inbetween). Read more on creating metadata fields, allowed types etc in the API documentation.

You can view metadata fields in your system by making a GET request to http://localhost:8080/API/metadata-field/. This GET request can for example be made using your browser.

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 on your server setting the system metadata tag "title" to "Nasa1", and setting the custom metadata tag "legal_copyright" to "www.nasa.gov". Also, we will add the command tag=__mp4 to the URL to create an mp4-proxy-version of the file.

var importResource = rootResource.Import;
var newJob = importResource.PostImport.Uri("/srv/media/NASA1.mov").Tag("__mp4").CallXmlObj(new {
	Timespan = new {
		Start = "-INF",
		End = "+INF",
		Field = new[] {
			new {
				Name = "title",
				Value = new {
					Value = "my new item"
				}
			},
			new {
				Name = "legal_copyright",
				Value = new {
					Value = "www.nasa.gov"
				}
			}
		}
	}
});

This will now trigger the file to be imported, creating 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:

var jobResource = rootResource.Job;
var jobStatus = jobResource.Id(newJob.jobId).GetJob.Metadata(true).CallXml();

string itemId;
foreach(var jobData in jobStatus.data) {
	Console.WriteLine(jobData.key + "=" + jobData.value);
	if (jobData.key == "itemId") {
		itemId = jobData.value;
	}
}

This will return an object 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.

View Item data

When the import job has finished, you can see the complete result by:

In the return object there should be two shapes, in this case VX-8 for the lowres 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, using XML representation (metadata section shortened)

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 URL's for all available versions (shapes) of an item:

This will return (in XML format):

The URL's will be valid for 5 minutes. This concludes the getting started guide.

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. In the knowledge base of our Support Forum, i.e., this web-site, 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 web-site) to get help directly from our developers.

Customer Knowledge Base

Getting Started With the Vidispine .NET SDK