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 |
|---|---|
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]]
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>
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 = Level.CRITICAL; 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 = Level.CRITICAL; 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(): Promise<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
Promise<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.