Creates a Streaming Engine.
The StreamingEngine is responsible for setting up the Manifest's Streams
(i.e., for calling each Stream's createSegmentIndex() function), for
downloading segments, for co-ordinating audio, video, and text buffering.
The StreamingEngine provides an interface to switch between Streams, but it
does not choose which Streams to switch to.
The StreamingEngine does not need to be notified about changes to the
Manifest's SegmentIndexes; however, it does need to be notified when new
Variants are added to the Manifest.
To start the StreamingEngine the owner must first call configure(), followed
by one call to switchVariant(), one optional call to switchTextStream(), and
finally a call to start(). After start() resolves, switch*() can be used
freely.
The owner must call seeked() each time the playhead moves to a new location
within the presentation timeline; however, the owner may forego calling
seeked() when the playhead moves outside the presentation timeline.
Constructor
new StreamingEngine(manifest, playerInterface)
Creates a Streaming Engine.
The StreamingEngine is responsible for setting up the Manifest's Streams
(i.e., for calling each Stream's createSegmentIndex() function), for
downloading segments, for co-ordinating audio, video, and text buffering.
The StreamingEngine provides an interface to switch between Streams, but it
does not choose which Streams to switch to.
The StreamingEngine does not need to be notified about changes to the
Manifest's SegmentIndexes; however, it does need to be notified when new
Variants are added to the Manifest.
To start the StreamingEngine the owner must first call configure(), followed
by one call to switchVariant(), one optional call to switchTextStream(), and
finally a call to start(). After start() resolves, switch*() can be used
freely.
The owner must call seeked() each time the playhead moves to a new location
within the presentation timeline; however, the owner may forego calling
seeked() when the playhead moves outside the presentation timeline.
Parameters:
- Implements:
- Source:
Members
APPEND_WINDOW_END_FUDGE_ :number
The fudge factor for appendWindowEnd. By adjusting the window backward, we
avoid rounding errors that could cause us to remove the last few samples of
the Period. This rounding error could then create an artificial gap and a
stutter when the gap-jumping logic takes over.
https://github.com/shaka-project/shaka-player/issues/1597
Type:
- Source:
APPEND_WINDOW_START_FUDGE_ :number
The fudge factor for appendWindowStart. By adjusting the window backward, we
avoid rounding errors that could cause us to remove the keyframe at the start
of the Period.
NOTE: This was increased as part of the solution to
https://github.com/shaka-project/shaka-player/issues/1281
Type:
- Source:
MAX_RUN_AHEAD_SEGMENTS_ :number
The maximum number of segments by which a stream can get ahead of other
streams.
Introduced to keep StreamingEngine from letting one media type get too far
ahead of another. For example, audio segments are typically much smaller
than video segments, so in the time it takes to fetch one video segment, we
could fetch many audio segments. This doesn't help with buffering, though,
since the intersection of the two buffered ranges is what counts.
Type:
- Source:
bufferingScale_ :number
Type:
- Source:
deferredCloseSegmentIndex_ :Map.<string, !function()>
Retains a reference to the function used to close SegmentIndex objects
for streams which were switched away from during an ongoing update_().
Type:
-
Map.<string, !function()>
- Source:
Used for delay and backoff of failure callbacks, so that apps do not
retry instantly.
Type:
- Source:
fatalError_ :boolean
Set to true on fatal error. Interrupts fetchAndAppend_().
Type:
- Source:
Maps a content type, e.g., 'audio', 'video', or 'text', to a MediaState.
Type:
- Source:
playRangeEnd_ :number
Type:
- Source:
playRangeStart_ :number
Type:
- Source:
startupComplete_ :boolean
Set to true once the initial media states have been created.
Type:
- Source:
textStreamSequenceId_ :number
Type:
- Source:
Methods
isEmbeddedText_(mediaState) → {boolean}
Parameters:
- Source:
Returns:
-
Type
-
boolean
logPrefix_(mediaState) → {string}
Parameters:
- Source:
Returns:
A log prefix of the form ($CONTENT_TYPE:$STREAM_ID), e.g.,
"(audio:5)" or "(video:hd)".
-
Type
-
string
abortOperations_() → {Promise}
If |mediaState| holds any in-progress operations, abort them.
- Source:
Returns:
-
Type
-
Promise
append_(mediaStatenon-null, presentationTime, stream, referencenon-null, segment, isChunkedDataopt, adaptationopt) → {Promise}
Appends the given segment and evicts content if required to append.
Parameters:
- Source:
Returns:
-
Type
-
Promise
applyPlayRange(playRangeStart, playRangeEnd)
Applies a playback range. This will only affect non-live content.
Parameters:
Name |
Type |
Description |
playRangeStart |
number
|
|
playRangeEnd |
number
|
|
- Source:
cancelUpdate_(mediaState)
If |mediaState| is scheduled to update, stop it.
Parameters:
- Source:
clearBuffer_(mediaStatenon-null, flush, safeMargin)
Clears the buffer and schedules another update.
The optional parameter safeMargin allows to retain a certain amount
of buffer, which can help avoiding rebuffering events.
The value of the safe margin should be provided by the ABR manager.
Parameters:
- Source:
concatArray_(remainingnon-null, datanon-null) → {Uint8Array}
Append the data to the remaining data.
Parameters:
Name |
Type |
Description |
remaining |
Uint8Array
|
|
data |
Uint8Array
|
|
- Source:
Returns:
-
Type
-
Uint8Array
Called by the Player to provide an updated configuration any time it
changes. Must be called at least once before start().
Parameters:
- Source:
destroy() → {Promise}
Request that this object be destroyed, releasing all resources and shutting
down all operations. Returns a Promise which is resolved when destruction
is complete. This Promise should never be rejected.
- Implements:
- Source:
Returns:
-
Type
-
Promise
doDestroy_() → {Promise}
- Source:
Returns:
-
Type
-
Promise
evict_(mediaState, presentationTime)
Evicts media to meet the max buffer behind limit.
Parameters:
- Source:
fetch_(mediaStatenon-null, reference, streamDataCallbacknullable) → {Promise.<BufferSource>}
Fetches the given segment.
Parameters:
- Source:
Returns:
-
Type
-
Promise.<BufferSource>
fetchAndAppend_(mediaStatenon-null, presentationTime, referencenon-null, adaptation)
Fetches and appends the given segment. Sets up the given MediaState's
associated SourceBuffer and evicts segments if either are required
beforehand. Schedules another update after completing successfully.
Parameters:
- Source:
forceClearBuffer_(mediaStatenon-null)
Clear the buffer for a given stream. Unlike clearBuffer_, this will handle
cases where a MediaState is performing an update. After this runs, the
MediaState will have a pending update.
Parameters:
- Source:
Get the text stream we are streaming. Returns null if there is no text
streaming.
- Source:
Returns:
-
Type
-
shaka.extern.Stream
Get the current variant we are streaming. Returns null if nothing is
streaming.
- Source:
Returns:
-
Type
-
shaka.extern.Variant
getDisabledTime_(errornon-null) → {number}
Parameters:
- Source:
Returns:
-
Type
-
number
getSegmentReferenceNeeded_(mediaState, presentationTime, bufferEndnullable) → {shaka.media.SegmentReference}
Gets the SegmentReference of the next segment needed.
Parameters:
- Source:
Returns:
The SegmentReference of the
next segment needed. Returns null if a segment could not be found, does
not exist, or is not available.
-
Type
-
shaka.media.SegmentReference
getTimeNeeded_(mediaState, presentationTime) → {number}
Gets the next timestamp needed. Returns the playhead's position if the
buffer is empty; otherwise, returns the time at which the last segment
appended ends.
Parameters:
- Source:
Returns:
The next timestamp needed.
-
Type
-
number
handleDeferredCloseSegmentIndexes_(mediaStatenon-null)
Handles deferred releases of old SegmentIndexes for the mediaState's
content type from a previous update.
Parameters:
- Source:
handleQuotaExceeded_(mediaState, errornon-null) → {Promise}
Handles a QUOTA_EXCEEDED_ERROR.
Parameters:
- Source:
Returns:
-
Type
-
Promise
handleStreamingError_(mediaState, errornon-null) → {Promise}
Handle streaming errors by delaying, then notifying the application by
error callback and by streaming failure callback.
Parameters:
- Source:
Returns:
-
Type
-
Promise
initSourceBuffer_(mediaState, referencenon-null, adaptation) → {Promise}
Sets the given MediaState's associated SourceBuffer's timestamp offset,
append window, and init segment if they have changed. If an error occurs
then neither the timestamp offset or init segment are unset, since another
call to switch() will end up superseding them.
Parameters:
- Source:
Returns:
-
Type
-
Promise
initStreams_(segmentPrefetchByIdnon-null) → {Promise}
Initializes the initial streams and media states. This will schedule
updates for the given types.
Parameters:
- Source:
Returns:
-
Type
-
Promise
loadNewTextStream_(stream) → {Promise}
Start streaming text, creating a new media state.
Parameters:
- Source:
Returns:
-
Type
-
Promise
makeAbortDecision_(mediaStatenon-null)
Decide if it makes sense to abort the current operation, and abort it if
so.
Parameters:
- Source:
onUpdate_(mediaStatenon-null)
Called when |mediaState|'s update timer has expired.
Parameters:
- Source:
parseEMSG_(referencenon-null, emsgSchemeIdUrisnullable, boxnon-null)
Parse the EMSG box from a MP4 container.
Parameters:
- Source:
reloadTextStream()
Reload the current text stream.
- Source:
Reset Media Source
Parameters:
Name |
Type |
Attributes |
Default |
Description |
force |
boolean
|
<optional>
|
false
|
|
- Source:
Returns:
-
Type
-
Promise.<boolean>
retry(delaySeconds) → {boolean}
Clear per-stream error states and retry any failed streams.
Parameters:
Name |
Type |
Description |
delaySeconds |
number
|
|
- Source:
Returns:
False if unable to retry.
-
Type
-
boolean
scheduleUpdate_(mediaStatenon-null, delay)
Schedules |mediaState|'s next update.
Parameters:
- Source:
seeked()
Notifies the StreamingEngine that the playhead has moved to a valid time
within the presentation timeline.
- Source:
setProperties_(mediaStatenon-null, timestampOffset, appendWindowStart, appendWindowEnd, referencenon-null, codecsopt, nullable, mimeTypeopt, nullable)
Parameters:
- Source:
setTrickPlay(on)
Set trick play on or off.
If trick play is on, related trick play streams will be used when possible.
Parameters:
Name |
Type |
Description |
on |
boolean
|
|
- Source:
shouldAbortCurrentRequest_(mediaStatenon-null) → {boolean}
Returns whether we should abort the current request.
Parameters:
- Source:
Returns:
-
Type
-
boolean
start(segmentPrefetchByIdopt, non-null) → {Promise}
Initialize and start streaming.
By calling this method, StreamingEngine will start streaming the variant
chosen by a prior call to switchVariant(), and optionally, the text stream
chosen by a prior call to switchTextStream(). Once the Promise resolves,
switch*() may be called freely.
Parameters:
Name |
Type |
Attributes |
Description |
segmentPrefetchById |
Map.<number, shaka.media.SegmentPrefetch>
|
<optional>
|
If provided, segments prefetched for these streams will be used as needed
during playback. |
- Source:
Returns:
-
Type
-
Promise
switchInternal_(stream, clearBuffer, safeMargin, force, adaptationopt)
Switches to the given Stream. |stream| may be from any Variant.
Parameters:
Name |
Type |
Attributes |
Description |
stream |
shaka.extern.Stream
|
|
|
clearBuffer |
boolean
|
|
|
safeMargin |
number
|
|
|
force |
boolean
|
|
If true, reload the text stream even if it did not change. |
adaptation |
boolean
|
<optional>
|
If true, update the media state to indicate MediaSourceEngine should
reset the timestamp offset to ensure the new track segments are correctly
placed on the timeline. |
- Source:
switchTextStream(textStream)
Parameters:
- Source:
switchVariant(variant, clearBufferopt, safeMarginopt, forceopt, adaptationopt)
Parameters:
Name |
Type |
Attributes |
Default |
Description |
variant |
shaka.extern.Variant
|
|
|
|
clearBuffer |
boolean
|
<optional>
|
false
|
|
safeMargin |
number
|
<optional>
|
0
|
|
force |
boolean
|
<optional>
|
false
|
If true, reload the variant even if it did not change. |
adaptation |
boolean
|
<optional>
|
false
|
If true, update the media state to indicate MediaSourceEngine should
reset the timestamp offset to ensure the new track segments are correctly
placed on the timeline. |
- Source:
unloadTextStream()
Stop fetching text stream when the user chooses to hide the captions.
- Source:
update_(mediaState) → {number}
Updates the given MediaState.
Parameters:
- Source:
Returns:
The number of seconds to wait until updating again or
null if another update does not need to be scheduled.
-
Type
-
number
updateDuration()
Sets the MediaSource's duration.
- Source:
updatePrefetchMapForAudio_()
Populates the prefetch map depending on the configuration
- Source:
updateSegmentIteratorReverse_()
Update the segment iterator direction.
- Source:
updateSpatialVideoInfo_(info)
Update the spatial video info and notify to the app.
Parameters:
- Source:
Type Definitions
Contains the state of a logical stream, i.e., a sequence of segmented data
for a particular content type. At any given time there is a Stream object
associated with the state of the logical stream.
Type:
-
{type: shaka.util.ManifestParserUtils.ContentType, stream: shaka.extern.Stream, segmentIterator: shaka.media.SegmentIterator, lastSegmentReference: shaka.media.SegmentReference, lastInitSegmentReference: shaka.media.InitSegmentReference, lastTimestampOffset: ?number, lastAppendWindowStart: ?number, lastAppendWindowEnd: ?number, lastCodecs: ?string, lastMimeType: ?string, restoreStreamAfterTrickPlay: ?shaka.extern.Stream, endOfStream: boolean, performingUpdate: boolean, updateTimer: shaka.util.DelayedTick, waitingToClearBuffer: boolean, waitingToFlushBuffer: boolean, clearBufferSafeMargin: number, clearingBuffer: boolean, seeked: boolean, adaptation: boolean, recovering: boolean, hasError: boolean, operation: shaka.net.NetworkingEngine.PendingRequest, segmentPrefetch: shaka.media.SegmentPrefetch}
Properties:
Name |
Type |
Attributes |
Description |
type |
shaka.util.ManifestParserUtils.ContentType
|
|
The stream's content type, e.g., 'audio', 'video', or 'text'. |
stream |
shaka.extern.Stream
|
|
The current Stream. |
segmentIterator |
shaka.media.SegmentIndexIterator
|
|
An iterator through the segments of |stream|. |
lastSegmentReference |
shaka.media.SegmentReference
|
|
The SegmentReference of the last segment that was appended. |
lastInitSegmentReference |
shaka.media.InitSegmentReference
|
|
The InitSegmentReference of the last init segment that was appended. |
lastTimestampOffset |
number
|
<nullable>
|
The last timestamp offset given to MediaSourceEngine for this type. |
lastAppendWindowStart |
number
|
<nullable>
|
The last append window start given to MediaSourceEngine for this type. |
lastAppendWindowEnd |
number
|
<nullable>
|
The last append window end given to MediaSourceEngine for this type. |
lastCodecs |
string
|
<nullable>
|
The last append codecs given to MediaSourceEngine for this type. |
lastMimeType |
string
|
<nullable>
|
The last append mime type given to MediaSourceEngine for this type. |
restoreStreamAfterTrickPlay |
shaka.extern.Stream
|
<nullable>
|
The Stream to restore after trick play mode is turned off. |
endOfStream |
boolean
|
|
True indicates that the end of the buffer has hit the end of the
presentation. |
performingUpdate |
boolean
|
|
True indicates that an update is in progress. |
updateTimer |
shaka.util.DelayedTick
|
|
A timer used to update the media state. |
waitingToClearBuffer |
boolean
|
|
True indicates that the buffer must be cleared after the current update
finishes. |
waitingToFlushBuffer |
boolean
|
|
True indicates that the buffer must be flushed after it is cleared. |
clearBufferSafeMargin |
number
|
|
The amount of buffer to retain when clearing the buffer after the update. |
clearingBuffer |
boolean
|
|
True indicates that the buffer is being cleared. |
seeked |
boolean
|
|
True indicates that the presentation just seeked. |
adaptation |
boolean
|
|
True indicates that the presentation just automatically switched variants. |
recovering |
boolean
|
|
True indicates that the last segment was not appended because it could not
fit in the buffer. |
hasError |
boolean
|
|
True indicates that the stream has encountered an error and has stopped
updating. |
operation |
shaka.net.NetworkingEngine.PendingRequest
|
|
Operation with the number of bytes to be downloaded. |
segmentPrefetch |
shaka.media.SegmentPrefetch
|
<nullable>
|
A prefetch object for managing prefetching. Null if unneeded
(if prefetching is disabled, etc). |
- Source:
PlayerInterface
Type:
-
{getPresentationTime: function(): number, getBandwidthEstimate: function(): number, getPlaybackRate: function(): number, mediaSourceEngine: !shaka.media.MediaSourceEngine, netEngine: shaka.net.NetworkingEngine, onError: function(!shaka.util.Error), onEvent: function(!Event), onManifestUpdate: function(), onSegmentAppended: function(!shaka.media.SegmentReference, !shaka.extern.Stream), onInitSegmentAppended: function(!number, !shaka.media.InitSegmentReference), beforeAppendSegment: function(shaka.util.ManifestParserUtils.ContentType, !BufferSource): Promise, onMetadata: !function(!Array.<shaka.extern.ID3Metadata>, number, ?number), disableStream: function(!shaka.extern.Stream, number): boolean}
Properties:
Name |
Type |
Description |
getPresentationTime |
function
|
Get the position in the presentation (in seconds) of the content that the
viewer is seeing on screen right now. |
getBandwidthEstimate |
function
|
Get the estimated bandwidth in bits per second. |
getPlaybackRate |
function
|
Get the playback rate |
mediaSourceEngine |
shaka.media.MediaSourceEngine
|
The MediaSourceEngine. The caller retains ownership. |
netEngine |
shaka.net.NetworkingEngine
|
The NetworkingEngine instance to use. The caller retains ownership. |
onError |
function
|
Called when an error occurs. If the error is recoverable (see
shaka.util.Error) then the caller may invoke either
StreamingEngine.switch*() or StreamingEngine.seeked() to attempt recovery. |
onEvent |
function
|
Called when an event occurs that should be sent to the app. |
onManifestUpdate |
function
|
Called when an embedded 'emsg' box should trigger a manifest update. |
onSegmentAppended |
function
|
Called after a segment is successfully appended to a MediaSource. |
onInitSegmentAppended |
function
|
Called when an init segment is appended to a MediaSource. |
beforeAppendSegment |
function
|
A function called just before appending to the source buffer. |
onMetadata |
function
|
Called when an ID3 is found in a EMSG. |
disableStream |
function
|
Called to temporarily disable a stream i.e. disabling all variant
containing said stream. |
- Source: