Skip to main content

Video API

Video Playback API​

The Video Playback API can be initialized through the divaConfig object with the setAPI, making the APIs globally available throughout the video player instance.
In addition to the WebAPI functions, DIVA provides Video Player API that are immediately available without the need for explicit initialization.

In the example below you will get the apiRef object, which will contain all the methods, properties, and events available in the DIVA Web APIs.

import { AssetState, BoAdapterWebComponentProps, DivaWebBoAdapter, VideoMetadata } from "@deltatre-vxp/diva-sdk/diva-web-bo-adapter";
import "@deltatre-vxp/diva-sdk/diva-web-sdk/index.min.css";
import { useState } from "react";

const videoId = "<videoId>";

const libs = {
  mux: "https://cdnjs.cloudflare.com/ajax/libs/mux.js/6.2.0/mux.min.js",
  shaka: "https://cdnjs.cloudflare.com/ajax/libs/shaka-player/4.11.2/shaka-player.compiled.js",
  hlsJs: "https://cdn.jsdelivr.net/npm/hls.js@1.5.7",
  googleIMA: false,
  googleDAI: false,
  googleCast: false,
  threeJs: false
};

const config = {
  videoId: videoId,
  libs: libs,
  setAPI: (apiRef: DivaAPI) => {
      console.log("API Reference:", apiRef);
  }
};

function App() {
  const [isVideoLive, setIsVideoLive] = useState(false);
  const props: BoAdapterWebComponentProps = {
    settingsUrl: "<settings URL>",
    languageCode: "en-US",
    languageDictionary: "en-US",
    onDivaBoAdapterError: console.error,
    config: config
  }

  return (
    <>
      <DivaWebBoAdapter {...props} />
    </>
  );
}

GET Methods​

getPlaybackRate​

getPlaybackRate(videoId?: string): number

This function returns the current playback rate of the video. The playback rate is a numeric value that indicates the speed at which the video is playing.

  • A value of 1 means the video is playing at normal speed.
  • Values greater than 1 indicate faster playback.
  • Values less than 1 indicate slower playback.

Parameters:

  • videoId (optional): The unique identifier of the video for which the position is being requested. If omitted, the current or default video will be used.

getPlayerDuration​

getPlayerDuration(videoId?: string): { relative: number; absolute: Date }

This function returns the total duration of the video. It provides two values:

  • relative: A numeric value indicating the video's total duration in seconds, relative to the video's logical start.
  • absolute: A Date object that represents the absolute end time of the video, calculated as a Unix timestamp.

Parameters:

  • videoId (optional): The unique identifier of the video for which the position is being requested. If omitted, the current or default video will be used.

getPlayerPosition​

getPlayerPosition(videoId?: string): { relative: number; absolute: Date }

This function retrieves the current playback position of the video. It returns two values:

  • relative: A numeric value representing the playback position in seconds, relative to the video's logical start.
  • absolute: A Date object representing the playback position as a Unix timestamp (the absolute time in the real world when the video reached the current position).

Parameters:

  • videoId (optional): The unique identifier of the video for which the position is being requested. If omitted, the current or default video will be used.

getPlayerState​

getPlayerState(videoId?: string): PlayerState

This function returns the current state of the video player. The returned value is one of the following predefined states:

  • STOPPED: Video playback has stopped.
  • PLAYING: Video is currently playing.
  • BUFFERING: Video is buffering, waiting for data to be loaded.
  • PAUSED: Video playback is paused.
  • UNKNOWN: The video player state cannot be determined.
  • NOT_MONITORED: The player state is not currently being monitored.

Parameters:

  • videoId (optional): The unique identifier of the video for which the position is being requested. If omitted, the current or default video will be used.

getSessionId​

getSessionId(): string

This function returns the unique session identifier of the video player.

getVersion​

getVersion(): string

This function returns the version of the Diva SDK in the format major.minor.patch.

getVolume​

getVolume(videoId?: string): number

This function returns the current volume level of the video player. The volume level is a numeric value between 0 and 1:

  • 0 represents muted audio (no sound).
  • 1 represents maximum volume.

Parameters:

  • videoId (optional): The unique identifier of the video for which the position is being requested. If omitted, the current or default video will be used.

getVideoMetadata​

getVideoMetadata(videoId?: string): VideoMetadata | undefined

This function returns the metadata of the video player. The metadata includes information such as the video's title, description, duration, and other properties.

Parameters:

  • videoId (optional): The unique identifier of the video for which the position is being requested. If omitted, the current or default video will be used.

Actions​

lowerVolume​

lowerVolume: (videoId?: string) => void;

This function decreases the volume level of the video player.

mute​

mute(value: boolean): void

This function mutes or unmutes the audio of the video player based on the value of the value parameter.

  • true: the audio is muted.
  • false: the audio is unmuted.

Parameters:

  • value: A boolean value indicating whether to mute (true) or unmute the audio (false).

pause​

pause(interactive?: boolean): void

This function pauses video playback. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • interactive: A boolean value indicating whether the pause action was triggered by user interaction (true) or programmatically (false or omitted).

Parameters:

  • interactive(optional): A boolean for analytics purposes, to indicate if the pause action was triggered by the user.

play​

play(interactive?: boolean): Promise<void>

This function starts the video playback and returns a promise that resolves once the video begins playing. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • interactive: A boolean value indicating whether the play action was triggered by user interaction (true) or programmatically (false or omitted).

Returns: A promise that resolves when the video starts playing.

Parameters:

  • interactive(optional): A boolean to track if the play action was triggered by user interaction.

raiseVolume​

raiseVolume: (videoId?: string) => void;

This function increases the volume level of the video player.

resolve​

resolve(
	value: string,
	options?: {
		videoId?: string; // if not provided it will fallback to main item
		data?: Record<string, string>;
		dontApplyDefault?: boolean;
	}
): string;

This function resolves a path based on the provided string and optional configuration options. If no options are provided, it falls back to using the main item.

  • value: A string representing the path to resolve.
  • options (optional): An object containing additional data for the resolution process.
    • data: A key-value pair object containing additional context data.
    • dontApplyDefault: A boolean indicating whether to apply default resolution if no other parameters are provided.

Returns: A string representing the resolved path.

Parameters:

  • value: The string to resolve.
  • options (optional): Configuration options for the resolution process.

seek​

seek(value: number, interactive?: boolean): Promise<void>

This function seeks the video playback to a specific position, relative to the video's logical start time. It returns a promise that resolves once the seek operation is complete. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • value: A numeric value representing the position in milliseconds to which the video should seek.
  • interactive: A boolean value indicating whether the seek action was triggered by user interaction (true) or programmatically (false or omitted).

Returns: A promise that resolves when the seek operation is complete.

Parameters:

  • value: The position in milliseconds to which the video should seek.
  • interactive(optional): A boolean to track if the seek action was triggered by user interaction.

seekAbsolute​

seekAbsolute(value: Date, interactive?: boolean): Promise<void>

This function seeks the video playback to a specific position, expressed as a Date object. It returns a promise that resolves once the seek operation is complete. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • value: A Date object in ISO 8601 format (e.g., YYYY-MM-DDThh:mm:ssZ) representing the absolute time to seek to.
  • interactive: A boolean value indicating whether the seek action was triggered by user interaction (true) or programmatically (false or omitted).

Returns: A promise that resolves when the seek operation is complete.

Parameters:

  • value: The absolute time to seek to, expressed as a Date object.

seekPercentage​

seekPercentage(value: number, interactive?: boolean): Promise<void>

This function seeks the video playback to a specific position, expressed as a percentage of the video's total duration. It returns a promise that resolves once the seek operation is complete. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • value: A number representing the percentage of the video to seek to (from 0 to 100).
  • interactive: A boolean value indicating whether the seek action was triggered by user interaction (true) or programmatically (false or omitted).

Returns: A promise that resolves when the seek operation is complete.

