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.
#### 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.
SDK provides a lightweight playback-only player. You can use it to build your own Player UI on top of it.
##### NPM
`js import { Player } from '@brightcove/web-sdk/playback'; `
##### CDN
`html
`
#### Playback with UI For applications that need playback functionality along with a UI, use the following player entry point:
##### NPM
`js import { Player } from '@brightcove/web-sdk/ui'; import '@brightcove/web-sdk/ui/styles'; `
##### CDN
`html
`
$3
`js // Account ID is required to initialize a player const player = new Player({ accountId: '' }); `
$3
`js // 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();
`
$3
`js // you can update player configuration during runtime, example: player.updateConfiguration({ brightcove: { policyKey: '' }, ui: { language: 'en', playsinline: true } }); `
$3
#### Video Cloud VOD
`js // you should pass policy key or authToken before using any Brightcove API: player.updateConfiguration({ brightcove: { policyKey: '', // authToken: '' // or authToken }, });
async function loadVideo(videoId) { // you can also abort request by calling abort() const { abort, promise } = player.getVideoByIdFromPlaybackApi({ videoId: '' });
`js // you should pass policy key or authToken before using any Brightcove API: player.updateConfiguration({ brightcove: { policyKey: '', // authToken: '' // or authToken }, });
async function loadPlaylist(playlistId) { // you can also abort request by calling abort() const { abort, promise } = player.getPlaylistByIdFromPlaybackApi({ playlistId });
// Advance to the next item playlist.moveToNext(); player.loadBrightcoveVideoModel(playlist.getCurrentItem()); }
advanceToNextItem();
`
#### Video Cloud Related Videos
`js // you should pass policy key or authToken before using any Brightcove API: player.updateConfiguration({ brightcove: { policyKey: '', // authToken: '' // or authToken }, });
async function loadRelatedVideos(videoId) { // you can also abort request by calling abort() const { abort, promise } = player.getRelatedVideosByVideoIdFromPlaybackApi({ videoId });
// Advance to the next item playlist.moveToNext(); player.loadBrightcoveVideoModel(playlist.getCurrentItem()); }
advanceToNextItem();
`
#### Video Cloud Search
`js // you should pass policy key or authToken before using any Brightcove API: player.updateConfiguration({ brightcove: { policyKey: '', // authToken: '' // or authToken }, });
async function loadSearchVideos(query) { // you can also abort request by calling abort() const { abort, promise } = player.getVideosBySearchFromPlaybackApi({ q: query });
// 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('');
You can integrate specific features using modular imports and the IntegrationsManager:
#### NPM
`js 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: '' });
player.updateConfiguration({ // Integrations can have their own configuration options integrations: { pinning: { posX: 'left', posY: 'top', closeable: true } } });
// you can modify response, but you have to return response object: return response; });
`
$3
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
`js import { UiManager, BigPlayButtonUiComponent, UiComponentType } from '@brightcove/web-sdk/ui';
class CustomPlayButton extends BigPlayButtonUiComponent { // ... custom play button code }
// 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
`html
`
$3
The PlaylistManager is used for manipulation of a Playlist object, comprising a list of media sources:`js const playlistManager = player.getPlaylistManager();
// Create playlist object from a Playback API response const videoCloudPlaylist = playlistManager.createPlaylistFromBrightcoveVideoModels(/ Array/);
// 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());
`
$3
`js // Handle only the first emission of the PlayerPlaying event player.once(Player.Event.PlayerPlaying, (event) => { console.log('PlayerPlaying 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();
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//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.`css .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;
$3
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.
// 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
$3
Support for multiple languages and localizations can be included as follows:`js // 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';