@liveryvideo/player

[@liveryvideo/player v7.15.0](../index.md) / LiveryPlayer # Class: LiveryPlayer Element defined as `<livery-player>` which can be used to play a Livery video stream as specified by [streamId](LiveryPlayer.md#streamid). If auto play is enabled in the stream config this will attempt to start playback unmuted. If that is not allowed it will attempt to fall back to muted auto play and show a click to unmute dialog. And if that is not allowed it will just show a click to play (unmuted) dialog. Once a user has manually muted or unmuted that state will be attempted to be persisted and respected on subsequent player page loads. This can dispatch the following events: - [livery-config-change](LiveryConfigChangeEvent.md) - Dispatched when [config](LiveryPlayer.md#config) has changed. - [livery-display-change](LiveryDisplayChangeEvent.md) - Dispatched when [display](LiveryPlayer.md#display) has changed. - [livery-error](LiveryErrorEvent.md) - Dispatched when an error occurred and [error](LiveryPlayer.md#error) is a string. - [livery-features-change](LiveryFeaturesChangeEvent.md) - Dispatched when [features](LiveryPlayer.md#features) has changed. - [livery-mode-change](LiveryModeChangeEvent.md) - Dispatched when [mode](LiveryPlayer.md#mode) has changed. - [livery-playback-change](LiveryPlaybackChangeEvent.md) - Dispatched when [playbackState](LiveryPlayer.md#playbackstate) has changed. - [livery-qualities-change](LiveryQualitiesChangeEvent.md) - Dispatched when [qualities](LiveryPlayer.md#qualities) has changed. - [livery-recovered](LiveryRecoveredEvent.md) - Dispatched when player has recovered and [error](LiveryPlayer.md#error) is undefined. - [livery-volume-change](LiveryVolumeChangeEvent.md) - Dispatched when [volume](LiveryPlayer.md#volume-1) and/or [muted](LiveryPlayer.md#muted) have changed. Note: Element properties that are reflected to attributes are listed with their property names, p.e: `streamId`, as in: `player.streamId = '1234abcd'`. The reflected attribute names however are lower case, p.e: `streamid`, as in: `<livery-player streamid="1234abcd">`. For string attributes the value will be `null` when absent or empty. For boolean attributes the effective value will be `true` when the attribute is present and `false` when absent, no matter the attribute value, p.e: `<livery-player controlsdisabled>`. ## Example ```html  <livery-player streamid="6613d164e4b0bf3ad645f3c6"></livery-player> ``` ## Extends - `LitElement` ## Properties ### display > `readonly` **display**: [`DisplayMode`](../type-aliases/DisplayMode.md) Display mode. Dispatches: [livery-display-change](LiveryDisplayChangeEvent.md) #### Default Value ```ts 'DEFAULT' ``` *** ### error? > `optional` `readonly` **error**: `Error` Most recent unrecovered error. Dispatches: [livery-error](LiveryErrorEvent.md), [livery-recovered](LiveryRecoveredEvent.md) #### Default Value ```ts undefined ``` *** ### features > `readonly` **features**: `object` Registry of features supported by the player in general and under given circumstances. Dispatches: [livery-features-change](LiveryFeaturesChangeEvent.md) #### Default Value ```ts All features false ``` #### airplay > **airplay**: `boolean` #### chromecast > **chromecast**: `boolean` #### contact > **contact**: `boolean` #### fullscreen > **fullscreen**: `boolean` #### pip > **pip**: `boolean` #### scrubber > **scrubber**: `boolean` #### volume > **volume**: `boolean` *** ### interactiveAuth > **interactiveAuth**: `string` \| [`AuthClaims`](../type-aliases/AuthClaims.md) AuthClaims object, JWT token string or `undefined` value to be used for interactive authentication. An undefined value here should result in logging out. #### Default Value `'livery_auth'` query parameter JSON parsed claims object, token string or `undefined` *** ### mode > `readonly` **mode**: [`PlaybackMode`](../type-aliases/PlaybackMode.md) Mode of playback, e.g. how to buffer, sync, adapt quality, manage stalls, etc. Dispatches: [livery-mode-change](LiveryModeChangeEvent.md) #### Default Value ```ts 'UNKNOWN' ``` *** ### playbackState > `readonly` **playbackState**: [`PlaybackState`](../type-aliases/PlaybackState.md) Playback state. Dispatches: [livery-playback-change](LiveryPlaybackChangeEvent.md) #### Default Value ```ts 'ENDED' ``` *** ### qualities > `readonly` **qualities**: `object` Stream qualities. Dispatches: [livery-qualities-change](LiveryQualitiesChangeEvent.md) #### Default Value ```ts undefined ``` #### active > **active**: `number` Index of quality that is being played, or -1 if no quality is active yet. #### list > **list**: [`Quality`](../interfaces/Quality.md)[] List of qualities that can be played. #### selected > **selected**: `number` Index of quality that is selected to be played, or -1 if ABR is used. *** ### ~~quality~~ > `readonly` **quality**: `string` Active quality label. Dispatches: livery-quality-change #### Deprecated Instead use [qualities](LiveryPlayer.md#qualities) #### Default Value ```ts null ``` *** ### sources? > `optional` **sources**: `string`[] Custom video source URLs to override sources specified by stream config with. ## Accessors ### buffer > `get` **buffer**(): `number` Current playback buffer in seconds ahead of current position. #### Default Value ```ts NaN ``` #### Returns `number` *** ### config > `get` **config**(): `object` Public part of Livery stream config, can change with server side updates or when streamId is changed. Note: Player will not be fully usable until configured. Dispatches: [livery-config-change](LiveryConfigChangeEvent.md) #### Default Value ```ts undefined ``` #### Returns `object` ##### controls > **controls**: `object` Registry of controls that should be shown to the user. ##### controls.cast > **cast**: `boolean` Enable toggling AirPlay and/or Chromecast display. ##### controls.contact > **contact**: `boolean` Enable submitting user feedback. ##### controls.error > **error**: `boolean` Enable error feedback and recovery controls. ##### controls.fullscreen > **fullscreen**: `boolean` Enable toggling fullscreen display. ##### controls.mute > **mute**: `boolean` Enable muting and unmuting audio. ##### controls.pip > **pip**: `boolean` Enable toggling picture-in-picture display. ##### controls.play > **play**: `boolean` Enable toggling play/pause. ##### controls.quality > **quality**: `boolean` Enable quality selection. ##### controls.scrubber > **scrubber**: `boolean` Enable seeking through the stream. ##### customerId > **customerId**: `string` Livery customer ID. ##### streamPhase > **streamPhase**: `"LIVE"` \| `"POST"` \| `"PRE"` Livery stream phase, i.e: PRE/LIVE/POST before/while/after streaming to viewers. ##### streamPhases > **streamPhases**: [`number`, `"LIVE"` \| `"POST"` \| `"PRE"`][] Array of [unixTimestamp, streamPhase] tuples listing the times at which those phases started. ##### tenantId > **tenantId**: `string` Livery tenant ID. *** ### customerId > `get` **customerId**(): `string` Livery customer ID. #### Deprecated Instead use [config](LiveryPlayer.md#config).customerId #### Default Value ```ts null ``` #### Returns `string` *** ### duration > `get` **duration**(): `number` Current playback duration in seconds from start to end of live stream or VOD. #### Default Value ```ts NaN ``` #### Returns `number` *** ### latency > `get` **latency**(): `number` Current end-to-end latency in seconds. #### Default Value ```ts NaN ``` #### Returns `number` *** ### paused > `get` **paused**(): `boolean` True if `playbackState` is PAUSED or ENDED. I.e: not playing as intended. Can change on: [livery-playback-change](LiveryPlaybackChangeEvent.md). #### Default Value ```ts true ``` #### Returns `boolean` *** ### playing > `get` **playing**(): `boolean` True if `playbackState` is PLAYING, FAST_FORWARD, SLOW_MO or REWIND. I.e: playing as intended. Can change on: [livery-playback-change](LiveryPlaybackChangeEvent.md). #### Default Value ```ts false ``` #### Returns `boolean` *** ### position > `get` **position**(): `number` Current playback position in seconds since start of live stream or VOD. #### Default Value ```ts NaN ``` #### Returns `number` *** ### stalled > `get` **stalled**(): `boolean` True if `playbackState` is BUFFERING or SEEKING. I.e: not playing, but trying to. Can change on: [livery-playback-change](LiveryPlaybackChangeEvent.md). #### Default Value ```ts false ``` #### Returns `boolean` *** ### streamPhase > `get` **streamPhase**(): `"LIVE"` \| `"POST"` \| `"PRE"` Livery stream phase, i.e: PRE/LIVE/POST before/while/after streaming to viewers. Dispatches: livery-phase-change #### Deprecated Instead use [config](LiveryPlayer.md#config).streamPhase #### Default Value ```ts 'PRE' ``` #### Returns `"LIVE"` \| `"POST"` \| `"PRE"` ## Methods ### pause() > **pause**(): `void` Pause playback. #### Returns `void` *** ### play() > **play**(): `void` Attempt to start or resume playback. This will also attempt to auto unmute (unless user previously muted) while we're at it. Can fail if not allowed by the browser, e.g: when not called directly from a click event listener. The user paused state is kept track of by the player though and respected on reload when possible. If starting playback unmuted fails this can fall back to muted playback, changing [muted](LiveryPlayer.md#muted) to `true`. If muted autoplay also fails then [paused](LiveryPlayer.md#paused) will remain `true`. #### Returns `void` *** ### registerPlayerCommand() > **registerPlayerCommand**(`name`, `handler`): `void` Register custom player bridge command `handler` by `name`. The `handler` will be called with `arg` and `listener` when `sendPlayerCommand()` is called with matching `name` from the interactive layer bridge side. The value or Promise returned by `handler` will be passed back and returned by that interactive bridge call. Any `listener` calls here will similarly result in the interactive `listener` being called with those values. #### Parameters • **name**: `string` • **handler** #### Returns `void` *** ### reload() > **reload**(): `void` Reload player, e.g: to try to recover from an error. #### Returns `void` *** ### selectQuality() > **selectQuality**(`index`): `void` Select index of quality from [qualities](LiveryPlayer.md#qualities) to play, or select -1 to use ABR (Automatic BitRate selection). #### Parameters • **index**: `number` Index of quality to select #### Returns `void` #### Throws Error "Player unconfigured" when config has not been loaded yet #### Throws Error "Qualities undefined" when stream qualities have not been loaded yet #### Throws RangeError when index is not -1 or a valid index of the [qualities](LiveryPlayer.md#qualities) array *** ### sendInteractiveCommand() > **sendInteractiveCommand**(`name`, `arg`?, `listener`?): `Promise`\<`unknown`\> Send command to interactive layer via player bridge and return promise of value returned by interactive bridge's custom command handler with matching `name` that was passed `arg`. Any of that interactive handler's `listener` calls will subsequently also be bridged to this `listener` callback. #### Parameters • **name**: `string` • **arg?**: `unknown` • **listener?** #### Returns `Promise`\<`unknown`\> *** ### setDisplay() > **setDisplay**(`display`): `Promise`\<`void`\> Attempt to change display mode to specified value. #### Parameters • **display**: [`DisplayMode`](../type-aliases/DisplayMode.md) Display mode to change to #### Returns `Promise`\<`void`\> #### Throws DOMException NotSupportedError: Unsupported feature: [feature] - If related features property is false #### Throws DOMException NotAllowedError: [message] - If browser does not allow it *** ### setMuted() > **setMuted**(`muted`): `void` Attempt to change muted state to specified value. Unmuting can fail if not allowed by the browser, e.g: when not called directly from a click event listener. The specified state is kept track of by the player though and respected on reload when possible. Look at muted state to track actual unmuting. #### Parameters • **muted**: `boolean` Muted state to change to #### Returns `void` *** ### unregisterPlayerCommand() > **unregisterPlayerCommand**(`name`): `void` Unregister custom player bridge command by `name`. #### Parameters • **name**: `string` #### Returns `void` ## Attributes ### akamaiLongToken > **akamaiLongToken**: `string` Access token to use to be able to see a stream that uses Akamai’s Long Token Auth feature. #### Default Value ```ts null ``` *** ### akamaiToken > **akamaiToken**: `string` Access token to use to be able to see a stream that uses Akamai’s Token Auth feature. #### Default Value ```ts null ``` *** ### bubbles > **bubbles**: `boolean` If true then events dispatched by this element will bubble. #### Default Value ```ts false ``` *** ### configType > **configType**: `string` Type of stream config to use. Defaults to SDK platform (WEB) when value is null (attribute is absent). #### Default Value ```ts null ``` *** ### controlsDisabled > **controlsDisabled**: `boolean` Change this to true to disable all default player controls, e.g: to be able to use your own instead. #### Default Value ```ts false ``` *** ### ~~fullscreen~~ > **fullscreen**: `boolean` If true then player is fullscreen. Dispatches: livery-fullscreen-change #### Deprecated Instead use [display](LiveryPlayer.md#display) and [setDisplay](LiveryPlayer.md#setdisplay) #### Default Value ```ts false ``` *** ### locale > **locale**: `string` Global Livery locale ('de-DE' | 'en-US' | 'es-ES' | 'fr-FR' | 'nl-NL' | 'pt-PT'). If just the first part (e.g: 'en') of a locale is assigned that will result in the first matching full locale value (e.g: 'en-US') being changed to. #### Default Value ```ts The first supported locale matching one of the browser languages in-order or falls back to 'en-US' ``` *** ### logLevel > **logLevel**: `string` Log level ('quiet' | 'error' | 'warn' | 'info' | 'debug' | 'spam'). Defaults to 'info' when value is null (attribute is absent). #### Default Value ```ts null ``` *** ### muted > `readonly` **muted**: `boolean` If true then audio is muted. This value should just be browser controlled (i.e: read only); changing this value as a user is deprecated. Use [setMuted](LiveryPlayer.md#setmuted) instead to attempt to change this value, if allowed by the browser. Until there is browser controlled video however (e.g: in PRE stream phase) this is the user requested value. Dispatches: livery-volume-change #### Default Value Persisted user muted value or `false` *** ### streamId > **streamId**: `string` Livery stream ID specifying which stream to play. #### Default Value `'livery_stream'` query parameter value or `null` *** ### volume > **volume**: `number` Audio volume, from `0.0` (silent) to `1.0` (loudest). When a player starts unmuted at volume `0` and this is changed to a higher volume later, that can be disallowed by the browser, e.g: when not called directly from a click event listener. In that case this will fall back to changing [muted](LiveryPlayer.md#muted) to `true` to allow the volume change to persist. Dispatches: livery-volume-change #### Default Value Persisted user muted value or `1` *** ### vuMeter > **vuMeter**: `boolean` If true then volume unit meter is shown. #### Default Value ```ts false ```