Parameters:

  • value: The position as a percentage (0 to 100) of the video's total duration.

  • interactive(optional): A boolean to track if the seek action was triggered by user interaction.

setPlaybackRate​

setPlaybackRate(value: number): void

This function sets the playback rate of the video player to the specified value. The playback rate is a numeric value that indicates the speed at which the video is playing.

  • A value of 1 means the video is playing at normal speed.
  • Values greater than 1 indicate faster playback.
  • Values less than 1 indicate slower playback.

Parameters:

  • value: A numeric value representing the desired playback rate.

setVolume​

setVolume(value: number): void

This function sets the volume level of the video player to the specified value. The volume level is a numeric value between 0 and 1:

  • 0 represents muted audio (no sound).
  • 1 represents maximum volume.

Parameters:

  • value: A numeric value between 0 and 1 representing the desired volume level.

skipBack​

skipBack(interactive?: boolean): Promise<void>

This function seeks the video playback backward by the value specified in the video metadata's behaviour.seekInterval property. The default value is 10 seconds. It returns a promise that resolves once the seek operation is complete. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • interactive: A boolean value indicating whether the skip-back action was triggered by user interaction (true) or programmatically (false or omitted).

Returns: A promise that resolves when the seek operation is complete.

Parameters:

  • interactive(optional): A boolean to track if the skip-back action was triggered by user interaction.

skipForward​

skipForward(interactive?: boolean): Promise<void>

This function seeks the video playback forward by the value specified in the video metadata's behaviour.seekInterval property. The default value is 10 seconds. It returns a promise that resolves once the seek operation is complete. It can optionally track whether the action was initiated by user interaction for analytics purposes.

  • interactive: A boolean value indicating whether the skip-forward action was triggered by user interaction (true) or programmatically (false or omitted).

Returns: A promise that resolves when the seek operation is complete.

Parameters:

  • interactive(optional): A boolean to track if the skip-forward action was triggered by user interaction.

Other Methods​

requestVideoMetadataUpdate​

requestVideoMetadataUpdate(videoId?: string): void

This function forces the video player to request updated metadata for the video from the videoMetadataProvider. This action ensures that any changes to the video's metadata, such as updated duration, seek intervals, or other properties, are applied.

Parameters:

  • videoId (optional): The unique identifier of the video for which to request updated metadata. If omitted, the current or default video will be used.

sendPlayerCommand​

sendPlayerCommand(command: DivaCommand, interactive: boolean, videoId?: string): void | Promise<void>

This function sends a player command to the video player. The command can be one of the following predefined actions:

  • MUTE: Mutes or unmutes the audio.
  • PAUSE: Pauses video playback.
  • PLAY: Starts video playback.
  • PLAYBACK_RATE: Sets the playback rate.
  • SEEK: Seeks the video to a specific position.
  • SEEK_ABSOLUTE: Seeks the video to an absolute position.

Parameters:

  • command: A predefined player command to execute.
  • interactive: A boolean value indicating whether the command was triggered by user interaction.
  • videoId (optional): The unique identifier of the video for which to send the player command. If omitted, the current or default video will be used.
DivaCommand types
export type DivaCommand =
	| DivaCommandMute
	| DivaCommandPause
	| DivaCommandPlay
	| DivaCommandPlaybackRate
	| DivaCommandSeek
	| DivaCommandSeekAbsolute;

Advanced UI Actions​

closeDataPanel​

closeDataPanel(videoId?: string): void

This function closes the currently open data panel in the video player interface.

Parameters:

  • videoId (optional): The unique identifier of the video for which to close the data panel. If omitted, the current or default video will be used.

enterFullscreen​

enterFullscreen(videoId?: string): void

This function enters full-screen mode, expanding the video player to fill the entire screen.

Parameters:

  • videoId (optional): The unique identifier of the video for which to enter full-screen mode. If omitted, the current or default video will be used.

enterPiP​

enterPiP(videoId?: string): void

This function enters Picture-in-Picture (PiP) mode, allowing the video player to be displayed in a small window while the user navigates other content or applications.

Parameters:

  • videoId (optional): The unique identifier of the video for which to enter PiP mode. If omitted, the current or default video will be used.

exitFullscreen​

exitFullscreen(videoId?: string): void

This function exits full-screen mode, returning the video player to its normal display mode.

Parameters:

  • videoId (optional): The unique identifier of the video for which to exit full-screen mode. If omitted, the current or default video will be used.

exitPiP​

exitPiP(videoId?: string): void

This function exits Picture-in-Picture (PiP) mode, returning the video player to its normal display mode.

Parameters:

  • videoId (optional): The unique identifier of the video for which to exit PiP mode. If omitted, the current or default video will be used.

fireEvent​

fireEvent: (
	type: MediaAnalyticEventType,
	payload?:
		| {
				ad: Ad;
			}
		| undefined,
	videoId?: string
) => void;

This function fires an event of the specified type with an optional payload. It is used for Ad beaconing and other analytics purposes.

Parameters:

  • type: The type of event to fire.
  • payload (optional): An object containing additional data associated with the event.
  • videoId (optional): The unique identifier of the video for which to fire the event. If omitted, the current or default video will be used.

openDataPanel​

openDataPanel(value: string, videoId?: string): void

This function opens a data panel in the video player interface. The data panel displays additional information or interactive elements related to the video content.

Parameters:

  • value: A string representing the data panel to open.
  • videoId (optional): The unique identifier of the video for which to open the data panel. If omitted, the current or default video will be used.

setTimelineIconsMinDistance​

setTimelineIconsMinDistance(pixel: number): void

This function sets the minimum distance between icons on the video player's timeline. The value is specified in pixels and determines the spacing between icons displayed on the timeline.

Parameters:

  • pixel: A numeric value representing the minimum distance between icons on the timeline, in pixels.

toggleFullscreen​

toggleFullscreen(videoId?: string): void

This function toggles full-screen mode, switching between full-screen and normal display modes.

Parameters:

  • videoId (optional): The unique identifier of the video for which to toggle full-screen mode. If omitted, the current or default video will be used.

togglePiP​

togglePiP(videoId?: string): void

This function toggles Picture-in-Picture (PiP) mode, switching between PiP and normal display modes.

Parameters:

  • videoId (optional): The unique identifier of the video for which to toggle PiP mode. If omitted, the current or default video will be used.

Video Player API​

These Video Player APIs are accessible directly and do not require the instantiation of the DIVA player.

getDivaResolverSession​

getDivaResolverSession: () => string;

This function returns the unique session identifier of the video player.

getDivaVersion​

getDivaVersion: () => string;

This function returns the version of the DIVA SDK in the format major.minor.patch.

getDivaMajorVersion​

getDivaMajorVersion: () => string;

This function returns the major version of the DIVA SDK.

getDivaMinorVersion​

getDivaMinorVersion: () => string;

This function returns the minor version of the DIVA SDK.

getDivaPatchVersion​

getDivaPatchVersion: () => string;

This function returns the patch version of the DIVA SDK.

getDivaPlatform​

getDivaPlatform: () => 'HTML5';

This function returns the platform on which the DIVA SDK is running. The value is always HTML5.

getDivaDevice​

getDivaDevice: () => 'Web' | 'Tablet' | 'Smartphone';

This function returns the device type on which the DIVA SDK is running. The possible values are:

  • Web: The player is running on a desktop or laptop computer.
  • Tablet: The player is running on a tablet device.
  • Smartphone: The player is running on a smartphone device.

getDivaDensity​

getDivaDensity: () => string;

This function returns the pixel density of the device on which the DIVA SDK is running. The possible values are:

  • @1x: Standard pixel density.
  • @2x: Double pixel density (Retina display).
  • @3x: Triple pixel density (High-resolution display).
import { getDivaDevice } from '@deltatre-vxp/diva-web-sdk';

...

console.log(getDivaDevice());

Was this page helpful?