1.0 Overview

This document defines the Native Video engine (AAMP) APIs for embedded devices.  


Table of key web links

Web ResourceOwnerDescrption
W3C MSE SpecificationsW3CHTML5 specs for Media Source Extenstions


 

2.0 Architecture

This section provides a high level architecture 



3.0 AAMP Video Engine APIs 

This section defines the properties, methods and events for the AAMP Video Engine

3.1 Core Video Engine Functionality

Class

                       AAMPVideoEngine

Properties

NameData Type

Read or Write

Description

PlayerVersion

Stringr

Version of the player available as a string

MediaType

Numberr

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

Numberr

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

Numberr

Current media play position (milliseconds or seconds?)

MediaInfo

Objectr

Information about the Media being played by the Player

totalDuration – Total duration of the Media

startPostion – Media Start Position

endPosition – Media End Position

currentPlaybackSpeed

Numberr

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

Timeliner

Timeline for tracking dynamic ad insertion (DAI)

Volume

Numberr

Current volume (only mute/unmute is actually used)

drmDrmrinterface to Drm specific properties and methods


Methods

NameReturn ValueArgumentsDescription

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?


3.2  DAI  APIs

Classes


AAMPVideoEngine.TimedMetadata
AAMPVideoEngine.Timeline
AAMPVideoEngine.AdBreak
AAMPVideoEngine.Ad
AAMPVideoEngine.TrickModeRestrictions
AAMPVideoEngine.AdOpportunity


Timeline Properties


NameData Type

Read or Write

Description

adBreaks

AdBreak[ ]r

Array of Ad breaks

adOpportunities

AdOpportunity[]r

Array of Ad opportunities

startNumberrTime (ms) of earliest content
durationNumberrTime (ms) of content + placed ads
positionNumberrTime (ms) of current playback postion
restrictionsTrickModeRestrictionsrTrickmode restrictions on the entire timeline.
timedMetadataTimedMetadata[]rArray of TimedMetadata

Timeline Methods

NameReturn ValueArgumentsDescription

addEventListener

errorcode

eventType – String
listener – Function

Method to add an event listener corresponding to an event type.

removeEventListener

errorcode

eventType – String
listener – Function

Method to remove an event listener corresponding to an event type.

placeAdBreakboolposition – Number
adBreak - Object

Places the specified AdBreak at the specified position in the timeline.
Return true if successful.

subscribeTimedMetadataerrorcodetags - String []

Sets array of HLS tags to monitor while parsing the manifest.
Fire "timedMetadata" event when timedMetadata[] is updated.;

Timeline Events

NamePayloadDescription
timedMetadatatimedMetadata - TimedMetadataFired when new TimedMetadata has been parsed, or modified.
timelineUpdated

seekableRangeChanged - bool
adBreaks - AdBreak[] - array of modified AdBreaks
adOpportunities - AdOpportunity[] - array of inserted AdOpportunities
duration - Number - duration of entire timeline (milliseconds)
start - Number - earliest seekable position in the timeline (milliseconds)

Fired when the timeline is updated.
An update occurs when the timeline start/duration changes, or new AdOpportunity has been inserted, or an AdBreak / Ad has been placed.

adBreakStart

adBreak - AdBreak - the adBreak being started
speed - Number - current playback rate
seenCount - Number - number of times Ad break was played (in full).

Fired when player starts playing an AdBreak.
adBreakComplete

adBreak - AdBreak - the adBreak being finished
progress - Number - percentage of Ads played
ads - Ad[] - array of Ad including played progress of each Ad.

Fired when player finishes playing an AdBreak.
adBreakSkipped

adBreak - AdBreak - the adBreak being skipped or exited
progress - Number - percentage of Ads played

Fired when player skips over an AdBreak.
adStart

ad - Ad - the Ad being started
speed - Number - current playback rate
seenCount - Number - number of times Ad was played (in full).

Fired when player start playing an Ad.
adProgress

ad - Ad - the Ad being played
progress - Number - percentage of Ad played

Reports the player's progress as it plays an Ad.
adComplete

ad - Ad - the Ad that finished begin played
progress - Number - percentage of Ad played

Fired when player finishes playing an Ad.

TimedMetadata Properties

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.

AdBreak Properties

NameData Type

Read or Write

Description
ADBREAK_TYPE_INSERT0static const

Indicates adBreak was inserted.

ADBREAK_TYPE_REPLACED1static const

Indicates adBreak was replaced.

type

NumberrType 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).
Contains the ads that will be played during the ad break.

 

AdBreak Methods

NameReturn ValueArgumentsDescription

placeAds

 boolposition - Number,

ads - Object[]

Place the specified Ad objects in the AdBreak.

Return true if successful.

Ad Properties

NameData 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.

restrictionsTrickModeRestrictionsrTrickmode restrictions applying to the Ad.

seenCount

NumberrNumber of time AdBreak was played (in full).

metadata

Object

r

Additional metadata associated with the ad.

TrickModeRestrictions Properties

NameData Type

Read or Write

Description
TRICKMODE_RESTRICTED_ALWAYS-1static const

Indicates restriciton applies always.

TRICKMODE_RESTRICTED_NEVER0static const

Indicates restriciton does not apply.

pause

Number

r

Specifies if pause is restricted during Ad playback.
Values greater than 0 apply while less than seenCount.

rewind

Number

r

Specifies if rewind is restricted during Ad playback.

fastForward

Number

r

Specified if fastForward / seek is restricted during Ad playback.

AdOpportunity Properties

NameData Type

Read or Write

Description
AD_PLACEMENT_TYPE_PREROLL0static const

Indicates opportunity places ad before the main content.

AD_PLACEMENT_TYPE_MIDROLL1static const

Indicates opportunity places ad in the main content.

AD_PLACEMENT_TYPE_POSTROLL2static constIndicates opportunity places ad after the main content.


AD_PLACEMENT_MODE_INSERT0static const

Indicates restriciton applies always.

AD_PLACEMENT_MODE_REPLACE1static 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.

 3.3  DRM  APIs

These apis are modeled using the open CDMI framework

Classes


AAMPVideoEngine.Drm


DRM Properties

NameData Type

Read or Write

Description

supportedKeySystems

string[]rarray of supported DRM keysystems


DRM Methods

NameReturn Value

Arguments

Description

setPreferredKeySystem

errorcodestringsets the preferred DRM Key system AAMP player will use. Ex: "com.microsoft.playready"
setLicenseServerURLerrorcodestringsets the URL used for license acquisition
setAnonymousRequesterrorcodeboolif true, don't use session token in MDS license request (anonymous mode)
if false, use session token in MDS license request


DRM Events

NamePayloadDescription

drmReady

nonefired when license is acquired and content is ready to play

drmError


code - Number

description - String

fired when license acquisition fails


Appendix: JavaScript Player Generated Events

TODO: call out how VE supports these

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

onClosednonefired when the video stream is closed
onPlayerInitializednonefired when the video player is initialized
onBufferingnonefired when video starts buffering. playback is not possible at this time.
onPlayingnonefired when video starts playing for the first time.
onPausednonefired when video is paused (or speed is set to 0)
onCompletenonefired when video is reaches its end, VOD or cDVR for example.
onIndividualizingnonefired when player is individualizing. Playback is not possible. Not all instances will fire this event.
onAcquiringLicensenone

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.
onSpeedChangespeed - Numberfired when playback speed changes
onDRMMetadataprops - Objectfired 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


onPlaybackSpeedsChangedavailableSpeeds - 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


  • No labels