/**
* @license
* Copyright 2016 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.
*/
/** @externs */
/**
* @typedef {{
* timestamp: number,
* id: number,
* type: string,
* fromAdaptation: boolean,
* bandwidth: ?number
* }}
*
* @property {number} timestamp
* The timestamp the choice was made, in seconds since 1970
* (i.e. Date.now() / 1000).
* @property {number} id
* The id of the track that was chosen.
* @property {string} type
* The type of track chosen ('variant' or 'text').
* @property {boolean} fromAdaptation
* True if the choice was made by AbrManager for adaptation; false if it
* was made by the application through selectTrack.
* @property {?number} bandwidth
* The bandwidth of the chosen track (null for text).
* @exportDoc
*/
shakaExtern.TrackChoice;
/**
* @typedef {{
* timestamp: number,
* state: string,
* duration: number
* }}
*
* @property {number} timestamp
* The timestamp the state was entered, in seconds since 1970
* (i.e. Date.now() / 1000).
* @property {string} state
* The state the player entered. This could be 'buffering', 'playing',
* 'paused', or 'ended'.
* @property {number} duration
* The number of seconds the player was in this state. If this is the last
* entry in the list, the player is still in this state, so the duration will
* continue to increase.
* @exportDoc
*/
shakaExtern.StateChange;
/**
* @typedef {{
* width: number,
* height: number,
* streamBandwidth: number,
*
* decodedFrames: number,
* droppedFrames: number,
* estimatedBandwidth: number,
*
* loadLatency: number,
* playTime: number,
* bufferingTime: number,
*
* switchHistory: !Array.<shakaExtern.TrackChoice>,
* stateHistory: !Array.<shakaExtern.StateChange>
* }}
*
* @description
* Contains statistics and information about the current state of the player.
* This is meant for applications that want to log quality-of-experience (QoE)
* or other stats. These values will reset when load() is called again.
*
* @property {number} width
* The width of the current video track.
* @property {number} height
* The height of the current video track.
* @property {number} streamBandwidth
* The bandwidth required for the current streams (total, in bit/sec).
*
* @property {number} decodedFrames
* The total number of frames decoded by the Player. This may be NaN if this
* is not supported by the browser.
* @property {number} droppedFrames
* The total number of frames dropped by the Player. This may be NaN if this
* is not supported by the browser.
* @property {number} estimatedBandwidth
* The current estimated network bandwidth (in bit/sec).
*
* @property {number} loadLatency
* This is the number of seconds it took for the video element to have enough
* data to begin playback. This is measured from the time load() is called to
* the time the 'loadeddata' event is fired by the media element.
* @property {number} playTime
* The total time spent in a playing state in seconds.
* @property {number} bufferingTime
* The total time spent in a buffering state in seconds.
*
* @property {!Array.<shakaExtern.TrackChoice>} switchHistory
* A history of the stream changes.
* @property {!Array.<shakaExtern.StateChange>} stateHistory
* A history of the state changes.
* @exportDoc
*/
shakaExtern.Stats;
/**
* @typedef {{
* start: number,
* end: number
* }}
*
* @description
* Contains the times of a range of buffered content.
*
* @property {number} start
* The start time of the range, in seconds.
* @property {number} end
* The end time of the range, in seconds.
* @exportDoc
*/
shakaExtern.BufferedRange;
/**
* @typedef {{
* total: !Array.<shakaExtern.BufferedRange>,
* audio: !Array.<shakaExtern.BufferedRange>,
* video: !Array.<shakaExtern.BufferedRange>,
* text: !Array.<shakaExtern.BufferedRange>
* }}
*
* @description
* Contains information about the current buffered ranges.
*
* @property {!Array.<shakaExtern.BufferedRange>} total
* The combined audio/video buffered ranges, reported by |video.buffered|.
* @property {!Array.<shakaExtern.BufferedRange>} audio
* The buffered ranges for audio content.
* @property {!Array.<shakaExtern.BufferedRange>} video
* The buffered ranges for video content.
* @property {!Array.<shakaExtern.BufferedRange>} text
* The buffered ranges for text content.
* @exportDoc
*/
shakaExtern.BufferedInfo;
/**
* @typedef {{
* id: number,
* active: boolean,
*
* type: string,
* bandwidth: number,
*
* language: string,
* label: ?string,
* kind: ?string,
* width: ?number,
* height: ?number,
* frameRate: ?number,
* mimeType: ?string,
* codecs: ?string,
* audioCodec: ?string,
* videoCodec: ?string,
* primary: boolean,
* roles: !Array.<string>,
* videoId: ?number,
* audioId: ?number,
* channelsCount: ?number,
* audioBandwidth: ?number,
* videoBandwidth: ?number
* }}
*
* @description
* An object describing a media track. This object should be treated as
* read-only as changing any values does not have any effect. This is the
* public view of an audio/video paring (variant type) or text track (text
* type).
*
* @property {number} id
* The unique ID of the track.
* @property {boolean} active
* If true, this is the track being streamed (another track may be
* visible/audible in the buffer).
*
* @property {string} type
* The type of track, either 'variant' or 'text'.
* @property {number} bandwidth
* The bandwidth required to play the track, in bits/sec.
*
* @property {string} language
* The language of the track, or 'und' if not given. This is the exact
* value provided in the manifest; it may need to be normalized.
* @property {?string} label
* The track label, which is unique text that should describe the track.
* @property {?string} kind
* (only for text tracks) The kind of text track, either 'caption' or
* 'subtitle'.
* @property {?number} width
* The video width provided in the manifest, if present.
* @property {?number} height
* The video height provided in the manifest, if present.
* @property {?number} frameRate
* The video framerate provided in the manifest, if present.
* @property {?string} mimeType
* The MIME type of the content provided in the manifest.
* @property {?string} codecs
* The audio/video codecs string provided in the manifest, if present.
* @property {?string} audioCodec
* The audio codecs string provided in the manifest, if present.
* @property {?string} videoCodec
* The video codecs string provided in the manifest, if present.
* @property {boolean} primary
* True indicates that this in the primary language for the content.
* This flag is based on signals from the manifest.
* This can be a useful hint about which language should be the default, and
* indicates which track Shaka will use when the user's language preference
* cannot be satisfied.
* @property {!Array.<string>} roles
* The roles of the track, e.g. 'main', 'caption', or 'commentary'.
* @property {?number} videoId
* (only for variant tracks) The video stream id.
* @property {?number} audioId
* (only for variant tracks) The audio stream id.
* @property {?number} channelsCount
* The count of the audio track channels.
* @property {?number} audioBandwidth
* (only for variant tracks) The audio stream's bandwidth if known.
* @property {?number} videoBandwidth
* (only for variant tracks) The video stream's bandwidth if known.
* @exportDoc
*/
shakaExtern.Track;
/**
* @typedef {{
* minWidth: number,
* maxWidth: number,
* minHeight: number,
* maxHeight: number,
* minPixels: number,
* maxPixels: number,
*
* minBandwidth: number,
* maxBandwidth: number
* }}
*
* @description
* An object describing application restrictions on what tracks can play. All
* restrictions must be fulfilled for a track to be playable/selectable.
* The restrictions system behaves somewhat differently at the ABR level and the
* player level, so please refer to the documentation for those specific
* settings.
*
* @see shakaExtern.PlayerConfiguration
* @see shakaExtern.AbrConfiguration
*
* @property {number} minWidth
* The minimum width of a video track, in pixels.
* @property {number} maxWidth
* The maximum width of a video track, in pixels.
* @property {number} minHeight
* The minimum height of a video track, in pixels.
* @property {number} maxHeight
* The maximum height of a video track, in pixels.
* @property {number} minPixels
* The minimum number of total pixels in a video track (i.e. width * height).
* @property {number} maxPixels
* The maximum number of total pixels in a video track (i.e. width * height).
*
* @property {number} minBandwidth
* The minimum bandwidth of a variant track, in bit/sec.
* @property {number} maxBandwidth
* The maximum bandwidth of a variant track, in bit/sec.
* @exportDoc
*/
shakaExtern.Restrictions;
/**
* @typedef {{
* persistentState: boolean
* }}
*
* @property {boolean} persistentState
* Whether this key system supports persistent state.
* @exportDoc
*/
shakaExtern.DrmSupportType;
/**
* @typedef {{
* manifest: !Object.<string, boolean>,
* media: !Object.<string, boolean>,
* drm: !Object.<string, ?shakaExtern.DrmSupportType>
* }}
*
* @description
* An object detailing browser support for various features.
*
* @property {!Object.<string, boolean>} manifest
* A map of supported manifest types.
* The keys are manifest MIME types and file extensions.
* @property {!Object.<string, boolean>} media
* A map of supported media types.
* The keys are media MIME types.
* @property {!Object.<string, ?shakaExtern.DrmSupportType>} drm
* A map of supported key systems.
* The keys are the key system names. The value is null if it is not
* supported. Key systems not probed will not be in this dictionary.
*
* @exportDoc
*/
shakaExtern.SupportType;
/**
* @typedef {{
* schemeIdUri: string,
* value: string,
* startTime: number,
* endTime: number,
* id: string,
* eventElement: Element
* }}
*
* @description
* Contains information about a region of the timeline that will cause an event
* to be raised when the playhead enters or exits it. In DASH this is the
* EventStream element.
*
* @property {string} schemeIdUri
* Identifies the message scheme.
* @property {string} value
* Specifies the value for the region.
* @property {number} startTime
* The presentation time (in seconds) that the region should start.
* @property {number} endTime
* The presentation time (in seconds) that the region should end.
* @property {string} id
* Specifies an identifier for this instance of the region.
* @property {Element} eventElement
* The XML element that defines the Event.
* @exportDoc
*/
shakaExtern.TimelineRegionInfo;
/**
* @typedef {{
* schemeIdUri: string,
* value: string,
* startTime: number,
* endTime: number,
* timescale: number,
* presentationTimeDelta: number,
* eventDuration: number,
* id: number,
* messageData: Uint8Array
* }}
*
* @description
* Contains information about an EMSG MP4 box.
*
* @property {string} schemeIdUri
* Identifies the message scheme.
* @property {string} value
* Specifies the value for the event.
* @property {number} startTime
* The time that the event starts (in presentation time).
* @property {number} endTime
* The time that the event ends (in presentation time).
* @property {number} timescale
* Provides the timescale, in ticks per second.
* @property {number} presentationTimeDelta
* The offset that the event starts, relative to the start of the segment
* this is contained in (in units of timescale).
* @property {number} eventDuration
* The duration of the event (in units of timescale).
* @property {number} id
* A field identifying this instance of the message.
* @property {Uint8Array} messageData
* Body of the message.
* @exportDoc
*/
shakaExtern.EmsgInfo;
/**
* @typedef {function(!Element):Array.<shakaExtern.DrmInfo>}
* @see shakaExtern.DashManifestConfiguration
* @exportDoc
*/
shakaExtern.DashContentProtectionCallback;
/**
* @typedef {{
* distinctiveIdentifierRequired: boolean,
* persistentStateRequired: boolean,
* videoRobustness: string,
* audioRobustness: string,
* serverCertificate: Uint8Array
* }}
*
* @property {boolean} distinctiveIdentifierRequired
* <i>Defaults to false.</i> <br>
* True if the application requires the key system to support distinctive
* identifiers.
* @property {boolean} persistentStateRequired
* <i>Defaults to false.</i> <br>
* True if the application requires the key system to support persistent
* state, e.g., for persistent license storage.
* @property {string} videoRobustness
* A key-system-specific string that specifies a required security level for
* video.
* <i>Defaults to '', i.e., no specific robustness required.</i> <br>
* @property {string} audioRobustness
* A key-system-specific string that specifies a required security level for
* audio.
* <i>Defaults to '', i.e., no specific robustness required.</i> <br>
* @property {Uint8Array} serverCertificate
* <i>Defaults to null.</i> <br>
* <i>An empty certificate (byteLength 0) will be treated as null.</i> <br>
* <i>A certificate will be requested from the license server if
* required.</i> <br>
* A key-system-specific server certificate used to encrypt license requests.
* Its use is optional and is meant as an optimization to avoid a round-trip
* to request a certificate.
*
* @exportDoc
*/
shakaExtern.AdvancedDrmConfiguration;
/**
* @typedef {{
* retryParameters: shakaExtern.RetryParameters,
* servers: !Object.<string, string>,
* clearKeys: !Object.<string, string>,
* delayLicenseRequestUntilPlayed: boolean,
* advanced: Object.<string, shakaExtern.AdvancedDrmConfiguration>
* }}
*
* @property {shakaExtern.RetryParameters} retryParameters
* Retry parameters for license requests.
* @property {!Object.<string, string>} servers
* <i>Required for all but the clear key CDM.</i> <br>
* A dictionary which maps key system IDs to their license servers.
* For example, {'com.widevine.alpha': 'http://example.com/drm'}.
* @property {!Object.<string, string>} clearKeys
* <i>Forces the use of the Clear Key CDM.</i>
* A map of key IDs (hex) to keys (hex).
* @property {boolean} delayLicenseRequestUntilPlayed
* <i>Defaults to false.</i> <br>
* True to configure drm to delay sending a license request until a user
* actually starts playing content.
* @property {Object.<string, shakaExtern.AdvancedDrmConfiguration>} advanced
* <i>Optional.</i> <br>
* A dictionary which maps key system IDs to advanced DRM configuration for
* those key systems.
*
* @exportDoc
*/
shakaExtern.DrmConfiguration;
/**
* @typedef {{
* customScheme: shakaExtern.DashContentProtectionCallback,
* clockSyncUri: string,
* ignoreDrmInfo: boolean,
* xlinkFailGracefully: boolean,
* defaultPresentationDelay: number
* }}
*
* @property {shakaExtern.DashContentProtectionCallback} customScheme
* If given, invoked by a DASH manifest parser to interpret custom or
* non-standard DRM schemes found in the manifest. The argument is a
* ContentProtection node. Return null if not recognized.
* @property {string} clockSyncUri
* A default clock sync URI to be used with live streams which do not
* contain any clock sync information. The "Date" header from this URI
* will be used to determine the current time.
* @property {boolean} ignoreDrmInfo
* If true will cause DASH parser to ignore DRM information specified
* by the manifest and treat it as if it signaled no particular key
* system and contained no init data. Defaults to false if not provided.
* @property {boolean} xlinkFailGracefully
* If true, xlink-related errors will result in a fallback to the tag's
* existing contents. If false, xlink-related errors will be propagated
* to the application and will result in a playback failure. Defaults to
* false if not provided.
* @property {number} defaultPresentationDelay
* A default presentationDelay if suggestedPresentationDelay is missing
* in the MPEG DASH manifest. This has to be bigger than minBufferTime * 1.5.
*
* @exportDoc
*/
shakaExtern.DashManifestConfiguration;
/**
* @typedef {{
* retryParameters: shakaExtern.RetryParameters,
* availabilityWindowOverride: number,
* dash: shakaExtern.DashManifestConfiguration
* }}
*
* @property {shakaExtern.RetryParameters} retryParameters
* Retry parameters for manifest requests.
* @property {number} availabilityWindowOverride
* A number, in seconds, that overrides the availability window in the
* manifest, or NaN if the default value should be used. This is enforced by
* the manifest parser, so custom manifest parsers should take care to honor
* this parameter.
* @property {shakaExtern.DashManifestConfiguration} dash
* Advanced parameters used by the DASH manifest parser.
*
* @exportDoc
*/
shakaExtern.ManifestConfiguration;
/**
* @typedef {{
* retryParameters: shakaExtern.RetryParameters,
* failureCallback: function(!shaka.util.Error),
* rebufferingGoal: number,
* bufferingGoal: number,
* bufferBehind: number,
* ignoreTextStreamFailures: boolean,
* alwaysStreamText: boolean,
* startAtSegmentBoundary: boolean,
* smallGapLimit: number,
* jumpLargeGaps: boolean,
* durationBackoff: number,
* forceTransmuxTS: boolean
* }}
*
* @description
* The StreamingEngine's configuration options.
*
* @property {shakaExtern.RetryParameters} retryParameters
* Retry parameters for segment requests.
* @property {function(!shaka.util.Error)} failureCallback
* A callback to decide what to do on a streaming failure. Default behavior
* is to retry on live streams and not on VOD.
* @property {number} rebufferingGoal
* The minimum number of seconds of content that the StreamingEngine must
* buffer before it can begin playback or can continue playback after it has
* entered into a buffering state (i.e., after it has depleted one more
* more of its buffers).
* @property {number} bufferingGoal
* The number of seconds of content that the StreamingEngine will attempt to
* buffer ahead of the playhead. This value must be greater than or equal to
* the rebuffering goal.
* @property {number} bufferBehind
* The maximum number of seconds of content that the StreamingEngine will keep
* in buffer behind the playhead when it appends a new media segment.
* The StreamingEngine will evict content to meet this limit.
* @property {boolean} ignoreTextStreamFailures
* If true, the player will ignore text stream failures and continue playing
* other streams.
* @property {boolean} alwaysStreamText
* If true, always stream text tracks, regardless of whether or not they are
* shown. This is necessary when using the browser's built-in controls, which
* are not capable of signaling display state changes back to Shaka Player.
* Defaults to false.
* @property {boolean} startAtSegmentBoundary
* If true, adjust the start time backwards so it is at the start of a
* segment. This affects both explicit start times and calculated start time
* for live streams. This can put us further from the live edge. Defaults to
* false.
* @property {number} smallGapLimit
* The limit (in seconds) for a gap in the media to be considered "small".
* Small gaps are jumped automatically without events. Large gaps result
* in a Player event and can be jumped.
* @property {boolean} jumpLargeGaps
* If true, jump large gaps in addition to small gaps. The event will be
* raised first. Then, if the app doesn't call preventDefault() on the event,
* the Player will jump the gap. If false, then the event will be raised,
* but the gap will not be jumped.
* @property {number} durationBackoff
* By default, we will not allow seeking to exactly the duration of a
* presentation. This field is the number of seconds before duration we will
* seek to when the user tries to seek to or start playback at the duration.
* To disable this behavior, the config can be set to 0. We recommend using
* the default value unless you have a good reason not to.
* @property {boolean} forceTransmuxTS
* If this is true, we will transmux TS content even if not strictly necessary
* for the assets to be played. Shaka Player currently only supports CEA 708
* captions by transmuxing, so this value is necessary for enabling them on
* platforms with native TS support like Edge or Chromecast.
* This value defaults to false.
* @exportDoc
*/
shakaExtern.StreamingConfiguration;
/**
* @typedef {{
* enabled: boolean,
* defaultBandwidthEstimate: number,
* restrictions: shakaExtern.Restrictions,
* switchInterval: number,
* bandwidthUpgradeTarget: number,
* bandwidthDowngradeTarget: number
* }}
*
* @property {boolean} enabled
* If true, enable adaptation by the current AbrManager. Defaults to true.
* @property {number} defaultBandwidthEstimate
* The default bandwidth estimate to use if there is not enough data, in
* bit/sec.
* @property {shakaExtern.Restrictions} restrictions
* The restrictions to apply to ABR decisions. These are "soft" restrictions.
* Any track that fails to meet these restrictions will not be selected
* automatically, but will still appear in the track list and can still be
* selected via selectVariantTrack(). If no tracks meet these restrictions,
* AbrManager should not fail, but choose a low-res or low-bandwidth variant
* instead. It is the responsibiliy of AbrManager implementations to follow
* these rules and implement this behavior.
* @property {number} switchInterval
* The minimum amount of time that must pass between switches, in
* seconds. This keeps us from changing too often and annoying the user.
* @property {number} bandwidthUpgradeTarget
* The fraction of the estimated bandwidth which we should try to use when
* upgrading.
* @property {number} bandwidthDowngradeTarget
* The largest fraction of the estimated bandwidth we should use. We should
* downgrade to avoid this.
* @exportDoc
*/
shakaExtern.AbrConfiguration;
/**
* @typedef {{
* drm: shakaExtern.DrmConfiguration,
* manifest: shakaExtern.ManifestConfiguration,
* streaming: shakaExtern.StreamingConfiguration,
* abrFactory: shakaExtern.AbrManager.Factory,
* abr: shakaExtern.AbrConfiguration,
* preferredAudioLanguage: string,
* preferredTextLanguage: string,
* preferredVariantRole: string,
* preferredTextRole: string,
* preferredAudioChannelCount: number,
* restrictions: shakaExtern.Restrictions,
* playRangeStart: number,
* playRangeEnd: number,
* textDisplayFactory: shakaExtern.TextDisplayer.Factory
* }}
*
* @property {shakaExtern.DrmConfiguration} drm
* DRM configuration and settings.
* @property {shakaExtern.ManifestConfiguration} manifest
* Manifest configuration and settings.
* @property {shakaExtern.StreamingConfiguration} streaming
* Streaming configuration and settings.
* @property {shakaExtern.AbrManager.Factory} abrFactory
* A factory to construct an abr manager.
* @property {shakaExtern.AbrConfiguration} abr
* ABR configuration and settings.
* @property {shaka.extern.OfflineConfiguration} offline
* Offline configuration and settings.
* @property {string} preferredAudioLanguage
* The preferred language to use for audio tracks. If not given it will use
* the 'main' track.
* Changing this during playback will not affect the current playback.
* @property {string} preferredTextLanguage
* The preferred language to use for text tracks. If a matching text track
* is found, and the selected audio and text tracks have different languages,
* the text track will be shown.
* Changing this during playback will not affect the current playback.
* @property {string} preferredVariantRole
* The preferred role to use for variants.
* @property {string} preferredTextRole
* The preferred role to use for text tracks.
* @property {number} preferredAudioChannelCount
* The preferred number of audio channels.
* @property {shakaExtern.Restrictions} restrictions
* The application restrictions to apply to the tracks. These are "hard"
* restrictions. Any track that fails to meet these restrictions will not
* appear in the track list. If no tracks meet these restrictions, playback
* will fail.
* @property {number} playRangeStart
* Optional playback and seek start time in seconds. Defaults to 0 if
* not provided.
* @property {number} playRangeEnd
* Optional playback and seek end time in seconds. Defaults to the end of
* the presentation if not provided.
* @property {shakaExtern.TextDisplayer.Factory} textDisplayFactory
* A factory to construct text displayer.
* @exportDoc
*/
shakaExtern.PlayerConfiguration;
/**
* @typedef {{
* language: string,
* role: string
* }}
*
* @property {string} language
* The language code for the stream.
* @property {string} role
* The role name for the stream. If the stream has no role, |role| will be
* ''.
* @exportDoc
*/
shakaExtern.LanguageRole;