AAMP UVE – API

On this Page:

Unified Video Engine (UVE) APIs

AAMP is an open source native video engine that is built on top of GStreamer and optimized for performance, memory use, and 
code size. AAMP Reference Player demonstrates how to use the Unified Video Engine (UVE) JavaScript binding APIs to 
interact with an AAMP player. 
The bindings are made available in JavaScript with the help of the injectedbundle component once the DOM elements are 
loaded by WebKit.

This document is targeted towards OTT app vendors and HTML5 developers who are interested in evaluating/adopting AAMP for 
their media player applications on set-tops running RDKV based firmware. 

Features 

• Formats: HLS, DASH, Fragmented MP4 HLS 
• DRM Systems: Clear Key, Adobe Access, Vanilla AES-128, PlayReady, Widevine 
• Captions: CEA-608/708 Captions , WebVTT 

• Video Guard (VGC) DRM 
• DVB, EBU-TT captions

To setup the AAMP Reference Player in RDK devices (Comcast):

1. Host the ReferencePlayer folder in a web server.
2. Use Comcast’s IBIS tool (https://ibis.comcast.com/app-dev-tool/send-html-app) to launch the reference player in the 
   device: 

                   a. Under Launch HTML App, select Select a device to get started. 
                   b. From the list, find your device (it should be registered previously). 
                   c. Enter the ReferencePlayer URL in the URL field. 
                   d. Enter any name in the App name field. 
                   e. Click Launch.

-icons // UI elements of reference players and homepage 
 -UVE 
  -index.html // Homepage of UVE reference player 
  -UVEMediaPlayer.js // Includes “AAMPPlayer” JS class which wraps UVE binding object AAMPMediaPlayer 
  -UVEPlayerUI.js // JS code for the UI elements and their functionality 
  -UVERefPlayer.js // Main JS file 
  -UVERefPlayerStyle.js // JS code for reference player and its UI 
 -index.html // Homepage of reference player 
 -ReferencePlayer.js // JS code for Homepage and redirection to respective reference players 
 -URLs.js // list of selectable streams 
 -ReferencePlayerStyle.css // CSS for Homepage and its UI

Universal Video Engine APIs  

load( uri, autoplay, tuneParams) 

• Begin streaming

play() 

• Supported UVE version 0.7 and above.
• Start playback (if stream is in prebuffered state), or resume playback at normal speed. Equivalent to 
  setPlaybackRate(1).  

pause()

• Supported UVE version 0.7 and above.
• Pauses playback. Equivalent to setPlaybackRate(0). 

stop()

• Supported UVE version 0.7 and above.
• Stop playback and free resources associated with playback.

seek( offset )

• Supported UVE version 0.7 and above.
• Specify initial or new stream playback position. May be called prior to first load() call (or implicitly using 
  initConfig’s “offset” parameter), or while streaming.

getCurrentPosition()

• Supported UVE version 0.7 and above.

• Returns current playback position in seconds.

getCurrentState() 

• Supported UVE version 0.7 and above.
• Returns one of below logical player states as number: 

getDurationSec()

• Supported UVE version 0.7 and above.
• Returns current duration of content in seconds. Duration is fixed for VOD content, but may grow with DVR 
  content. 

getVolume()

• Supported UVE version 0.7 and above.
• Get current volume (value between 0 and 100). Default audio volume is 100. Volume is normally mapped from 
  remote directly to TV, with video engine used to manage an independent mute/unmute state for parental 
  control.

setVolume ( volume )

• Supported UVE version 0.7 and above.
• Sets the current volume (value between 0 and 100). Updated value reflected in subsequent calls to getVolume() 

setVideoMute( enabled )

• Supported UVE version 0.7 and above.
• Enable or black out video for parental control purposes, default is false

getPlaybackRate()

• Supported UVE version 0.7 and above.
• Returns the current playback rate.  

setPlaybackRate( rate )

• Supported UVE version 0.7 and above.
• Change playback rate, supported speeds are given below – 

getVideoBitrates()

• Supported UVE version 0.7 and above.
• Return array of available video bitrates across profiles. 

getCurrentVideoBitrate()

• Supported UVE version 0.7 and above.
• Return current video bitrate, as bits per second.

setVideoBitrate( bitrate )

• Supported UVE version 0.7 and above.

getCurrentAudioBitrate()

• Supported UVE version 0.7 and above.
• Return current audio bitrate, as bits per second. 

setVideoRect( x, y, w, h )

• Supported UVE version 0.7 and above.
• Set display video rectangle coordinates. Note that by default video will be fullscreen.
• Rectangle specified in “graphics resolution” coordinates (coordinate space used by graphics overlay).
• Window size is typically 1280×720, but can be queried at runtime as follows: 
  var w = window.innerWidth || document.documentElement.clientWidth ||document.body.clientWidth; 
  var h = window.innerHeight|| document.documentElement.clientHeight|| document.body.clientHeight;

setVideoZoom( videoZoom )

• Supported UVE version 0.7 and above.
• Set video zoom, by default its set to “full”

addCustomHTTPHeader( headerName, headerValue, isLicenseRequest )

• Supported UVE version 0.8 and above.
• Add custom headers to HTTP requests

removeCustomHTTPHeader( headerName )

• Supported UVE version 0.8 and above.
• Remove a custom header set previously. If called with no arguments, will remove all custom headers. 

getAvailableAudioTracks()

• Supported UVE version 1.0 and above.
• Returns the available audio tracks information in the content.

DASH 

HLS

getVideoRectangle()

• Supported UVE version 1.0 and above.
• Returns the current video rectangle co-ordinates. 

getAudioTrack( )

• Supported UVE version 2.6 and above.
• Returns the index of current audio track in available audio track list.

setAudioTrack(index ) 

• Supported UVE version 2.6 and above.
• Set the audio track language from available audio track list.

setAudioTrack( trackDescriptorObj )

• Supported UVE version 3.2 and above.
• Set the audio track by language and rendition from available audio track list.
• “language” match always takes precedence over “rendition” match.
• While playing passively to new periods with different track order/availability, or when tuning to new locator, 
  heuristic for track selection is automatically re-applied.
• Note that for now, “best” codec (ATMOS > DD+ > Stereo) is always selected, subject to filtering configuration.

setPreferredAudioLanguage( languages, rendition, accessibility)

• Supported UVE version 3.2 and above.
• Set the audio track preference by languages, rendition and accessibility.
• This is functionally equivalent to passing a trackDescriptorObject to setAudioTrack above.
• May be called pre-tune or post tune.

setAudioLanguage ( language )

• Supported UVE version 3.0 and above.
• Set the audio track language from available audio track list.

getTextTrack( ) 

• Supported UVE version 2.6 and above.
• Returns the index of current text track in available text track list.

setTextTrack( trackIndex )

• Supported UVE version 2.6 and above.
• Set the text track at trackIndex in available text track list.

setClosedCaptionStatus ( status )

• Supported UVE version 2.6 and above.
• Set the ClosedCaption rendering to on/off.

getTextStyleOptions ( )

• Supported UVE version 2.6 and above.
• Returns the JSON formatted string of current ClosedCaption style options and values.

setTextStyleOptions ( options ) 

• Supported UVE version 2.6 and above.
• Set the ClosedCaption style options to be used for rendering.

getAvailableThumbnailTracks ( )

•  Returns json array of each thumbnail track’s metadata.

setThumbnailTrack(index)

• Set the desired thumbnail track from the list of available thumbnail track metadata.
• Returns Boolean value true or false to indicate Success or Failure configuring the thumbnail track. 

getThumbnail(startPosition, endPosition) 

•  Get the thumbnail data for the time range “startPosition” till “endPosition”.  

addEventListener( name, handler )

removeEventListener( name, handler )

Supported for DASH Linear, working with period structure and SCTE35 markers, with optional replacement 
for like-amount of content. 

setSubscribedTags( tagNames )

• Supported UVE version 0.8 and above.
• Subscribe to specific tags / metadata in manifest.

setAlternateContent( reservationObject, promiseCallback )

•  Supported UVE version 0.8 and above.  

notifyReservationCompletion( reservationId, time )

• Supported UVE version 0.8 and above.
• Notify video engine when all ad placements for a particular reservation have been set via setAlternateContent.

Can be leveraged for quick stream transitions. Suitable for preroll, and midroll insertions. No limitations 
with respect to content type – can transition between DASH and HLS. 

detach()

• Supported UVE version 0.9 and above.
• Optional API that can be used to quickly stop playback of active stream before transitioning to 2nd prebuffered stream. 

Example use of detach and buffering:

var player = new AAMPMediaPlayer(); 
player.load( “http://test.com/content.m3u8” ); // begin streaming main content 
… 
var adPlayer = new AAMPMediaPlayer(); // create background player 
adPlayer.load( “http://test.com/ad.m3u8”, false ); // preroll 
… 
player.detach(); // stop playback of active player 
adPlayer.play(); // activate background player (fast transition) 
player.stop(); // release remaining resources for initial player instance

Example of midroll Ad insertions and resume main content playback:

initConfig( config )

Configuration options are passed to AAMP using the UVE initConfig method. This allows the application override 
default configuration used by AAMP player to give more control over player behavior. Parameter is a JSON Object with 
one or more attribute/value pairs as follows:  

setDRMConfig( config ) 

DRM configuration options are passed to AAMP using the setDRMConfig method. Parameter is JSON object with pairs of 
protectionScheme: licenseServerUrl pairs, along with preferredKeySystem specifying a preferred protectionScheme.

To use inband closed captions, first register an event listener to discover decoder handle: 

player.addEventListener("decoderAvailable", decoderHandleAvailable);

Along with corresponding event handler to publish the decoder handle to CC subsystem as follows:

function decoderHandleAvailable(event) { 
console.log("decoderHandleAvailable " + event.decoderHandle); 
XREReceiver.onEvent("onDecoderAvailable", { decoderHandle: event.decoderHandle }); 
}

Toggle CC display on or off at runtime:

XREReceiver.onEvent("onClosedCaptions", { enable: true }); 
XREReceiver.onEvent("onClosedCaptions", { enable: false }); 

Set CC track at runtime:

XREReceiver.onEvent("onClosedCaptions", { setTrack: trackID });

Set CC style options at runtime: 

XREReceiver.onEvent("onClosedCaptions", { setOptions: defaultCCOptions}); 

defaultCCOptions is a JSON object of various style options and its values.

When closing stream, detach decoder handle: 

XREReceiver.onEvent("onDecoderAvailable", { decoderHandle: null }); 

Environments without the XREReceiver JS object may exist in future. Applications may use alternate CC rendering methods to 
avoid dependency on XREReceiver object. 

To use, turn on nativeCCRendering init configuration value to true as follows:

player.initConfig( { nativeCCRendering: true } ); 

Toggle CC display on or off at runtime:

player.setClosedCaptionStatus(true); 
player.setClosedCaptionStatus(false); 

Get/Set CC track at runtime:  

player.getTextTrack();
player.setTextTrack(trackIndex);  

Get/Set CC style options at runtime:

player.getTextStyleOptions(); 
player.setTextStyleOptions(options); 

options in a JSON formatted string of style options and its values.

ATSC – Unified Video Engine Features

Support for ATSC-UVE is included from 3.0 version. 
A subset of UVE APIs and Events are available when using UVE JS APIs for ATSC playback.  

API Methods

New Set of APIs added for ATSC Parental Control Settings  

disableContentRestrictions (until)  

• Temporarily disable content restriction based on the control input provided by the ‘until’ parameter.
• Can be used for unlocking a locked channel (Channel locked due to Restrictions set)

enableContentRestrictions ()  

•  To re-enable parental control locks based on restrictions.

Events Supported 

InitConfig