RDK Resources
[*RDK Preferred*]
Code Management Facility
RDK Forums
[RDK Conferences]
RDK Support
Archives
Papers & Presentations Archive
This document defines the Native Video engine (AAMP) APIs for embedded devices.
Table of key web links
Web Resource | Owner | Descrption |
---|---|---|
W3C MSE Specifications | W3C | HTML5 specs for Media Source Extenstions |
This section provides a high level architecture
This section defines the properties, methods and events for the AAMP Video Engine
AAMPVideoEngine
Name | Data Type | Read or Write | Description |
---|---|---|---|
PlayerVersion | String | r | Version of the player available as a string |
MediaType | Number | r | Type of media enum { LIVE =1, VOD=2, cDVR=3 } Note: may be implied by manifest contents (open/live vs. closed), but in some cases media type (EAS, CDVR) may be knowable only by Player. |
PlayerState | Number | r | Player State Enum. IDLE, // initial state of player INITIALIZING, // drm individualization, etc. INITIALIZED, // TBR? PREPARING, // manifest request in progress - TBR? PREPARED, // have knowledge about stream contents, language availability, etc. BUFFERING, // collecting a/v fragments - not currently presenting; could happen if run dry during playback PAUSED, // player-initiated pause SEEKING, // seek-in-progress - variant of buffering PLAYING, // a/v actively streaming/presenting STOPPING, // reflects async state - needed? STOPPED, // playback stopped at end of asset COMPLETE, // ? ERROR, // fatal video engine state RELEASED |
CurrentPosition | Number | r | Current media play position (milliseconds or seconds?) |
MediaInfo | Object | r | Information about the Media being played by the Player totalDuration – Total duration of the Media startPostion – Media Start Position endPosition – Media End Position |
currentPlaybackSpeed | Number | r | Current speed (play rate); 0 if paused, negative if rewinding |
getSupportedSpeed | Number[ ] | r | Array of supported speeds; [-64, -32, -16, -4, -1, 0, 1, 4, 16, 32, 64]; Needed? An ip video player can present iframe track at arbitrary speeds This set changes during trick mode restrictions; subset may be used during ad. |
timeline | Timeline | r | Timeline for tracking dynamic ad insertion (DAI) |
Volume | Number | r | Current volume (only mute/unmute is actually used) |
drm | Drm | r | interface to Drm specific properties and methods |
Name | Return Value | Arguments | Description |
---|---|---|---|
setURI | errorcode | String | URI of the content |
initParam | errorcode | String | JSON string of key value pair of all the properties to be set. |
play | errorcode | none | starts video playback |
pause | errorcode | none | pauses video playback. Equivalent to speed = 1 |
stop | void | none | stops video playback. Video is not expected to resume. |
seek | errorcode | Msec – Number | Desired Playback position in milliseconds |
seekToLive | errorcode | Void | Seek to live stream |
setSpeed | errorcode | speed - Number overshootCorrection - Number (milliseconds) | sets the speed and adjusts the position of the video by the number of milliseconds specified by overshootCorrection |
setRect | errorcode | OffsetX – number OffsetY – number Width – number Height - number | Method to set the rectangular coordinates for video display |
setAutoPlay | errorcode | autoPlay - Boolean | when true, video starts playing immediately; when false, playback must be manually started. |
setZoom | errorcode | Setting – number | Desired zoom setting enum – { FULL = 0; NONE-1 } |
addEventListener | errorcode | eventName – String listener - Function | Method to add an event listener corresponding to an event TODO: list of event names and semantics |
removeEventListener | errorcode | eventName – String | Method to remove an event listener corresponding to an event |
getAvailableLanguages | Object | None | Returns a collection of available of audio languages as enums currently polled - why? |
setLanguage | errorcode | Language – Number | Desired audio language. Default is Eng. {ENG=0; SPANISH = 1; FRENCH=2; ITALIAN=3; ….. } enum or iso language code? |
setVideoMute | errorcode | Mute – Boolean | True if mute or false otherwise. |
setAudioVolume | errorcode | Volume - Number | Preferred audio volume to set. |
getProperty | Object | Property – String | Returns the property value or a null object if error - TBR? |
setProperty | errorcode | Property – String Value – object | Sets the value for the specified property - TBR? |
AAMPVideoEngine.TimedMetadata
AAMPVideoEngine.Timeline
AAMPVideoEngine.AdBreak
AAMPVideoEngine.Ad
AAMPVideoEngine.TrickModeRestrictions
AAMPVideoEngine.AdOpportunity
Name | Data Type | Read or Write | Description |
---|---|---|---|
adBreaks | AdBreak[ ] | r | Array of Ad breaks |
adOpportunities | AdOpportunity[] | r | Array of Ad opportunities |
start | Number | r | Time (ms) of earliest content |
duration | Number | r | Time (ms) of content + placed ads |
position | Number | r | Time (ms) of current playback postion |
restrictions | TrickModeRestrictions | r | Trickmode restrictions on the entire timeline. |
timedMetadata | TimedMetadata[] | r | Array of TimedMetadata |
Name | Return Value | Arguments | Description |
---|---|---|---|
addEventListener | errorcode | eventType – String | Method to add an event listener corresponding to an event type. |
removeEventListener | errorcode | eventType – String | Method to remove an event listener corresponding to an event type. |
placeAdBreak | bool | position – Number adBreak - Object | Places the specified AdBreak at the specified position in the timeline. |
subscribeTimedMetadata | errorcode | tags - String [] | Sets array of HLS tags to monitor while parsing the manifest. |
Name | Payload | Description |
---|---|---|
timedMetadata | timedMetadata - TimedMetadata | Fired when new TimedMetadata has been parsed, or modified. |
timelineUpdated | seekableRangeChanged - bool | Fired when the timeline is updated. |
adBreakStart | adBreak - AdBreak - the adBreak being started | Fired when player starts playing an AdBreak. |
adBreakComplete | adBreak - AdBreak - the adBreak being finished | Fired when player finishes playing an AdBreak. |
adBreakSkipped | adBreak - AdBreak - the adBreak being skipped or exited | Fired when player skips over an AdBreak. |
adStart | ad - Ad - the Ad being started | Fired when player start playing an Ad. |
adProgress | ad - Ad - the Ad being played | Reports the player's progress as it plays an Ad. |
adComplete | ad - Ad - the Ad that finished begin played | Fired when player finishes playing an Ad. |
Name | Data Type | Read or Write | Description |
METADATA_TYPE_TAG | 0 | static const | Indicates metadata is from the manifest. |
METADATA_TYPE_ID3 | 1 | static const | Indicates metadata was embedded in the content. |
METADATA_TYPE_DASH | 2 | static const | Indicates metadata was generated from DASH MPD. |
type | Number | r | Specified the metadata type: manifest vs. embedded. |
time | Number | r | Time (in milliseconds) of the metadata. |
name | String | r | Name of the metadata. E.g., #EXT-X-CUE, #EXT-X-SCTE35. |
content | String | r | Value of the metadata. |
id | String | r | Unique identifier associated with the metadata. |
metadata | Object | r | Additional name / value pairs obtained from the metadata content string. |
Name | Data Type | Read or Write | Description |
---|---|---|---|
ADBREAK_TYPE_INSERT | 0 | static const | Indicates adBreak was inserted. |
ADBREAK_TYPE_REPLACED | 1 | static const | Indicates adBreak was replaced. |
type | Number | r | Type of adBreak (inserted or replaced). |
id | String | r | Unique identifier associated with the ad break. |
start | Number | r | Starting position (milliseconds) of the ad break in the timeline. |
duration | Number | r | Duration (milliseconds) of the ad break. |
ads | Ad[] | r | Array of Ad objects (sorted by time). |
Name | Return Value | Arguments | Description |
---|---|---|---|
placeAds | bool | position - Number, ads - Object[] | Place the specified Ad objects in the AdBreak. Return true if successful. |
Name | Data Type | Read or Write | Description |
---|---|---|---|
id | String | r | Unique identifier associated with the Ad. |
url | String | r | URL specifying the location of the ad's manifest.. |
duration | Number | r | Duration (milliseconds) of the ad. |
restrictions | TrickModeRestrictions | r | Trickmode restrictions applying to the Ad. |
seenCount | Number | r | Number of time AdBreak was played (in full). |
metadata | Object | r | Additional metadata associated with the ad. |
Name | Data Type | Read or Write | Description |
---|---|---|---|
TRICKMODE_RESTRICTED_ALWAYS | -1 | static const | Indicates restriciton applies always. |
TRICKMODE_RESTRICTED_NEVER | 0 | static const | Indicates restriciton does not apply. |
pause | Number | r | Specifies if pause is restricted during Ad playback. |
rewind | Number | r | Specifies if rewind is restricted during Ad playback. |
fastForward | Number | r | Specified if fastForward / seek is restricted during Ad playback. |
Name | Data Type | Read or Write | Description |
---|---|---|---|
AD_PLACEMENT_TYPE_PREROLL | 0 | static const | Indicates opportunity places ad before the main content. |
AD_PLACEMENT_TYPE_MIDROLL | 1 | static const | Indicates opportunity places ad in the main content. |
AD_PLACEMENT_TYPE_POSTROLL | 2 | static const | Indicates opportunity places ad after the main content. |
AD_PLACEMENT_MODE_INSERT | 0 | static const | Indicates restriciton applies always. |
AD_PLACEMENT_MODE_REPLACE | 1 | static const | Indicates restriciton does not apply. |
id | String | r | Unique identifier associated with the ad opportunity. |
placement | Number | r | Indicates placement type: preroll vs. midroll vs. postroll. |
mode | Number | r | Indicates placement mode: insertion vs. replacement. |
start | Number | r | Starting position (milliseconds) of the ad opportunity. |
duration | Number | r | Duration (milliseconds) of the ad. |
metadata | Object | r | Additional metadata associated with the ad opportunity. |
These apis are modeled using the open CDMI framework
AAMPVideoEngine.Drm
DRM Properties
Name | Data Type | Read or Write | Description |
---|---|---|---|
supportedKeySystems | string[] | r | array of supported DRM keysystems |
DRM Methods
Name | Return Value | Arguments | Description |
---|---|---|---|
setPreferredKeySystem | errorcode | string | sets the preferred DRM Key system AAMP player will use. Ex: "com.microsoft.playready" |
setLicenseServerURL | errorcode | string | sets the URL used for license acquisition |
setAnonymousRequest | errorcode | bool | if true, don't use session token in MDS license request (anonymous mode) if false, use session token in MDS license request |
DRM Events
Name | Payload | Description |
---|---|---|
drmReady | none | fired when license is acquired and content is ready to play |
drmError | code - Number description - String | fired when license acquisition fails |
TODO: call out how VE supports these
Name | Payload | Description |
---|---|---|
onMediaOpened | mediaType - String - has one of the following values: live, recorded width - Number height - Number availableSpeeds - Number availableAudioLanguages - String [ ] availableClosedCaptionsLanguages - String [ ] customProperties - Object mediaSegments - Object | Gathered in JS from VE Fired when video content has been opened (in "PREPARED" state) |
onClosed | none | fired when the video stream is closed |
onPlayerInitialized | none | fired when the video player is initialized |
onBuffering | none | fired when video starts buffering. playback is not possible at this time. |
onPlaying | none | fired when video starts playing for the first time. |
onPaused | none | fired when video is paused (or speed is set to 0) |
onComplete | none | fired when video is reaches its end, VOD or cDVR for example. |
onIndividualizing | none | fired when player is individualizing. Playback is not possible. Not all instances will fire this event. |
onAcquiringLicense | none | fired when player is acquiring a license. Playback is not yet possible. Not all instances will fire this event. Technically not needed, but potentially useful for troubleshooting/profiling |
onProgress | position - Number - current position in milliseconds duration - Number - length of content in milliseconds (recorded video only) speed - Number - current playback speed | fired periodically when player progresses |
onWarning | code - Number description - String | fired when a warning occurs. video playback will likely continue. |
onError | code - Number description - String | fired when an error occurs. video playback will terminate. |
onSpeedChange | speed - Number | fired when playback speed changes |
onDRMMetadata | props - Object | fired when DRM metadata is acquired. Contains DRM related properties. |
onSegmentStarted | segmentType - String duration - Number segmentId - String segment - Object | fired when a new segment is started. |
onSegmentCompleted | segmentType - String duration - Number segmentId - String segment - Object | fired when a segment is has completed |
onSegmentWatched | segmentType - String duration - Number segmentId - String segment - Object | fired when a segment has been started and completed. |
onBufferWarning | warningType - String - one of BUFFER_UNDERFLOW or BUFFER_OVERFLOW bufferSize - Number - total size of buffer bufferFillSize - Number - current filled size of buffer | |
onPlaybackSpeedsChanged | availableSpeeds - String [ ] | fired when playback speeds have changed. This may happen when the video switches from one segment to the next. |
onAdditionalAuthRequired | locator - String eventId - String | fired when video needs additional auth to continue playback |