Using the Video API to Make Trailer Links

The Video API allows you to take an IVA Published ID and create a link to the video asset. These links will return a video and require a paid subscription.

IVA’s Video API

Note: if you are using IVA’s player you do not need to use our Video API.  The player handles video delivery by itself.

Overview

Paid subscribers to IVA’s service use our Video API with our Published ID’s to deliver videos to the player of their choice.  To make a proper request for a video, you will need a customer ID number, a security token, and a published ID.  The customer ID number and security token are provided in your welcome letter.  Published ID’s are available two ways:  If you have your own data, use our OData API to create a query and do your own matching.  If you are using a data provider use one of the matching tables that we provide for our data partners. Once you have created a proper URL, pass it to your player and the link will do an instant 302 redirect to the file on our CDN.

Step One: Pick your base application URL. There are a few application URLs from which to choose. The chart below will show indicates which bases go with which formats. Pick the one that corresponds to the video format you prefer or use the generic player.aspx.

ISM: http://www.videodetective.net/video.ism/Manifest?cmd=6&publishedid=91&customerid=12345&fmt=12&e=13500092&h=298y9386666 MP4: http://www.videodetective.net/video.mp4?cmd=6&publishedid=91&customerid=12345&fmt=4&e=13500092&h=298y9386666 XML: http://www.videodetective.net/video.xml?cmd=3&publishedid=91&customerid=12345&fmt=4&e=13500092&h=298y9386666 DASH: http://www.videodetective.net/video.mpd?cmd=6&publishedid=91&customerid=12345&fmt=14&e=13500092&h=298y9386666 HDS: http://www.videodetective.net/video.f4m?cmd=6&publishedid=91&customerid=12345&fmt=13&e=13500092&h=298y9386666 M3U8: http://www.videodetective.net/video.m3u8?cmd=6&publishedid=91&customerid=12345&fmt=11&e=13500092&h=298y9386666

Step Two: Pick your options.  The chart below lists all the required and optional parameters that you can/must pass to the API to get back the proper video. 

Application Parameters
cmd (required)	Default is cmd=6.  This will validate the link and do a 302 redirect to the content.  Be sure to use the appropriate base application URL for the format you want.  Note: Adaptive technologies require cmd=6. Alternate cmd=3.
fmt (required)	This option tell what format you would like returned. Current options are: MP4 - (fmt=4) Good for all devices and situations. HLS - (fmt=11)  Good for devices and situations that have access to good bandwidth speeds. HSS - (fmt=12) Good for devices and situations that have access to good bandwidth speeds. HDS - (fmt=13) Good for devices and situations that have access to good bandwidth speeds. Dash - (fmt=14) (coming soon) Click here for more information or help choosing a format. Note:  If a device does not support HLS or Flash the IVA player will default back to HTML5 and use the MP4 format.
customerid (required)	ID's are assigned to paid subscription users by their salesman. It is a unique ID used for security and customization purposes. Ex customerid=45678
videokbrate (required for MP4)	This specifies the speed of the file you want to play.  Consult the Encodes Entity to see what speeds and formats are available for each video asset. Available formats and speeds are:  MP4 - 80, 212, 450, 750, 1500, 2500(HD sources only) Kbps  HLS, HSS, HDS, Dash are multi-bitrate formats and do not require VideoKbrate.  You can however, use minrate and maxrate parameters to adjust bitrates.
publishedid (required)	Every video asset in our library is given a unique number known as its Published ID. You can list mulitple Published ID's separated by a comma to make a playlist. Example: http://www.videodetective.net/player.aspx?cmd=6&fmt=4&customerid=45868& videokbrate=2500&publishedid=1756,1757,1758&e=1291562741&h =1e7096ca5689034f5804be881c3c8c2d
e (required)	Time when the URL expires.  This value is calculated in the number of seconds since 01/01/1970. Click here for a time converter.
h (required)	The hash code for the requested URL. You will create this unique number for every video request by using your Secret Token and doing an MD5 hash of the entire link including the 'e' parameter. Check out the Encryption Documentation below.
start (optional)	The start option can be used to tell supported players where to start the video.  This is useful when detecting buffering events and you want to start the video at the point of the event.  For example:  Generate links to a few different videokbrates.  If a buffering event occurs you can tell the player to switch to a lower videokbrate and append the time in seconds to start.  To take advantage of this, make sure your player supports range requests.  You do not need to MD5 hash the start or end options when creating a URL as long as you append it after the hash code in the link.  Format: start=25 where 25 is the number of seconds into the video you would like to start.
end (optional)	The end option works like just like the start option only that it tells the player when to stop playing the video.  Format end=55 where 55 is the number of seconds into the video from the beginning when to stop the video.
minrate (optional)	Used with Adaptive bitrate technologies like HLS, HSS, HDS, and Dash.  This parameter is in bits per second (bps).  To set a minimum bitrate of 1200 Kbps, use minrate=1200000. Currently IVA offer 600Kbps, 1200Kbps, 2000Kbps, and 2500Kbps(HD) when available.
maxrate (optional)	Used with Adaptive bitrate technologies like HLS, HSS, HDS, and Dash.  This parameter is in bits per second (bps).  To set a maximum bitrate of 1200 Kbps, use maxrate=1200000.  Currently IVA offer 600Kbps, 1200Kbps, 2000Kbps, and 2500Kbps(HD) when available.

 

Using Start and End parameters 

Start and End parameters do exactly what they say.  They tell the video when to start and when to end.  A good use case for using this functionality would be if you were detecting buffering events in your player and wanted to have the video start at the time in the video where it buffered.  For example, your player is playing one of our HD 2500 kbps files but the user does not have enough bandwidth and the video starts to buffer.  Tell your player to switch to a smaller file and start at the time in seconds into the file.

 

Example:   File currently playing - http://www.videodetective.net/player.aspx?cmd=6&fmt=4&customerid=12345&videokbrate=2500&publishedid=244133&e=312456677&h=74lkkjsfalksdjf ***Buffering Event at 34 seconds*** Switch to file - http://www.videodetective.net/player.aspx?cmd=6&fmt=4&customerid=12345&videokbrate=2500&publishedid=244133&e=312456677&h=74lkkjsfalksdjf&start=34

 

Example of an HLS Link using the minrate and maxrate:  http://www.videodetective.net/player.aspx?cmd=6&fmt=4&customerid=12345&minrate=1200000&maxrate=2500000&publishedid=244133&e=312456677 &h=74lkkjsfalksdjf

 

Step 3  Apply security settings.  IVA requires customers to secure the links they are making by setting a time to live (TTL) and applying an MD5 hash code to the link to prevent deep linking from unwanted sources.  To make the hash you will need your customer account number and your security token.  Read the steps below for more information on creating this hash code.

Hash Code The hash code (h in the URL) is an MD5 hash appended to the end of the request to the player. Encrypting your security token and URL to the video creates this hash code. 

For example: http://www.videodetective.net/player.aspx?customerId=12345&cmd=6&videokbrate=750&fmt=4&publishedid=1757&e=1171159092&h= 1dc7a1455f4a7f5f7f74fd32093a201f

Customers can check their hash against our Hash Code Generator .

The logic to create a hash is as follows:

dim Md5Hash as string ' the hash code to append to the URL dim URL as string ' the URL containing publishedId, customerId, e, etc... dim RequestUrl as string ' the URL and the hash (a valid URL) dim SharedSecurityToken as string ' the constant shared token between IVA and you. Md5Hash = MD5(lcase(Sharedsecuritytoken & URL)) ' calls a MD5 function to create a hashcode RequestUrl = URL + "&h=" + Hash + "&Stuff not included in the hash if you want."

 

Note: Make sure that you put your security token before the URL.  See the example below:

 

Security Token = 1234 URL = http://www.videodetective.net/player.aspx?customerId=12345&cmd=6&fmt=4&videokbrate=750&publishedid=1757&e=1171159092 Code to Generate Hash = MD5(lcase(1234http://www.videodetective.net/player.aspx?customerId=18088&cmd=6&fmt=4&videokbrate=750&publishedid=1757&e=1171159092)) Hash = c13c876ea56c6124cba712c050a7ae69 Finished URL = http://www.videodetective.net/player.aspx?customerId=12345&cmd=6&fmt=4videokbrate=750&publishedid=1757&e=1171159092&h=c13c876ea

 

 

Below are a number of ways to create an MD5 hash.

ASP: http://mediamanager.internetvideoarchive.com/md5.txt
PHP: http://us3.php.net/md5
ASP.NET: Use the built in function FormsAuthentication.HashPasswordForStoringInConfigFile(StringToEncrypt, "MD5")
ActionScript 2.0: There are various scripts available. We have successfully tested this one .

Important: although MD5 is available in Actionscript 2.0 we recommend not including your security token inside an SWF as SWFs can easily be decompiled allowing other sites to use your IVA account. 

 

EXPIRATION

In order to prevent a valid URL from being "hot linked" for an extended period of time an expiration, or Time To Live (TTL) is required. The expiration for the videodetective.net/player.aspx is measured in the number of seconds from 1/1/1970. Below is a vbscript example of creating a TTL of 3 minutes.  (Server date is based on Greenwich Mean Time, or GMT.)

 

Public Function makettl() TimeoutDate = DateAdd("n", 3, Now) makettl = DateDiff("s", "01/01/1970 00:00:00", TimeoutDate) ' convert to Unix time End Function

 

GMT Offset - the difference between your server's time and GMT Time.  One way to get GMT Offset is to use jScript:  GMT Offset = 0 - new Date().gettimezonetoffset()  // GMT offset in minutes of the server (sign inversed to bring into line with reality)