Skip to main content

Interface: Options

Options for the Vindral instance

Properties​

abrEnabled​

• Optional abrEnabled: boolean

Enable or disable Adaptive Bit Rate. This allows for automatically adapting the incoming bit rate based on the viewers bandwidth and thus avoiding buffering events. This also disables the sizeBasedResolutionCapEnabled option.

Is enabled by default.

Note: It is strongly recommended to keep this enabled as user experience can greatly suffer without ABR.

advanced​

• Optional advanced: AdvancedOptions

Advanced options to override default behaviour.

authenticationToken​

• Optional authenticationToken: string

An authentication token to provide to the server when connecting - only needed for channels with authentication enabled Note: If not supplied when needed, an "Authentication Failed" error will be raised.

burstEnabled​

• Optional burstEnabled: boolean

Enable bursting for initial connection and channel switches. This makes time to first frame faster at the cost of stability (more demanding due to the sudden burst of live content)

Is disabled by default.

channelGroupId​

• Optional channelGroupId: string

Channel group to connect to Note: Only needed for fast channel switching

channelId​

• channelId: string

Channel ID to connect to initially - can be changed later mid-stream when connected to a channel group.

container​

• Optional container: HTMLElement

A container to attach the video view in - can be provided later with .attach() on the vindral core instance

iosBackgroundPlayEnabled​

• Optional iosBackgroundPlayEnabled: boolean

Enable or disable support for playing audio in the background for iOS devices.

Is false (disabled) by default.

Note: This may be enabled by default in a future (major) release

iosMediaElementEnabled​

• Optional iosMediaElementEnabled: boolean

Enables iOS devices to use a media element for playback. This enables fullscreen and picture in picture support on iOS.

iosWakeLockEnabled​

• Optional iosWakeLockEnabled: boolean

Enable wake lock for iOS devices. The wake lock requires that the audio has been activated at least once for the instance, othwerwise it will not work. Other devices already provide wake lock by default.

This option is redundant and has no effect if iosMediaElementEnabled is enabled since that automatically enables wake lock.

Disabled by default.

language​

• Optional language: string

Language to use initially - can be changed during during runtime on the vindral instance Note: Only needed when multiple languages are provided - if no language is specified, one will be automatically selected.

logLevel​

• Optional logLevel: Level

Sets the log level - defaults to info

maxAudioBitRate​

• Optional maxAudioBitRate: number

Maximum audio bit rate allowed. This can be used to provide user options to limit the audio bandwidth usage.

maxBufferTime​

• Optional maxBufferTime: number

Sets the maximum buffer time allowed. The vindral instance will automatically slowly increase the buffer time if the use experiences to much buffering with the initial buffer time.

Note: This is not yet implemented

maxSize​

• Optional maxSize: Size

Set a cap on the maximum video size. This can be used to provide user options to limit the video bandwidth usage.

Note: This takes presedence over any size based resolution caps.

maxVideoBitRate​

• Optional maxVideoBitRate: number

Maximum video bit rate allowed. This can be used to provide user options to limit the video bandwidth usage.

minBufferTime​

• Optional minBufferTime: number

Sets the minimum and initial buffer time

mseEnabled​

• Optional mseEnabled: boolean

Enable usage of the MediaSource API on supported browsers.

Is enabled by default.

Note: We recommend to keep this at the default value unless you have very specific needs.

mseOpusEnabled​

• Optional mseOpusEnabled: boolean

Enable Opus with the MediaSource API on supported browsers.

Is enabled by default.

Note: Opus generally provides better audio quality and is therefore recommended to keep enabled.

muted​

• Optional muted: boolean

Whether to start the player muted or to try to start playing audio automatically.

pauseSupportEnabled​

• Optional pauseSupportEnabled: boolean

Disabling this will revert to legacy behaviour where Vindral will try to always keep the video element playing.

pictureInPictureEnabled​

• Optional pictureInPictureEnabled: boolean

Enables or disables picture in picture support.

poster​

• Optional poster: string | boolean

Controls video element background behaviour while loading.

  • If false, a black background will be shown.
  • If undefined or true, a live thumbnail will be shown.
  • If set to a string containing a URL (https://urltoimage), use that. Default true - meaning a live thumbnail is shown

reconnectHandler​

• Optional reconnectHandler: (state: ReconnectState) => boolean | Promise<boolean>

Type declaration​

▸ (state): boolean | Promise<boolean>

Provide a custom reconnect handler to control when the instance should stop trying to reconnect. The reconnect handler should either return true to allow the reconnect or false to stop reconnecting. It can also return a promise with true or false if it needs to make any async calls before determining wether to reconnect.

The default reconnect handler allows 30 reconnects before stopping.

Note: the ReconnectState gets reset every time the client instance makes a successful connection. This means the default reconnect handler will only stop reconnecting after 30 consecutive failed connections.

// An example reconnect handler that will reconnect forever
const reconnectHandler = (state: ReconnectState) => true

// An example reconnect handler that will fetch an url and determine whether to reconnect
const reconnectHandler = async (state: ReconnectState) => {
  const result = await fetch("https://should-i-reconnect-now.com")
  return result.ok
},
Parameters​
NameType
stateReconnectState
Returns​

boolean | Promise<boolean>

sizeBasedResolutionCapEnabled​

• Optional sizeBasedResolutionCapEnabled: boolean

Enables or disables user bandwidth savings by capping the video resolution to the size of the video element.

Is enabled by default.

Note: This is automatically set to false when abrEnabled is set to false.

telemetryEnabled​

• Optional telemetryEnabled: boolean

Enable or disable telemetry. This allows for telemetry and errors being collected.

Is enabled by default.

We appreciate you turning it off during development/staging to not bloat real telemetry data.

Note: It is strongly recommended to keep this enabled in production as it is required for insights and KPIs.

url​

• url: string

URL to use when connecting to the stream