Event timeline

To test this feature and view the example code, please see the  Android SDK 5 Example Code Quick Start guide.

Performance metrics are provided for measurement of key playback and network actions. At different levels, three classes provide the performance measurement functionality:

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

The list of events is as follows:

Prerequisites

There are no additional requirements beyond the basic playback capabilities.

Process

Start capturing

Enabling and disabling the event timeline captures can take place at any time. As some events occur before the player is instantiated, we advise you to enable captures in the first activity of the app.

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

Fetch event list

Once capturing is enabled, and after some playback, events will have been captured. You can use one of the availablegetTimelineList()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 OTVTimelineAnalyzer

OTVTimelineAnalyzer is a helper class that provides an analysis of common aspects of the captured list in the form of static query methods. It uses the information it retrieves from the OTVEventTimeline class, and you can 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 one until the first frame of stream two is rendered).

Adding events to the list

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

There is one static method that adds an event to the timeline list, OTVEventTimeline.addToTimeline(String xType, String xCommand, String xExtra). For example:

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);