Event timeline

To test this feature and view the example code, please see the (5.33.x) 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.

Click here to the list of events.

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)
`MANIFEST_DL` `SEGMENT_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`	`url` (of the request, not the stream) `url` `url, error` `url` (of the request, not the stream) `url` `url, error`
`SESSION_MANAGEMENT`	`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`	`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.

JAVA

...
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 available getTimelineList() method variants to retrieve a list of events to analyse. For example:

JAVA

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

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:

JAVA

...
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) 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:

JAVA

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