Bitmovin Player UI Framework

4.11.0 · active · verified Sun Apr 19

The `bitmovin-player-ui` package provides a flexible and modular UI framework designed to integrate with the Bitmovin Player API (specifically v8). It abstracts common player controls and displays into customizable components, allowing developers to easily adapt the player's appearance and functionality to specific application needs. Currently at version 4.11.0, the package demonstrates an active release cadence with frequent patch and minor updates focusing on fixes and feature additions, such as enhanced ad display logic and improved UI component exports. Key differentiators include its extensibility, native TypeScript support, and a design that encourages community contributions for further customization and feature development, moving beyond a rigid, predefined player interface.

Common errors

```
TypeError: UIFactory is not a constructor
```
cause Attempting to instantiate `UIFactory` in a CommonJS environment without proper transpilation or using incorrect `require()` syntax.

fix Ensure you are using ES module imports (`import { UIFactory } from 'bitmovin-player-ui';`) and your project is configured for ESM. If strictly in CommonJS, you may need a bundler like Webpack or Rollup to correctly handle ESM imports, or ensure your `tsconfig.json`'s `module` option is set appropriately for your target.
```
Player container element not found! Make sure an element with id="player-container" exists in your HTML.
```
cause The HTML element specified as the target container for the player UI (e.g., `document.getElementById('player-container')`) does not exist or has an incorrect ID in the DOM when the JavaScript executes.

fix Verify that the HTML element (e.g., `<div id='player-container'></div>`) is correctly defined in your `index.html` or similar file, and that your JavaScript code is executed after the DOM is fully loaded (e.g., within a `DOMContentLoaded` listener or at the end of `<body>`).
```
Failed to construct 'Player': 'key' is missing from config.
```
cause The `bitmovin-player` instance was initialized without a valid license key in its configuration object, which is mandatory for the player to function.

fix Provide a valid Bitmovin Player license key in your `playerConfig` object, typically obtained from your Bitmovin dashboard. For production, consider using environment variables for security (`process.env.BITMOVIN_PLAYER_KEY`).

Warnings

breaking The `bitmovin-player-ui` v4.x is specifically designed for and compatible only with `bitmovin-player` v8. Using it with older or newer major versions of the core player will lead to unexpected behavior or outright failure, as API contracts may differ significantly.
Fix: Ensure `bitmovin-player` is installed at a v8.x.x version and correctly initialized alongside `bitmovin-player-ui` v4.x.
gotcha The Bitmovin Player UI framework requires its associated CSS file (`bitmovinplayer-ui.css`) to be loaded for proper rendering and styling. Forgetting to import it will result in an unstyled, broken, or dysfunctional UI components.
Fix: Include `import 'bitmovin-player-ui/dist/css/bitmovinplayer-ui.css';` in your application's entry file (e.g., `index.ts`/`index.js`) or link the CDN CSS file directly in your HTML `<head>` section.

Install

npm install bitmovin-player-ui npm
yarn add bitmovin-player-ui yarn
pnpm add bitmovin-player-ui pnpm

Imports

UIFactory
wrong:
```
const UIFactory = require('bitmovin-player-ui').UIFactory;
```
correct:
```
import { UIFactory } from 'bitmovin-player-ui';
```
The primary class for creating and managing player UI instances. Ensure your build system supports ES Modules.
PlayerUI
```
import { PlayerUI } from 'bitmovin-player-ui';
```
Represents a single UI instance attached to a player. Typically created via `UIFactory.build()`.
UIConfig
wrong:
```
import { UIConfig } from 'bitmovin-player-ui';
```
correct:
```
import type { UIConfig } from 'bitmovin-player-ui';
```
Type definition for configuring the UI. Use `import type` for interfaces to ensure it's removed during compilation.

Quickstart

Initializes a Bitmovin Player (v8) with the default UI layout, attaching it to a specified HTML container element and loading a sample DASH stream.

import { Player } from 'bitmovin-player'; // Requires 'bitmovin-player' v8.x
import { UIFactory } from 'bitmovin-player-ui';
import 'bitmovin-player-ui/dist/css/bitmovinplayer-ui.css'; // Essential for styling

// 1. Get a reference to the container element where the player will be rendered
const playerContainer = document.getElementById('player-container');
if (!playerContainer) {
  console.error('Player container element not found! Make sure an element with id="player-container" exists in your HTML.');
  // In a real application, you might throw an error or handle this gracefully
} else {
  // 2. Initialize the Bitmovin Player with your license key
  const playerConfig = {
    key: process.env.BITMOVIN_PLAYER_KEY ?? 'YOUR_BITMOVIN_PLAYER_LICENSE_KEY_HERE', // Replace with your actual license key
    // Other player configurations can go here
  };
  const player = new Player(playerConfig);

  // 3. Initialize the UI factory and build the default UI for the player
  const uiFactory = new UIFactory();
  const uiManager = uiFactory.build(player, playerContainer);

  // 4. Load a video source
  player.load({
    dash: 'https://bitmovin-a.akamaihd.net/content/MIUI_Sample/MIUI_Sample.mpd',
    // Other source configurations
  }).then(() => {
    console.log('Bitmovin Player UI and source loaded successfully!');
    // player.play(); // Uncomment to auto-play after loading
  }).catch((error) => {
    console.error('Error loading player source:', error);
  });

  // For debugging or global access, expose player and uiManager
  (window as any).bitmovinPlayer = player;
  (window as any).bitmovinUIManager = uiManager;
}

view raw JSON →