Skip to main content

Web Player SDK API Reference

BlendVision Web Player SDK API Reference

Overview​

Interfaces​

Functions​

Functions​

createPlayer​

▸ createPlayer(id, config): null | Player

Main function to create a Player instance, you may create with container element or media element. If a media element is provided, the player will start with no UI, if a container element is provided, the player will start with default UI, and create a video element in it.

Parameters​

NameTypeDescription
idstring | HTMLElementid, selector or reference to the container or media element
configPlayerConfigurationobject for providing settings

Returns​

null | Player

instance of the player

BV Player

Methods​

Events​

Playback​

UI​

Methods​

currentTime​

▸ currentTime(): number

Returns the current playback time in seconds of the video.

Returns​

number

Current playback time.

forward​

▸ forward(seconds?): void

Forward to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video.

Parameters​

NameTypeDefault valueDescription
secondsnumber10Seconds to seek forward / 10 seconds by default.

Returns​

void

getDuration​

▸ getDuration(): number

Returns the total duration in seconds of the current video. There's no reference value if it's a live stream.

Returns​

number

duration of the video, -1 if playing a live stream.

getPlaybackSpeed​

▸ getPlaybackSpeed(): number

Returns the current playback speed of the player. 1.0 is the default playback speed, values between 0.0 and 1.0 refer to slow motion and values greater than 1.0 refer to fast forward. Negative values are ignored.

Returns​

number

Current playback speed.

getVolume​

▸ getVolume(): number

Returns the player’s volume between 0.0 (silent) and 1.0 (max volume) by a float number.

Returns​

number

Current volume level.

isPaused​

▸ isPaused(): boolean

Returns true if the video is currently paused.

Returns​

boolean

True if the video is paused.

isPlaying​

▸ isPlaying(): boolean

Returns true if the video is currently playing.

Returns​

boolean

True if the video is playing.

isStalled​

▸ isStalled(): boolean

Returns true if the video is currently stalled (empty buffer).

Returns​

boolean

True if the video is stalled.

load​

▸ load(source): Promise<object>

Sets a new video source and returns a promise which resolves to the player. For cross browser support like Chrome & Safari, you should both DASH/HLS manifest URLs, the player will choose the proper to play.

Example

player.load([
    {
        type: "dash",
        src: "https://storage.googleapis.com/shaka-demo-assets/bbb-dark-truths/dash.mpd",
    },
    {
        type: "hls",
        src: "https://storage.googleapis.com/shaka-demo-assets/bbb-dark-truths-hls/hls.m3u8",
    },
]);

Parameters​

NameType
sourceSource | Source[]

Returns​

Promise<object>

mute​

▸ mute(): void

Mutes the player if an audio track is available. Has no effect if the player is already muted.

Returns​

void

pause​

▸ pause(): void

Pauses the video if it is playing. Has no effect if the player is already paused.

Returns​

void

play​

▸ play(): Promise<void>

Starts playback or resumes after being paused. No need to call it if the player is set autoplay as true during initialize player. Has no effect if the player is already playing

Returns​

Promise<void>

release​

▸ release(): void

Destroy the player and removes all inserted HTML elements and event handlers.

Returns​

void

rewind​

▸ rewind(seconds?): void

Rewind to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video.

Parameters​

NameTypeDefault valueDescription
secondsnumber10Seconds to rewind / 10 seconds by default.

Returns​

void

seek​

▸ seek(time): number

Seeks to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video. Has no effect when watching a live stream as seeking is not possible.

Note: As seeking to end the video may cause glitches and no response to replay. We set the duration - 0.7 in order to prevent these problems.

Parameters​

NameTypeDescription
timenumberPlayback time to set in seconds

Returns​

number

Current playback time

setPlaybackSpeed​

▸ setPlaybackSpeed(speed): void

Sets the playback speed of the player. Fast forward as well as slow motion is supported. Slow motion is used by values between 0 and 1, and fast forward by values greater than 1.

Parameters​

NameType
speednumber

Returns​

void

setVolume​

▸ setVolume(volume): void

Sets the player’s volume in the range of 0.0 (silent) to 1.0 (max volume). Unmutes a muted player if volume > 0.

Parameters​

NameTypeDescription
volumenumberThe volume level of the player from 0.0 to 1.0.

Returns​

void

unmute​

▸ unmute(): void

Unmutes the player if muted.

Returns​

void

Events​

addEventListener​

▸ addEventListener(type, listener): void

Add event listener to player, event types are defined in HTMLMediaElement events, the listener will be attach directly to the inner video element.

See Web Callback Integration for how to use this function.

Parameters​

NameTypeDescription
typestringThe event type
listeneranyThe event handler

Returns​

void

removeEventListener​

▸ removeEventListener(type, listener): void

Remove event listener from player.

Parameters​

NameTypeDescription
typestringthe event type, please use the same type as you used in addEventListener
listeneranythe event handler

Returns​

void

Playback​

getAudioTracks​

▸ getAudioTracks(): Track[]

Get all available audio tracks.

Returns​

Track[]

An array of all available audio tracks.

getCurrentAudioTrack​

▸ getCurrentAudioTrack(): Track

Returns the currently selected audio track, if the user manually selected one. In this case it returns one of the elements of getAudioTracks.

Returns​

Track

Currently selected audio track.

getCurrentQuality​

▸ getCurrentQuality(): void | Quality

Returns the currently selected video quality, if the user manually selected one. In this case it returns one of the elements of getQualities.

Returns​

void | Quality

Current quality or undefined

getCurrentSubtitle​

▸ getCurrentSubtitle(): "off" | Track

Returns the currently selected subtitle, if the user manually selected one. In this case it returns one of the elements of getSubtitles.

Returns​

"off" | Track

Currently selected subtitle.

getQualities​

▸ getQualities(): Quality[]

Returns an array containing all available video qualities the player can adapt.

Returns​

Quality[]

Quality list

getSubtitles​

▸ getSubtitles(): Track[]

Returns an array of all available subtitles.

Returns​

Track[]

An array of all available subtitles.

setAudioTrack​

▸ setAudioTrack(track): any

Manually sets the audio track to a specified language. Available tracks can be retrieved with getAudioTracks.

Parameters​

NameTypeDescription
trackstringThe language of audio

Returns​

any

setQuality​

▸ setQuality(restrictions): any

Manually sets the video stream to a fixed quality, e.g. height range, specified bitrate or null (means auto resets to dynamic switching). A list can be retrieved by calling getQualities.

Parameters​

NameType
restrictionsObject
restrictions.maxHeightnumber
restrictions.minHeightnumber

Returns​

any

setSubtitle​

▸ setSubtitle(track): void

Manually sets the subtitle to a specified trackId or turn-off. Available subtitles can be retrieved with getSubtitles.

Parameters​

NameTypeDescription
tracknumberThe id of subtitle

Returns​

void

UI​

setViewMode​

▸ setViewMode(viewMode): void

Sets the player to fullscreen or exit fullscreen, going fullscreen must be in a user triggered event handler.

Parameters​

NameTypeDescription
viewMode"fullscreen" | "inline"view mode

Returns​

void

switchControlMode​

▸ switchControlMode(mode): void

Sets the UI state automatically. Shows controller when the user interacts with and did when no interaction in 3 seconds. The controller includes a progress bar, seek function, title, back button, play, pause, rewind, thumbnail, and so on.

Parameters​

NameTypeDescription
modestringDesired UI mode.

Returns​

void

Player Configuration

Configuration of the player

Properties​

autoplay​

• autoplay: Boolean

config​

• config: modulesConfig

license​

• license: string

metadata​

• metadata: object

source​

• Optional source: Source[]

title​

• title: string

ui​

• ui: Object

Type declaration​

NameType
locale"en" | "ja" | "zh-TW"
uiMode"audio" | "standalone" | "embedded"

Quality

Properties​

bitrate​

• bitrate: number

frameRate​

• frameRate: number

height​

• height: number

width​

• width: number

Source

An object that describes a single piece of media

Properties​

src​

• src: string

Manifest URL

type​

• type: "thumbnail" | "dash" | "hls"

Track

Properties​

enabled​

• enabled: boolean

id​

• Optional id: string

kind​

• Optional kind: "video" | "audio" | "text"

label​

• Optional label: string

language​

• Optional language: string

Modules Config

normalizeTabSwitch​

• normalizeTabSwitch: boolean | (e: any) => {}

This property controls the default behavior of our player when switching tabs on various versions of Safari and across different devices.

Example

import { createPlayer } from "@blendvision/player";

const player = createPlayer("player-container", {
    modulesConfig: {
        normalizeTabSwitch: false,
    },
});