Category Archives: API

Using Tin Can API in video: Complete Documentation

Tin Can API is a specification for learning technologies that enables Learning Management Systems to collect data from various learning activities that a student may undertake. Tin Can API has succeeded SCORM (Sharable Content Object Reference Model) as the new standard for learner analytics.

tin can api in video

Requirements for Tin Can API

In Tin Can API any learner activity on the web may be integrated and logged to the LMS. This includes activities such as reading a blog and watching a video online. For Tin Can API to succeed, all learning activities that a learner performs should be able to transmit learning data to the LMS.

Statements in the Tin Can API are rendered in the form Noun Verb Activity. For example if Learner A has completed watching a video on “Machine Learning: Supervised Learning Part 1”, the corresponding Tin Can API statement would be:

  • Learner A completed Machine Learning: Supervised Learning Part 1

Tin Can API with videos

The motive of Tin Can API is to have maximum feedback for user experience and act on to improve the key metrics. As in case with video, fetching in side video data becomes quite tricky owing to the variety and scale of actions performed by viewers on a video.

VdoCipher as a part of its secure video hosting service,  currently provides viewer data points on all the relevant analytics requirement for Tin Can API

Below are some of the prominent actions of viewers on video (start, pause, end, seek, progress, repeat, load, buffer, view) which are a part of Tin Can API and VdoCipher provides direct JavaScript codes for them.

It is interesting to note that there is always a debate amongst content creators and marketers on what should be taken as a view for the video ? Should just clicking on the play button be considered sufficient to be counted as a view ? Some times it is decided to take say 10 seconds of playback or 2 mins of playback as a view. With the information collected by VdoCipher’s start and progress event trackers you can easily collect viewer information for your particular definition of a video view.

Start, End, Pause, Mute, Unmute events on video player

Please check this javascript code to capture the play and pause events from the embedded video player:
<script>		
function onVdoCipherAPIReady(){
    console.log("VdoCipher API init");
    var videoObjects = vdo.getObjects();
    var video_ = videoObjects[videoObjects - 1];
    video_.addEventListener("resume", function(){
        console.log("ready event called" , video_.time);
    });
    video_.addEventListener("pause", function(data){
        // document.getElementById('totalPlayed').value = video_.totalPlayed;
    });
    }
</script>
You can similarly listen for “start”, “end” and “mute”, “unmute”.

Time Calculation per video playback

<div id="vdo<?= $OTP ?>" style="height: 300px; width: 520px;"></div>
<input type="text" id="totalPlayed" value="" />

/// this is the embed code

<script>
    (function(v,i,d,e,o){v[o]={}; v[o].a = v[o].a || function V(a){ (v[o].d=v[o].d||[]).push(a);};
    if(!v[o].l) { v[o].l=1*new Date(); a=i.createElement(d), m=i.getElementsByTagName(d)[0];
    a.async=1; a.src=e; m.parentNode.insertBefore(a,m);}
    })(window,document,'script','//de122v0opjemw.cloudfront.net/vdo.js','vdo');
    vdo.a({
        o: "<?= $OTP ?>",
    });
</script>

/// this is the script

<script>		
function onVdoCipherAPIReady(){
    console.log("VdoCipher API init");
    var videoObjects = vdo.getObjects();
    var video_ = videoObjects[0];
    video_.addEventListener("ready", function(data){
        console.log("ready event called" , data);
    });
    video_.addEventListener("progress", function(data){
        document.getElementById('totalPlayed').value = data.totalPlayed;
    });
    }
</script>
 
Note: The function wrapper with onVdoCipherAPIReady is needed only when it is part of the document load. If this script is to be run after document load, you can run it directly.
Let us know for any custom tracking functionality you require. Most of them are possible with a combination of the above scripts.

Secure Video Streaming API: VdoCipher for Developers

We are happy to release a new set of full-solution streaming APIs for our secure video streaming service. In this blog article, I’ll mention the common business use case which generally developers use with our streaming API. The links to the new set of APIs and sample codes are also given.

  1. Secure Video Embed

    Encrypted Streaming + Backend authentication with an OTP to prevent video download and sharing is the key essential feature we provide as part of our secure video streaming service.

    Please visit Embed API and sample codes in section 9 of this blog to see how to embed secure streaming videos.

  2. Dynamic Watermark configuration

    Dynamic watermarking prevents video piracy via screen capture methods. Viewer specific watermark configuration for type of watermark, movement, color and size can be customized using watermark api.

  3. Upload from various sources

    To help you manage your video content we offer various options for optimal video ingestion and video management. VdoCipher supports video upload from the desktop, server, URL and FTP. The upload api can be found at the updated API page.

  4. Tagging Videos

    Video tags are one of the key elements used for categorising videos. Multiple video management needs multiple tags to better categorise and search. The tagging api can be found here.

  5. Searching Videos

    APIs to enable video search from names and tags can be found here.

  6. Upload from website for your viewers

    Enterprise customers can have their own customers upload videos directly on our site. This can be implemented with APIs using these links.
    Upload from viewer api
    Upload APIs 

  7. Setting Bitrates, Checking video status

    Both of the points 8,9 are available at video apis with vdocipher.

  8. Sample codes for php & asp

The below mentioned blog archives provide a complete list of blogs on api details and also some codes in asp and php.

All API blogs – Contain 14 articles

Some sample php codes (3 articles)

Some sample asp codes (4 articles)

 

Video Streaming Hosting VdoCipher

All these things, VdoCipher handles for you. Launch Today.

Start a free full version 5 GB trial today at VdoCipher

Have a glimpse of the number of your viewers using video download tools for easy piracy. 

An Open Source Contribution by VdoCipher

ASP.net C# web forms embed vdocipher video

The following code is the complete set up for embedding video in ASP.NET Web forms using vdocipher secure streaming. This code has been generated using Visual Studio Community 2015.

For the MVC implementation, please check: https://www.vdocipher.com/blog/2016/02/example-code-for-streaming-protected-video-in-asp-net/

For  vbscript implementation of aspx, check this: https://www.vdocipher.com/blog/2015/01/asp-net-implementation-vdocipher-api/

Vdocipher video in asp.net: aspx and aspx.cs files:

Do not save API Secret in the code

API secret is a key which gives your website authority to generate access tokens (OTPs) for video playback. This secret key can also be used to upload, delete videos in your vdocipher account. Hence, it should not be hard-coded in the application. It should be kept as an app secret. In the above example, it has been added to the web.config file which is not the recommended method. Please read this official article on best practices of saving secret keys in ASP.NET.

Complete code

Download the complete sample application from the Github.

Adding watermark to the videos

Watermark can be added when generating the OTP in the controller file. Please read this article on structuring your watermark and a sample code. The watermark has to be URLencoded and sent as a post data. You shall need to change around line 33 to send annotation information. Let us know if you find any trouble with the watermark setup.

A note about caching

OTP generated here is temporary. You can not cache this OTP and send it to multiple users as it might cause trouble. The OTP once used gets expired and can no longer be used to play video. Some extensions might try to automate the page rendering and especially when on pages which do not need login. The configuration must be set to make sure pages with embedded videos are not cached and cause error while playback.

vdocipher api illustration

For reference about how everything works, please check API reference.

Do let us know about your experiences setting up your secure video in asp.net to create your own PPV or subscription-based video portal. and how we can make the integration simpler.

PHP sample video upload from browser to VdoCipher

[This article is based on API v2 as document here.]

The Upload API workflow and overview can be found here.

Please find below a sample code for enabling video upload from your PHP website’s users. Note that this is sample code and you will need to configure it according to the controller-view structure in your application. It is not a recommended to put Controller logic and HTML output in a single file.

When setting up your front-end, you will like to enable better interface with AJAX upload such that your user’s can have a seamless experience. For this it is recommended to use one of the available libraries(angularjs, jquery or standalone, etc.) . Note that all these can be modified to be used in this set up. You can also see a sample implementation of the angular’s ng-file-upload library in your vdocipher dashboard itself.

Drupal module to embed vdocipher videos

Your videos on vdocipher are protected and can only be played when generating an access token for each video view. This access token needs to be generated securely in your website backend. The Drupal module does this thing in your Drupal website without getting your hands dirty in API programming.  With this module you can add videos inside any text field in content_type in your Drupal website.

The module uses a shortcode like syntax to parse and display videos inside any node such as an article or a page or a custom content type. The markup of the content body is processed and the shortcode syntax is replaced with the player code.

Download here

  1. Download the module file from the link above.
  2. Upload the module file from the install new module page in your Drupal “install new module” page.
  3. Enable the uploaded module.
  4. Click on the configure link in the module page to complete your setup.
  5. Copy your API secret key from vdocipher dashboard > config > general.
  6. Enter the API key in Drupal and save your settings.
  7. Save the configuration.
  8. Copy a video id from your vdocipher dashboard. Edit an existing node in Drupal and add this code in any text field (replace aaaaaaa with id of a video).
    1. [vdo id=aaaaaaa]
  9. Open the article on a page. You should see the video player in your Drupal website.

Q. I am seeing the message: Unauthorized
A. Most probably, you have extra spaces in the API key configuration. Go to the module configuration for vdocipher and make sure the API key is correct.

Q. I am seeing message: Video not found
A. This would probably mean that the video id is not correct. The rich-text editor you are using to add the shortcode might have added extra characters. Content saved in the database is HTML while you are shown rendered HTML in the editor. Click on one of the “view source” option in your editor and try re-pasting the shortcode. Also, make sure there are no spaces before or after the equality sign.

Q. How to set this up for selling video as PPV or subscription?
A. The video can only be viewed by the person who has purchased a membership or a video. You need to set up Drupal permissions such as only those persons can view the assigned content-type which has video.

Q. The height and width are not what I want
A. The height and width are taken from the module configuration and overridden from the shortcode. Did I tell you, you can also add the height and width info like the following. In case the provided width is greater than the available width, the width is set to 100% of available width and height is adjusted to keep the same aspect ratio as provided by the settings.

Q. Why is this not integrated with the media module
A. That what was the idea when we started working on it. But turns out there are certain permission concerns that we need to understand to make sure that using the media module is alright for your video accessibility.

Q. How to manage permission on creating video playable contents
A. The shortcode for video can be added to any node and thus anybody who has the permission to create node(any content type) can add a shortcode to play the video. Note that comment is not a node. We understand this might be a problem for your set-up in a multi-user environment. We plan to solve this problem in the next version with either a custom content type or using the media module to make it easy to control permissions. At the very least, we can add a white-list of content-types which can only have a video embedded in it but it might not work in all cases.

Note on watermark adding.

The watermark can be added to your videos to imprint info about the logged in user or an image for branding. You can configure the watermark from the module configuration page. Check this article for more information on the structure and format required to add watermark text or image in the video. We are going to add a new article on how to configure the watermark in Drupal.

A note about caching

OTP generated here is temporary. You can not cache this OTP and send it to multiple users as it might cause trouble. The OTP once used gets expired and can no longer be used to play video. Some extensions might try to automate the page rendering and especially when on pages which do not need login. The configuration must be set to make sure pages with embedded videos are not cached and cause error while playback.

vdocipher api illustration

For reference about how everything works, please check API reference.

Do let us know about your experiences setting up your secure video in Drupal to create your own PPV or subscription-based video portal. and how we can make the integration simpler.

 

C# sample video upload from browser to VdoCipher

To automate your video website platform, you need video upload directly through your website. Read this for details about this method. The following code gives an example written in C#.

Controller makes API request to vdocipher API to get authorized data about the upload. View file creates the HTML form required for uploading data. Note that the HTML form is only for illustration. You need to hide the extra input fields and perhaps use one of the better javascript libraries (angularjs, jquery or standalone, etc.) for video upload to make user flow better according to rest of your website.

After the video is uploaded, it is not ready instantly. Do not load the player immediately. Use the API to query when video is ready and only then render the video player. The API for querying video status is described in the API reference as videos/ .

