Interface: shaka.media.IStream

IStream provides an interface to present streams. A stream is data, which may be fragmented into multiple segments, that can be presented to the user (e.g., aurally or visually). A StreamInfo object describes an individual stream. IStream does not dictate a presentation medium or mechanism; Stream implementations may present streams however they wish (e.g., via an HTMLMediaElement).

Stream callers (i.e., clients) can use a single Stream object to present one or more streams, but a Stream object can only present one stream at one time (note that multiple Stream objects can present multiple streams in parallel). Stream implementations should support stream switching, although this may not be possible for all stream types. Furthermore, Streams may support just one stream type (e.g., text) or multiple stream types (e.g., audio and video).

Stream implementations must implement the IStream state model, which enables callers to deduce which state the Stream is in based upon its interaction with the Stream. The IStream state model consists of the following states

  1. idle
    The caller has created the Stream but has not called switch().
  2. startup
    The caller has called switch(), and the Stream is performing its initialization sequence (see shaka.media.IStream#started). If the Stream encounters an error during startup then it must reject its started() Promise. Stream implementations may treat errors during startup as either recoverable or unrecoverable and may provide their own recovery mechanism if they so choose.
  3. waiting
    The Stream has completed startup, but the caller has not signalled the Stream to proceed (see shaka.media.IStream#started).
  4. streaming
    The caller has signalled the Stream to proceed, and the Stream is processing and presenting data. If the Stream encounters an error while streaming then it should attempt to recover, fire an error event, or do both.
  5. ended
    The Stream has no more data available but may still be presenting data.
And state transitions 
idle --> startup --> waiting --> streaming --> ended --+
                                     ^                 |
                                     |                 |
                                     +-----------------+

Implementations:
Extends:
  • EventTarget
Source:

Methods

configure(confignon-null)

Configures the Stream options. Options are set via key-value pairs.
Parameters:
Name Type Description
config Object.<string, *> A configuration object, which contains the configuration options as key-value pairs. All fields should have already been validated.
Implementations:
Source:
Example
stream.configure({'streamBufferSize': 20});

destroy()

Destroys the Stream.
Implementations:
Source:

getEnabled() → {boolean}

Implementations:
Source:
Returns:
True if the stream is enabled; otherwise, return false.
Type
boolean

getSegmentIndex() → {shaka.media.SegmentIndex}

Gets the SegmentIndex of the StreamInfo that corresponds to the stream that is currently being processed or presented. Note that this SegmentIndex may be different than the SegmentIndex of the last StreamInfo that was passed to switch() (see shaka.media.IStream#switch).
Implementations:
Source:
Returns:
Type
shaka.media.SegmentIndex

getStreamInfo() → {shaka.media.StreamInfo}

Gets the StreamInfo that corresponds to the stream that is currently being processed or presented. Note that this StreamInfo may be different than the last StreamInfo that was passed to switch() (see shaka.media.IStream#switch).
Implementations:
Source:
Returns:
Type
shaka.media.StreamInfo

hasEnded() → {boolean}

Returns true if the stream has ended; otherwise, returns false. The Stream can only end while it's in the 'streaming' state.
Implementations:
Source:
Returns:
True if the stream has ended; otherwise, return false.
Type
boolean

isBuffered(time) → {boolean}

Gets whether the given time is currently buffered by the stream.
Parameters:
Name Type Description
time number The time in seconds to check.
Implementations:
Source:
Returns:
Type
boolean

resync()

Resynchronizes the Stream's current position, e.g., to the video's playhead, or does nothing if the Stream does not require manual resynchronization.
Implementations:
Source:

setEnabled(enabled)

Enables or disables stream presentation or does nothing if the Stream cannot disable stream presentation.
Parameters:
Name Type Description
enabled boolean
Implementations:
Source:

started(proceednon-null) → (non-null) {Promise.<number>}

Returns a promise that the Stream will resolve immediately after startup (i.e., the Stream's initialization sequence) completes. Stream implementations may implement startup as they wish but startup should entail acquiring some initial resources. Implementations must resolve the returned Promise if startup completes and reject the returned Promise if startup fails. This function can only be called once.
Parameters:
Name Type Description
proceed Promise A Promise that the caller must resolve after startup completes to signal the Stream that it can proceed. The Stream will idle while in the 'waiting' state. Callers must never reject |proceed|.
Implementations:
Source:
Returns:
A promise to a timestamp correction, which is the number of seconds that the media timeline (the sequence of timestamps in the stream's media segments) is offset from the Stream's initial StreamInfo's SegmentIndex (which is an approximation of the stream's media timeline). For example, if the timestamp correction is 5 then a SegmentReference that has a start time of 10 would correspond to a segment that actually starts at 15. For well formed content, the absolute value of the timestamp correction should be small, specifically, less than the duration of any one segment in the stream.
Type
Promise.<number>

switch(streamInfonon-null, clearBuffer, opt_clearBufferOffsetopt)

Starts presenting the specified stream. Stream implementations may implement stream switching asynchronously, in which case, they must implement the switch state model, which consists of the following states
  1. acquiring-metadata
    The caller has called switch(), and the Stream is acquiring the new stream's metadata, but the stream itself is not being processed; getStreamInfo() and getSegmentIndex() must not return the new StreamInfo and SegmentIndex.
  2. processing
    The Stream is processing the new stream's content, but the stream's content is not buffered yet; getStreamInfo() and getSegmentIndex() must return the new StreamInfo and SegmentIndex.
  3. buffered
    The Stream has buffered some of the new stream's content (e.g., at least one segment), but the Stream may or may not be presenting the new stream's content, i.e., the Stream's current position may or may not be within the new stream's buffered range at this time.
Stream implementations must fire an AdaptationEvent when/after transitioning from the 'processing' state to the 'buffered' state.
Parameters:
Name Type Attributes Description
streamInfo shaka.media.StreamInfo
clearBuffer boolean If true, removes the previous stream's content before switching to the new stream.
opt_clearBufferOffset number <optional>
 if |clearBuffer| and |opt_clearBufferOffset| are truthy, clear the stream buffer from the given offset (relative to the Stream's current position) to the end of the stream.
Implementations:
Source:

Events

AdaptationEvent

Fired when an audio, video, or text track has changed, or more specifically, when the Stream has buffered at least one segment of a new stream. Bubbles up through the Player.
Properties:
Name Type Attributes Description
type string 'adaptation'
bubbles boolean true
contentType string The new stream's content type, e.g., 'audio', 'video', or 'text'.
size ?{width: number, height: number} <nullable>
 The new stream's resolution, if applicable. Note: the new stream may not start presenting immediately (see shaka.media.IStream#switch), so the user may not see the resolution change immediately.
bandwidth number The new stream's bandwidth requirement in bits per second.
Source: