You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »

<Work in progress>

Unified Video Engine (UVE) APIs

This document explains how users can evaluate/adopt AAMP for media player applications. 


Overview


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.


Target Audience

This document is targeted to OTT app vendors and HTML5 developers who are interested in evaluating/adopting AAMP for 
their media player applications on settops 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 

Roadmap

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

Release Version

S.No.Release VersionRelease Notes 
10.7 Initial draft of UVE APIs implemented 
20.8 CDAI support, configuration options for tune optimization 
API: 
  • setAlternateContent 
  • notifyReservationCompletion 
  • addCustomHTTPHeader 


Configuration: 

  • stereoOnly 
  • bulkTimedMetadata 
  • useWesterosSink 
  • parallelPlaylistDownload 


Events: 

  • bufferingChanged 
  • timedMetadata 
  • adResolved 
  • reservationStart 
  • reservationEnd 
  • placementStart 
  • placementEnd 
  • placementProgress 
  • placementError
30.9 “Player Switching” Feature
  • load (autoplay=false support) 
  • detach() method
41.0

Added support to get available audio track and closed captioning info

API: 

  • getAvailableAudioTracks
  •  getAvailableTextTracks 


Configuration: 

  • playlistTimeout
  • parallelPlaylistRefresh
  • useAverageBandwidth
  • preCachePlaylistTime
  • progressReportingInterval
  • useRetuneForUnpairedDiscontinuity
  • drmDecryptFailThreshold 
52.4 

April 2020 Release Update 

Configuration:

  • initialBuffer
  • useMatchingBaseUrl
  • initFragmentRetryCount

Event Notification 

62.6 

June 2020 Release Update 
Seek while paused, get/set audio and text track supported 

API:

  • getAudioTrack
  • setAudioTrack
  • getTextTrack
  • setTextTrack
  • setClosedCaptionStatus
  • setTextStyleOptions
  • getTextStyleOptions 

Configuration:

  • nativeCCRendering
  • langCodePreferenc
  • descriptiveTrackName  
72.7 

Aug 2020 Release Update 

Configuration:

  • Deprecated useWesterosSink 
82.9 

Sept 2020 Release Update 

Configuration:

  • authToken
  • useRetuneForGstInternalError
93

Oct 2020 Release update. 

  • Updated getAvailableAudioTracks / getAvailableTextTracks 

API: 

  • setAudioLanguage 

Configuration: 

  • propagateUriParameters 
    reportVideoPTS

ATSC – UVE Features Added .  

103.1

Jan 2021 Release update. 
ATSC New APIs / Events

API: 

  • getAvailableThumbnailTracks
  • setThumbnailTrack
  • getThumbnail 

Configuration: 

  • sslVerifyPeer
  • persistBitrateOverSeek
  • setLicenseCaching
  • maxPlaylistCacheSize
  • enableSeekableRange  
113.2

Mar 2021 Release update 
API: 

  • setPreferredAudioLanguage
  • setAudioTrack 

Configuration:  

  • livePauseBehavior
  • limitResolution 
123.3

May 2021 Release update 
Configuration:

  • useAbsoluteTimeline asyncTune 

Events : 

  • Updated bitrateChanged for ATSC 
133.4

Events :  

  • audioTracksChanged
  • textTracksChanged
  • seeked
  • vttCueDataListener
  • id3Metadata
143.5

Aug 2021 Release update 
API:

  • load (updated)
  • setPreferredAudioLanguage (updated)
  • getAvailableAudioTracks (updated)
  • getAvailableTextTracks (updated)
  • downloadBuffer default value(updated) 

Events :

 id3Metadata

153.6 

Sept 2021 Release update 

Configuration:

  • disable4K
  • sharedSSL
  • preferredAudioRendition
  • preferredAudioCodec  

Events: 

  • mediaMetadata (updated) 

Minimal Sample Player

<html><head><title>IP Video Playback in WPE browser using UVE API</title></head>
<script>
window.onload = function() { 
var player = new AAMPMediaPlayer(); 
var url = "https://cpetestutility.stb.r53.xcal.tv/multilang/main.m3u8"; 
 player.load(url); 
} 
</script>
<body>
 <div id="videoContainer">
 <video style="height:100%; width:100%; position:absolute; bottom:0; left:0">
 <source src="dummy.mp4" type=”video/ave”> <!-- hole punching -->
 </video>
 </div>
</body>
</html>

General Setup

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.

Folder Structure: Full Reference Player

-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  

PROPERTIES:

NameType Description
version numberMay be used to confirm if RDKV 
build in use supports a newer 
feature 
AAMP.version numberGlobal variable for applications to 
get UVE API version without 
creating a player instance. Value 
will be same as player.version. 

METHODS:  

load( uri, autoplay, tuneParams) 

  • Begin streaming
NameType Description
UriString URI of the Media to be played by the Video Engine
autoplayBooleanoptional 2nd parameter (defaults to true) 
If false, causes stream to be prerolled/prebuffered only, but not immediately 
automatically presented. Available starting with version 0.8. 
tuneParamsObjectoptional 3rd parameter 
The tuneParams Object includes four elements contentType, traceId, 
isInitialAttempt and isFinalAttempt. Details provided in below table 
NameTypeDescription
contentType String Content Type of the asset taken for playback. 
Eg: CDVR, VOD, LINEAR_TV, IVOD, EAS, PPV, OTT, OTA, HDMI_IN, 
COMPOSITE_IN, SLE  
traceIdStringTrace ID which is unique for a tune. 
isInitialAttempt BooleanFlag indicates if it’s the first tune initiated, tune is neither a retry nor a 
rollback. 
isInitialAttempt Boolean Flag indicates if it’s the first tune initiated, tune is neither a retry nor a 
rollback. 

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.
Name Type Description
offset Number (s)Offset from beginning of VOD asset. For live playback, offset is relative to 
eldest portion of initial window. Offset value should be in seconds 
Note that ability to seek is currently limited to fragment granularity.
keepPauseBooleanFlag indicates if player was in paused state before seek then maintain the 
same state post seek 
Available starting with version 2.6 

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: 
State NameValue SemanticsRemarks 
idle0eSTATE_IDLE Player is idle
initializing1eSTATE_INITIALIZINGPlayer is initializaing resources to 
start playback 

2eSTATE_INITIALIZEDPlayer is initializaing resources to 
start playback 

3eSTATE_PREPARINGCreate internal resources required 
for DRM decryption and playback 

4eSTATE_PREPARED Required resources are initialized 
successfully

5eSTATE_BUFFERINGWhen player does internal buffering 
mid-playback. Note -send out in 
initial buffering

6eSTATE_PAUSEDIndicates player is paused 

7eSTATE_SEEKINGIndicates player is seeking

8eSTATE_PLAYINGIndicates player is seeking

9eSTATE_STOPPINGNot supported, for future 

10eSTATE_STOPPEDNot supported, for future 

11eSTATE_COMPLETE When the media reaches end. 

12eSTATE_ERRORIn case any error occurred

13eSTATE_RELEASED Not supported, for future  

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() 
NameNameDescription
volumeNumberPass zero to mute audio. 
Pass 100 for normal (max) audio volume.

setVideoMute( enabled )

  • Supported UVE version 0.7 and above.
  • Enable or black out video for parental control purposes, default is false
NameTypeDescription
volume NumberPass false to black out video. 
Pass true to resume presenting video. 

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 - 
ValueDescription
0Pause
1Normal Play 
42x Fast Forward (using iframe track) 
164x Fast Forward (using iframe track) 
328x Fast Forward (using iframe track) 
6416x Fast Forward (using iframe track)
-42x Rewind (using iframe track)
-164x Rewind (using iframe track)
-324x Rewind (using iframe track)
-6416x Rewind (using iframe track) 

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.
NameType Description
bitrate NumberPass bitrate from getVideoBitrates to disable ABR and lock playback to single 
profile. 
Pass zero to (re)enable ABR, allowing Video Engine to select from available 
bitrates based on network bandwidth.

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 1280x720, 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;
NameType Description
X NumberLeft position for video  
YNumberTop position for video
WNumberVideo width
HNumberVideo height

setVideoZoom( videoZoom )

  • Supported UVE version 0.7 and above.
  • Set video zoom, by default its set to “full”
Name Type Description
videoZoomString“none” to disable video zoom mode. “full” to enable video zoom mode.

addCustomHTTPHeader( headerName, headerValue, isLicenseRequest )

  • Supported UVE version 0.8 and above.
  • Add custom headers to HTTP requests
NameTypeDescription
headerName StringHTTP header name
headerValue isLicenseRequestString Array Boolean

HTTP header value

(defaults to false) indicates if the HTTP header is for exclusive use with PlayReady/Widevine license 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. 
Name TypeDescription
headerName String HTTP header name

getAvailableAudioTracks()

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

DASH 

NameType Description 
name String Human readable language name 
e.g: Spanish, English
languageString Specifies dominant language of the audio
e.g: spa, eng
renditionString Role for DASH 
If not present, the role is assumed to be main 
e.g: caption, subtitle, main
characteristics String Not mapped
Channels String Indicates the maximum number of audio channels 
1 = mono, 2=stereo, up to 8 for DD+
bandwidthString Represents variants of the bitrates available for the media type 
e.g: 288000
codec String codec associated with Adaptation Set.
e.g: mp4a.40.2  
accessibilityTypeString Accessibility value for descriptive, visually impaired signaling 
e.g: description, captions 
Example
Example

{ 
"name": "5", 
"language": "ger", 
"codec": "mp4a.40.2", 
"rendition": "german", 
"accessibiltyType": "description", 
"bandwidth": 288000 
} 
Reference: 
<AdaptationSet id="3" contentType="audio" segmentAlignment="true" bitstreamSwitching="true" lang="ger"> 
<Role schemeIdUri="urn:mpeg:dash:role:2011" value="german"/> 
<Accessibility schemeIdUri="urn:mpeg:dash:role:2011" value="description" /> 
<Representation id="5" mimeType="audio/mp4" codecs="mp4a.40.2" bandwidth="288000" audioSamplingRate="48000"
> 
<AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="1"/> 
</AdaptationSet>