Code to embed vdocipher video in ASP.NET MVC with C#

The following code is the complete set up for embedding video in ASP.NET MVC using vdocipher secure streaming. This code has been generated using Visual Studio Community 2015.

new asp.net create dialog for video in asp.net

Vdocipher video in asp.net: controller view and config files

Do not save API Secret in the code

API secret is a key which gives your website authority to generate access tokens (OTPs) for video playback. This secret key can also be used to upload, delete videos in your vdocipher account. Hence, it should not be hard-coded in the application. It should be kept as an app secret. In the above example, it has been added to the web.config file which is not the recommended method. Please read this official article on best practices of saving secret keys in ASP.NET.

Complete code

Download the complete sample application from the Github.

Adding watermark to the videos

Watermark can be added when generating the OTP in the controller file. Please read this article on structuring your watermark and a sample code. The watermark has to be URLencoded and sent as a post data. You shall need to change around line 33 to send annotation information. Let us know if you find any trouble with the watermark setup.

A note about caching

OTP generated here is temporary. You can not cache this OTP and send it to multiple users as it might cause trouble. The OTP once used gets expired and can no longer be used to play video. Some extensions might try to automate the page rendering and especially when on pages which do not need login. The configuration must be set to make sure pages with embedded videos are not cached and cause error while playback.

vdocipher api illustration

For reference about how everything works, please check API reference.

Do let us know about your experiences setting up your secure video in asp.net to create your own PPV or subscription-based video portal. and how we can make the integration simpler.

Load video files from public ftp server

Videos upload from local computer can be a tedious job unless you have a very good upload speed. Often our customers have to upload TBs of content from their public servers. Here we list two methods of load videos directly from your servers to your VdoCipher account.

Option 1: FTP upload

This option requires your server to expose ftp access from public servers.

  • Go to your dashboard and choose import from FTP. Enter the server ip, username and password to login to your server.
  • You shall see a list of files on your home account of ftp server. Navigate to the folders using breadcrumbs.
  • When there will be a video file, you can see an import button. Click on the import button to import the video.

After import, these videos will now be reflected on your dashboard. It shall take some time for the video to get ready. You can also poll the API to know the processing state.

Option 2: HTTP URL

If your server is capable of generating http URL to the video files, you can use the url import feature to add videos to your VdoCipher account.

  • Generate publicly accessible http(s) URLs to the videos. Make sure these videos are accessible for at least next 48 hours.
  • Login to your VdoCipher account and choose import from url.
  • Enter the list of urls with line break as delimiter.
  • Click import button and wait for message box to display the status. These videos shall be added to your account and will take time to process.

If the above methods does not work for your case, let us know in the comments below.

Bandwidth account usage API for video streaming

We provide data on your video usage streaming in terms of the bandwidth used and the total storage billed for the day. These data are deducted from the plan you have purchased. Account usage is updated daily at 5 am UTC everyday. The data granularity is 1 day. So on 3rd Feb 2016 at 5am, usage data for the complete day of 2nd Feb 2016 will be avilable. Currently, we are not collecting hourly data for the usage.

We have added two APIs to allow you to monitor your streaming usage using simple HTTP requests and create business relevant decisions based on these data. These data can also be downloaded from your account page when you log in to your vdocipher account.

Note that high usage or going over your allotted quota of bandwidth or storage does not stop your videos being streamed. We continuously monitor your usage and let you know in advance of any suspiciously high usage in your account.

Daily account usage:

You can obtain usage reports for your account on a daily basis.

Request
URL: https://api.vdocipher.com/v2/usage
Query Param: ?startdate=YYYY-MM-DD&enddate=YYYY-MM-DD
Method: POST
PostData: clientSecretKey=API_SECRET_KEY
Response
Content-Type: application/json
[
{date: 'YYYY-MM-DD' , bandwidth: ''},
{date: 'YYYY-MM-DD' , bandwidth: ''},
....
]

API can only return data of upto 60 days at maximum starting at the start date. startdate and enddate provided are the inclusive boundaries i.e. data will include both these dates.

