Skip to main content

Class: Vindral

Represents a Vindral client instance

The most most essential methods when using the Vindral class are:

  • connect() - this has to be called to actually start connecting
  • attach() - to attach the Vindral video view to the DOM so that users can see it
  • userInput() - to activate audio on browsers that require a user gesture to play audio
  • unload() - unloads the instance, its very important that this is called when cleaning up the Vindral instance, otherwise background timers may leak.

The Vindral instance will emit a variety of events during its lifetime. Use .on("event-name", callback) to listen to these events. See [[PublicVindralEvents]] for the events types that can be emitted.

// minimal configuration of a Vindral client instance
const instance = new Vindral({
  url: "https://lb.cdn.vindral.com",
  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
})

// Will be called when timed metadata is received
instance.on("metadata", console.log)

// Will be called when a user interaction is needed to activate audio
instance.on("needs user input", console.log)

// Start connecting to the cdn
instance.connect()

// Attach the video view to the DOM
instance.attach(document.getElementById("root"))

// When done with the instance
instance.unload()

Extends​

Properties​

pictureInPicture​

readonly pictureInPicture: object

Picture in picture

enter()​

enter: () => Promise<void>

Enters picture in picture

Returns​

Promise<void>

a promise that resolves if successful

exit()​

exit: () => Promise<void>

Exits picture in picture

Returns​

Promise<void>

a promise that resolves if successful

isActive()​

isActive: () => boolean

returns whether picture in picture is currently active

Returns​

boolean

isSupported()​

isSupported: () => boolean

returns whether picture in picture is supported

Returns​

boolean

Accessors​

abrEnabled​

Get Signature​

get abrEnabled(): boolean

Whether ABR is currently enabled

Returns​

boolean

Set Signature​

set abrEnabled(enabled): void

Enable or disable ABR

The client will immediatly stop changing renditon level based on QoS metrics

Note: It is strongly recommended to keep this enabled as it can severly increase the number of buffering events for viewers.

Parameters​

• enabled: boolean

Returns​

void

audioBitRate​

Get Signature​

get audioBitRate(): number

The current average audio bit rate in bits/s

Returns​

number

audioBufferedRanges​

Get Signature​

get audioBufferedRanges(): readonly TimeRange[]

The time ranges buffered for audio. The ranges are specified in milliseconds.

Returns​

readonly TimeRange[]

bufferFullness​

Get Signature​

get bufferFullness(): number

The current buffer fullness as a floating point value between 0-1, where 1 is full and 0 i empty.

Returns​

number

channelCurrentTime​

Get Signature​

get channelCurrentTime(): number

Current time for the channel. This is the actual stream time, passed on from your ingress. Integer overflow could make this value differ from your encoder timestamps if it has been rolling for more than 42 days with RTMP as target.

Note: This is not normalized between channels, thus it can make jumps when switching channels

Returns​

number

channelId​

Get Signature​

get channelId(): string

The current channelId

Returns​

string

Set Signature​

set channelId(channelId): void

Set the current channelId

Possible channels to set are available from [[channels]]

Note that the following scenarios are not possible right now:

  • switching channel from a channel with audio to a channel without audio (unless audio only mode is active)
  • switching channel from a channel with video to a channel without video (unless video only mode is active)
Parameters​

• channelId: string

Returns​

void

channels​

Get Signature​

get channels(): readonly Channel[]

Channels that can be switched between

Returns​

readonly Channel[]

connectionState​

Get Signature​

get connectionState(): Readonly<State>

The current connection state

Returns​

Readonly<State>

currentRenditionLevel​

Get Signature​

get currentRenditionLevel(): undefined | Readonly<RenditionLevel>

The current rendition level

Returns​

undefined | Readonly<RenditionLevel>

currentTime​

Get Signature​

get currentTime(): number

Local current time normalized between all channels in the channel group

Returns​

number

isSwitchingRenditionLevel​

Get Signature​

get isSwitchingRenditionLevel(): boolean

True if the client is currently switching from one rendition level to another

Returns​

boolean

language​

Get Signature​

get language(): undefined | string

The current language

Returns​

undefined | string

Set Signature​

set language(language): void

Set the current language

Parameters​

• language: undefined | string

Returns​

void

languages​

Get Signature​

get languages(): readonly string[]

Languages available

Returns​

readonly string[]

maxAudioBitRate​

Get Signature​

get maxAudioBitRate(): number

The max audio bit rate that will be subscribed to

Note: Returns Number.MAX_SAFE_INTEGER if no limits have been set

Returns​

number

Set Signature​

set maxAudioBitRate(bitRate): void

Set max audio bit rate that will be subscribed to

Note: If ABR is disabled, setting this will make the client instantly subscribe to this bit rate

Parameters​

• bitRate: number

Returns​

void

maxSize​

Get Signature​

get maxSize(): Size

Max size that will be subcribed to

Returns​

Size

Set Signature​

set maxSize(size): void

Set max size that will be subscribed to

Note: If ABR is disabled, setting this will make the client instantly subscribe to this size

Parameters​

• size: Size

Returns​

void

maxVideoBitRate​

Get Signature​

get maxVideoBitRate(): number

The max video bit rate that will be subscribed to

Note: Returns Number.MAX_SAFE_INTEGER if no limits have been set

Returns​

number

Set Signature​

set maxVideoBitRate(bitRate): void

Set max video bit rate that will be subscribed to

Note: If ABR is disabled, setting this will make the client instantly subscribe to this bitrate

Parameters​

• bitRate: number

Returns​

void

media​

Get Signature​

get media(): Media

Media (audio | video | audio+video)

Returns​

Media

muted​

Get Signature​

get muted(): boolean

Whether the playback is muted or not

Returns​

boolean

Set Signature​

set muted(muted): void

Set playback to muted/unmuted

Parameters​

• muted: boolean

Returns​

void

playbackLatency​

Get Signature​

get playbackLatency(): undefined | number

The estimated playback latency based on target buffer time, the connection rtt and local playback drift

Returns​

undefined | number

playbackState​

Get Signature​

get playbackState(): Readonly<PlaybackState>

The current playback state

Returns​

Readonly<PlaybackState>

playbackWallclockTime​

Get Signature​

get playbackWallclockTime(): undefined | number

The estimated utc timestamp (in ms) for the playhead.

Returns​

undefined | number

renditionLevels​

Get Signature​

get renditionLevels(): readonly RenditionLevel[]

The rendition levels available.

Returns​

readonly RenditionLevel[]

serverEdgeTime​

Get Signature​

get serverEdgeTime(): undefined | number

Estimated live edge time for the current channel

Returns​

undefined | number

serverWallclockTime​

Get Signature​

get serverWallclockTime(): undefined | number

Returns​

undefined | number

Estimated wallclock time on the edge server in milliseconds

sizeBasedResolutionCapEnabled​

Get Signature​

get sizeBasedResolutionCapEnabled(): boolean

Whether user bandwidth savings by capping the video resolution to the size of the video element is enabled

Returns​

boolean

Set Signature​

set sizeBasedResolutionCapEnabled(enabled): void

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

Parameters​

• enabled: boolean

Returns​

void

targetBufferTime​

Get Signature​

get targetBufferTime(): number

The current target buffer time in milliseconds

Returns​

number

Set Signature​

set targetBufferTime(bufferTimeMs): void

Set the current target buffer time in milliseconds

Parameters​

• bufferTimeMs: number

Returns​

void

targetRenditionLevel​

Get Signature​

get targetRenditionLevel(): undefined | Readonly<RenditionLevel>

The target rendition level that the client is currently switching to

Returns​

undefined | Readonly<RenditionLevel>

textTrack​

Get Signature​

get textTrack(): undefined | string

Get the active text track

Returns​

undefined | string

Set Signature​

set textTrack(label): void

Set the active text track

Parameters​

• label: undefined | string

Returns​

void

textTracks​

Get Signature​

get textTracks(): string[]

Get the available text tracks

Returns​

string[]

uptime​

Get Signature​

get uptime(): number

How long in milliseconds since the instance was created

Returns​

number

videoBitRate​

Get Signature​

get videoBitRate(): number

The current average video bit rate in bits/s

Returns​

number

videoBufferedRanges​

Get Signature​

get videoBufferedRanges(): readonly TimeRange[]

The time ranges buffered for video. The ranges are specified in milliseconds.

Returns​

readonly TimeRange[]

volume​

Get Signature​

get volume(): number

The current volume. Note that if the playback is muted volume can still be set.

Returns​

number

Set Signature​

set volume(volume): void

Set the current volume. Setting this to 0 is not equivalent to muting the audio. Setting this to >0 is not equivalent to unmuting the audio.

Note that setting volume is not allowed on iPadOS and iOS devices. This is an OS/browser limitation on the video element.

Read more about it on Apple docs for iOS-Specific Considerations. The following section is the important part: On iOS devices, the audio level is always under the user's physical control. The volume property is not settable in JavaScript. Reading the volume property always returns 1.

Parameters​

• volume: number

Returns​

void

Methods​

attach()​

attach(container): void

Attaches the video view to a DOM element. The Vindral video view will be sized to fill this element while maintaining the correct aspect ratio.

Parameters​

• container: HTMLElement

the container element to append the video view to. Often a div element.

Returns​

void

connect()​

connect(): void

Returns​

void

Deprecated​

since 3.0.0 Use play instead. Connects to the configured channel and starts streaming

getApiClient()​

getApiClient(): ApiClient

The API client for calls to the public available endpoints of the Vindral Live CDN.

Returns​

ApiClient

getCastOptions()​

getCastOptions(): Options

Get options that can be used for CastSender

Returns​

Options

getOptions()​

getOptions(): Options & object

Get active Vindral Options

Returns​

Options & object

getStatistics()​

getStatistics(): Statistics

This method collects a statistics report from internal modules. While many of the report's properties are documented, the report may also contain undocumented properties used internally or temporarily for monitoring and improving the performance of the service.

Use undocumented properties at your own risk.

Returns​

Statistics

getThumbnailUrl()​

getThumbnailUrl(): string

Get url for fetching thumbnail. Note that fetching thumbnails only works for an active channel.

Returns​

string

on()​

on<T>(eventName, fn): void

Add an event listener to eventName

Event listeners may optionally return a "defer function" that will be called once all other listeners have been called. This is useful when one listener may want everone to have reacted to an event before calling something.

Type Parameters​

• T extends "initialized media"

Parameters​

• eventName: T

• fn

Returns​

void

Inherited from​

Emitter.on

once()​

once<T>(eventName, fn): void

Add an event listener to eventName that will be called once only

Event listeners may optionally return a "defer function" that will be called once all other listeners have been called. This is useful when one listener may want everone to have reacted to an event before calling something.

Type Parameters​

• T extends "initialized media"

Parameters​

• eventName: T

• fn

Returns​

void

Inherited from​

Emitter.once

pause()​

pause(): void

Pauses the stream. Call .play() to resume playback again.

Returns​

void

play()​

play(): void

Start playing the stream.

This method also activates audio or video on web browsers that require a user gesture to enable media playback. The Vindral instance will emit a "needs user input" event to indicate when this is needed. But it is also safe to pre-emptively call this if it is more convenient - such as in cases where the Vindral instance itself is created in a user input event.

Note: In most browsers this method needs to be called within an user-input event handler, such as an onclick handler in order to activate audio. Most implementations call this directly after constructing the Vindral instance once in order to start playing, and then listen to a user-event in order to allow audio to be activated.

Note 2: Even if you pre-emptively call this it is still recommended to listen to "needs user input" and handle that event gracefully.

Returns​

void

unload()​

unload(): Promise<void>

Fully unloads the instance. This disconnects the clients and stops any background tasks. This client instance can not be used after this has been called.

Returns​

Promise<void>

updateAuthenticationToken()​

updateAuthenticationToken(token): void

Update authentication token on an already established and authenticated connection

Parameters​

• token: string

Returns​

void

userInput()​

userInput(): void

Returns​

void

Deprecated​

since 3.0.0 Use play instead.

Activates audio or video on web browsers that require a user gesture to enable media playback. The Vindral instance will emit a "needs user input" event to indicate when this is needed. But it is also safe to pre-emptively call this if it is more convenient - such as in cases where the Vindral instance itself is created in a user input event.

Requirements: This method needs to be called within an user-input event handler to function properly, such as an onclick handler.

Note: Even if you pre-emptively call this it is still recommended to listen to "needs user input" and handle that event gracefully.