HLS

Name TypeDescription 
nameStringHuman-readable description of the Rendition.
e.g:english, spanish
type StringSpecifies the media type. Valid strings are AUDIO, VIDEO, SUBTITLES 
and CLOSED-CAPTIONS. This attribute is REQUIRED. 
e.g: CLOSED-CAPTIONS 
language StringIdentifies the primary language used in the Rendition. This attribute 
is OPTIONAL. 
e.g: es
rendition StringSpecifies the group to which the Rendition belongs. 
GROUP-ID for HLS.  
instreamId StringSpecifies a Rendition within the segments in the Media Playlist. This 
attribute is REQUIRED if the TYPE attribute is CLOSED-CAPTIONS 
e.g: "CC1", "CC2", "CC3", "CC4", or "SERVICEn" where n MUST be an 
integer between 1 and 63
codecStringComma-delimited list of formats, where each format specifies a media 
sample type that is present in one or more Renditions specified by 
the Variant Stream.
characteristics StringPne or more comma-delimited Uniform Type Identifiers [UTI]. This 
attribute is OPTIONAL.  
Example
Example

 { 
 "name": "Deutsch", 
 "type": "SUBTITLES", 
 "language": "de", 
 "rendition": "subs" 
 } 
Reference 
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUPID="subs",NAME="Deutsch",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="de",URI="subtitles_de.m3u8" 
#EXT-X-STREAM-INF:PROGRAMID=1,BANDWIDTH=258157,CODECS="avc1.4d400d,mp4a.40.2",AUDIO="stereo",RESOLUTION=422x180,SUBTITLES="subs"

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.
NameType Description
indexNumber Track Index of desired audio track in 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.
Name Type Description
languageStringLanguage of desired audio track in available audio track list 
renditionStringRendition of desired audio track in available audio track list
Example
Example

var trackDescriptorObject = 
{ 
"language": "ger", 
"rendition": "commentary" 
} 
playerInstance.setAudioTrack( trackDescriptorObject );

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.
NameType Description
languages String ISO-639 audio language preference; for more than one language, provide comma delimited list from highest to lowest priority: ‘,<...>,’ 
rendition String Optional preferred rendition for automatic audio selection.
accessibilityString Optional preferred accessibility type for descriptive audio. 

setAudioLanguage ( language )

  • Supported UVE version 3.0 and above.
  • Set the audio track language from available audio track list.
NameType Type 
languageString Language of desired audio track in the 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.
Name TypeDescription 
trackIndexNumberIndex of desired text track in available text track list

setClosedCaptionStatus ( status )

  • Supported UVE version 2.6 and above.
  • Set the ClosedCaption rendering to on/off.
Name Type Description
 Status Boolean To turn on/off ClosedCaption rendering.

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.
NameTypeDescription
options String JSON formatted string of different rendering style options and its values.

getAvailableThumbnailTracks ( )

  •  Returns json array of each thumbnail track's metadata.
Name TypeDescription 
Resolution StringString indicating the width x height of the thumbnail images.
Bandwidth StringDecimal-Integer encoding - bits per second. Represents bit rate of the 
thumbnail track.  
Example
Example 

[{ 
 "RESOLUTION": "416x234", 
 "BANDWIDTH": 71416 
 }, { 
 "RESOLUTION": "336x189", 
 "BANDWIDTH": 52375 
 }, { 
 "RESOLUTION": "224x126", 
 "BANDWIDTH": 27413 
 }]

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. 
NameType Description 
IndexNumberIndex value based on the available thumbnail tracks. 

getThumbnail(startPosition, endPosition) 

  •  Get the thumbnail data for the time range “startPosition” till “endPosition”.  
NameType Description
startPositionNumberStart value from which the thumbnail data is fetched. 
endPositionNumberEnd value till which the thumbnail data is fetched. 
baseUrl String The base url which is appended to tile url to fetch the required thumbnail 
image. 
raw_w String Original width of the thumbnail sprite sheet. 
raw_h String Original height of the thumbnail sprite sheet.  
width String Width of each thumbnail tile present in the sprite sheet.
height StringHeight of each thumbnail tile present in the sprite sheet. 
tile StringJSON array of multiple thumbnail tile information.
url StringUrl for each tile, which is appended with base url to form complete url.  
t String Presentation time for each tile. 
d StringDuration value of each tile.  
xStringX co-ordinate position to locate the tile from sprite sheet. 
y String Y co-ordinate position to locate the tile from sprite sheet.


  • No labels

DISCLAIMER: Please note that the use of the RDK Wiki is subject to its Privacy Policy & Terms of Use. In addition, this Wiki may be accessed by all RDK licensees and their contractors.