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 the 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 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 analysers based on the same data.

The list of events is as follows:

Event Type

Command

Extra

PLAYBACK

prepared
firstframe
seturl
start
stop
seek_start
seek_complete

none
none
url
none
none
msec (time in ms of the target position)
none

MANIFEST_DL
SEGMENT_DL
network_start
network_complete
network_cancel
network_error
url
url
url
url, error
LICENCE_REQUESTprovision_request_start
provision_request_success
provision_request_failure
key_request_start
key_request_success
key_request_failure
url (of the request, not the stream)
url
url, error
url (of the request, not the stream)
url
url, error
SESSION_MANAGEMENTssm_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
contentToken
contentToken, sessionToken
contentToken, error
contentToken, sessionToken
contentToken, sessionToken
contentToken, sessionToken, error
contentToken, sessionToken
contentToken, sessionToken
contentToken, sessionToken, error

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, NAGRA advises you to enable captures in the first activity of the app.

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

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;
}
}
}
JAVA

Using OTVTimelineAnalyzer

The OTVTimelineAnalyzer helper class provides an analysis of common aspects of the captured list in static query methods. It uses the information it retrieves from the OTVEventTimeline class, and you can implement queries similar to OTVTimelineAnalyzer or 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");
}
JAVA

Other queries provided by this class:

  • getStartupTimeDurations(String xUrl) is 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 fetches 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 for the DRM callback handlers to 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);
JAVA