Performance metrics

This feature enables measurement of key playback and network actions. Three classes at different levels provide the performance measurement functionality:

  • An OTVEvent instance is generated for each key event containing:
    • A timestamp for when the event occurred
    • The type/group the event belongs to
    • The command - a more specific description of the event
    • extra information (if available) in JSON format
  • The OTVEventTimeline singleton object contains the list of all OTVEvent captured, and functionality to retrieve a filtered selection of that list. It also provides methods for enabling/disabling capture of events, and the possibility to discard some, or all, of the accrued data.
  • The OTVTimelineAnalyzer is an optional addition that provides basic analysis of the data retrieved from the OTVEventTimeline instance. You can implement your own analysers based on the same data.

The list of events is as follows:

Event Type Command Extra
PLAYBACK prepared
firstframe
seturl
start
stop
none
none
url
none
none
MANIFEST_DL
SEGMENT_DL
DRM_DL
network_start
network_complete
network_cancel
network_error
url
url
url
url, error
LICENCE_REQUEST provision_request_start
provision_request_success
provision_request_failure
key_request_start
key_request_success
key_request_failure
ssm_setup_start
ssm_setup_success
ssm_setup_failure
ssm_teardown_start
ssm_teardown_success
ssm_teardown_failure
ssm_renewal_startup
ssm_renewal_success
ssm_renewal_failure
url
url
url, error
url
url
url, error
none
none
none
none
none
none
none
none
none

Prerequisites

There are no additional requirements beyond the basic playback capabilities.

Example code

See the event timeline example code provided in the SDK package.

Start capture

Enabling and disabling the event timeline captures can take place at any time; however as some events occur before the player is actually instantiated, it is advised to enable captures in the first activity of the app.

...
OTVSDK.load()
...
OTVEventTimeline.instance().enable(true);

Fetch event list

Once capturing is enabled, after some playback, events will have been captured. You can use one of the available getTimelineList() method variants to retrieve a list of events to analyse; for example:

Date startTime;
String url = "";
List<OTVEvent> events = OTVEventTimeline.instance().getTimelineList(OTVEvent.TYPE_PLAYBACK);
for (OTVEvent event : events) {
  if (event.getCommand().equals(OTVEvent.PLAYBACK_COMMAND_SETURL)) {
    startTime = event.getTimestamp();
    try {
      url = (new JSONObject(event.getExtra()).get(OTVEvent.EXTRA_KEY_URL);
    } catch (JSONException e) {
      ...
    }
  } else if (event.getCommand().equals(OTVEvent.PLAYBACK_COMMAND_FIRSTFRAME)) {
    if (startTime != null) {
      long startUpTime = event.getTimestamp().getTime() - startTime.getTime();
      Log.d(TAG, "Startup time for stream " + url + " was " + startUpTime + " milliseconds");
      break;
    }
  }
}

Using OTVAnalyser

The OTVTimelineAnalyzer helper class provides analysis of common aspects of the captured list in the form of static query methods. It uses information it retrieves from the OTVEventTimeline class, ebabling you to implement queries similar to that of OTVTimelineAnalyzer or other more complex ones.

For example, to retrieve start-up time (in milliseconds) for each stream played (since events capturing was enabled), use the following code:

...
OTVSDK.load()
...
OTVEventTimeline.instance().enable(true);
...
// Play some streams and then...
List<Pair<String,Long>> startupTimes = OTVTimelineAnalyzer.getStartupTimeDurations();
for (Pair<String,Long> streamInfo : startupTimes) {
  Log.d("Info", "Start-up time for stream " + streamInfo.first + " was " + sream.Info.second + " milliseconds");
}

Other queries provided by this class:

  • getStartupTimeDurations(String xUrl) - a list of start-up time long integers (milliseconds) for a given stream's URL (start-up time is defined as the time measured from the moment the path is set until the first frame is rendered).
  • getStreamEventDetails(String xUrl) - for a given stream's URL, fetch all events associated with that stream.
  • getZapDuration(String xUrlFrom, String xUrlTo) returns the measured zapping time for the last zap from one given stream to another (from the moment 'stop' was called on stream 1 until the first frame of stream 2 is rendered).

Adding events to the list

In most cases, the application does not need to add events to the existing timeline list although it is still possible. For example, the DRM key requests are captured by the DRM callback handlers. The default callback classes provided by NAGRA already register the necessary events (see list above), but if you choose to implement your own callback classes, you might want to add your own event.

One static method adds an event to the timeline list, OTVEventTimeline.addToTimeline(String xType, String xCommand, String xExtra):

JSONObject json = new JSONObject();
try {
  json.put(OTVEvent.EXTRA_KEY_URL, url);
} catch (JSONException e) {
  ...
}
OTVEventTimeline.addToTimeline(OTVEvent.TYPE_LICENCE_REQUEST, OTVEvent.KEY_REQUEST_START, json);