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()
Hierarchy
-
Emitter
<PublicVindralEvents
>↳
Vindral
Properties
pictureInPicture
• Readonly
pictureInPicture: Object
Picture in picture
Type declaration
Name | Type | Description |
---|---|---|
enter | () => Promise <void > | - |
exit | () => Promise <void > | - |
isActive | () => boolean | - |
isSupported | () => boolean | - |
Accessors
abrEnabled
• get
abrEnabled(): boolean
Whether ABR is currently enabled
Returns
boolean
• 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
Name | Type |
---|---|
enabled | boolean |
Returns
void
audioBitRate
• get
audioBitRate(): number
The current average audio bit rate in bits/s
Returns
number
audioBufferedRanges
• get
audioBufferedRanges(): readonly TimeRange
[]
The time ranges buffered for audio. The ranges are specified in milliseconds.
Returns
readonly TimeRange
[]
bufferFullness
• 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
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
channelId(): string
The current channelId
Returns
string
• 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
Name | Type |
---|---|
channelId | string |
Returns
void
channels
• get
channels(): readonly Channel
[]
Channels that can be switched between
Returns
readonly Channel
[]
connectionState
• get
connectionState(): Readonly
<State
>
The current connection state
Returns
Readonly
<State
>
currentRenditionLevel
• get
currentRenditionLevel(): undefined
| Readonly
<RenditionLevel
>
The current rendition level
Returns
undefined
| Readonly
<RenditionLevel
>
currentTime
• get
currentTime(): number
Local current time normalized between all channels in the channel group
Returns
number
isSwitchingRenditionLevel
• get
isSwitchingRenditionLevel(): boolean
True if the client is currently switching from one rendition level to another
Returns
boolean
language
• get
language(): undefined
| string
The current language
Returns
undefined
| string
• set
language(language
): void
Set the current language
Parameters
Name | Type |
---|---|
language | undefined | string |
Returns
void
languages
• get
languages(): readonly string
[]
Languages available
Returns
readonly string
[]
maxAudioBitRate
• 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
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
Name | Type |
---|---|
bitRate | number |
Returns
void
maxSize
• get
maxSize(): Size
Max size that will be subcribed to
Returns
Size
• 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
Name | Type |
---|---|
size | Size |
Returns
void
maxVideoBitRate
• 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
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
Name | Type |
---|---|
bitRate | number |
Returns
void
media
• get
media(): Media
Media (audio | video | audio+video)
Returns
Media
muted
• get
muted(): boolean
Whether the playback is muted or not
Returns
boolean
• set
muted(muted
): void
Set playback to muted/unmuted
Parameters
Name | Type |
---|---|
muted | boolean |
Returns
void
playbackLatency
• 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
playbackState(): Readonly
<PlaybackState
>
The current playback state
Returns
Readonly
<PlaybackState
>
playbackWallclockTime
• get
playbackWallclockTime(): undefined
| number
The estimated utc timestamp (in ms) for the playhead.
Returns
undefined
| number
renditionLevels
• get
renditionLevels(): readonly RenditionLevel
[]
The rendition levels available.
Returns
readonly RenditionLevel
[]
serverEdgeTime
• get
serverEdgeTime(): undefined
| number
Estimated live edge time for the current channel
Returns
undefined
| number
serverWallclockTime
• get
serverWallclockTime(): undefined
| number
Returns
undefined
| number
Estimated wallclock time on the edge server in milliseconds
sizeBasedResolutionCapEnabled
• get
sizeBasedResolutionCapEnabled(): boolean
Whether user bandwidth savings by capping the video resolution to the size of the video element is enabled
Returns
boolean
• set
sizeBasedResolutionCapEnabled(enabled
): void
Enables or disables user bandwidth savings by capping the video resolution to the size of the video element.
Parameters
Name | Type |
---|---|
enabled | boolean |
Returns
void
targetBufferTime
• get
targetBufferTime(): number
The current target buffer time in milliseconds
Returns
number
• set
targetBufferTime(bufferTimeMs
): void
Set the current target buffer time in milliseconds
Parameters
Name | Type |
---|---|
bufferTimeMs | number |
Returns
void
targetRenditionLevel
• get
targetRenditionLevel(): undefined
| Readonly
<RenditionLevel
>
The target rendition level that the client is currently switching to
Returns
undefined
| Readonly
<RenditionLevel
>
textTrack
• get
textTrack(): undefined
| string
Get the active text track
Returns
undefined
| string
• set
textTrack(label
): void
Set the active text track
Parameters
Name | Type |
---|---|
label | undefined | string |
Returns
void
textTracks
• get
textTracks(): string
[]
Get the available text tracks
Returns
string
[]
uptime
• get
uptime(): number
How long in milliseconds since the instance was created
Returns
number
videoBitRate
• get
videoBitRate(): number
The current average video bit rate in bits/s
Returns
number
videoBufferedRanges
• get
videoBufferedRanges(): readonly TimeRange
[]
The time ranges buffered for video. The ranges are specified in milliseconds.
Returns
readonly TimeRange
[]
volume
• get
volume(): number
The current volume. Note that if the playback is muted volume can still be set.
Returns
number
• 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
Name | Type |
---|---|
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
Name | Type | Description |
---|---|---|
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
getCastOptions
▸ getCastOptions(): Options
Get options that can be used for CastSender
Returns
getOptions
▸ getOptions(): Options
& { abrEnabled
: boolean
= true; advanced
: { wasmDecodingConstraint
: Partial
<VideoConstraint
> } ; burstEnabled
: boolean
= false; iosMediaElementEnabled
: boolean
= false; iosWakeLockEnabled
: boolean
= false; logLevel
: Level
; maxAudioBitRate
: number
; maxBufferTime
: number
= 1500; maxSize
: Size
; maxVideoBitRate
: number
; media
: Media
; minBufferTime
: number
= 1500; mseEnabled
: boolean
= true; mseOpusEnabled
: boolean
= false; muted
: boolean
= false; pauseSupportEnabled
: boolean
= true; pictureInPictureEnabled
: boolean
= true; poster
: string
| boolean
; reconnectHandler
: (state
: ReconnectState
) => boolean
| Promise
<boolean
> ; sizeBasedResolutionCapEnabled
: boolean
= true; tags
: string
[] ; telemetryEnabled
: boolean
= true; videoCodecs
: VideoCodec
[] }
Get active Vindral Options
Returns
Options
& { abrEnabled
: boolean
= true; advanced
: { wasmDecodingConstraint
: Partial
<VideoConstraint
> } ; burstEnabled
: boolean
= false; iosMediaElementEnabled
: boolean
= false; iosWakeLockEnabled
: boolean
= false; logLevel
: Level
; maxAudioBitRate
: number
; maxBufferTime
: number
= 1500; maxSize
: Size
; maxVideoBitRate
: number
; media
: Media
; minBufferTime
: number
= 1500; mseEnabled
: boolean
= true; mseOpusEnabled
: boolean
= false; muted
: boolean
= false; pauseSupportEnabled
: boolean
= true; pictureInPictureEnabled
: boolean
= true; poster
: string
| boolean
; reconnectHandler
: (state
: ReconnectState
) => boolean
| Promise
<boolean
> ; sizeBasedResolutionCapEnabled
: boolean
= true; tags
: string
[] ; telemetryEnabled
: boolean
= true; videoCodecs
: VideoCodec
[] }
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
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
Name | Type |
---|---|
T | extends "initialized media" |
Parameters
Name | Type |
---|---|
eventName | T |
fn | () => void |
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
Name | Type |
---|---|
T | extends "initialized media" |
Parameters
Name | Type |
---|---|
eventName | T |
fn | () => void |
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
Name | Type |
---|---|
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.