## @brightcove/web-sdk - v0.1.0

# 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 Contents

- Installation
  - NPM
  - CDN
  - Specifying a Version
- Usage
  - Importing the Player
    - Playback-Only
    - Playback with UI
  - Initializing a Player
  - Loading Media
    - Video Cloud VOD
    - Video Cloud Playlist
    - Remote Source
  - `IntegrationsManager`
  - `NetworkingManager`
  - `UiManager`
  - `Playlist` and `PlaylistManager`
  - Events
  - Errors
  - Styling
  - Smart TV Usage
  - Localizations
- API Documentation

## Installation

### NPM

To install the Brightcove Web and Smart TV SDK via npm, run the following command:

    npm install @brightcove/web-sdk

After installation, you can import the SDK using your preferred module system:

#### CommonJS

    const { Player } = require('@brightcove/web-sdk');

#### ES Module

    import { Player } from '@brightcove/web-sdk';

### CDN

You can also include the SDK directly from a CDN:

#### CommonJS:

    <script src="https://players.brightcove.net/sdk/v1/playback/index.cjs.js"></script>

#### ES Module:

    <script type="module" src="https://players.brightcove.net/sdk/v1/playback/index.es.js"></script>

#### IIFE (Immediately Invoked Function Expression):

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

### Specifying a Version

To specify a version in the CDN URL:

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

For example:

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

## Usage

### Importing the Player

#### Playback-Only

For applications that only require playback functionality, and no additional UI features, you can use the playback-only player entry point:

    import { Player } from '@brightcove/web-sdk/playback';

#### Playback with UI

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

    import { Player } from '@brightcove/web-sdk';
    import '@brightcove/web-sdk/styles';

### Initializing a Player

    import { Player } from '@brightcove/web-sdk';
    import '@brightcove/web-sdk/styles';

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

      // Examples of optional parameters
      brightcove: {
        policyKey: '<POLICY_KEY>'
      },
      ui: {
        language: 'fr',
        playsinline: true
      }
    });

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

    // Attach the player to a mount root (DOM element in the page).
    player.attach(root);

    // Dynamically update params in the player configuration
    player.updateConfiguration({
      ui: {
        language: 'en',
        playsinline: false
      }
    });

### Loading Media

#### Video Cloud VOD

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

    async function loadVideo(videoId) {
      const { promise } = player.getVideoByIdFromPlaybackApi({ videoId });

      try {
        let videoModel = await promise;

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

    loadVideo('<VIDEO_ID>');

#### Video Cloud Playlist

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

    async function loadPlaylist(playlistId) {
      const { 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() {
      try {
        const playlistManager = player.getPlaylistManager();
        const playlist = playlistManager.getPlaylist();

        // Advance to the next item
        playlist.moveToNext();
        player.loadBrightcoveVideoModel(playlist.getCurrentItem());
      } catch (error) {
        // Handle error
        console.error('Error advancing to next item:', error);
      }
    }

    advanceToNextItem();

#### Remote Source

    const player = new Player({
      // accountId is still required even when loading remote media
      accountId: '<ACCOUNT_ID>'
    });

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

    try {
      player.loadRemoteVideo(source);
    } catch (error) {
      // Handle error
    }

### `IntegrationsManager`

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

    import { Player, IntegrationsManager } from '@brightcove/web-sdk';
    import { PinningIntegration } from '@brightcove/web-sdk/integrations/pinning';
    import { ThumbnailsIntegration } from '@brightcove/web-sdk/integrations/thumbnails';
    import '@brightcove/web-sdk/styles';
    import '@brightcove/web-sdk/integrations/pinning/styles';
    import '@brightcove/web-sdk/integrations/thumbnails/styles';

    // Register integrations before creating a Player
    IntegrationsManager.registerPinningIntegrationFactory(PinningIntegration);
    IntegrationsManager.registerThumbnailsIntegrationFactory(ThumbnailsIntegration);

    const player = new Player({
      accountId: '<ACCOUNT_ID>',

      // 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();

### `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);

      return request;
    });

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

      return response;
    });

### `UiManager`

    TODO

### `Playlist` and `PlaylistManager`

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

TODO

### Styling

TODO

### Smart TV Usage

TODO

### Localizations

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

    import Japanese from '@brightcove/web-sdk/ui/languagePacks/ja';

    // .. other imports and code

    const uiManager = player.getUiManager();

    uiManager.addLanguagePack('ja', Japanese);

## API Documentation

Detailed API documentation is available here (TODO: ADD LINK)