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 |
shakaExtern.Manifest | |
playerInterface |
shaka.media.StreamingEngine.PlayerInterface |
- Implements:
- Source:
Members
(private, static, constant) 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/google/shaka-player/issues/1597
Type:
- number
- Source:
(private, static, constant) 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/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) 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:
- Array.<?{promise: shaka.util.PublicPromise, resolved: boolean}>
- 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:
- Object.<number, ?{promise: shaka.util.PublicPromise, resolved: 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) 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) 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 |
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) 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)
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.
Must be called at least once before init().
Parameters:
Name | Type | Description |
---|---|---|
config |
shakaExtern.StreamingConfiguration |
- Source:
(private) createMediaState_(stream, needPeriodIndex, opt_resumeAtopt) → {shaka.media.StreamingEngine.MediaState_}
Creates a media state.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
stream |
shakaExtern.Stream | ||
needPeriodIndex |
number | ||
opt_resumeAt |
number |
<optional> |
- Source:
Returns:
(export) 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
getActiveAudio() → (nullable) {shakaExtern.Stream}
Get the active audio stream. Returns null if there is no audio streaming.
- Source:
Returns:
- Type
- shakaExtern.Stream
getActivePeriod() → (nullable) {shakaExtern.Period}
Gets the Period in which we are currently buffering. This might be different
from the Period which contains the Playhead.
- Source:
Returns:
- Type
- shakaExtern.Period
getActiveText() → (nullable) {shakaExtern.Stream}
Get the active text stream. Returns null if there is no text streaming.
- Source:
Returns:
- Type
- shakaExtern.Stream
getActiveVideo() → (nullable) {shakaExtern.Stream}
Get the active video stream. Returns null if there is no video streaming.
- Source:
Returns:
- Type
- 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 might 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:
(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.
(private) getStream_(type) → (nullable) {shakaExtern.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
- shakaExtern.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 |
shakaExtern.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, 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 |
---|---|---|---|
chosenStreams |
shaka.media.StreamingEngine.ChosenStreams | ||
opt_resumeAt |
number |
<optional> |
- Source:
Returns:
- Type
- Promise
loadNewTextStream(stream) → (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 |
shakaExtern.Stream |
- 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, boxnon-null)
Parse the EMSG box from a MP4 container.
Parameters:
Name | Type | Description |
---|---|---|
period |
shakaExtern.Period | |
reference |
shaka.media.SegmentReference | |
box |
shakaExtern.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.<!shakaExtern.Stream> |
- Source:
Returns:
- Type
- Promise
(private) switchInternal_(stream, clearBuffer)
Switches to the given Stream. |stream| may be from any Variant or any Period.
Parameters:
Name | Type | Description |
---|---|---|
stream |
shakaExtern.Stream | |
clearBuffer |
boolean |
- Source:
switchTextStream(textStream)
Parameters:
Name | Type | Description |
---|---|---|
textStream |
shakaExtern.Stream |
- Source:
switchVariant(variant, clearBuffer)
Parameters:
Name | Type | Description |
---|---|---|
variant |
shakaExtern.Variant | |
clearBuffer |
boolean |
- 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:
- {variant: (?shakaExtern.Variant|undefined), text: ?shakaExtern.Stream}
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
variant |
shakaExtern.Variant | undefined | The chosen variant. May be omitted for text re-init. | |
text |
shakaExtern.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:
- {type: shaka.util.ManifestParserUtils.ContentType, stream: shakaExtern.Stream, lastStream: ?shakaExtern.Stream, lastSegmentReference: shaka.media.SegmentReference, restoreStreamAfterTrickPlay: ?shakaExtern.Stream, 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 |
shaka.util.ManifestParserUtils.ContentType | 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. | |
restoreStreamAfterTrickPlay |
shakaExtern.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. | |
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:
- {playhead: !shaka.media.Playhead, mediaSourceEngine: !shaka.media.MediaSourceEngine, netEngine: shaka.net.NetworkingEngine, onChooseStreams: function(!shakaExtern.Period): shaka.media.StreamingEngine.ChosenStreams, onCanSwitch: function(), onError: function(!shaka.util.Error), onEvent: function(!Event), onManifestUpdate: function(), onSegmentAppended: function(), onInitialStreamsSetup: (function()|undefined), onStartupComplete: (function()|undefined)}
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: