Interface Player

An interface describing the API of the media player. Create a player instance with the create function. The player's APIs are generally asynchronous when setting and synchronous when getting. Listen to events via Player.addEventListener for state updates.

interface Player {
    addEventListener<K>(name, fn): void;
    attachHTMLVideoElement(videoElement): void;
    delete(): void;
    getBufferDuration(): number;
    getBuffered(): BufferRange;
    getChannelMetadata(): string[];
    getDisplayHeight(): number;
    getDisplayWidth(): number;
    getDuration(): number;
    getHTMLVideoElement(): HTMLVideoElement;
    getLiveLatency(): number;
    getPlaybackRate(): number;
    getPosition(): number;
    getQualities(): Quality[];
    getQuality(): Quality;
    getSessionId(): undefined | string;
    getState(): PlayerState;
    getSyncTime(): number;
    getVersion(): string;
    getVolume(): number;
    isAutoQualityMode(): boolean;
    isAutoplay(): boolean;
    isLiveLowLatency(): boolean;
    isMuted(): boolean;
    isPaused(): boolean;
    load(path, mediaType?): void;
    pause(): void;
    play(): void;
    removeEventListener<K>(name, fn): void;
    seekTo(time): void;
    setAutoMaxQuality(quality): void;
    setAutoMaxVideoSize(width, height): void;
    setAutoQualityMode(enable): void;
    setAutoplay(enabled): void;
    setInitialBufferDuration(duration): void;
    setLiveLowLatencyEnabled(enable): void;
    setLogLevel(level): void;
    setMuted(mute): void;
    setPlaybackRate(rate): void;
    setQuality(quality, adaptive?): void;
    setRebufferToLive(enable): void;
    setRequestCredentials(credentials): void;
    setVolume(volume): void;
}

Implemented by

Methods

addEventListener attachHTMLVideoElement delete getBufferDuration getBuffered getChannelMetadata getDisplayHeight getDisplayWidth getDuration getHTMLVideoElement getLiveLatency getPlaybackRate getPosition getQualities getQuality getSessionId getState getSyncTime getVersion getVolume isAutoQualityMode isAutoplay isLiveLowLatency isMuted isPaused load pause play removeEventListener seekTo setAutoMaxQuality setAutoMaxVideoSize setAutoQualityMode setAutoplay setInitialBufferDuration setLiveLowLatencyEnabled setLogLevel setMuted setPlaybackRate setQuality setRebufferToLive setRequestCredentials setVolume

Methods

addEventListener

  • addEventListener<K>(name, fn): void

  • Adds an event listener to the player. PlayerEventMap is a computed type which maps event names to their payloads.

    Remove listeners with Player.removeEventListener.

    Type Parameters

    • K extends PlayerState | (keyof PlayerEventTypeMap) | (keyof MetadataPayloadMap)

    Parameters

    • name: K

      The name of the event. Available events include PlayerState events and PlayerEventType events.

    • fn: ((payload) => void)

      The handler function.

    Returns void

attachHTMLVideoElement

  • attachHTMLVideoElement(videoElement): void

  • Attaches a video element (tag) to be used for playback. This replaces any video element in use. This is optional; if it is not called, the Player creates and uses a video element.

    Parameters

    • videoElement: HTMLVideoElement

      The video element to attach.

    Returns void

delete

  • delete(): void

  • Removes the player instance and stops playback. After deletion, the player no longer emits events or responds to API calls.

    Returns void

getBufferDuration

  • getBufferDuration(): number

  • Gets the buffer length ahead of the current playback position.

    Returns number

    The duration, in seconds, from the playhead to the end of the buffer.

getBuffered

  • getBuffered(): BufferRange

  • Gets the currently buffered range.

    Returns BufferRange

    The buffered range which the playhead is within.

getChannelMetadata

  • getChannelMetadata(): string[]

  • Returns an array of string values that represent channel features or capabilities. Refer to IVS Channel documentation for more information about these values.

    Returns string[]

    An array of optional string metadata associated with this channel.

getDisplayHeight

  • getDisplayHeight(): number

  • Gets the clientHeight of the underyling HTMLMediaElement.

    Returns number

    The clientHeight property of the active video element.

getDisplayWidth

  • getDisplayWidth(): number

  • Gets the clientWidth of the underyling HTMLMediaElement.

    Returns number

    The clientWidth property of the active video element.

getDuration

  • getDuration(): number

  • Gets the duration of the currently loaded media stream.

    Returns number

    The duration of the stream in seconds for video on demand content, and Infinity for live streams.

getHTMLVideoElement

  • getHTMLVideoElement(): HTMLVideoElement

  • Gets the video element in use.

    Returns HTMLVideoElement

    The video element in use.

getLiveLatency

  • getLiveLatency(): number

  • For a live stream, returns the latency from the server to the player. Note: For non-live streams, this value is not meaningful.

    Returns number

    the latency in seconds.

getPlaybackRate

  • getPlaybackRate(): number

  • Gets the playback rate.

    Returns number

    The playback of the rate of the player.

getPosition

  • getPosition(): number

  • Gets the playback position.

    Returns number

    The current position of the player, in seconds. When the player is rendering via MediaSourceExtensions, the starting position is 0. Otherwise, the starting position is relative to the current duration of the stream.

getQualities

  • getQualities(): Quality[]

  • Returns Quality[]

    Set of available Quality objects from the loaded source or empty if none are currently available. The qualities will be available after the PlayerState.READY state has been entered. This set contains the qualities that can be used with Player.setQuality. Note that this set will contain only qualities capable of being played on the current device and not all those present in the source stream. On iOS mobile (iPhone) browsers, this API will return an empty array. The reason is that underlying Safari browser manages the playback entirely and does not provide any way to access the available qualities.

getQuality

  • getQuality(): Quality

  • Gets the quality that the player is using. On iOS mobile (iPhone) browsers, this API will return an empty Quality object. The reason is that underlying Safari browser manages the playback entirely and does not provide any way to access the available qualities.

    Returns Quality

    The current quality of the source.

getSessionId

  • getSessionId(): undefined | string

  • Gets the ID of the playback session.

    Returns undefined | string

    A unique identifier ID of the current play session, or undefined if the session is not yet known. The ID is known after the player enters the PlayerState.READY state. This session identifier can be shared with support or displayed in an user interface to help troubleshoot or diagnose playback issues with the currently playing stream.

getState

getSyncTime

  • getSyncTime(): number

  • Gets the synchronized time, in milliseconds

    The synchronized time is a UTC time that represents a specific time during playback, at a granularity of 1 second. It can be used to sync external events and state to a specific moment during playback.

    Note an event is dispatched when this value changes: PlayerEventType events.

    Returns number

    The current synchronized time of the player, in milliseconds.

getVersion

  • getVersion(): string

  • Gets the version of the player.

    Returns string

    The semantic version of the player.

getVolume

  • getVolume(): number

  • Gets the player's volume level.

    Returns number

    The volume level of the player, between 0.0f and 1.0f.

isAutoQualityMode

  • isAutoQualityMode(): boolean

  • Gets whether the Adaptive Bitrate (ABR) streaming algorithm is enabled. The maximum quality is controlled by Player.setAutoMaxQuality.

    Returns boolean

    True if ABR is enabled, false otherwise.

isAutoplay

  • isAutoplay(): boolean

  • Gets whether autoplay is enabled. Defaults to false.

    Returns boolean

    True if autoplay is enabled, false otherwise.

isLiveLowLatency

  • isLiveLowLatency(): boolean

  • Gets whether low-latency live streaming is enabled.

    This API is not supported on iOS mobile (iPhone) browsers.

    Returns boolean

    True if low-latency streaming is enabled on both the server and the client, false otherwise.

isMuted

  • isMuted(): boolean

  • Gets whether the player is muted.

    Returns boolean

    True if the player is muted, false otherwise.

isPaused

  • isPaused(): boolean

  • Gets whether the player is paused.

    Returns boolean

    True if the player is paused, otherwise false. This flag reflects pauses initiated by the user, autoplay failure, and error handling.

load

  • load(path, mediaType?): void

  • Loads the specified stream and prepares the player for playback. On success, the player state changes to PlayerState.READY. On failure, this invokes the PlayerEventType.ERROR listener.

    Parameters

    • path: string

      The URL of the stream to load.

    • Optional mediaType: string

      Media type of the content if known; for example, 'video/mp4' or 'application/x-mpegURL'. If not provided, the type is inferred from the path.

    Returns void

pause

  • pause(): void

  • Pauses playback of the current stream or fails if no stream is loaded. On failure invokes the onError listener method.

    If you resume the stream with play, the position may be different than where it paused, depending on the type of media being played.

    Returns void

play

  • play(): void

  • Starts or resumes playback of the stream, if no stream is loaded indicates intent to play and the player will automatically play on a subsequent load call. On success, depending on the type of stream, the player state changes to PlayerState.BUFFERING and then PlayerState.PLAYING, or just PlayerState.PLAYING. On failure, this invokes the PlayerEventType.ERROR listener. This does not need to be called if autoplay is enabled.

    Returns void

removeEventListener

  • removeEventListener<K>(name, fn): void

  • Removes an event listener from the player. PlayerEventMap is a computed type which maps event names to their payloads.

    Type Parameters

    • K extends PlayerState | (keyof PlayerEventTypeMap) | (keyof MetadataPayloadMap)

    Parameters

    • name: K

      The name of the event. Available events include PlayerState events and PlayerEventType events.

    • fn: ((payload) => void)

      The handler function.

    Returns void

seekTo

  • seekTo(time): void

  • Seeks to a specified time in the stream and begins playing at that position if play() was called. If no stream is loaded the seek will be be deferred until load is called. On success, depending on the type of stream, the player state changes to PlayerState.BUFFERING and then PlayerState.PLAYING, or just PlayerState.PLAYING. On failure, this invokes the PlayerEventType.ERROR listener.

    Parameters

    • time: number

      The position to seek to, in seconds.

    Returns void

setAutoMaxQuality

  • setAutoMaxQuality(quality): void

  • Sets the maximum quality the player is allowed to auto-switch up to (if ABR is enabled) using the input quality's bitrate value. This allows you to control resource usage. The Quality you provide here is applied to the current stream. If you load a new stream, call this again after PlayerState.READY.

    This API is not supported on iOS mobile (iPhone) browsers.

    Parameters

    • quality: Quality

      The maximum quality to use for ABR.

    Returns void

setAutoMaxVideoSize

  • setAutoMaxVideoSize(width, height): void

  • Sets the maximum video display size of the player. This prevents the player from auto-switching to qualities above the specified resolution when ABR is enabled.

    This API is not supported on iOS mobile (iPhone) browsers.

    Parameters

    • width: number

      The display width.

    • height: number

      The display height.

    Returns void

setAutoQualityMode

  • setAutoQualityMode(enable): void

  • Enables or disables the Adaptive Bitrate (ABR) streaming algorithm. Note the maximum quality is controlled by Player.setAutoMaxQuality. The player chooses the quality to play based on current network and device conditions. By default, the player starts in this mode. This mode is implicitly disabled by a call to Player.setQuality.

    This API is not supported on iOS mobile (iPhone) browsers.

    Parameters

    • enable: boolean

      True to enable ABR, false to disable.

    Returns void

setAutoplay

  • setAutoplay(enabled): void

  • Enables or disables playback autoplay. Defaults to false.

    Parameters

    • enabled: boolean

      True to enable autoplay, false otherwise.

    Returns void

setInitialBufferDuration

  • setInitialBufferDuration(duration): void

  • Sets the initial (minimum) buffer duration required to start playback. If a value outside the allowable range is used, the current value is maintained. Defaults to 1s in low latency mode, 2s otherwise. Lowering this value may increase rebuffering.

    This API is not supported on iOS mobile (iPhone) browsers.

    Parameters

    • duration: number

      Buffer duration in seconds. The allowable range is 0.1 to 5

    Returns void

setLiveLowLatencyEnabled

  • setLiveLowLatencyEnabled(enable): void

  • Enables low-latency playback for live streams configured to support it. Changing this value during playback restarts the stream.

    This API is not supported on iOS mobile (iPhone) browsers.

    Parameters

    • enable: boolean

      True to enable, false to disable. Default: true.

    Returns void

setLogLevel

  • setLogLevel(level): void

  • Sets the log level for the player.

    Parameters

    Returns void

setMuted

  • setMuted(mute): void

  • Mutes or unmutes the player.

    Parameters

    • mute: boolean

      True to mute the player, false to unmute.

    Returns void

setPlaybackRate

  • setPlaybackRate(rate): void

  • Sets the stream playback rate.

    Parameters

    • rate: number

      Playback rate to set. Valid values: in the range [0.25, 2.0].

    Returns void

setQuality

  • setQuality(quality, adaptive?): void

  • Sets the quality the player should use for playback. On success, this invokes the PlayerEventType.QUALITY_CHANGED listener. This call disables adaptive bitrate (ABR) streaming. This call has no effect when the HTMLVideoElement's controls attribute is present.

    Parameters

    • quality: Quality

      A valid quality entry from Player.getQualities.

    • Optional adaptive: boolean

      True for an adaptive quality change; that is, to change quality smoothly at the end of the current buffer. False to change quality immediately.

      This API is not supported on iOS mobile (iPhone) browsers.

    Returns void

setRebufferToLive

  • setRebufferToLive(enable): void

  • Enables skipping to the live edge on a rebuffer. Note this can cause video content and content associated with it such as timed metadata to be skipped.

    This API is not supported on iOS mobile (iPhone) browsers.

    Parameters

    • enable: boolean

      True to enable, false otherwise.

    Returns void

setRequestCredentials

  • setRequestCredentials(credentials): void

  • Sets the Request.credentials property used when the player makes HTTP requests. Possible values are "include" | "omit" | "same-origin" from the JavaScript fetch API. The default value used is "same-origin". This can be used for credentialed playback of IVS recordings (e.g. via CloudFront if configured) but not for IVS live streams.

    Parameters

    • credentials: RequestCredentials

      "include" | "omit" | "same-origin"

      This API is not supported on iOS mobile (iPhone) browsers.

    Returns void

setVolume

  • setVolume(volume): void

  • Sets the playback volume of the audio track, for the current stream or the next stream that is loaded.

    Parameters

    • volume: number

      The volume to be set. Valid values: in the range 0.0f to 1.0f.

    Returns void

Settings

Member Visibility

Theme

On This Page

addEventListenerattachHTMLVideoElementdeletegetBufferDurationgetBufferedgetChannelMetadatagetDisplayHeightgetDisplayWidthgetDurationgetHTMLVideoElementgetLiveLatencygetPlaybackRategetPositiongetQualitiesgetQualitygetSessionIdgetStategetSyncTimegetVersiongetVolumeisAutoQualityModeisAutoplayisLiveLowLatencyisMutedisPausedloadpauseplayremoveEventListenerseekTosetAutoMaxQualitysetAutoMaxVideoSizesetAutoQualityModesetAutoplaysetInitialBufferDurationsetLiveLowLatencyEnabledsetLogLevelsetMutedsetPlaybackRatesetQualitysetRebufferToLivesetRequestCredentialssetVolume