Video specific usage:

You can also query usage report for one specific video over a range of days.

Request
URL: https://api.vdocipher.com/v2/videousage
Query Param: ?startdate=YYYY-MM-DD&enddate=YYYY-MM-DD&video=xxxxxx
Method: POST
PostData: clientSecretKey=API_SECRET_KEY
Response
Content-type: application/json

[
{date: 'YYYY-MM-DD' , bandwidth: ''},
{date: 'YYYY-MM-DD' , bandwidth: ''},
....
]

API_SECRET_KEY can be obtained from your dashboard config.

Video upload from website or server to vdocipher API

[The following article on video upload is based on vdocipher API v2 which is the latest version]

We use Amazon aws storage to store original user videos securely in AWS S3. With an intent to automate their online business, many of our customers wish to allow their users to upload videos directly from their website. To enable this, we have a API call that returns an authenticated policy document which is used video upload into a S3 bucket allotted to your account.

Step 1 (Obtain authorized access):

Create authorized video upload request with your API secret key.

Request
Endpoint: https://api.vdocipher.com/v2/uploadPolicy
Content type: application/x-www-form-urlencoded
Method: POST
PostData: clientSecretKey=API_SECRET_KEY&title=newTitle
Response
Content-Type: application/json

{
 policy:
 key:
 x-amz-signature: 
 x-amz-algorithm: ,
 x-amz-date:
 x-amz-credential: 
 policy:
 upload_link_secure:
 video_id:
}

The API call has returned a set of parameters that must go with the video upload call to the AWS S3 endpoint. We shall refer to this JSON object returned above as uploadData.

The policy document is valid only for the next 1 hour. It is recommended to make the video upload immediately after creating the authorized access. There is also a soft restriction on the number of upload calls every hour, so it is advised to create it only after the user has chosen to upload the video. It should not be made every time somebody loads their dashboard or mobile app.

This call must be made from a secure environment such as your server. This should not be called from a mobile device or the browser to protect your API key. The uploadData should then be passed to user’s device (mobile or browser) to do the file upload.

Step 2 (Video upload via S3 API):

Upload the file to amazon s3 directly. This upload can be made using server code or using an HTML5 form. You can use any third party upload library to make the upload script. The famous ones already have tutorials on setting it up with S3 upload.

application Request
Endpoint: https://{bucket}.s3.amazonaws.com/
Method: POST
PostData:
 'x-amz-credential': uploadData['x-amz-credential'],
 'x-amz-algorithm': uploadData['x-amz-algorithm'],
 'x-amz-date' : uploadData['x-amz-date'],
 'x-amz-signature': uploadData['x-amz-signature'],
 key : uploadData['key'],
 policy : uploadData['policy'],
 success_action_status : 201,
 success_action_redirect : 'http://example.com'
 file: <file content>
  • upload_link_secure string – The vdocipher storage location that has been allocated for this file
  • key string – A name for the S3 object that will store the uploaded file’s data
  • policy string – authorization string
  • x-amz-signature string – A signature value that authorizes the form and proves that only vdocipher could have created it.
  • x-amz-credential string – These must be accompanied in the upload request.
  • x-amz-algorithm string
  • x-amz-date string
  • success_action_status integer – The status code returned upon successful upload if success_action_redirect is not specified.
  • success_action_redirect string(optional) – Specifies if to redirect to a URL after a successful post instead of issuing a 201.

If everything goes right, the response from the above request should be:

Response
<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>
  <Location>https://vdo-ap-southeast.s3.amazonaws.com/orig%2F5555555555555</Location>
  <Bucket>vdo-ap-southeast</Bucket><Key>orig/5555555555555</Key>
  <ETag>xxxxxxxxxxxxxxxxxx</ETag>
</PostResponse>

You can ignore the content of this response. Now, the video status should be shown as Queued or Processing in the API or on your dashboard. The video will get processed after some time. You can poll the API or configure the web hooks(coming soon) to know the time when video is ready. You should only load the video player if the video is ready.

 

Some sample code for the above operations: