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.

// DIVA Player SDK
import { DivaWebComponent } from "@deltatre-vxp/diva-sdk/diva-web-sdk";
import type { DivaConfiguration, VideoMetadata, VideoMetadataClean } from "@deltatre-vxp/diva-sdk/diva-web-sdk";
// Import SDK style
import "@deltatre-vxp/diva-sdk/diva-web-sdk/index.min.css";

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: 'https://imasdk.googleapis.com/js/sdkloader/ima3.js',
  googleDAI: 'https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js',
  googleCast: 'https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1',
  threeJs: 'https://cdnjs.cloudflare.com/ajax/libs/three.js/0.148.0/three.min.js',
};

const config: DivaConfiguration = {
  videoId: "<video id>",
  libs: libs,
  setting: {
    general: {
      culture: 'en-GB',
  }
  }, 
  dictionary: {
  messages: {},
  },
  videoMetadataProvider: async (
    videoId: string,
    currentVideoMetadata?: VideoMetadataClean,
    playbackState?: {
      chromecast?: boolean | undefined;
    }): Promise<VideoMetadata> => {
    return {
      "title": "Video Title",
      "sources": [
        {
        "uri": "<stream URL>",
        "format": "HLS"
        }
      ],
      "videoId": "<video id>",
    };
  },
  setAPI: (apiRef: DivaAPI) => {
    //track the API object
    console.log("API Reference:", apiRef);
  },
};

export const App = () => {
  return <DivaWebComponent config={config} />;
};

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

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.

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.

sendCustomKeypress

sendCustomKeypress(key: InputKeys, e?: KeyboardEvent): void

Used to send directly a keypress command like Keys.ARROW_UP ('ArrowUp').
NOTE: remember to send also Keys.ON_KEYUP: 'OnKeyUp' when the user has finished pressing the key

Parameters:

key: The unique InputKey identifier.
e (optional): KeyboardEvent.

InputKeys

export const InputKeys = {
  ARROW_UP: 'ArrowUp',
  ARROW_DOWN: 'ArrowDown',
  ARROW_LEFT: 'ArrowLeft',
  ARROW_RIGHT: 'ArrowRight',

  ENTER: 'Enter',
  BACK: 'Back',
  MENU: 'Menu',
  DELETE: 'Delete',
  EXIT: 'Exit',

  ONE: 'One',
  TWO: 'Two',
  THREE: 'Three',
  FOUR: 'Four',
  FIVE: 'Five',
  SIX: 'Six',
  SEVEN: 'Seven',
  EIGHT: 'Eight',
  NINE: 'Nine',
  ZERO: 'Zero',

  PLAY: 'Play',
  PAUSE: 'Pause',
  TOGGLE_PLAY_PAUSE: 'Play/Pause',
  STOP: 'Stop',
  FAST_FORWARD: 'FastForward',
  FAST_REWIND: 'FastRewind',
  SKIP_BACKWARD: 'SkipBackward',
  SKIP_FORWARD: 'SkipForward',

  CHANNEL_UP: 'ChannelUp',
  CHANNEL_DOWN: 'ChannelDown',

  OPEN_SUBTITLE: 'OpenSubtitle',
  OPEN_TIMELINE_EVENT_LIST: 'OpenTimelineEventList',
  OPEN_VIDEO_LIST_MODE: 'OpenVideoListMode',
  OPEN_AUDIO_PANEL: 'OpenAudioPanel',
  OPEN_VIDEO_QUALITIES_PANEL: 'OpenVideoQualitiesPanel',
  OPEN_DATA_PANELS: 'OpenDataPanels',

  TAB_NAV: 'TabNavigation',
  TAB_BACK_NAV: 'TabBackNav',

  ON_KEYUP: 'OnKeyUp',

  PLAY_FORCED: 'PlayForced',
  PAUSE_FORCED: 'PauseForced',
  SKIP_FORWARD_FORCED: 'SkipForwardForced',
  SKIP_BACKWARD_FORCED: 'SkipBackwardForced',
  OPEN_SETTINGS_FORCED: 'OpenSettingsForced',
  OPEN_AUDIO_PANEL_FORCED: 'OpenAudioPanelForced',
  OPEN_VIDEO_QUALITIES_PANEL_FORCED: 'OpenVideoQualitiesPanelForced',
  OPEN_SUBTITLE_FORCED: 'OpenSubtitleForced',
  OPEN_VIDEO_LIST_MODE_FORCED: 'OpenVideoListMode',

  EXIT_FROM_DIVA: 'ExitFromDiva',

  MOUSE_MOVE: 'MouseMove',
  WHEEL_UP: 'WheelUp',
  WHEEL_DOWN: 'WheelDown',
} as const;

export type InputKeys = (typeof InputKeys)[keyof typeof InputKeys];

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.

openAudioPanel

openAudioPanel(): void

This function opens tha audio selection panel in the video player interface.

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.

openSettingsPanel

openSettingsPanel(): void

This function opens tha settings panel in the video player interface.

openVideoList

openVideoList(): void

This function opens tha videolist panel in the video player interface.

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).

Webpack App
Vanilla Javascript

import { getDivaDevice } from '@deltatre-vxp/diva-web-sdk';

...

console.log(getDivaDevice());

<head>
    ...
    <script src="path/to/diva.bundle.min.js"></script>
</head>
<body>
    <script>
        console.log(divaWebSdk.getDivaDevice());
    </script>
</body>

Video Playback API​

GET Methods​

getPlaybackRate ​

getPlayerDuration ​

getPlayerPosition ​

getPlayerState ​

getSessionId ​

getVersion ​

getVolume ​

getVideoMetadata ​

Actions​

lowerVolume ​

mute ​

pause ​

play ​

raiseVolume ​

resolve ​

seek ​

seekAbsolute ​

seekPercentage ​

setPlaybackRate ​

setVolume ​

skipBack ​

skipForward ​

Other Methods​

fireEvent ​

requestVideoMetadataUpdate ​

sendCustomKeypress ​

sendPlayerCommand ​

Advanced UI Actions​

closeDataPanel ​

enterFullscreen ​

enterPiP ​

exitFullscreen ​

exitPiP ​

openAudioPanel ​

openDataPanel ​

openSettingsPanel ​

openVideoList ​

setTimelineIconsMinDistance ​

toggleFullscreen ​

togglePiP ​

Video Player API​

getDivaResolverSession​

getDivaVersion​

getDivaMajorVersion​

getDivaMinorVersion​

getDivaPatchVersion​

getDivaPlatform​

getDivaDevice​

getDivaDensity​

Video Playback API

GET Methods

getPlaybackRate

getPlayerDuration

getPlayerPosition

getPlayerState

getSessionId

getVersion

getVolume

getVideoMetadata

Actions

lowerVolume

mute

pause

play

raiseVolume

resolve

seek

seekAbsolute

seekPercentage

setPlaybackRate

setVolume

skipBack

skipForward

Other Methods

fireEvent

requestVideoMetadataUpdate

sendCustomKeypress

sendPlayerCommand

Advanced UI Actions

closeDataPanel

enterFullscreen

enterPiP

exitFullscreen

exitPiP

openAudioPanel

openDataPanel

openSettingsPanel

openVideoList

setTimelineIconsMinDistance

toggleFullscreen

togglePiP

Video Player API

getDivaResolverSession

getDivaVersion

getDivaMajorVersion

getDivaMinorVersion

getDivaPatchVersion

getDivaPlatform

getDivaDevice

getDivaDensity