Web Player SDK API Reference

BlendVision Web Player SDK API Reference

Overview

Interfaces

• Player Configuration
• Quality
• Source
• Track

Functions

• createPlayer

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

Name	Type	Description
id	string | HTMLElement	id, selector or reference to the container or media element
config	PlayerConfiguration	object for providing settings

Returns

null | Player

instance of the player

BV Player

Methods

• currentTime
• forward
• getDuration
• getPlaybackSpeed
• getVolume
• isPaused
• isPlaying
• isStalled
• load
• mute
• pause
• play
• release
• rewind
• seek
• setPlaybackSpeed
• setVolume
• unmute

Events

• addEventListener
• removeEventListener

Playback

• getAudioTracks
• getCurrentAudioTrack
• getCurrentQuality
• getCurrentSubtitle
• getQualities
• getSubtitles
• setAudioTrack
• setQuality
• setSubtitle

UI

• setViewMode
• switchControlMode

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

Name	Type	Default value	Description
seconds	number	10	Seconds 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

Name	Type
source	Source | 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

Name	Type	Default value	Description
seconds	number	10	Seconds 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

Name	Type	Description
time	number	Playback 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

Name	Type
speed	number

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

Name	Type	Description
volume	number	The 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

Name	Type	Description
type	string	The event type
listener	any	The event handler

Returns

void

---

removeEventListener

▸ removeEventListener(type, listener): void

Remove event listener from player.

Parameters

Name	Type	Description
type	string	the event type, please use the same type as you used in addEventListener
listener	any	the 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

Name	Type	Description
track	string	The 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

Name	Type
restrictions	Object
restrictions.maxHeight	number
restrictions.minHeight	number

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

Name	Type	Description
track	number	The 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

Name	Type	Description
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

Name	Type	Description
mode	string	Desired 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

Name	Type
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,
    },
});