The main player object for Shaka Player.
Constructor
new Player(mediaElementopt, dependencyInjectoropt)
The main player object for Shaka Player.
Parameters:
Name |
Type |
Attributes |
Description |
mediaElement |
HTMLMediaElement
|
<optional>
|
When provided, the player will attach to mediaElement ,
similar to calling attach . When not provided, the player
will remain detached. |
dependencyInjector |
function
|
<optional>
|
Optional callback
which is called to inject mocks into the Player. Used for testing. |
- Implements:
- Source:
Members
EventName :string
An internal enum that contains the string values of all of the player events.
This exists primarily to act as an implicit list of events, for tests.
Type:
Properties:
Name |
Value |
Type |
Description |
AbrStatusChanged |
abrstatuschanged
|
string
|
|
Adaptation |
adaptation
|
string
|
|
Buffering |
buffering
|
string
|
|
DownloadFailed |
downloadfailed
|
string
|
|
DrmSessionUpdate |
drmsessionupdate
|
string
|
|
Emsg |
emsg
|
string
|
|
Error |
error
|
string
|
|
ExpirationUpdated |
expirationupdated
|
string
|
|
LargeGap |
largegap
|
string
|
|
Loaded |
loaded
|
string
|
|
Loading |
loading
|
string
|
|
ManifestParsed |
manifestparsed
|
string
|
|
MediaQualityChanged |
mediaqualitychanged
|
string
|
|
Metadata |
metadata
|
string
|
|
OnStateChange |
onstatechange
|
string
|
|
OnStateIdle |
onstateidle
|
string
|
|
RateChange |
ratechange
|
string
|
|
SessionDataEvent |
sessiondata
|
string
|
|
Streaming |
streaming
|
string
|
|
TextChanged |
textchanged
|
string
|
|
TextTrackVisibility |
texttrackvisibility
|
string
|
|
TimelineRegionAdded |
timelineregionadded
|
string
|
|
TimelineRegionEnter |
timelineregionenter
|
string
|
|
TimelineRegionExit |
timelineregionexit
|
string
|
|
TracksChanged |
trackschanged
|
string
|
|
Unloading |
unloading
|
string
|
|
VariantChanged |
variantchanged
|
string
|
|
- Source:
LoadMode :number
In order to know what method of loading the player used for some content, we
have this enum. It lets us know if content has not been loaded, loaded with
media source, or loaded with src equals.
This enum has a low resolution, because it is only meant to express the
outer limits of the various states that the player is in. For example, when
someone calls a public method on player, it should not matter if they have
initialized drm engine, it should only matter if they finished loading
content.
Type:
Properties:
Name |
Value |
Type |
Description |
DESTROYED |
0
|
number
|
|
NOT_LOADED |
1
|
number
|
|
MEDIA_SOURCE |
2
|
number
|
|
SRC_EQUALS |
3
|
number
|
|
- Source:
restrictedStatuses_ :Array.<string>
These are the EME key statuses that represent restricted playback.
'usable', 'released', 'output-downscaled', 'status-pending' are statuses
of the usable keys. 'expired' status is being handled separately in
DrmEngine.
Type:
- Source:
SRC_EQUAL_EXTENSIONS_TO_MIME_TYPES_ :Object.<string, string>
Type:
- Source:
supportPlugins_ :Object.<string, function(): *>
Type:
-
Object.<string, function(): *>
- Source:
TEXT_EXTENSIONS_TO_MIME_TYPES_ :Object.<string, string>
Type:
- Source:
TextTrackLabel :string
Type:
- Source:
TYPICAL_BUFFERING_THRESHOLD_ :number
The typical buffering threshold. When we have less than this buffered (in
seconds), we enter a buffering state. This specific value is based on manual
testing and evaluation across a variety of platforms.
To make the buffering logic work in all cases, this "typical" threshold will
be overridden if the rebufferingGoal configuration is too low.
Type:
- Source:
version :string
A version number taken from git at compile time.
Type:
- Source:
The factory that was used to create the abrManager_ instance.
Type:
- Source:
assetUri_ :string
Type:
- Source:
For listeners scoped to the lifetime of the media element attachment.
Type:
- Source:
cleanupOnUnload_ :Array.<function(): (!Promise|undefined)>
Type:
-
Array.<function(): (!Promise|undefined)>
- Source:
currentTextForced_ :boolean
Type:
- Source:
currentTextLanguage_ :string
Type:
- Source:
currentTextRole_ :string
Type:
- Source:
For listeners scoped to the lifetime of the Player instance.
Type:
- Source:
isTextVisible_ :boolean
Since we may not always have a text displayer created (e.g. before |load|
is called), we need to track what text visibility SHOULD be so that we
can ensure that when we create the text displayer. When we create our
text displayer, we will use this to show (or not show) text as per the
user's requests.
Type:
- Source:
The TextDisplayerFactory that was last used to make a text displayer.
Stored so that we can tell if a new type of text displayer is desired.
Type:
- Source:
For listeners scoped to the lifetime of the loaded content.
Type:
- Source:
maxHwRes_ :{width: number, height: number}
Type:
-
{width: number, height: number}
- Source:
nextExternalStreamId_ :number
Contains an ID for use with creating streams. The manifest parser should
start with small IDs, so this starts with a large one.
Type:
- Source:
The playhead observers are used to monitor the position of the playhead
and some other source of data (e.g. buffered content), and raise events.
Type:
- Source:
This is our control over the playback rate of the media element. This
provides the missing functionality that we need to provide trick play,
for example a negative playback rate.
Type:
- Source:
updatedStartTime_ :number
This playback start position will be used when
updateStartTime()
has been called to provide an updated
start position during the media loading process.
Type:
- Source:
video_ :HTMLVideoElement
Type:
- Source:
video_ :HTMLVideoElement
Type:
- Source:
videoContainer_ :HTMLElement
Type:
- Source:
Methods
applyPlayRange_(timeline, playRangeStart, playRangeEnd)
Applies playRangeStart and playRangeEnd to the given timeline. This will
only affect non-live content.
Parameters:
- Source:
filterForAVVariants_(manifest)
Take a series of variants and ensure that they only contain one type of
variant. The different options are:
1. Audio-Video
2. Audio-Only
3. Video-Only
A manifest can only contain a single type because once we initialize media
source to expect specific streams, it must always have content for those
streams. If we were to start with audio+video and switch to an audio-only
variant, media source would block waiting for video content.
Parameters:
- Source:
getLanguagesFrom_(tracksnon-null) → {Set.<string>}
Get the normalized languages for a group of tracks.
Parameters:
- Source:
Returns:
-
Type
-
Set.<string>
isBrowserSupported() → {boolean}
Return whether the browser provides basic support. If this returns false,
Shaka Player cannot be used at all. In this case, do not construct a
Player instance and do not use the library.
- Source:
Returns:
-
Type
-
boolean
Probes the browser to determine what features are supported. This makes a
number of requests to EME/MSE/etc which may result in user prompts. This
should only be used for diagnostics.
NOTE: This may show a request to the user for permission.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
promptsOkay |
boolean
|
<optional>
|
true
|
|
- Source:
- See:
-
Returns:
-
Type
-
Promise.<shaka.extern.SupportType>
registerSupportPlugin(name, callback)
Registers a plugin callback that will be called with
support()
. The callback will return the value that will be
stored in the return value from support()
.
Parameters:
Name |
Type |
Description |
name |
string
|
|
callback |
function():*
|
|
- Source:
setAdManagerFactory(factorynon-null)
Set a factory to create an ad manager during player construction time.
This method needs to be called bafore instantiating the Player class.
Parameters:
- Source:
activateChaptersTrack_(tracknullable)
Set the mode on a chapters track so that it loads.
Parameters:
Name |
Type |
Attributes |
Description |
track |
TextTrack
|
<nullable>
|
|
- Source:
addChaptersTrack(uri, language, mimeTypeopt) → {Promise.<shaka.extern.Track>}
Adds the given chapters track to the loaded manifest. load()
must resolve before calling. The presentation must have a duration.
This returns the created track.
Parameters:
Name |
Type |
Attributes |
Description |
uri |
string
|
|
|
language |
string
|
|
|
mimeType |
string
|
<optional>
|
|
- Source:
Returns:
-
Type
-
Promise.<shaka.extern.Track>
addSrcTrackElement_(uri, language, kind, mimeType, label, adCuePointsnon-null) → {Promise.<!HTMLTrackElement>}
Parameters:
Name |
Type |
Description |
uri |
string
|
|
language |
string
|
|
kind |
string
|
|
mimeType |
string
|
|
label |
string
|
|
adCuePoints |
Array.<!shaka.extern.AdCuePoint>
|
|
- Source:
Returns:
-
Type
-
Promise.<!HTMLTrackElement>
addTextStreamToSwitchHistory_(textStream, fromAdaptation)
Parameters:
- Source:
addTextTrack(uri, language, kind, mimeTypeopt, codecopt, labelopt, forcedopt) → {shaka.extern.Track}
Adds the given text track to the loaded manifest. load()
must
resolve before calling. The presentation must have a duration.
This returns the created track, which can immediately be selected by the
application. The track will not be automatically selected.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
uri |
string
|
|
|
|
language |
string
|
|
|
|
kind |
string
|
|
|
|
mimeType |
string
|
<optional>
|
|
|
codec |
string
|
<optional>
|
|
|
label |
string
|
<optional>
|
|
|
forced |
boolean
|
<optional>
|
false
|
|
- Source:
Returns:
-
Type
-
shaka.extern.Track
addTextTrackAsync(uri, language, kind, mimeTypeopt, codecopt, labelopt, forcedopt) → {Promise.<shaka.extern.Track>}
Adds the given text track to the loaded manifest. load()
must
resolve before calling. The presentation must have a duration.
This returns the created track, which can immediately be selected by the
application. The track will not be automatically selected.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
uri |
string
|
|
|
|
language |
string
|
|
|
|
kind |
string
|
|
|
|
mimeType |
string
|
<optional>
|
|
|
codec |
string
|
<optional>
|
|
|
label |
string
|
<optional>
|
|
|
forced |
boolean
|
<optional>
|
false
|
|
- Source:
Returns:
-
Type
-
Promise.<shaka.extern.Track>
addVariantToSwitchHistory_(variant, fromAdaptation)
Parameters:
- Source:
adjustStartTime_(initialVariant, time) → {Promise.<number>}
Parameters:
- Source:
Returns:
-
Type
-
Promise.<number>
applyConfig_()
Apply config changes.
- Source:
attach(mediaElementnon-null, initializeMediaSourceopt) → {Promise}
Tell the player to use
mediaElement
for all
load
requests until
detach
or
destroy
are called.
Calling attach
with initializedMediaSource=true
will tell the player to take the initial load step and initialize media
source.
Calls to attach
will interrupt any in-progress calls to
load
but cannot interrupt calls to attach
,
detach
, or unload
.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
mediaElement |
HTMLMediaElement
|
|
|
|
initializeMediaSource |
boolean
|
<optional>
|
true
|
|
- Source:
Returns:
-
Type
-
Promise
cancelTrickPlay()
Cancel trick-play. If the player has not loaded content or is still loading
content this will be a no-op.
- Source:
checkPlayableVariants_(manifestnon-null)
Confirm some variants are playable. Otherwise, throw an exception.
Parameters:
- Source:
checkRestrictedVariants_(manifest)
Checks if the variants are all restricted, and throw an appropriate
exception if so.
Parameters:
- Source:
Choose a text stream from all possible text streams while taking into
account user preference.
- Source:
Returns:
-
Type
-
shaka.extern.Stream
Chooses a variant from all possible variants while taking into account
restrictions, preferences, and ABR.
On error, this dispatches an error event and returns null.
- Source:
Returns:
-
Type
-
shaka.extern.Variant
chooseVariantAndSwitch_()
Chooses a new Variant. If the new variant differs from the old one, it
adds the new one to the switch history and switches to it.
Called after a config change, a key status event, or an explicit language
change.
- Source:
Changes configuration settings on the Player. This checks the names of
keys and the types of values to avoid coding errors. If there are errors,
this logs them to the console and returns false. Correct fields are still
applied even if there are other errors. You can pass an explicit
undefined
value to restore the default value. This has two
modes of operation:
First, this can be passed a single "plain" object. This object should
follow the shaka.extern.PlayerConfiguration object. Not all fields
need to be set; unset fields retain their old values.
Second, this can be passed two arguments. The first is the name of the key
to set. This should be a '.' separated path to the key. For example,
'streaming.alwaysStreamText'
. The second argument is the
value to set.
Parameters:
Name |
Type |
Attributes |
Description |
config |
string
|
Object
|
|
This should either be a field name or an
object. |
value |
*
|
<optional>
|
In the second mode, this is the value to set. |
- Source:
Returns:
True if the passed config object was valid, false if
there were invalid entries.
-
Type
-
boolean
convertToWebVTT_(buffer, mimeType, adCuePointsnon-null) → {string}
Converts an input string to a WebVTT format string.
Parameters:
- Source:
Returns:
-
Type
-
string
Create an error for when we purposely interrupt a load operation.
- Source:
Returns:
-
Type
-
shaka.util.Error
createCmcd_()
Create a new CMCD manager.
- Source:
Create a new DrmEngine instance. This may be replaced by tests to create
fake instances. Configuration and initialization will be handled after
|createDrmEngine|.
Parameters:
- Source:
Returns:
-
Type
-
shaka.media.DrmEngine
Create a new media source engine. This will ONLY be replaced by tests as a
way to inject fake media source engine instances.
Parameters:
- Source:
Returns:
-
Type
-
shaka.media.MediaSourceEngine
Creates a new instance of NetworkingEngine. This can be replaced by tests
to create fake instances instead.
- Source:
Returns:
-
Type
-
shaka.net.NetworkingEngine
Creates a new instance of Playhead. This can be replaced by tests to
create fake instances instead.
Parameters:
Name |
Type |
Attributes |
Description |
startTime |
number
|
<nullable>
|
|
- Source:
Returns:
-
Type
-
shaka.media.Playhead
Create the observers for MSE playback. These observers are responsible for
notifying the app and player of specific events during MSE playback.
- Source:
Returns:
-
Type
-
shaka.media.PlayheadObserverManager
Creates a new instance of StreamingEngine. This can be replaced by tests
to create fake instances instead.
- Source:
Returns:
-
Type
-
shaka.media.StreamingEngine
defaultStreamingFailureCallback_(errornon-null)
Parameters:
- Source:
delayDispatchEvent_(eventnon-null)
Fire an event, but wait a little bit so that the immediate execution can
complete before the event is handled.
Parameters:
- Source:
destroy() → {Promise}
After destruction, a Player object cannot be used again.
- Implements:
- Source:
Returns:
-
Type
-
Promise
detach() → {Promise}
Tell the player to stop using its current media element. If the player is:
- detached, this will do nothing,
- attached, this will release the media element,
- loading, this will abort loading, unload, and release the media
element,
- playing content, this will stop playback, unload, and release the
media element.
Calls to detach
will interrupt any in-progress calls to
load
but cannot interrupt calls to attach
,
detach
, or unload
.
- Source:
Returns:
-
Type
-
Promise
Construct and fire a Player.Metadata event
Parameters:
Name |
Type |
Attributes |
Description |
startTime |
number
|
|
|
endTime |
number
|
<nullable>
|
|
metadataType |
string
|
|
|
payload |
shaka.extern.ID3Metadata
|
|
|
- Source:
Get the drm info used to initialize EME. If EME is not being used, this
will return null
. If the player is idle or has not initialized
EME yet, this will return null
.
- Source:
Returns:
-
Type
-
shaka.extern.DrmInfo
filterManifest_(manifestnullable)
Filters a manifest, removing unplayable streams/variants.
Parameters:
- Source:
filterManifestByCurrentVariant_()
- Source:
filterManifestWithRestrictions_(manifestnullable)
Apply the restrictions configuration to the manifest, and check if there's
a variant that meets the restrictions.
Parameters:
- Source:
filterManifestWithStreamUtils_(manifestnullable)
Filters a manifest, removing unplayable streams/variants.
Parameters:
- Source:
Returns a shaka.ads.AdManager instance, responsible for Dynamic
Ad Insertion functionality.
- Source:
Returns:
-
Type
-
shaka.extern.IAdManager
getAssetUri() → {string}
Get the uri to the asset that the player has loaded. If the player has not
loaded content, this will return null
.
- Source:
Returns:
-
Type
-
string
getAudioLanguages() → {Array.<string>}
Return a list of audio languages available. If the player has not loaded
any content, this will return an empty list.
- Source:
Returns:
-
Type
-
Array.<string>
Return a list of audio language-role combinations available. If the
player has not loaded any content, this will return an empty list.
- Source:
Returns:
-
Type
-
Array.<shaka.extern.LanguageRole>
Get information about what the player has buffered. If the player has not
loaded content or is currently loading content, the buffered content will
be empty.
- Source:
Returns:
-
Type
-
shaka.extern.BufferedInfo
getBufferFullness() → {number}
Returns the ratio of video length buffered compared to buffering Goal
- Source:
Returns:
-
Type
-
number
This returns the list of chapters.
Parameters:
Name |
Type |
Description |
language |
string
|
|
- Source:
Returns:
-
Type
-
Array.<shaka.extern.Chapter>
getChaptersTracks_() → {Array.<TextTrack>}
Get the TextTracks with the 'chapters' kind.
- Source:
Returns:
-
Type
-
Array.<TextTrack>
Return a copy of the current configuration. Modifications of the returned
value will not affect the Player's active configuration. You must call
player.configure()
to make changes.
- Source:
Returns:
-
Type
-
shaka.extern.PlayerConfiguration
Get the drm engine.
This method should only be used for testing. Applications SHOULD NOT
use this in production.
- Source:
Returns:
-
Type
-
shaka.media.DrmEngine
getExpiration() → {number}
Get the next known expiration time for any EME session. If the session
never expires, this will return Infinity
. If there are no EME
sessions, this will return Infinity
. If the player has not
loaded content, this will return Infinity
.
- Source:
Returns:
-
Type
-
number
getFilteredTextTracks_() → {Array.<TextTrack>}
Ignore the TextTracks with the 'metadata' or 'chapters' kind, or the one
generated by the SimpleTextDisplayer.
- Source:
Returns:
-
Type
-
Array.<TextTrack>
Return a list of image tracks that can be switched to.
If the player has not loaded content, this will return an empty list.
- Source:
Returns:
-
Type
-
Array.<shaka.extern.Track>
getKeyStatuses() → {Object.<string, string>}
Gets a map of EME key ID to the current key status.
- Source:
Returns:
-
Type
-
Object.<string, string>
Get the manifest that the player has loaded. If the player has not loaded
any content, this will return null
.
NOTE: This structure is NOT covered by semantic versioning compatibility
guarantees. It may change at any time!
This is marked as deprecated to warn Closure Compiler users at compile-time
to avoid using this method.
- Deprecated:
- Source:
Returns:
-
Type
-
shaka.extern.Manifest
Get the type of manifest parser that the player is using. If the player has
not loaded any content, this will return null
.
- Source:
Returns:
-
Type
-
shaka.extern.ManifestParser.Factory
Get the media element that the player is currently using to play loaded
content. If the player has not loaded content, this will return
null
.
- Source:
Returns:
-
Type
-
HTMLMediaElement
Get the TextTracks with the 'metadata' kind.
- Source:
Returns:
-
Type
-
Array.<TextTrack>
- Source:
Returns:
A reference to the Player's networking
engine. Applications may use this to make requests through Shaka's
networking plugins.
-
Type
-
shaka.net.NetworkingEngine
getNextAfterUnload_(goingTonon-null, has, wants) → {shaka.routing.Node}
After unload there are only two options, attached or detached. This choice
is based on whether or not we have a media element. If we have a media
element, then we go to attach. If we don't have a media element, we go to
detach.
Parameters:
- Source:
Returns:
-
Type
-
shaka.routing.Node
getNextMatchingAllDependencies_(destinationNodenon-null, nextNodenon-null, resetNodenon-null, goingTonon-null, has, wants) → {shaka.routing.Node}
A general method used to handle routing when we can either than one step
toward our destination (while all our dependencies match) or go to a node
that will reset us so we can try again.
Parameters:
Name |
Type |
Description |
destinationNode |
shaka.routing.Node
|
What |goingTo| must be for us to step toward |nextNode|. Otherwise we
will go to |resetNode|. |
nextNode |
shaka.routing.Node
|
The node we will go to next if |goingTo == destinationNode| and all
dependencies match. |
resetNode |
shaka.routing.Node
|
The node we will go to next if |goingTo != destinationNode| or any
dependency does not match. |
goingTo |
shaka.routing.Node
|
The node that the walker is trying to go to. |
has |
shaka.routing.Payload
|
The payload that the walker currently has. |
wants |
shaka.routing.Payload
|
The payload that the walker wants to have when iy gets to |goingTo|. |
- Source:
Returns:
-
Type
-
shaka.routing.Node
getNextStep_(currentlyAtnon-null, currentlyWith, wantsToBeAtnon-null, wantsToHave) → {shaka.routing.Node}
Key
----------------------
D : Detach Node
A : Attach Node
MS : Media Source Node
P : Manifest Parser Node
M : Manifest Node
DRM : Drm Engine Node
L : Load Node
U : Unloading Node
SRC : Src Equals Node
Graph Topology
----------------------
[SRC]-----+
^ |
| v
[D]<-->[A]<-----[U]
| ^
v |
[MS]------+
| |
v |
[P]-------+
| |
v |
[M]-------+
| |
v |
[DRM]-----+
| |
v |
[L]-------+
Parameters:
- Source:
Returns:
-
Type
-
shaka.routing.Node
getPlaybackRate() → {number}
Get the playback rate of what is playing right now. If we are using trick
play, this will return the trick play rate.
If no content is playing, this will return 0.
If content is buffering, this will return the expected playback rate once
the video starts playing.
If the player has not loaded content, this will return a playback rate of
0.
- Source:
Returns:
-
Type
-
number
getPlayheadTimeAsDate() → {Date}
Get the current playhead position as a date. This should only be called
when the player has loaded a live stream. If the player has not loaded a
live stream, this will return null
.
- Source:
Returns:
-
Type
-
Date
getPresentationStartTimeAsDate() → {Date}
Get the presentation start time as a date. This should only be called when
the player has loaded a live stream. If the player has not loaded a live
stream, this will return null
.
- Source:
Returns:
-
Type
-
Date
Return a reference to the current configuration. Modifications to the
returned value will affect the Player's active configuration. This method
is not exported as sharing configuration with external objects is not
supported.
- Source:
Returns:
-
Type
-
shaka.extern.PlayerConfiguration
Get statistics for the current playback session. If the player is not
playing content, this will return an empty stats object.
- Source:
Returns:
-
Type
-
shaka.extern.Stats
getTextData_(uri, netEnginenon-null, retryParams) → {Promise.<BufferSource>}
Parameters:
- Source:
Returns:
-
Type
-
Promise.<BufferSource>
getTextLanguages() → {Array.<string>}
Return a list of text languages available. If the player has not loaded
any content, this will return an empty list.
- Source:
Returns:
-
Type
-
Array.<string>
Return a list of text language-role combinations available. If the player
has not loaded any content, this will be return an empty list.
- Source:
Returns:
-
Type
-
Array.<shaka.extern.LanguageRole>
getTextMimetype_(uri) → {Promise.<string>}
Parameters:
Name |
Type |
Description |
uri |
string
|
|
- Source:
Returns:
-
Type
-
Promise.<string>
Return a list of text tracks that can be switched to.
If the player has not loaded content, this will return an empty list.
- Source:
Returns:
-
Type
-
Array.<shaka.extern.Track>
Return a Thumbnail object from a image track Id and time.
If the player has not loaded content, this will return a null.
Parameters:
Name |
Type |
Description |
trackId |
number
|
|
time |
number
|
|
- Source:
Returns:
-
Type
-
Promise.<?shaka.extern.Thumbnail>
Return a list of variant tracks that can be switched to.
If the player has not loaded content, this will return an empty list.
- Source:
Returns:
-
Type
-
Array.<shaka.extern.Track>
goToLive()
Go to live in a live stream.
- Source:
isAudioOnly() → {boolean}
Check if the manifest contains only audio-only content. If the player has
not loaded content, this will return
false
.
The player does not support content that contain more than one type of
variants (i.e. mixing audio-only, video-only, audio-video). Content will be
filtered to only contain one type of variant.
- Source:
Returns:
-
Type
-
boolean
isAutoLowLatencyMode_() → {boolean}
Return the value of autoLowLatencyMode configuration.
- Source:
Returns:
-
Type
-
boolean
isBufferedToEndMS_() → {boolean}
Assuming the player is playing content with media source, check if the
player has buffered enough content to make it to the end of the
presentation.
- Source:
Returns:
-
Type
-
boolean
isBufferedToEndSrc_() → {boolean}
Assuming the player is playing content with src=, check if the player has
buffered enough content to make it to the end of the presentation.
- Source:
Returns:
-
Type
-
boolean
isBuffering() → {boolean}
Check if the player is currently in a buffering state (has too little
content to play smoothly). If the player has not loaded content, this will
return false
.
- Source:
Returns:
-
Type
-
boolean
isInProgress() → {boolean}
Get if the player is playing in-progress content. If the player has not
loaded content, this will return false
.
- Source:
Returns:
-
Type
-
boolean
isLive() → {boolean}
Get if the player is playing live content. If the player has not loaded
content, this will return false
.
- Source:
Returns:
-
Type
-
boolean
isLowLatencyMode_() → {boolean}
Return the value of lowLatencyMode configuration.
- Source:
Returns:
-
Type
-
boolean
isTextTrackVisible() → {boolean}
Check if the text displayer is enabled.
- Source:
Returns:
-
Type
-
boolean
keySystem() → {string}
Get the key system currently used by EME. If EME is not being used, this
will return an empty string. If the player has not loaded content, this
will return an empty string.
- Source:
Returns:
-
Type
-
string
load(assetUri, startTimeopt, nullable, mimeTypeopt) → {Promise}
Tell the player to load the content at
assetUri
and start
playback at
startTime
. Before calling
load
,
a call to
attach
must have succeeded.
Calls to load
will interrupt any in-progress calls to
load
but cannot interrupt calls to attach
,
detach
, or unload
.
Parameters:
Name |
Type |
Attributes |
Description |
assetUri |
string
|
|
|
startTime |
number
|
<optional>
<nullable>
|
When startTime is null or
undefined , playback will start at the default start time (0
for VOD and liveEdge for LIVE). |
mimeType |
string
|
<optional>
|
|
- Source:
Returns:
-
Type
-
Promise
makeTextStreamsForClosedCaptions_(manifestnon-null)
For CEA closed captions embedded in the video streams, create dummy text
stream. This can be safely called again on existing manifests, for
manifest updates.
Parameters:
- Source:
onAbrStatusChanged_()
- Source:
onAdaptation_(fromnullable, to)
Dispatches an 'adaptation' event.
Parameters:
- Source:
onAttach_(has, wants) → {Promise}
This should only be called by the load graph when it is time to attach to
a media element. The only times this may be called are when we are being
asked to re-attach to the current media element, or attach to a new media
element while not attached to a media element.
This method assumes that it is safe for it to execute, the load-graph is
responsible for ensuring all assumptions are true.
Attaching to a media element is defined as:
- Registering error listeners to the media element.
- Caching the video element for use outside of the load graph.
Parameters:
- Source:
Returns:
-
Type
-
Promise
onDetach_(has, wants) → {Promise}
This should only be called by the load graph when it is time to detach from
a media element. The only times this may be called are when we are being
asked to detach from the current media element, or detach when we are
already detached.
This method assumes that it is safe for it to execute, the load-graph is
responsible for ensuring all assumptions are true.
Detaching from a media element is defined as:
- Removing error listeners from the media element.
- Dropping the cached reference to the video element.
Parameters:
- Source:
Returns:
-
Type
-
Promise
onError_(errornon-null)
Parameters:
- Source:
onExpirationUpdated_(keyId, expiration)
Callback from DrmEngine
Parameters:
Name |
Type |
Description |
keyId |
string
|
|
expiration |
number
|
|
- Source:
onInitializeDrm_(has, wants) → {Promise}
This should only be called by the load graph when it is time to initialize
drmEngine. The only time this may be called is when we are attached a
media element and have parsed a manifest.
The load-graph is responsible for ensuring all assumptions made by this
method are valid before executing it.
Parameters:
- Source:
Returns:
-
Type
-
Promise
This should only be called by the load graph when it is time to initialize
media source engine. The only time this may be called is when we are
attached to the same media element as in the request.
This method assumes that it is safe for it to execute. The load-graph is
responsible for ensuring all assumptions are true.
Parameters:
- Source:
Returns:
-
Type
-
Promise
onInitializeParser_(has, wants) → {Promise}
Create the parser for the asset located at |wants.uri|. This should only be
called as part of the load graph.
This method assumes that it is safe for it to execute, the load-graph is
responsible for ensuring all assumptions are true.
Parameters:
- Source:
Returns:
-
Type
-
Promise
onInitializeSrcEqualsDrm_(has, wants) → {Promise}
This should only be called by the load graph when it is time to initialize
drmEngine for src= playbacks.
The load-graph is responsible for ensuring all assumptions made by this
method are valid before executing it.
Parameters:
- Source:
Returns:
-
Type
-
Promise
onKeyStatus_(keyStatusMapnon-null)
Parameters:
Name |
Type |
Description |
keyStatusMap |
Object.<string, string>
|
A map of hex key IDs to
statuses. |
- Source:
onLoad_(has, wants)
This should only be called by the load graph when it is time to load all
playback components needed for playback. The only times this may be called
is when we are attached to the same media element as in the request.
This method assumes that it is safe for it to execute, the load-graph is
responsible for ensuring all assumptions are true.
Loading is defined as:
- Attaching all playback-related listeners to the media element
- Initializing playback and observers
- Initializing ABR Manager
- Initializing Streaming Engine
- Starting playback at |wants.startTime|
Parameters:
- Source:
onManifestUpdate_()
Callback from StreamingEngine.
- Source:
When notified of a media quality change we need to emit a
MediaQualityChange event to the app.
Parameters:
- Source:
Parse the manifest at |has.uri| using the parser that should have already
been created. This should only be called as part of the load graph.
This method assumes that it is safe for it to execute, the load-graph is
responsible for ensuring all assumptions are true.
Parameters:
- Source:
Returns:
-
Type
-
shaka.util.AbortableOperation
onRateChange_()
A callback for when the playback rate changes. We need to watch the
playback rate so that if the playback rate on the media element changes
(that was not caused by our play rate controller) we can notify the
controller so that it can stay in-sync with the change.
- Source:
onRegionEvent_(eventNamenon-null, region)
When we fire region events, we need to copy the information out of the
region to break the connection with the player's internal data. We do the
copy here because this is the transition point between the player and the
app.
Parameters:
- Source:
onSeek_()
Callback from Playhead.
- Source:
onSegmentAppended_()
Callback from StreamingEngine.
- Source:
This should only be called by the load graph when it is time to set-up the
media element to play content using src=. The only times this may be called
is when we are attached to the same media element as in the request.
This method assumes that it is safe for it to execute, the load-graph is
responsible for ensuring all assumptions are true.
Parameters:
- Source:
Returns:
-
Type
-
shaka.util.AbortableOperation
onTextChanged_()
Dispatches a 'textchanged' event.
- Source:
onTextTrackVisibility_()
- Source:
onTracksChanged_()
Dispatches a 'trackschanged' event.
- Source:
onUnload_(has, wants) → {Promise}
This should only be called by the load graph when it is time to unload all
currently initialized playback components. Unlike the other load actions,
this action is built to be more general. We need to do this because we
don't know what state the player will be in before unloading (including
after an error occurred in the middle of a transition).
This method assumes that any component could be |null| and should be safe
to call from any point in the load graph.
Parameters:
- Source:
Returns:
-
Type
-
Promise
onVariantChanged_(fromnullable, to)
Dispatches a 'variantchanged' event.
Parameters:
- Source:
onVideoError_(eventnon-null)
Parameters:
Name |
Type |
Description |
event |
Event
|
|
- Source:
pollBufferState_()
This method is called periodically to check what the buffering observer
says so that we can update the rest of the buffering behaviours.
- Source:
Parameters:
Name |
Type |
Attributes |
Description |
metadata |
Array.<shaka.extern.ID3Metadata>
|
|
|
offset |
number
|
|
|
segmentEndTime |
number
|
<nullable>
|
|
- Source:
We're looking for metadata tracks to process id3 tags. One of the uses is
for ad info on LIVE streams
Parameters:
Name |
Type |
Description |
track |
TextTrack
|
|
- Source:
resetConfiguration()
Reset configuration to default.
- Source:
retryStreaming() → {boolean}
Retry streaming after a streaming failure has occurred. When the player has
not loaded content or is loading content, this will be a no-op and will
return
false
.
If the player has loaded content, and streaming has not seen an error, this
will return false
.
If the player has loaded content, and streaming seen an error, but the
could not resume streaming, this will return false
.
- Source:
Returns:
-
Type
-
boolean
seekRange() → {{start: number, end: number}}
Get the range of time (in seconds) that seeking is allowed. If the player
has not loaded content, this will return a range from 0 to 0.
- Source:
Returns:
-
Type
-
{start: number, end: number}
selectAudioLanguage(language, roleopt)
Sets the current audio language and current variant role to the selected
language and role, and chooses a new variant if need be. If the player has
not loaded any content, this will be a no-op.
Parameters:
Name |
Type |
Attributes |
Description |
language |
string
|
|
|
role |
string
|
<optional>
|
|
- Source:
selectTextLanguage(language, roleopt, forcedopt)
Sets the current text language and current text role to the selected
language and role, and chooses a new variant if need be. If the player has
not loaded any content, this will be a no-op.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
language |
string
|
|
|
|
role |
string
|
<optional>
|
|
|
forced |
boolean
|
<optional>
|
false
|
|
- Source:
selectTextTrack(track)
Select a specific text track.
track
should come from a call to
getTextTracks
. If the track is not found, this will be a
no-op. If the player has not loaded content, this will be a no-op.
Note that AdaptationEvents
are not fired for manual track
selections.
Parameters:
- Source:
selectVariantsByLabel(label)
Select variant tracks that have a given label. This assumes the
label uniquely identifies an audio stream, so all the variants
are expected to have the same variant.audio.
Parameters:
Name |
Type |
Description |
label |
string
|
|
- Source:
selectVariantTrack(track, clearBufferopt, safeMarginopt)
Select a specific variant track to play.
track
should come
from a call to
getVariantTracks
. If
track
cannot
be found, this will be a no-op. If the player has not loaded content, this
will be a no-op.
Changing variants will take effect once the currently buffered content has
been played. To force the change to happen sooner, use
clearBuffer
with safeMargin
. Setting
clearBuffer
to true
will clear all buffered
content after safeMargin
, allowing the new variant to start
playing sooner.
Note that AdaptationEvents
are not fired for manual track
selections.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
track |
shaka.extern.Track
|
|
|
|
clearBuffer |
boolean
|
<optional>
|
false
|
|
safeMargin |
number
|
<optional>
|
0
|
Optional amount of buffer (in seconds) to
retain when clearing the buffer. Useful for switching variant quickly
without causing a buffering event. Defaults to 0 if not provided. Ignored
if clearBuffer is false. Can cause hiccups on some browsers if chosen too
small, e.g. The amount of two segments is a fair minimum to consider as
safeMargin value. |
- Source:
setInitialTextState_()
Decide during startup if text should be streamed/shown.
- Source:
setMaxHardwareResolution(width, height)
Set the maximum resolution that the platform's hardware can handle.
This will be called automatically by shaka.cast.CastReceiver
to enforce limitations of the Chromecast hardware.
Parameters:
Name |
Type |
Description |
width |
number
|
|
height |
number
|
|
- Source:
setTextTrackVisibility(isVisible)
Enable or disable the text displayer. If the player is in an unloaded
state, the request will be applied next time content is loaded.
Parameters:
Name |
Type |
Description |
isVisible |
boolean
|
|
- Source:
setupPreferredAudioOnSrc_()
This method setup the preferred audio using src=..
- Source:
setupPreferredTextOnSrc_()
This method setup the preferred text using src=.
- Source:
setVideoContainer(videoContainer)
Set the videoContainer to construct UITextDisplayer.
Parameters:
Name |
Type |
Description |
videoContainer |
HTMLElement
|
|
- Source:
shouldInitiallyShowText_(audioStream, textStream) → {boolean}
Check if we should show text on screen automatically.
The text should automatically be shown if the text is language-compatible
with the user's text language preference, but not compatible with the
audio.
For example:
preferred | chosen | chosen |
text | text | audio | show
-----------------------------------
en-CA | en | jp | true
en | en-US | fr | true
fr-CA | en-US | jp | false
en-CA | en-US | en-US | false
Parameters:
- Source:
Returns:
-
Type
-
boolean
shouldStreamText_() → {boolean}
- Source:
Returns:
true if we should stream text right now.
-
Type
-
boolean
shouldUseSrcEquals_(payload) → {boolean}
Check if src= should be used to load the asset at |uri|. Assume that media
source is the default option, and that src= is for special cases.
Parameters:
- Source:
Returns:
|true| if the content should be loaded with src=, |false| if the content
should be loaded with MediaSource.
-
Type
-
boolean
startBufferManagement_(rebufferingGoal)
Initialize and start the buffering system (observer and timer) so that we
can monitor our buffer lead during playback.
Parameters:
Name |
Type |
Description |
rebufferingGoal |
number
|
|
- Source:
switch_(variant, clearBufferopt, safeMarginopt)
Callback from AbrManager.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
variant |
shaka.extern.Variant
|
|
|
|
clearBuffer |
boolean
|
<optional>
|
false
|
|
safeMargin |
number
|
<optional>
|
0
|
Optional amount of buffer (in seconds) to
retain when clearing the buffer.
Defaults to 0 if not provided. Ignored if clearBuffer is false. |
- Source:
switchHtml5Track_(track)
Parameters:
Name |
Type |
Description |
track |
AudioTrack
|
|
- Source:
switchVariant_(variant, fromAdaptation, clearBuffer, safeMargin)
Parameters:
Name |
Type |
Description |
variant |
shaka.extern.Variant
|
|
fromAdaptation |
boolean
|
|
clearBuffer |
boolean
|
|
safeMargin |
number
|
|
- Source:
trickPlay(rate)
Enable trick play to skip through content without playing by repeatedly
seeking. For example, a rate of 2.5 would result in 2.5 seconds of content
being skipped every second. A negative rate will result in moving
backwards.
If the player has not loaded content or is still loading content this will
be a no-op. Wait until load
has completed before calling.
Trick play will be canceled automatically if the playhead hits the
beginning or end of the seekable range for the content.
Parameters:
Name |
Type |
Description |
rate |
number
|
|
- Source:
unload(initializeMediaSourceopt) → {Promise}
Tell the player to either return to:
- detached (when it does not have a media element),
- attached (when it has a media element and
initializedMediaSource=false
)
- media source initialized (when it has a media element and
initializedMediaSource=true
)
Calls to unload
will interrupt any in-progress calls to
load
but cannot interrupt calls to attach
,
detach
, or unload
.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
initializeMediaSource |
boolean
|
<optional>
|
true
|
|
- Source:
Returns:
-
Type
-
Promise
updateAbrManagerVariants_() → {boolean}
Update AbrManager with variants while taking into account restrictions,
preferences, and ABR.
On error, this dispatches an error event and returns false.
- Source:
Returns:
True if successful.
-
Type
-
boolean
updateBufferingSettings_(rebufferingGoal)
Updates the buffering thresholds based on the new rebuffering goal.
Parameters:
Name |
Type |
Description |
rebufferingGoal |
number
|
|
- Source:
updateBufferState_()
Update the buffering state to be either "we are buffering" or "we are not
buffering", firing events to the app as needed.
- Source:
updateStartTime(startTime)
Provides a way to update the stream start position during the media loading
process. Can for example be called from the manifestparsed
event handler to update the start position based on information in the
manifest.
Parameters:
Name |
Type |
Description |
startTime |
number
|
|
- Source:
updateStateHistory_()
Try updating the state history. If the player has not finished
initializing, this will be a no-op.
- Source:
Turn the media element's error object into a Shaka Player error object.
- Source:
Returns:
-
Type
-
shaka.util.Error
wrapWalkerListenersWithPromise_(listeners) → {Promise}
Using a promise, wrap the listeners returned by |Walker.startNewRoute|.
This will work for most usages in |Player| but should not be used for
special cases.
This will connect |onCancel|, |onEnd|, |onError|, and |onSkip| with
|resolve| and |reject| but will leave |onStart| unset.
Parameters:
- Source:
Returns:
-
Type
-
Promise
Events
AbrStatusChangedEvent
Fired when the state of abr has been changed.
(Enabled or disabled).
Properties:
Name |
Type |
Description |
type |
string
|
'abrstatuschanged' |
newStatus |
boolean
|
The new status of the application. True for 'is enabled' and
false otherwise. |
- Source:
AdaptationEvent
Fired when an automatic adaptation causes the active tracks
to change. Does not fire when the application calls
selectVariantTrack()
, selectTextTrack()
,
selectAudioLanguage()
, or selectTextLanguage()
.
Properties:
- Source:
BufferingEvent
Fired when the player's buffering state changes.
Properties:
Name |
Type |
Description |
type |
string
|
'buffering' |
buffering |
boolean
|
True when the Player enters the buffering state.
False when the Player leaves the buffering state. |
- Source:
DownloadFailed
Fired when a download has failed, for any reason.
'downloadfailed'
Parameters:
Name |
Type |
Description |
httpResponseCode |
number
|
|
aborted |
boolean
|
|
Properties:
- Source:
Fired when the networking engine has received the headers for
a download, but before the body has been downloaded.
If the HTTP plugin being used does not track this information, this event
will default to being fired when the body is received, instead.
Properties:
- Source:
DrmSessionUpdateEvent
Fired when the CDM has accepted the license response.
Properties:
Name |
Type |
Description |
type |
string
|
'drmsessionupdate' |
- Source:
EmsgEvent
Fired when a non-typical emsg is found in a segment.
Properties:
Name |
Type |
Description |
type |
string
|
'emsg' |
detail |
shaka.extern.EmsgInfo
|
An object which contains the content of the emsg box. |
- Source:
ErrorEvent
Fired when a playback error occurs.
Properties:
Name |
Type |
Description |
type |
string
|
'error' |
detail |
shaka.util.Error
|
An object which contains details on the error. The error's
category and code properties will identify the
specific error that occurred. In an uncompiled build, you can also use the
message and stack properties to debug. |
- Source:
ExpirationUpdatedEvent
Fired when there is a change in the expiration times of an
EME session.
Properties:
Name |
Type |
Description |
type |
string
|
'expirationupdated' |
- Source:
LargeGapEvent
Fired when the playhead enters a large gap. If the
streaming.jumpLargeGaps
configuration is set, the default
action of this event is to jump the gap; this can be prevented by calling
preventDefault()
on the event object.
Properties:
Name |
Type |
Description |
type |
string
|
'largegap' |
currentTime |
number
|
The current time of the playhead. |
gapSize |
number
|
The size of the gap, in seconds. |
- Source:
LoadedEvent
Fired when the player ends the load.
Properties:
Name |
Type |
Description |
type |
string
|
'loaded' |
- Source:
LoadingEvent
Fired when the player begins loading. The start of loading is
defined as when the user has communicated intent to load content (i.e.
Player.load
has been called).
Properties:
Name |
Type |
Description |
type |
string
|
'loading' |
- Source:
ManifestParsedEvent
Fired after the manifest has been parsed, but before anything
else happens. The manifest may contain streams that will be filtered out,
at this stage of the loading process.
Properties:
Name |
Type |
Description |
type |
string
|
'manifestparsed' |
- Source:
Fired when the media quality changes at the playhead.
That may be caused by an adaptation change or a DASH period transition.
Separate events are emitted for audio and video contentTypes.
This is supported for only DASH streams at this time.
Properties:
Name |
Type |
Description |
type |
string
|
'mediaqualitychanged' |
mediaQuality |
shaka.extern.MediaQualityInfo
|
Information about media quality at the playhead position. |
position |
number
|
The playhead position. |
- Source:
Triggers after metadata associated with the stream is found.
Usually they are metadata of type ID3.
Properties:
Name |
Type |
Attributes |
Description |
type |
string
|
|
'metadata' |
startTime |
number
|
|
The time that describes the beginning of the range of the metadata to
which the cue applies. |
endTime |
number
|
<nullable>
|
The time that describes the end of the range of the metadata to which
the cue applies. |
metadataType |
string
|
|
Type of metadata. Eg: org.id3 or org.mp4ra |
payload |
shaka.extern.ID3Metadata
|
|
The metadata itself |
- Source:
RateChangeEvent
Fired when the video's playback rate changes.
This allows the PlayRateController to update it's internal rate field,
before the UI updates playback button with the newest playback rate.
Properties:
Name |
Type |
Description |
type |
string
|
'ratechange' |
- Source:
SessionDataEvent
Fired when the manifest parser find info about session data.
Specification: https://tools.ietf.org/html/rfc8216#section-4.3.4.4
Properties:
Name |
Type |
Description |
type |
string
|
'sessiondata' |
id |
string
|
The id of the session data. |
uri |
string
|
The uri with the session data info. |
language |
string
|
The language of the session data. |
value |
string
|
The value of the session data. |
- Source:
StateChangeEvent
Fired when the player changes load states.
Properties:
Name |
Type |
Description |
type |
string
|
'onstatechange' |
state |
string
|
The name of the state that the player just entered. |
- Source:
StateIdleEvent
Fired when the player has stopped changing states and will
remain idle until a new state change request (e.g. load
,
attach
, etc.) is made.
Properties:
Name |
Type |
Description |
type |
string
|
'onstateidle' |
state |
string
|
The name of the state that the player stopped in. |
- Source:
StreamingEvent
Fired after the manifest has been parsed and track information
is available, but before streams have been chosen and before any segments
have been fetched. You may use this event to configure the player based on
information found in the manifest.
Properties:
Name |
Type |
Description |
type |
string
|
'streaming' |
- Source:
TextChangedEvent
Fired when a call from the application caused a text stream
change. Can be triggered by calls to selectTextTrack()
or
selectTextLanguage()
.
Properties:
Name |
Type |
Description |
type |
string
|
'textchanged' |
- Source:
TextTrackVisibilityEvent
Fired when text track visibility changes.
Properties:
Name |
Type |
Description |
type |
string
|
'texttrackvisibility' |
- Source:
TimelineRegionAddedEvent
Fired when a media timeline region is added.
Properties:
- Source:
TimelineRegionEnterEvent
Fired when the playhead enters a timeline region.
Properties:
- Source:
TimelineRegionExitEvent
Fired when the playhead exits a timeline region.
Properties:
- Source:
TracksChangedEvent
Fired when the list of tracks changes. For example, this will
happen when new tracks are added/removed or when track restrictions change.
Properties:
Name |
Type |
Description |
type |
string
|
'trackschanged' |
- Source:
UnloadingEvent
Fired when the player unloads or fails to load.
Used by the Cast receiver to determine idle state.
Properties:
Name |
Type |
Description |
type |
string
|
'unloading' |
- Source:
VariantChangedEvent
Fired when a call from the application caused a variant change.
Can be triggered by calls to selectVariantTrack()
or
selectAudioLanguage()
. Does not fire when an automatic
adaptation causes a variant change.
Properties:
- Source: