Streaming Start / Resume API

yospaceCDS supports an API to provide control over content delivered via streaming over RTSP/RTP. This API is useful if you want to:

  • Start playing a video at a arbitrary time code
  • Learn when the user stopped playing the video

If you are using yospaceCDS to delivery long-form content to mobile, then you should consider using this API to allow users to come back to a video they have been watching where they left off. This is especially important in mobile as users usually watch smaller segments of content than on-line for a variety of reasons. The API can be used to implement a converged video offering where users can seamlessly watch content on their mobile and on-line, each time continuing from where they left off regardless of how they are accessing the content.

API Overview

The API lets you specify the time code when you want the video to start from, and will tell your application when the stream has stopped, regardless of whether the user pressed stop, pressed the red key, lost coverage, their battery ran out, etc., etc. In order to make full use of the API it will be necessary for you to be able to track your users and store the information of when they stopped playing in your application against the specific user. The API does not mandate how you do this, and it is up to you to choose the method that suits your application.

Understanding Access URLs

Before reading about the Streaming Start / Stop API, we recommend that you first read about the Access URL Syntax.

Usage

Setting a Start Position

Here is an example URL to some content streamed over RTSP/RTP:

rtsp://s.cds1.yospace.com/access/s/100/u/0/1/795566?f=75752683687

Note that this URL contains the optional feed ID (f=75752683687). The use of the feed ID parameter is not significant for Start / Resume, but we recommend that you make use of it so that video accesses are reported correctly against the different feeds that you have set up in your yospaceCDS account.

Using the start parameter you can choose the number of seconds where the video will start playing:

rtsp://s.cds1.yospace.com/access/s/100/u/0/1/795566?f=75752683687&start=30

This example will start the video 30 seconds in, however the user is free to use video transport controls on their handset to seek anywhere in the video, regardless of the initial start point.

Recording the Stop Position

As soon as yospaceCDS has stopped streaming video content to the handset, the Streaming Start / Stop API can be used to send information to a Progress Logger within your application. You must register your progress logger URL with Yospace (by emailing support@yospace.com). In fact, you can register multiple loggers, for example, each environment having its own logger, e.g. development, staging, production. 

Dear Support,


Please register the following Progress Loggers:


http://dev.myapplication.com/app/progress.php
http://staging.myapplication.com/app/progress.php
http://www.myapplication.com/app/progress.php


Regards,
Your Name
Your Company
Your Yospace Account

You will then receive a Progress Logger reference for each of the loggers that you register. You will need to change the Access URL to contain your Progress Logger reference.

Therefore,

rtsp://s.cds1.yospace.com/access/s/100/u/0/1/795566?f=75752683687

becomes...

rtsp://s.cds1.yospace.com/mylogger/s/100/u/0/1/795566?f=75752683687

Where mylogger is the logger ID that you were given by Yospace support.

You will also need to specify a user reference that will be passed to your Progress Logger so that it can identify which user account to associate the stop position, this is achieved with the ref parameter. Hence, the final URL will look something like this (in this example, the feed ID parameter has been ommitted for the purposes of clarity):

rtsp://s.cds1.yospace.com/mylogger/s/100/u/0/1/795566?ref=c302814&start=30

yospaceCDS will append:

  • the parameter ref containing the original ref you passed in,
  • a parameter finish which determines the approximate point at which the user stopped playing, and
  • the parameter length which is the total length of the video.

All timings given are in whole seconds.

Given the example above, assuming that mylogger is registered against http://www.myapplication.com/app/progress.php, when the user stops playing the video, the following URL will be fetched by yospaceCDS: 

http://www.myapplication.com/app/progress.php&ref=c302814&finish=120&length=360

This means that the user stopped playing at approximately 120 seconds into the 360 second video.

What is meant by approximate end point?

Due to handset buffering, which can vary between device and device, yospaceCDS cannot determine exactly when the video stopped playing on the handset. On average the actual value given to you may be up to 10 seconds earlier than when the video was actually stopped.