@brightcove/web-sdk
TypeScript icon, indicating that this package has built-in type declarations

1.0.3 • Public • Published

Brightcove Web and Smart TV SDK

The Brightcove Web and Smart TV SDK is a general-purpose SDK for implementing the Brightcove Player in modern applications on web-based platforms - desktop browsers, mobile browsers, and web-based Smart TVs.

Table of Content

API Reference

https://players.brightcove.net/sdk/v{VERSION}/web-sdk/docs/index.html

# use v{major} - latest API reference within a major version
# use v{major}.{minor} - latest API reference within a minor version
# use v{major}.{minor}.{patch} - API reference for a specific version

# Examples:
# latest API reference for v1.x.x:
https://players.brightcove.net/sdk/v1/web-sdk/docs/index.html
# latest API reference for v1.0.x
https://players.brightcove.net/sdk/v1.0/web-sdk/docs/index.html
# API reference for v1.0.0
https://players.brightcove.net/sdk/v1.0.0/web-sdk/docs/index.html

Installation

NPM

npm install @brightcove/web-sdk

CDN

<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/playback/index.iife.min.js"></script>

Specifying a Version

As you may notice, CDN urls have a placeholder for version: {VERSION}.

To specify a version in the CDN URL:

  • Use v{major} to include the latest updates within a major version.
  • Use v{major}.{minor} to include the latest updates within a minor version.
  • Use v{major}.{minor}.{patch} to include a specific version.

For example:

<script src="https://players.brightcove.net/sdk/v1/web-sdk/playback/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v1.1/web-sdk/playback/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v1.1.1/web-sdk/playback/index.iife.min.js"></script>

Here is a list of all available CDN resources:

Playback-only Player

# Playback-only player CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/playback/index.iife.min.js
# Playback-only player CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/playback/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/playback/index.es.js

Playback + UI player

# Playback + UI player CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.iife.min.js
# Playback + UI player CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.es.js
# Playback + UI player CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.css
# Playback + UI player CDN language packs:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/ar.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/de.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/en.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/es.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/fr.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/ja.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/ko.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/zh-Hans.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/languagePacks/zh-Hant.js

Thumbnails Integration

# Thumbnails integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/thumbnails/index.iife.min.js
# Thumbnails integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/thumbnails/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/thumbnails/index.es.js
# Thumbnails integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/thumbnails/index.css

Pinning Integration

# Pinning integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/pinning/index.iife.min.js
# Pinning integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/pinning/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/pinning/index.es.js
# Pinning integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/pinning/index.css

Custom End Screen Integration

# Custom End Screen integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/index.iife.min.js
# Custom End Screen integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/index.es.js
# Custom End Screen integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/index.css
# Custom End Screen integration CDN language packs:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/ar.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/de.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/en.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/es.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/fr.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/ja.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/ko.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/zh-Hans.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/languagePacks/zh-Hant.js

Social End Screen Integration

# Social End Screen integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/index.iife.min.js
# Social End Screen integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/index.es.js
# Social End Screen integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/index.css
# Social End Screen integration CDN language packs:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/ar.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/de.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/en.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/es.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/fr.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/ja.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/ko.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/zh-Hans.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/languagePacks/zh-Hant.js

Social Sharing Integration

# Social Sharing integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/index.iife.min.js
# Social Sharing integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/index.es.js
# Social Sharing integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/index.css
# Social Sharing integration CDN language packs:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/ar.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/de.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/en.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/es.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/fr.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/ja.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/ko.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/zh-Hans.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/languagePacks/zh-Hant.js

IMA Client Side Integration

# IMA Client Side integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/imaClientSide/index.iife.min.js
# IMA Client Side integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/imaClientSide/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/imaClientSide/index.es.js
# IMA Client Side integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/imaClientSide/index.css

SSAI Integration

# SSAI integration CDN JS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/index.iife.min.js
# SSAI integration CDN JS alternative bundles:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/index.cjs.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/index.es.js
# SSAI integration CDN CSS bundle:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/index.css
# SSAI integration CDN language packs:
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/ar.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/de.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/en.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/es.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/fr.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/ja.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/ko.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/zh-Hans.js
https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/languagePacks/zh-Hant.js

Usage

Importing the Player

Playback-Only

SDK provides a lightweight playback-only player. You can use it to build your own Player UI on top of it.

NPM
import { Player } from '@brightcove/web-sdk/playback';
CDN
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/playback/index.iife.min.js"></script>
<script>
  // BrightcoveWebSdkPlayback is globally available namespace
  const { Player } = BrightcoveWebSdkPlayback;
</script>

Playback with UI

For applications that need playback functionality along with a UI, use the following player entry point:

NPM
import { Player } from '@brightcove/web-sdk/ui';
import '@brightcove/web-sdk/ui/styles';
CDN
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.css">
<!--...-->
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.iife.min.js"></script>
<script>
  // BrightcoveWebSdkUi is globally available namespace
  const { Player } = BrightcoveWebSdkUi;
</script>

Initializing a Player

// Account ID is required to initialize a player
const player = new Player({ accountId: '<ACCOUNT_ID>' });

Attach and Detach

// you should "mount" player to some DOM element presented on the page, to start using it:
const root = document.querySelector('#player-mount-root');

player.attach(root);

// you can "unmount" player from the DOM during runtime:
player.detach();

Update Configuration

// you can update player configuration during runtime, example:
player.updateConfiguration({
  brightcove: {
    policyKey: '<POLICY_KEY>'
  },
  ui: {
    language: 'en',
    playsinline: true
  }
});

Loading Media

Video Cloud VOD

// you should pass policy key or authToken before using any Brightcove API:
player.updateConfiguration({
  brightcove: {
    policyKey: '<POLICY_KEY>',
    // authToken: '<AUTH_TOKEN>' // or authToken
  },
});

async function loadVideo(videoId) {
  // you can also abort request by calling abort()
  const { abort, promise } = player.getVideoByIdFromPlaybackApi({ videoId: '<VIDEO_ID>' });

  try {
    let brightcoveVideoModel = await promise;

    player.loadBrightcoveVideoModel(brightcoveVideoModel);
  } catch (error) {
    // Handle error
    console.error('Error loading video:', error);
  }
}

loadVideo('<VIDEO_ID>');

Video Cloud Playlist

// you should pass policy key or authToken before using any Brightcove API:
player.updateConfiguration({
  brightcove: {
    policyKey: '<POLICY_KEY>',
    // authToken: '<AUTH_TOKEN>' // or authToken
  },
});

async function loadPlaylist(playlistId) {
  // you can also abort request by calling abort()
  const { abort, promise } = player.getPlaylistByIdFromPlaybackApi({ playlistId });

  try {
    const playlistModel = await promise;
    const playlistManager = player.getPlaylistManager();

    // Create playlist object
    const playlist = playlistManager.createPlaylistFromBrightcoveVideoModels(playlistModel.videos);

    // Pass the playlist object to the PlaylistManager
    playlistManager.setPlaylist(playlist);

    // Load the first playlist item
    player.loadBrightcoveVideoModel(playlist.getCurrentItem());
  } catch (error) {
    // Handle error
    console.error('Error loading playlist:', error);
  }
}

loadPlaylist('<PLAYLIST_ID>');

function advanceToNextItem() {
  const playlistManager = player.getPlaylistManager();
  const playlist = playlistManager.getPlaylist();

  // Advance to the next item
  playlist.moveToNext();
  player.loadBrightcoveVideoModel(playlist.getCurrentItem());
}

advanceToNextItem();

Video Cloud Related Videos

// you should pass policy key or authToken before using any Brightcove API:
player.updateConfiguration({
  brightcove: {
    policyKey: '<POLICY_KEY>',
    // authToken: '<AUTH_TOKEN>' // or authToken
  },
});

async function loadRelatedVideos(videoId) {
  // you can also abort request by calling abort()
  const { abort, promise } = player.getRelatedVideosByVideoIdFromPlaybackApi({ videoId });

  try {
    const relatedVideos = await promise;
    const playlistManager = player.getPlaylistManager();

    // Create playlist object
    const playlist = playlistManager.createPlaylistFromBrightcoveVideoModels(relatedVideos);

    // Pass the playlist object to the PlaylistManager
    playlistManager.setPlaylist(playlist);

    // Load the first playlist item
    player.loadBrightcoveVideoModel(playlist.getCurrentItem());
  } catch (error) {
    // Handle error
    console.error('Error loading playlist:', error);
  }
}

loadRelatedVideos('<VIDEO_ID>');

function advanceToNextItem() {
  const playlistManager = player.getPlaylistManager();
  const playlist = playlistManager.getPlaylist();

  // Advance to the next item
  playlist.moveToNext();
  player.loadBrightcoveVideoModel(playlist.getCurrentItem());
}

advanceToNextItem();

Video Cloud Search

// you should pass policy key or authToken before using any Brightcove API:
player.updateConfiguration({
  brightcove: {
    policyKey: '<POLICY_KEY>',
    // authToken: '<AUTH_TOKEN>' // or authToken
  },
});

async function loadSearchVideos(query) {
  // you can also abort request by calling abort()
  const { abort, promise } = player.getVideosBySearchFromPlaybackApi({ q: query });

  try {
    const searchVideos = await promise;
    const playlistManager = player.getPlaylistManager();

    // Create playlist object
    const playlist = playlistManager.createPlaylistFromBrightcoveVideoModels(searchVideos);

    // Pass the playlist object to the PlaylistManager
    playlistManager.setPlaylist(playlist);

    // Load the first playlist item
    player.loadBrightcoveVideoModel(playlist.getCurrentItem());
  } catch (error) {
    // Handle error
    console.error('Error loading playlist:', error);
  }
}

// see https://apis.support.brightcove.com/playback/references/reference_v2.html#tag/Videos/operation/Get_Videos
// for query guide
loadSearchVideos('<QUERY>');

function advanceToNextItem() {
  const playlistManager = player.getPlaylistManager();
  const playlist = playlistManager.getPlaylist();

  // Advance to the next item
  playlist.moveToNext();
  player.loadBrightcoveVideoModel(playlist.getCurrentItem());
}

advanceToNextItem();

Remote Source

const source = {
  url: 'http://video.com/index.m3u8'
};

player.loadRemoteVideo(source);

IntegrationsManager

You can integrate specific features using modular imports and the IntegrationsManager:

NPM

import { Player, IntegrationsManager } from '@brightcove/web-sdk/ui';
import { ThumbnailsIntegrationFactory } from '@brightcove/web-sdk/integrations/thumbnails';
import { PinningIntegrationFactory } from '@brightcove/web-sdk/integrations/pinning';
import '@brightcove/web-sdk/ui/styles';
import '@brightcove/web-sdk/integrations/thumbnails/styles';
import '@brightcove/web-sdk/integrations/pinning/styles';

// Register integrations before creating a Player
IntegrationsManager.registerThumbnailsIntegrationFactory(ThumbnailsIntegrationFactory);
IntegrationsManager.registerPinningIntegrationFactory(PinningIntegrationFactory);

const player = new Player({ accountId: '<ACCOUNT_ID>' });

player.updateConfiguration({
  // Integrations can have their own configuration options
  integrations: {
    pinning: {
      posX: 'left',
      posY: 'top',
      closeable: true
    }
  }
});

const root = document.querySelector('#player-mount-root');

player.attach(root);

// Access individual integrations via the IntegrationsManager
const { pinningIntegration } = player.getIntegrationsManager();

// Perform integration-specific operations
pinningIntegration.togglePinning();

CDN

<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/thumbnails/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/pinning/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/imaClientSide/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/index.css">
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/index.css">
<!--...-->
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/thumbnails/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/pinning/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/imaClientSide/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialSharing/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/socialEndScreen/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/customEndScreen/index.iife.min.js"></script>
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/integrations/ssai/index.iife.min.js"></script>
<script>
  // BrightcoveWebSdkUi is available when including web-sdk/ui/index.iife.min.js
  // BrightcoveWebSdkThumbnailsIntegration is available when including web-sdk/integrations/thumbnails/index.iife.min.js
  // BrightcoveWebSdkImaClientSideIntegration is available when including web-sdk/integrations/imaClientSide/index.iife.min.js
  // BrightcoveWebSdkSocialSharingIntegration is available when including web-sdk/integrations/socialSharing/index.iife.min.js
  // BrightcoveWebSdkPinningIntegration is available when including web-sdk/integrations/pinning/index.iife.min.js
  // BrightcoveWebSdkSocialEndScreenIntegration is available when including web-sdk/integrations/socialEndScreen/index.iife.min.js
  // BrightcoveWebSdkCustomEndScreenIntegration is available when including web-sdk/integrations/customEndScreen/index.iife.min.js
  // BrightcoveWebSdkSsaiIntegration is available when including web-sdk/integrations/ssai/index.iife.min.js

  // NOTE! this example is just a demonstration of the IntegrationsManager's available API for each integration.
  // Some integrations might conflict with each other, for example: custom end screen and social end screen.
  // Please do not use this snippet in production.

  const { Player, IntegrationsManager } = BrightcoveWebSdkUi;

  const { ThumbnailsIntegrationFactory } = BrightcoveWebSdkThumbnailsIntegration;
  const { ImaClientSideIntegrationFactory } = BrightcoveWebSdkImaClientSideIntegration;
  const { SocialSharingIntegrationFactory  } = BrightcoveWebSdkSocialSharingIntegration;
  const { PinningIntegrationFactory } = BrightcoveWebSdkPinningIntegration;
  const { SocialEndScreenIntegrationFactory } = BrightcoveWebSdkSocialEndScreenIntegration;
  const { CustomEndScreenIntegrationFactory } = BrightcoveWebSdkCustomEndScreenIntegration;
  const { BrightcoveWebSdkSsaiIntegrationFactory } = BrightcoveWebSdkSsaiIntegration;

  // Register integrations before creating a Player
  IntegrationsManager.registerThumbnailsIntegrationFactory(ThumbnailsIntegrationFactory);
  IntegrationsManager.registerImaClientSideIntegrationFactory(ImaClientSideIntegrationFactory);
  IntegrationsManager.registerSocialSharingIntegrationFactory(SocialSharingIntegrationFactory);
  IntegrationsManager.registerPinningIntegrationFactory(PinningIntegrationFactory);
  IntegrationsManager.registerSsaiIntegrationFactory(BrightcoveWebSdkSsaiIntegrationFactory);
  // you can register only one end screen:
  IntegrationsManager.registerEndScreenIntegrationFactory(SocialEndScreenIntegrationFactory);
  // or
  IntegrationsManager.registerEndScreenIntegrationFactory(CustomEndScreenIntegrationFactory);

  const player = new Player({ accountId: '<ACCOUNT_ID>' });

  player.updateConfiguration({
    // Integrations can have their own configuration options
    integrations: {
      pinning: {
        posX: 'left',
        posY: 'top',
        closeable: true
      }
    }
  });

  const root = document.querySelector('#player-mount-root');

  player.attach(root);

  // Access individual integrations via the IntegrationsManager
  const { pinningIntegration } = player.getIntegrationsManager();

  // Perform integration-specific operations
  pinningIntegration.togglePinning();
</script>

NetworkingManager

The NetworkingManager can be used to hook into the SDK's request/response cycle:

const networkingManager = player.getNetworkingManager();

networkingManager.addRequestInterceptor(Player.RequestType.HlsPlaylist, (request) => {
  console.log('HLS Playlist request interceptor ', request);

  // you can modify request, but you have to return request object:
  return request;
});

networkingManager.addResponseInterceptor(Player.RequestType.HlsPlaylist, (response) => {
  console.log('HLS Playlist response interceptor ', response);

  // you can modify response, but you have to return response object:
  return response;
});

UiManager and UI Components

The UiManager can be used to create and manage UI Components. All SDK UI Components extend the UiComponent class, which has an extensive API.

See the UiComponentDependencies interface for the basic list of options that can be passed to components. Note that different component types can have additional options.

Overriding Default Components

The SDK has the ability to override preexisting default player components. Note that only default player components can be overridden.

NPM
import { UiManager, BigPlayButtonUiComponent, UiComponentType } from '@brightcove/web-sdk/ui';

class CustomPlayButton extends BigPlayButtonUiComponent {
   // ... custom play button code
}

UiManager.overrideDefaultComponent(UiComponentType.BigPlayButton, CustomPlayButton);
CDN
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.css">
<!--...-->
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.iife.min.js"></script>
<script>
  // BrightcoveWebSdkUi is globally available namespace
  const { UiManager, BigPlayButtonUiComponent, UiComponentType } = BrightcoveWebSdkUi;

  class CustomPlayButton extends BigPlayButtonUiComponent {
    // ... custom play button code
  }

  UiManager.overrideDefaultComponent(UiComponentType.BigPlayButton, CustomPlayButton);
</script>

Custom Components

Custom Components can be made from scratch by using the BaseUiComponent class.

Note that each instance of a custom component should have a unique name property.

NPM
import { BaseUiComponent } from '@brightcove/web-sdk/ui';

// import and initialize UI Player

const uiManager = player.getUiManager();
const playerComponent = uiManager.getPlayerContainerUiComponent();

// create a DOM element for the custom component
const customElement = document.createElement('div');

const customComponent = new BaseUiComponent({
  // add a unique name
  name: 'CustomUiComponent',
  componentOptions: {
    // pass the custom DOM element as an option
    el: customElement,
  },
});

// Add the custom component as a child of the player component
playerComponent.addChild(customComponent);

// Or add it as a child of another component, for example the ControlBar
const controlBarComponent = playerComponent.getChild('ControlBar');

controlBarComponent.addChild(customComponent);
CDN
<link rel="stylesheet" type="text/css" href="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.css">
<!--...-->
<script src="https://players.brightcove.net/sdk/v{VERSION}/web-sdk/ui/index.iife.min.js"></script>
<script>
  // BrightcoveWebSdkUi is globally available namespace
  const { BaseUiComponent } = BrightcoveWebSdkUi;

  // ...

  const uiManager = player.getUiManager();
  const playerComponent = uiManager.getPlayerContainerUiComponent();

  // create a DOM element for the custom component
  const customElement = document.createElement('div');

  const customComponent = new BaseUiComponent({
    // add a unique name
    name: 'CustomUiComponent',
    componentOptions: {
      // pass the custom DOM element as an option
      el: customElement,
    },
  });

  // Add the custom component as a child of the player component
  playerComponent.addChild(customComponent);

  // Or add it as a child of another component, for example the ControlBar
  const controlBarComponent = playerComponent.getChild('ControlBar');

  controlBarComponent.addChild(customComponent);
</script>

PlaylistManager and Playlist

The PlaylistManager is used for manipulation of a Playlist object, comprising a list of media sources:

const playlistManager = player.getPlaylistManager();

// Create playlist object from a Playback API response
const videoCloudPlaylist = playlistManager.createPlaylistFromBrightcoveVideoModels(/* Array<BrightcoveVideoModel> */);

// Create playlist object from remote sources
const remotePlaylist = playlistManager.createPlaylistFromRemoteSources(/* Array<Source> */);

// Pass the playlist object to the PlaylistManager
playlistManager.setPlaylist(/* videoCloudPlaylist | remotePlaylist */);

// Load the first playlist item
player.loadBrightcoveVideoModel(playlist.getCurrentItem());

// Playlist methods to set a new item index as the current index
playlist.moveToNext();
playlist.moveToPrevious();
playlist.moveTo(/* index number */)
playlist.shuffle();

// Load the new playlist item
player.loadBrightcoveVideoModel(playlist.getCurrentItem());

Events

// Handle only the first emission of the PlayerPlaying event
player.once(Player.Event.PlayerPlaying, (event) => {
  console.log('PlayerPlaying event: ', event);
});

const handlePlayerQualityLevelsChanged = (event) => console.log('PlayerQualityLevelsChanged event: ', event);

// Handle every emission of the PlayerQualityLevelsChanged event
player.addEventListener(Player.Event.PlayerQualityLevelsChanged, handlePlayerQualityLevelsChanged);

// Remove one specific event listener
player.removeEventListener(Player.Event.PlayerQualityLevelsChanged, handlePlayerQualityLevelsChanged);

// Remove all listeners for a specific event
player.removeAllEventListenersForType(Player.Event.PlayerQualityLevelsChanged);

// Remove all event listeners
player.removeAllEventListeners();

Errors

// Listening for error events
this.player.addEventListener(Player.Event.PlayerError, (event) => {
  const error = event.error;

  console.log('An error occurred:', error);
});

Styling

The SDK provides CSS for the specific modules that have UI features.

If importing the UI-supported Player class from the '@brightcove/web-sdk/ui' entrypoint, you must import the associated CSS from '@brightcove/web-sdk/ui/styles'.

Additionally, if importing any of the integrations with UI features, you must import the styles specific to that integration from '@brightcove/web-sdk/integrations/<integration-name>/styles'

CSS Variables

The CSS from '@brightcove/web-sdk/ui/styles' comes with a set of preset CSS variables to control certain aspects of the player's styling. These CSS variables can be overriden by resetting the value.

.bc-sdk {
  /* Override the default control bar color */
  --bc-sdk-control-bar-color: red;
}

The following are all available CSS variables, along with their default values.

--bc-sdk-control-color

  • The color of buttons and text.
  • Default: #fff

--bc-sdk-progress-color

  • The color of the progress bar.
  • Default: #08088c

--bc-sdk-control-bar-transparency

  • The transparency of the background color of the control bar and the big play button.
  • Default: 0.45;

--bc-sdk-control-bar-color

  • The background color of the control bar and the big play button.
  • Default: rgba(0, 0, 0, var(--bc-sdk-control-bar-transparency));

--bc-sdk-big-play-button--border

  • The border of the big play button.
  • Default: none;

--bc-sdk-big-play-button--width

  • The width of the big play button.
  • Default: 2em;

--bc-sdk-big-play-button--height

  • The height of the big play button.
  • Default: 2em;

Spatial Navigation and Smart TV Usage

Spatial Navigation in the SDK enhances user experience and accessibility on Smart TV devices by enabling navigation through interactive elements within the player using remote control arrow keys.

Enabling Spatial Navigation

player.updateConfiguration({
  ui: {
    spatialNavigation: {
      // Enable Spatial Navigation
      enabled: true,

      // Enable horizontal navigation seek functionality, using right and left RCU arrow keys.
      horizontalSeek: true,
    }
  }
});

const spatialNavigationManager = player.getSpatialNavigationManager()

// Start listening for keydown events
spatialNavigationManager.start();

// Pause listening for keydown events without removing listeners
spatialNavigationManager.pause();

// Resume listening for keydown events after pausing
spatialNavigationManager.resume();

// Disable Spatial Navigation by removing all keydown listeners
spatialNavigationManager.stop();

Spatial Navigation Events

Spatial Navigation provides two events that you can listen to:

  • Player.Event.SpatialNavigation.EndOfFocusableComponents - fired when there are no more focusable components available in the desired direction within the player interface.
  • Player.Event.SpatialNavigation.FocusableComponentsChanged - fired when the list of focusable components changes

Localizations

Support for multiple languages and localizations can be included as follows:

// Import general player localizations
import mainJapanese from '@brightcove/web-sdk/ui/languagePacks/ja';

// Import integration-specific localizations
import ssaiJapanese from '@brightcove/web-sdk/integrations/ssai/languagePacks/ja';

// .. other imports and code

const uiManager = player.getUiManager();

uiManager.addLanguagePack('ja', mainJapanese);
uiManager.addLanguagePack('ja', ssaiJapanese);

Readme

Keywords

none

Package Sidebar

Install

npm i @brightcove/web-sdk

Weekly Downloads

164

Version

1.0.3

License

UNLICENSED

Unpacked Size

14.9 MB

Total Files

642

Last publish

Collaborators

  • rwbarber2
  • aperezbrightcove
  • ireyes94
  • brightcove-admin
  • tedk
  • abradley-brightcove
  • bc-alive
  • lasanchezc
  • marguinbc
  • brightcove-user
  • kmason
  • cbarstow
  • hikeh
  • myerramalla
  • pdias
  • jwhisenant
  • mfregozo
  • adavila1
  • bc-acgarcia
  • rjune
  • fsalazarbc
  • jonbwalsh
  • khaipham
  • wswanbeck
  • gastafurov
  • adalwani
  • ekelson-bcove
  • syseng
  • mcarreiro
  • hwoodbury
  • jblaker
  • bcmauleon
  • paco_oblea_bc
  • biswaranjan
  • barroyo
  • bmartinez
  • bc-jcarlson
  • eledezma
  • jcueto
  • erodrigues
  • psousa
  • marcogaray
  • javibright
  • bcpsalas
  • etobin
  • ackbabe
  • omartinez
  • mgonzalez_bc
  • pdohertybcov
  • muthukumar.bc
  • bzizmond
  • jmpmacedo
  • scorreia
  • lescorcio
  • cavieira
  • arunjeyaprasad
  • bvilvanathan
  • rociosantos
  • agarciabcov
  • attinder
  • lauralopez
  • skumar85
  • hrodriguez2
  • jasilvaantonio
  • palvarezbc
  • ericramos
  • carlosabajo
  • ingrid.s.cruz
  • luis_fernando_lopez_ruiz
  • vishal64
  • tresa.baji
  • luis.garcia.brightcove
  • rodrigofdz
  • pgutierrezgil
  • harish17
  • jjeyaprakash
  • rrajendran1698
  • jlomeli
  • tsraveling_bc
  • sjimenez
  • rwenger_brightcove
  • rujordan
  • niklagbrightcove
  • stuartmh
  • jherrerabcov
  • mshiwal
  • ptamizh
  • akamalakkannan
  • roman-bc
  • jvaldez1
  • mdeltorobcov
  • tnwanna
  • bsahlas.npm
  • dherrera1109
  • hswaminathan
  • echengbc
  • sbarrettbc
  • ldominguez
  • rtezera
  • poneill-bcov
  • v.kozlov_bc
  • kreynolds
  • bc-srimron-soutter
  • jguerra
  • michaelmccarthybc
  • randresf
  • bgs-devops
  • bcmneil
  • bcbclifford
  • brianhsu
  • mcho-bc
  • carredondo
  • kpandiyarajan
  • lvohra
  • sharanya.muruganandam
  • m.morrison
  • amillerbrightcove
  • kevin.schick
  • dsalnikov
  • cloewer_bc
  • dawnpacko
  • xgarcia_npm
  • awaldron
  • ebertaud
  • sstevanus
  • msivalls
  • eolvera
  • juan-sanchez
  • jose.luis.sanchez
  • ttabrilla-bc
  • lmelchorx1
  • joeylesh
  • pedro-cruz
  • rsilva_brightcove
  • abarstowbc
  • sbarathan
  • gestrada-br
  • albertogomez
  • miklospocsaji_bc
  • uomar
  • ddashkevich
  • walterseymourbc
  • imorones
  • norma.gonzalez
  • jfloresbc
  • aviel_resnick
  • alexey.kremsa
  • mlopez.b
  • melinda.darvasi
  • alfredo-reyes
  • daniel_campos
  • skarukamanna
  • jterranova
  • areis10
  • vmnavarro
  • maraiza
  • adambertalanbc
  • gabor.kiacz.brightcove
  • dgonzalez89
  • rwinger
  • ssah
  • sravan.pbr
  • apenigalapati
  • ijunaidf
  • lmaultsby
  • bcc-bfranklin
  • mgoncalves
  • mbalasubramaniam
  • cognatusbgs
  • hugocjim
  • madhu_g
  • arevelo
  • sachin-brightcove
  • bc-jcuevas