Class: shaka.media.StreamingEngine

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:
Name Type Description
manifest shaka.extern.Manifest
playerInterface shaka.media.StreamingEngine.PlayerInterface
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:
  • number
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:
  • number
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:
  • number
Source:

bufferingGoalScale_ :number

Type:
  • number
Source:

config_ :shaka.extern.StreamingConfiguration

Type:
Source:

currentTextStream_ :shaka.extern.Stream

Type:
Source:

currentVariant_ :shaka.extern.Variant

Type:
Source:

destroyer_ :shaka.util.Destroyer

Type:
Source:

failureCallbackBackoff_ :shaka.net.Backoff

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:
  • boolean
Source:

manifest_ :shaka.extern.Manifest

Type:
Source:

mediaStates_ :Map.<shaka.util.ManifestParserUtils.ContentType, !shaka.media.StreamingEngine.MediaState_>

Maps a content type, e.g., 'audio', 'video', or 'text', to a MediaState.
Type:
Source:

playerInterface_ :shaka.media.StreamingEngine.PlayerInterface

Type:
Source:

startupComplete_ :boolean

Set to true once the initial media states have been created.
Type:
  • boolean
Source:

Methods

isEmbeddedText_(mediaState) → {boolean}

Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:
Returns:
Type
boolean

logPrefix_(mediaState) → {string}

Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
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) → {Promise}

Appends the given segment and evicts content if required to append.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
presentationTime number
stream shaka.extern.Stream
reference shaka.media.SegmentReference
segment BufferSource
Source:
Returns:
Type
Promise

cancelUpdate_(mediaState)

If |mediaState| is scheduled to update, stop it.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
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:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
flush boolean
safeMargin number
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

configure(config)

Called by the Player to provide an updated configuration any time it changes. Must be called at least once before start().
Parameters:
Name Type Description
config shaka.extern.StreamingConfiguration
Source:

createMediaState_(stream) → {shaka.media.StreamingEngine.MediaState_}

Creates a media state.
Parameters:
Name Type Description
stream shaka.extern.Stream
Source:
Returns:
Type
shaka.media.StreamingEngine.MediaState_

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:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
presentationTime number
Source:

fetch_(mediaStatenon-null, reference, streamDataCallbacknullable) → {Promise.<BufferSource>}

Fetches the given segment.
Parameters:
Name Type Attributes Description
mediaState shaka.media.StreamingEngine.MediaState_
reference shaka.media.InitSegmentReference | shaka.media.SegmentReference
streamDataCallback ?function(BufferSource):!Promise= <nullable>
Source:
Returns:
Type
Promise.<BufferSource>

fetchAndAppend_(mediaStatenon-null, presentationTime, referencenon-null)

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:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
presentationTime number
reference shaka.media.SegmentReference
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, every MediaState will have a pending update.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:

getCurrentTextStream() → {shaka.extern.Stream}

Get the text stream we are streaming. Returns null if there is no text streaming.
Source:
Returns:
Type
shaka.extern.Stream

getCurrentVariant() → {shaka.extern.Variant}

Get the current variant we are streaming. Returns null if nothing is streaming.
Source:
Returns:
Type
shaka.extern.Variant

getSegmentReferenceNeeded_(mediaState, presentationTime, bufferEndnullable) → {shaka.media.SegmentReference}

Gets the SegmentReference of the next segment needed.
Parameters:
Name Type Attributes Description
mediaState shaka.media.StreamingEngine.MediaState_
presentationTime number
bufferEnd number <nullable>
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:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
presentationTime number
Source:
Returns:
The next timestamp needed.
Type
number

handleQuotaExceeded_(mediaState, errornon-null)

Handles a QUOTA_EXCEEDED_ERROR.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
error shaka.util.Error
Source:

handleStreamingError_(errornon-null) → {Promise}

Handle streaming errors by delaying, then notifying the application by error callback and by streaming failure callback.
Parameters:
Name Type Description
error shaka.util.Error
Source:
Returns:
Type
Promise

initSourceBuffer_(mediaState, referencenon-null) → {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:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
reference shaka.media.SegmentReference
Source:
Returns:
Type
Promise

initStreams_() → {Promise}

Initializes the initial streams and media states. This will schedule updates for the given types.
Source:
Returns:
Type
Promise

loadNewTextStream_(stream) → {Promise}

Start streaming text, creating a new media state.
Parameters:
Name Type Description
stream shaka.extern.Stream
Source:
Returns:
Type
Promise

makeAbortDecision_(mediaStatenon-null)

Decide if it makes sense to abort the current operation, and abort it if so.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:

onUpdate_(mediaStatenon-null)

Called when |mediaState|'s update timer has expired.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:

parseEMSG_(referencenon-null, emsgSchemeIdUrisnullable, boxnon-null)

Parse the EMSG box from a MP4 container.
Parameters:
Name Type Attributes Description
reference shaka.media.SegmentReference
emsgSchemeIdUris Array.<string> <nullable>
 Array of emsg scheme_id_uri for which emsg boxes should be parsed.
box shaka.extern.ParsedBox
Source:

reloadTextStream()

Reload the current text stream.
Source:

retry() → {boolean}

Clear per-stream error states and retry any failed streams.
Source:
Returns:
False if unable to retry.
Type
boolean

scheduleUpdate_(mediaStatenon-null, delay)

Schedules |mediaState|'s next update.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
delay number The delay in seconds.
Source:

seeked()

Notifies the StreamingEngine that the playhead has moved to a valid time within the presentation timeline.
Source:

setDuration_()

Sets the MediaSource's duration.
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:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:
Returns:
Type
boolean

start() → {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.
Source:
Returns:
Type
Promise

switchInternal_(stream, clearBuffer, safeMargin, force)

Switches to the given Stream. |stream| may be from any Variant.
Parameters:
Name Type Description
stream shaka.extern.Stream
clearBuffer boolean
safeMargin number
force boolean If true, reload the text stream even if it did not change.
Source:

switchTextStream(textStream)

Parameters:
Name Type Description
textStream shaka.extern.Stream
Source:

switchVariant(variant, clearBufferopt, safeMarginopt, forceopt)

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.
Source:

unloadTextStream()

Stop fetching text stream when the user chooses to hide the captions.
Source:

update_(mediaState) → {number}

Updates the given MediaState.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:
Returns:
The number of seconds to wait until updating again or null if another update does not need to be scheduled.
Type
number

Type Definitions

MediaState_

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:
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.
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.
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.
Source:

PlayerInterface

Type:
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.
modifySegmentRequest function The request modifier
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.
Source: