Class: shaka.media.StreamingEngine

Constructor

new StreamingEngine(manifest, playerInterface)

Creates a StreamingEngine. 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, and for handling Period transitions. The StreamingEngine provides an interface to switch between Streams, but it does not choose which Streams to switch to. The StreamingEngine notifies its owner when it needs to buffer a new Period, so its owner can choose which Streams within that Period to initially buffer. Moreover, the StreamingEngine also notifies its owner when any Stream within the current Period may be switched to, so its owner can switch bitrates, resolutions, or languages. The StreamingEngine does not need to be notified about changes to the Manifest's SegmentIndexes; however, it does need to be notified when new Periods are added to the Manifest, so it can set up that Period's Streams. To start the StreamingEngine the owner must first call configure() followed by init(). The StreamingEngine will then call onChooseStreams(p) when it needs to buffer Period p; it will then switch to the Streams returned from that function. The StreamingEngine will call onCanSwitch() when any Stream within the current Period may be switched to. 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

(private, static, constant) APPEND_WINDOW_START_FUDGE_ :number

The fudge factor for the 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/google/shaka-player/issues/1281
Type:
  • number
Source:

(private, static, constant) 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:

(private) bufferingGoalScale_ :number

Type:
  • number
Source:

(private) canSwitchPeriod_ :Array.<?{promise: shaka.util.PublicPromise, resolved: boolean}>

Maps a Period's index to an object that indicates that either 1. the Period has not been set up (undefined). 2. the Period is being set up ([a PublicPromise, false]). 3. the Period is set up (i.e., all Streams within the Period are set up) and can be switched to ([a PublicPromise, true]).
Type:
Source:

(private) canSwitchStream_ :Object.<number, ?{promise: shaka.util.PublicPromise, resolved: boolean}>

Maps a Stream's ID to an object that indicates that either 1. the Stream has not been set up (undefined). 2. the Stream is being set up ([a Promise instance, false]). 3. the Stream is set up and can be switched to ([a Promise instance, true]).
Type:
Source:

(private, nullable) config_ :shaka.extern.StreamingConfiguration

Type:
Source:

(private) destroyed_ :boolean

Type:
  • boolean
Source:

(private) failureCallbackBackoff_ :shaka.net.Backoff

Used for delay and backoff of failure callbacks, so that apps do not retry instantly.
Type:
Source:

(private) fatalError_ :boolean

Set to true on fatal error. Interrupts fetchAndAppend_().
Type:
  • boolean
Source:

(private, nullable) manifest_ :shaka.extern.Manifest

Type:
Source:

(private) mediaStates_ :Object.<shaka.util.ManifestParserUtils.ContentType, !shaka.media.StreamingEngine.MediaState_>

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

(private, nullable) playerInterface_ :shaka.media.StreamingEngine.PlayerInterface

Type:
Source:

(private) setupPeriodPromise_ :Promise

Type:
  • Promise
Source:

(private) startupComplete_ :boolean

Set to true once one segment of each content type has been buffered.
Type:
  • boolean
Source:

(private) textStreamSequenceId_ :number

Type:
  • number
Source:

(private) unloadingTextStream_ :boolean

Set to true when a request to unload text stream comes in. This is used since loading new text stream is async, the request of unloading text stream might come in before setting up new text stream is finished.
Type:
  • boolean
Source:

Methods

(private, static) isIdle_(mediaState) → {boolean}

Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:
Returns:
True if the given MediaState is idle; otherwise, return false.
Type
boolean

(private, static) 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

(private) append_(mediaStatenon-null, playheadTime, period, stream, referencenon-null, segmentnon-null) → (non-null) {Promise}

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

(private) cancelUpdate_(mediaStatenon-null)

Cancels |mediaState|'s next update if one exists.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:

(private) clearAllBuffers_()

Clears the buffer for every stream. Unlike clearBuffer_, this will handle cases where a MediaState is performing an update. After this runs, every MediaState will have a pending update.
Source:

(private) 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:

configure(config)

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

(private) createMediaState_(stream, needPeriodIndex, resumeAtopt) → {shaka.media.StreamingEngine.MediaState_}

Creates a media state.
Parameters:
Name Type Attributes Description
stream shaka.extern.Stream
needPeriodIndex number
resumeAt number <optional>
Source:
Returns:
Type
shaka.media.StreamingEngine.MediaState_

(export) destroy() → (non-null) {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

(private) evict_(mediaState, playheadTime) → (non-null) {Promise}

Evicts media to meet the max buffer behind limit.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
playheadTime number
Source:
Returns:
Type
Promise

(private) fetch_(reference) → (non-null) {Promise.<!ArrayBuffer>}

Fetches the given segment.
Parameters:
Name Type Description
reference shaka.media.InitSegmentReference | shaka.media.SegmentReference
Source:
Returns:
Type
Promise.<!ArrayBuffer>

(private) fetchAndAppend_(mediaStatenon-null, playheadTime, currentPeriodIndex, 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_
playheadTime number
currentPeriodIndex number The index of the current Period.
reference shaka.media.SegmentReference
Source:

(private) findPeriodContainingStream_(streamnon-null) → {number}

Parameters:
Name Type Description
stream shaka.extern.Stream
Source:
Returns:
The index of the Period which contains |stream|, or -1 if no Period contains |stream|.
Type
number

(private) findPeriodContainingTime_(time) → {number}

Parameters:
Name Type Description
time number The time, in seconds, relative to the start of the presentation.
Source:
Returns:
The index of the Period which starts after |time|
Type
number

getActiveAudio() → (nullable) {shaka.extern.Stream}

Get the active audio stream. Returns null if there is no audio streaming.
Source:
Returns:
Type
shaka.extern.Stream

getActivePeriod() → (nullable) {shaka.extern.Period}

Gets the Period in which we are currently buffering. This might be different from the Period which contains the Playhead.
Source:
Returns:
Type
shaka.extern.Period

getActiveText() → (nullable) {shaka.extern.Stream}

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

getActiveVideo() → (nullable) {shaka.extern.Stream}

Get the active video stream. Returns null if there is no video streaming.
Source:
Returns:
Type
shaka.extern.Stream

getCurrentPeriod() → {shaka.extern.Period}

Gets the current Period the stream is in. This Period might not be initialized yet if canSwitch(period) has not been called yet.
Source:
Returns:
Type
shaka.extern.Period

(private) getSegmentReferenceIfAvailable_(mediaState, currentPeriodIndex, position) → {shaka.media.SegmentReference}

Gets the SegmentReference at the given position if it's available.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
currentPeriodIndex number
position number
Source:
Returns:
Type
shaka.media.SegmentReference

(private) getSegmentReferenceNeeded_(mediaState, playheadTime, bufferEndnullable, currentPeriodIndex) → {shaka.media.SegmentReference}

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

(private) getStream_(type) → (nullable) {shaka.extern.Stream}

Get the active stream for the given type. Returns null if there is no stream for the given type.
Parameters:
Name Type Description
type shaka.util.ManifestParserUtils.ContentType
Source:
Returns:
Type
shaka.extern.Stream

(private) getTimeNeeded_(mediaState, playheadTime) → {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_
playheadTime number
Source:
Throws:
if the buffer is inconsistent with our expectations.
Type
shaka.util.Error
Returns:
The next timestamp needed.
Type
number

(private) handlePeriodTransition_(mediaState)

Calls onChooseStreams() when necessary.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_ The last MediaState updated.
Source:

(private) handleQuotaExceeded_(mediaState, errornon-null)

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

(private) handleStartup_(mediaState, stream)

Sets up all known Periods when startup completes; otherwise, does nothing.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_ The last MediaState updated.
stream shaka.extern.Stream
Source:

(private) handleStreamingError_(errornon-null)

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:

init() → (non-null) {Promise}

Initializes the StreamingEngine. After this function is called the StreamingEngine will call onChooseStreams(p) when it needs to buffer Period p and onCanSwitch() when any Stream within that Period may be switched to. After the StreamingEngine calls onChooseStreams(p) for the first time, it will begin setting up the Streams returned from that function and subsequently switch to them. However, the StreamingEngine will not begin setting up any other Streams until at least one segment from each of the initial set of Streams has been buffered (this reduces startup latency). After the StreamingEngine completes this startup phase it will begin setting up each Period's Streams (while buffering in parrallel). When the StreamingEngine needs to buffer the next Period it will have already set up that Period's Streams. So, when the StreamingEngine calls onChooseStreams(p) after the first time, the StreamingEngine will immediately switch to the Streams returned from that function.
Source:
Returns:
Type
Promise

(private) initSourceBuffer_(mediaState, currentPeriodIndex, appendWindowStart, appendWindowEnd) → (non-null) {Promise}

Sets the given MediaState's associated SourceBuffer's timestamp offset and init segment if either are required. 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_
currentPeriodIndex number
appendWindowStart number
appendWindowEnd number
Source:
Returns:
Type
Promise

(private) initStreams_(chosenStreams, resumeAtopt) → (non-null) {Promise}

Initializes the given streams and media states if required. This will schedule updates for the given types.
Parameters:
Name Type Attributes Description
chosenStreams shaka.media.StreamingEngine.ChosenStreams
resumeAt number <optional>
Source:
Returns:
Type
Promise

loadNewTextStream(stream, createMediaState) → (non-null) {Promise}

Notifies StreamingEngine that a new text stream was added to the manifest. This initializes the given stream. This returns a Promise that resolves when the stream has been set up, and a media state has been created.
Parameters:
Name Type Description
stream shaka.extern.Stream
createMediaState boolean
Source:
Returns:
Type
Promise

(private) lookupSegmentPosition_(mediaState, presentationTime, currentPeriodIndex) → (nullable) {number}

Looks up the position of the segment containing the given timestamp.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
presentationTime number The timestamp needed, relative to the start of the presentation.
currentPeriodIndex number
Source:
Returns:
A segment position, or null if a segment was not be found.
Type
number

(private) onUpdate_(mediaStatenon-null)

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

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

Parse the EMSG box from a MP4 container.
Parameters:
Name Type Attributes Description
period shaka.extern.Period
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:

retry() → {boolean}

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

(private) 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:

(private) 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:

(private) setupPeriod_(periodIndex) → (non-null) {Promise}

Sets up the given Period if necessary. Calls onError() if an error occurs.
Parameters:
Name Type Description
periodIndex number The Period's index.
Source:
Returns:
A Promise which resolves when the given Period is set up.
Type
Promise

(private) setupStreams_(streamsnon-null) → (non-null) {Promise}

Sets up the given Streams if necessary. Does NOT call onError() if an error occurs.
Parameters:
Name Type Description
streams Array.<!shaka.extern.Stream>
Source:
Returns:
Type
Promise

(private) switchInternal_(stream, clearBuffer, safeMargin)

Switches to the given Stream. |stream| may be from any Variant or any Period.
Parameters:
Name Type Description
stream shaka.extern.Stream
clearBuffer boolean
safeMargin number
Source:

switchTextStream(textStream)

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

switchVariant(variant, clearBuffer, safeMargin)

Parameters:
Name Type Description
variant shaka.extern.Variant
clearBuffer boolean
safeMargin number
Source:

unloadTextStream()

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

(private) update_(mediaState) → (nullable) {number}

Updates the given MediaState.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
Source:
Throws:
if an error occurs.
Type
shaka.util.Error
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

ChosenStreams

Type:
Properties:
Name Type Attributes Description
variant shaka.extern.Variant | undefined The chosen variant. May be omitted for text re-init.
text shaka.extern.Stream <nullable>
 The chosen text stream.
Source:

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.
lastStream shaka.extern.Stream <nullable>
 The Stream of the last segment that was appended.
lastSegmentReference shaka.media.SegmentReference The SegmentReference of the last segment that was appended.
restoreStreamAfterTrickPlay shaka.extern.Stream <nullable>
 The Stream to restore after trick play mode is turned off.
needInitSegment boolean True indicates that |stream|'s init segment must be inserted before the next media segment is appended.
endOfStream boolean True indicates that the end of the buffer has hit the end of the presentation.
needPeriodIndex number The index of the Period which needs to be buffered.
performingUpdate boolean True indicates that an update is in progress.
updateTimer number <nullable>
 A non-null value indicates that an update is scheduled.
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.
resumeAt number An override for the time to start performing updates at. If the playhead is behind this time, update_() will still start fetching segments from this time. If the playhead is ahead of the time, this field is ignored.
Source:

PlayerInterface

Type:
Properties:
Name Type Description
playhead shaka.media.Playhead The Playhead. The caller retains ownership.
mediaSourceEngine shaka.media.MediaSourceEngine The MediaSourceEngine. The caller retains ownership.
netEngine shaka.net.NetworkingEngine The NetworkingEngine instance to use. The caller retains ownership.
onChooseStreams function Called by StreamingEngine when the given Period needs to be buffered. StreamingEngine will switch to the variant and text stream returned from this function. The owner cannot call switch() directly until the StreamingEngine calls onCanSwitch().
onCanSwitch function Called by StreamingEngine when the Period is set up and switching is permitted.
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.
onInitialStreamsSetup function | undefined Optional callback which is called when the initial set of Streams have been setup. Intended to be used by tests.
onStartupComplete function | undefined Optional callback which is called when startup has completed. Intended to be used by tests.
Source: