Conviva Xbox One/Windows: MediaPlayer/MediaElement Sensor Integration

Peak Bitrate Reporting for HLS when Using AdaptiveMediaSource

MediaPlayer alone is not enough to gather information on video peak bitrate. If you use the Microsoft AdaptiveMediaSource class to play HLS content, add the following code to enable video peak bitrate reporting:

// Wrap the player with a monitoring proxy
this.playerProxy = new MediaPlayerProxy( this.player );
  
// Link to an AdaptiveMediaSource
this.playerProxy.setMediaStreamSource( adaptiveMediaSource );

// Wrap the player with a monitoring proxy
this.playerProxy = new MediaElementProxy( this.player );
  
// Link to an AdaptiveMediaSource
this.playerProxy.setMediaStreamSource( adaptiveMediaSource );

// Remove link to the old AdaptiveMediaSource
this.playerProxy.removeMediaStreamSource();
// Link to a new AdaptiveMediaSource
this.playerProxy.setMediaStreamSource( newAdaptiveMediaSource );

//set new peak bitrate and send the peak bitrate change event.
WinClient.setBitrate(this.sessionId, this.bitrateInKbps);

Conviva library does not automatically detect the playing average bitrate due to a limitation of the Windows UWP. Conviva's UWP library depends on the application to report the average bitrate. Use the following API to report the video average bitrate:

// Report the Average Bitrate:
// sessionId is Session ID for a given session
// avgBitrateInKbps is the new average bitrate available with application
WinClient.setAverageBitrate(this.sessionId, this.avgBitrateInKbps);

Seek events allow us to calculate the Video Restart Time (VRT) metric, to differentiate between buffering caused by user seek and buffering caused by network conditions. Please visit the seek scenarios page to review VRT calculations.

After a seek is triggered, and once the player has enough chunks downloaded to execute playback, Windows MediaPlayer raises a player seek end event. The player does not report any information on seek start, therefore the Conviva library cannot detect it. Due to this limitation, call Conviva's setSeekStart() API before the user initiates a seek.

The following code sample reports the player seek start event to the Conviva library:

// sessionId : is the Session ID.
// seekToPositon : is new play head position
// that the seek is trying to reach, in milliseconds.
// specify -1 if targeted time is unknown.
 
WinClient.setSeekStart(sessionId, seekToPosition);

Fatal errors are any events preventing the user from seeing the video they attempted to play or any non-user event that causes midstream video playback failure (after the video starts successfully). These fatal errors should be reported and will be used to calculate Video Playback Failures (VPF) and Video Start Failures (VSF) metrics in Conviva VSI.

Sample code for DRM Error reporting

int sessionId = WinClient.createSession( convivaMetadata );
 
// The DRM errors can be reported via:
WinClient.reportError( this.sessionId, "errMessage", WinErrorSeverity.FATAL );
 
// followed by cleaning up the session:
WinClient.cleanupSession( this.sessionId );
 
// If no error occurs, the player instance will be created as usual and should be attached
// to the session with this call:
WinClient.attachPlayer( this.sessionId, this.playerProxy );

The Conviva UWP library depends on the application to report CDN server IP. When the CDN Server IP is available to the application, the same can be reported to Conviva. The CDN Server IP is of type String and is set as attribute of the WinClient class, which provides the following method:

WinClient.setCDNServerIP(SessionID sessionId, String newCDNServerIP);

The following code sample reports CDN Server IP to the Conviva UWP library:

// Report the CDN Server IP:
// sessionId is Session ID for given session
// cdnserverip is the CDN Server IP available with application
WinClient.setCDNServerIP(sessionId, cdnserverip);

The dropped frames count for a specific interval is reported periodically. The Conviva UWP library depends on the application to report the dropped frames count. The dropped frames count is of the type Integer and is set as an attribute of the WinClient class, which provides the following method:

WinClient.setDroppedFrameCount(SessionID sessionId, int droppedFrameCount);

The following code sample reports the dropped frames count to the Conviva UWP library:

// Report the dropped frames count:
// sessionId is Session ID for the given session
// droppedFrameCount is the number of frames dropped by the player since last reported
WinClient.setDroppedFrameCount(sessionId, droppedFrameCount);

The Conviva UWP library depends on the application to report languages. Report the playback audio, closed captions, or subtitles language using:

Winclient.reportLanguage(SessionID sessionId, WinLanguageEventType languageType, String languageName);

The languageType denotes the type of the reporting language and holds one of these values:

• EVENT_AUDIO_LANGUAGE for audio

• EVENT_SUBTITLES_LANGUAGE for subtitles

• EVENT_CLOSED_CAPTIONS_LANGUAGE for closed captions

The languageName is the name of the language in [langCode]:langName format, for example, [en]:English. When only one of them is available, report it as such, for example, en or English.

IMPORTANT: At any given time, a player can report the language of either the subtitles or the closed captions. When it reports one of them, the other language is set to off if it has already been reported. Report these languages (if they're available) on session start as well as when the user changes them on the current playback.

Example:

// sessionId is the Session ID for the given session
// report closed_captions_language as "[en]:English” ([langCode]:langName)
WinClient.reportLanguage(sessionId, EVENT_CLOSED_CAPTIONS_LANGUAGE, "[en]:English");
// report the subtitles_language = "fr" (consider only language code is available)
// reporting the subtitles will set the previously-reported closed_captions_language = "off"
WinClient.reportLanguage(sessionId, EVENT_SUBTITLES_LANGUAGE, "fr");

If the audio, subtitle, or closed captions language option was initially enabled but later disabled, ensure to report the most recent language option value as off. Example:

WinClient.reportLanguage(sessionId, EVENT_SUBTITLES_LANGUAGE, "off");

WinClient.createAdSession( contentInfo, playerProxy ):

• contentInfo: object carries on metadata associated with the ad video playback.

• playerProxy: MediaPlayerProxy proxy object.

The keys / methods and expected values of the required metadata tags are defined in the Implement Metadata section below.

IMPORTANT: WinClient.createAdSession() API returns session ID which shall be stored till session lifecycle and shall be used for session specific API's.

Player Proxy

Media Player object shall be registered with Conviva proxy while creating player proxy object (MediaPlayerProxy / MediaElementProxy). Player proxy object shall be attached to Conviva session to monitor video experience.

public void playVideo() {
  this.player = mediaPlayerElement.MediaPlayer;
 
  // WinContentInfo Metadata Creation Block
  WinContentInfo winAdcontentInfo = new WinContentInfo();
 
  // required: unique value for every asset
  if (assetName != null) {
    winAdcontentInfo.setAssetName(assetName);
  }
     
  // highly recommended: dictionary of your custom metadata key/value string pairs
  foreach (pair in customMetadata) {
      string key = pair.key;
      string value = pair.value;
      if (key != null && value != null) {
          winAdcontentInfo.setTag(key, value);
      }
  }
 
  // Add the winAdcontentInfo as required
  …
 
  // Wrap the player with a monitoring proxy
  this.playerProxy = new MediaPlayerProxy(this.player);
 
  // Create a monitoring session and keep a reference to its ID
  // WinClient.createAdSession() will return an integer 0 or greater
  // this.player is also known as streamer
  this.adSessionId = WinClient.createAdSession(winAdcontentInfo, this.playerProxy );
 
  // Finish player initialization
  this.player.Source = MediaSource.CreateFromUri(new System.Uri(streamURL));
}

Please note that each ad video should be monitored separately - call this method for each new ad video played.

IMPORTANT: If some of the content metadata tags aren't available at start, they can be set later or amended by WinClient.updateContentInfo(adSessionId, winAdcontentInfo); API - refer here for details.

Please note, in most cases that it's required to set content metadata before the player reports "play" for the first time, to accurately attribute metadata to the video asset.

For a Client side Ad, at the start of the ad, the media player instance can be attached with the Conviva Ad session through WinClient.attachPlayer() API. Similarly,at the end of the ad, when the media player instance is removed or changed, attached media player instance can be detached from the Conviva Ad session through WinClient.detachPlayer() API.

The method signatures are:

// Attach the player proxy to the Ad monitoring session
WinClient.attachPlayer(this.adSessionId, this.playerProxy);
 
// Detach the player proxy from Ad monitoring session
WinClient.detachPlayer(this.adSessionId);

Report end of Ad playback by using these methods:

If used, remove the AdaptiveMediaSource object from the player proxy:

// Remove AdaptiveMediaSource
this.playerProxy.removeMediaStreamSource();

Clean up each player proxy once the video stream it is registered to is no longer used. This avoids memory or resource leaks.

// Clean up the player when the video has ended
protected void closePlayer() {
  if ( this.playerProxy >= 0 ) {
          this.playerProxy.cleanupStreamerProxy();
          this.playerProxy = null;
  }
}

Finally, close the monitoring session:

WinClient.cleanupSession( adSessionId );
adSessionId = -1;