Class: shaka.media.StreamingEngine

Constructor

new StreamingEngine(playheadnon-null, mediaSourceEnginenon-null, netEngine, manifest, onChooseStreams, onCanSwitch, onError, opt_onInitialStreamsSetupopt, opt_onStartupCompleteopt)

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 Attributes 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
manifest shakaExtern.Manifest
onChooseStreams function(!shakaExtern.Period): !Object.<string, shakaExtern.Stream> Called when the given Period needs to be buffered. The StreamingEngine will switch to the Streams returned from this function. The caller cannot call switch() directly until the StreamingEngine calls onCanSwitch()
onCanSwitch function() Called when any Stream within the current Period may be switched to.
onError function(!shaka.util.Error) Called when an error occurs. If the error is recoverable (see @link{shaka.util.Error}) then the caller may invoke either StreamingEngine.switch() or StreamingEngine.seeked() to attempt recovery.
opt_onInitialStreamsSetup function()= <optional>
 Optional callback which is called when the initial set of Streams have been setup. Intended to be used by tests.
opt_onStartupComplete function()= <optional>
 Optional callback which is called when startup has completed. Intended to be used by tests.
Implements:
Source:

Members

(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_ :shakaExtern.StreamingConfiguration

Type:
Source:

(private) destroyed_ :boolean

Type:
  • boolean
Source:

(private) fatalError_ :boolean

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

(private, nullable) manifest_ :shakaExtern.Manifest

Type:
Source:

(private) mediaSourceEngine_ :shaka.media.MediaSourceEngine

Type:
Source:

(private) mediaStates_ :Object.<string, !shaka.media.StreamingEngine.MediaState_>

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

(constant) MIN_BUFFER_LENGTH :number

The minimum number seconds that will remain buffered after evicting media.
Type:
  • number
Source:

(private) netEngine_ :shaka.net.NetworkingEngine

Type:
Source:

(private, nullable) onCanSwitch_ :?function()

Type:
  • ?function()
Source:

(private, nullable) onChooseStreams_ :?function(!shakaExtern.Period): !Object.<string, shakaExtern.Stream>

Type:
Source:

(private, nullable) onError_ :?function(!shaka.util.Error)

Type:
Source:

(private, nullable) onInitialStreamsSetup_ :?function()

Type:
  • ?function()
Source:

(private, nullable) onStartupComplete_ :?function()

Type:
  • ?function()
Source:

(private) playhead_ :shaka.media.Playhead

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:

Methods

(static) getRebufferingGoal(manifest, config, scaleFactor) → {number}

Gets the StreamingEngine's rebuffering goal.
Parameters:
Name Type Description
manifest shakaExtern.Manifest
config shakaExtern.StreamingConfiguration
scaleFactor number
Source:
Returns:
Type
number

(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 shakaExtern.Period
stream shakaExtern.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) clearBuffer_(mediaStatenon-null, flush)

Clears the buffer and schedules another update.
Parameters:
Name Type Description
mediaState shaka.media.StreamingEngine.MediaState_
flush boolean
Source:

configure(config)

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

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

Destroys the object, 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 shakaExtern.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

getActiveStreams() → (non-null) {Object.<string, shakaExtern.Stream>}

Gets a map of all the active streams.
Source:
Returns:
Type
Object.<string, shakaExtern.Stream>

(private) getBufferingGoal_() → {number}

Computes buffering goal.
Source:
Returns:
Type
number

getCurrentPeriod() → {shakaExtern.Period}

Gets the current Period the stream is in. This Period may not be initialized yet if canSwitch(period) has not been called yet.
Source:
Returns:
Type
shakaExtern.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, or null if a segment could not be found, does not exist, or is not available.
Type
shaka.media.SegmentReference

(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) handleNetworkError_(mediaState, errornon-null)

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

(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 shakaExtern.Stream
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, appendWindowEndnullable) → (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 Attributes Description
mediaState shaka.media.StreamingEngine.MediaState_
currentPeriodIndex number
appendWindowEnd number <nullable>
Source:
Returns:
Type
Promise

(private) initStreams_(streamsByTypenon-null, opt_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
streamsByType Object.<string, shakaExtern.Stream>
opt_resumeAt number <optional>
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

notifyNewStream(type, stream) → (non-null) {Promise}

Notifies StreamingEngine that a new stream was added to the manifest. This initializes the given stream. This returns a Promise that resolves when the stream has been set up.
Parameters:
Name Type Description
type string
stream shakaExtern.Stream
Source:
Returns:
Type
Promise

(private) onUpdate_(mediaStatenon-null)

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

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

(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 is resolved when the given Period is setup.
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.<!shakaExtern.Stream>
Source:
Returns:
Type
Promise

switch(contentType, stream, clearBuffer)

Switches to the given Stream. |stream| may be from any StreamSet or any Period.
Parameters:
Name Type Description
contentType string |stream|'s content type.
stream shakaExtern.Stream
clearBuffer boolean
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

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:
  • {type: string, stream: shakaExtern.Stream, lastStream: ?shakaExtern.Stream, lastSegmentReference: shaka.media.SegmentReference, needInitSegment: boolean, needPeriodIndex: number, endOfStream: boolean, performingUpdate: boolean, updateTimer: ?number, waitingToClearBuffer: boolean, waitingToFlushBuffer: boolean, clearingBuffer: boolean, recovering: boolean, hasError: boolean, resumeAt: number}
Properties:
Name Type Attributes Description
type string The stream's content type, e.g., 'audio', 'video', or 'text'.
stream shakaExtern.Stream The current Stream.
lastStream shakaExtern.Stream <nullable>
 The Stream of the last segment that was appended.
lastSegmentReference shaka.media.SegmentReference The SegmentReference of the last segment that was appended.
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.
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 updates.
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: