shaka-player/lib/media/i_stream.js

/**
 * @license
 * Copyright 2015 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

goog.provide('shaka.media.IStream');

goog.require('shaka.media.StreamInfo');



/**
 * <p>
 * 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).
 * </p>
 *
 * <p>
 * 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).
 * </p>
 *
 * <p>
 * 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
 * <ol>
 * <li>
 *   <b>idle</b> <br>
 *   The caller has created the Stream but has not called switch().
 *
 * <li>
 *   <b>startup</b> <br>
 *   The caller has called switch(), and the Stream is performing its
 *   initialization sequence (see {@link 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.
 *
 * <li>
 *   <b>waiting</b> <br>
 *   The Stream has completed startup, but the caller has not signalled the
 *   Stream to proceed (see {@link shaka.media.IStream#started}).
 *
 * <li>
 *   <b>streaming</b> <br>
 *   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.
 *
 * <li>
 *   <b>ended</b> <br>
 *   The Stream has no more data available but may still be presenting data.
 * </ol>
 *
 * And state transitions
 * <pre>
 * idle --> startup --> waiting --> streaming --> ended --+
 *                                      ^                 |
 *                                      |                 |
 *                                      +-----------------+
 * </pre>
 * </p>
 *
 * @interface
 * @extends {EventTarget}
 */
shaka.media.IStream = function() {};


/**
 * @event shaka.media.IStream.AdaptationEvent
 * @description 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.
 * @property {string} type 'adaptation'
 * @property {boolean} bubbles true
 * @property {string} contentType The new stream's content type, e.g., 'audio',
 *     'video', or 'text'.
 * @property {?{width: number, height: number}} size The new stream's
 *     resolution, if applicable. Note: the new stream may not start presenting
 *     immediately (see {@link shaka.media.IStream#switch}), so the user may not
 *     see the resolution change immediately.
 * @property {number} bandwidth The new stream's bandwidth requirement in
 *     bits per second.
 * @export
 */


/**
 * Configures the Stream options. Options are set via key-value pairs.
 *
 * @example
 *     stream.configure({'streamBufferSize': 20});
 *
 * @param {!Object.<string, *>} config A configuration object, which contains
 *     the configuration options as key-value pairs. All fields should have
 *     already been validated.
 */
shaka.media.IStream.prototype.configure = function(config) {};


/**
 * Destroys the Stream.
 */
shaka.media.IStream.prototype.destroy = function() {};


/**
 * 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 {@link shaka.media.IStream#switch}).
 *
 * @return {shaka.media.StreamInfo}
 */
shaka.media.IStream.prototype.getStreamInfo = function() {};


/**
 * 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 {@link shaka.media.IStream#switch}).
 *
 * @return {shaka.media.SegmentIndex}
 */
shaka.media.IStream.prototype.getSegmentIndex = function() {};


/**
 * 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.
 *
 * @param {!Promise} proceed 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|.
 * @return {!Promise.<number>} 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.
 */
shaka.media.IStream.prototype.started = function(proceed) {};


/**
 * Returns true if the stream has ended; otherwise, returns false. The Stream
 * can only end while it's in the 'streaming' state.
 *
 * @return {boolean} True if the stream has ended; otherwise, return false.
 */
shaka.media.IStream.prototype.hasEnded = function() {};


/**
 * 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
 * <ol>
 * <li>
 *   <b>acquiring-metadata</b> <br>
 *   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.
 *
 * <li>
 *   <b>processing</b> <br>
 *   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.
 *
 * <li>
 *   <b>buffered</b> <br>
 *   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.
 * </ol>
 *
 * Stream implementations must fire an AdaptationEvent when/after transitioning
 * from the 'processing' state to the 'buffered' state.
 *
 * @param {!shaka.media.StreamInfo} streamInfo
 * @param {boolean} clearBuffer If true, removes the previous stream's content
 *     before switching to the new stream.
 * @param {number=} opt_clearBufferOffset 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.
 */
shaka.media.IStream.prototype.switch = function(
    streamInfo, clearBuffer, opt_clearBufferOffset) {};


/**
 * Resynchronizes the Stream's current position, e.g., to the video's playhead,
 * or does nothing if the Stream does not require manual resynchronization.
 */
shaka.media.IStream.prototype.resync = function() {};


/**
 * Gets whether the given time is currently buffered by the stream.
 *
 * @param {number} time The time in seconds to check.
 * @return {boolean}
 */
shaka.media.IStream.prototype.isBuffered = function(time) {};


/**
 * Enables or disables stream presentation or does nothing if the Stream cannot
 * disable stream presentation.
 *
 * @param {boolean} enabled
 */
shaka.media.IStream.prototype.setEnabled = function(enabled) {};


/**
 * @return {boolean} True if the stream is enabled; otherwise, return false.
 */
shaka.media.IStream.prototype.getEnabled = function() {};