{"id":10578,"library":"bitmovin-player-ui","title":"Bitmovin Player UI Framework","description":"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.","status":"active","version":"4.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/bitmovin/bitmovin-player-ui","tags":["javascript","typescript"],"install":[{"cmd":"npm install bitmovin-player-ui","lang":"bash","label":"npm"},{"cmd":"yarn add bitmovin-player-ui","lang":"bash","label":"yarn"},{"cmd":"pnpm add bitmovin-player-ui","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The UI framework is built to integrate with and requires a Bitmovin Player instance (specifically v8.x.x) to function.","package":"bitmovin-player","optional":false}],"imports":[{"note":"The primary class for creating and managing player UI instances. Ensure your build system supports ES Modules.","wrong":"const UIFactory = require('bitmovin-player-ui').UIFactory;","symbol":"UIFactory","correct":"import { UIFactory } from 'bitmovin-player-ui';"},{"note":"Represents a single UI instance attached to a player. Typically created via `UIFactory.build()`.","wrong":null,"symbol":"PlayerUI","correct":"import { PlayerUI } from 'bitmovin-player-ui';"},{"note":"Type definition for configuring the UI. Use `import type` for interfaces to ensure it's removed during compilation.","wrong":"import { UIConfig } from 'bitmovin-player-ui';","symbol":"UIConfig","correct":"import type { UIConfig } from 'bitmovin-player-ui';"}],"quickstart":{"code":"import { Player } from 'bitmovin-player'; // Requires 'bitmovin-player' v8.x\nimport { UIFactory } from 'bitmovin-player-ui';\nimport 'bitmovin-player-ui/dist/css/bitmovinplayer-ui.css'; // Essential for styling\n\n// 1. Get a reference to the container element where the player will be rendered\nconst playerContainer = document.getElementById('player-container');\nif (!playerContainer) {\n  console.error('Player container element not found! Make sure an element with id=\"player-container\" exists in your HTML.');\n  // In a real application, you might throw an error or handle this gracefully\n} else {\n  // 2. Initialize the Bitmovin Player with your license key\n  const playerConfig = {\n    key: process.env.BITMOVIN_PLAYER_KEY ?? 'YOUR_BITMOVIN_PLAYER_LICENSE_KEY_HERE', // Replace with your actual license key\n    // Other player configurations can go here\n  };\n  const player = new Player(playerConfig);\n\n  // 3. Initialize the UI factory and build the default UI for the player\n  const uiFactory = new UIFactory();\n  const uiManager = uiFactory.build(player, playerContainer);\n\n  // 4. Load a video source\n  player.load({\n    dash: 'https://bitmovin-a.akamaihd.net/content/MIUI_Sample/MIUI_Sample.mpd',\n    // Other source configurations\n  }).then(() => {\n    console.log('Bitmovin Player UI and source loaded successfully!');\n    // player.play(); // Uncomment to auto-play after loading\n  }).catch((error) => {\n    console.error('Error loading player source:', error);\n  });\n\n  // For debugging or global access, expose player and uiManager\n  (window as any).bitmovinPlayer = player;\n  (window as any).bitmovinUIManager = uiManager;\n}","lang":"typescript","description":"Initializes a Bitmovin Player (v8) with the default UI layout, attaching it to a specified HTML container element and loading a sample DASH stream."},"warnings":[{"fix":"Ensure `bitmovin-player` is installed at a v8.x.x version and correctly initialized alongside `bitmovin-player-ui` v4.x.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to instantiate `UIFactory` in a CommonJS environment without proper transpilation or using incorrect `require()` syntax.","error":"TypeError: UIFactory is not a constructor"},{"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>`).","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.","error":"Player container element not found! Make sure an element with id=\"player-container\" exists in your HTML."},{"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`).","cause":"The `bitmovin-player` instance was initialized without a valid license key in its configuration object, which is mandatory for the player to function.","error":"Failed to construct 'Player': 'key' is missing from config."}],"ecosystem":"npm"}