@weltn24/videoplayer NPM

WELT Video Player

This video player is a wrapper for the Bitmovin Player with its own module/plugin system. In production on welt.de.

Architecture

Architecture Schema

Bitmovin

Bitmovin Player Documentation - Often not complete, not up to date.

Bitmovin Slack Support Channel - Ask for help and advice. To get access, ask somebody from the 1UP team.

Axel-Springer & Bitmovin Bugtracking Repo - File an issue or report a bug.

Usage

yarn add @weltn24/videoplayer

To use the video player in your project follow that scheme:

import { VideoPlayerBuilder, VideoPlayer } from '@weltn24/videoplayer';

import { AdvertisementPlayerModule } from '@weltn24/videoplayer/dist/module/advertisement';
import { TrackingPlayerModule } from '@weltn24/videoplayer/dist/module/tracking';

// HTML Element where to render the player
const videoPlayerElement = document.getElementById('video-player-id');

// source configuration (here an example)
const config = {
    title: 'Foo bar title',
    poster: 'https://www.example.com/images/poster.jpg',
    sources: [
        {
            src: 'https://example.com/videos/foo.m3u8',
            extension: 'm3u8'
        },
        {
            src: 'https://example.com/videos/bar.mp4',
            extension: 'mp4'
        }
    ]
};

// modules to apply to the player
const modules = [new AdvertisementPlayerModule('https://www.domain.de/vast-url.vast'), new TealiumTrackingPlayerModule({ id: 'video-id' })];

// Create a new instance.
// The VideoPlayerBuilder handles the whole assembly process of a player instance.
const videoPlayer = new VideoPlayerBuilder(videoPlayerElement, config).withModules(modules).build();

await videoPlayer.init();

// Player controls.
await videoPlayer.play();
videoPlayer.pause();

// Destroying the player instance.
await videoPlayer.destroy();

Modules

Each player module is a class instance located at weltn24/videoplayer/dist/module/<MODULE_NAME>.

Here are some examples:

// basic player modules
import { PlayerExposalPlayerModule } from '@weltn24/videoplayer/dist/module/player-exposal';
import { VRPlayerModule } from '@weltn24/videoplayer/dist/module/virtual-reality';

const playerExposalPlayerModule = new PlayerExposalPlayerModule();
const vrPlayerModule = new VRPlayerModule();

// configurable modules
import { AnalyticsPlayerModule } from '@weltn24/videoplayer/dist/module/analytics';
import { TealiumTrackingPlayerModule } from '@weltn24/videoplayer/dist/module/tealium-tracking';

const analyticsPlayerModule = new AnalyticsPlayerModule('some-video-id');
const trackingPlayerModule = new TealiumTrackingPlayerModule({ id: 'video-id' });

The modules get passed to the VideoPlayerBuilder instance before calling videoPlayerBuilder.build().

Configuration

const config = {
    sources: [], // Mandatory list of playable video sources (URLs).
    apiKey: '', // Optional Bitmovin Player API key.
    title: '', // Optional title of the current video. This is part of the player UI.
    poster: '', // Optional poster image url. Gets displayed at the beginning, in the error and end screens.
    isPreload: false, // Optional flag for preloading the video (before user interacts). Default: false
    isAutoplay: false, // Optional flag for auto playing the video (depends on the browser). Default: false
    isMuted: true, // Optional flag for muting the video. Default: false
    startLivestreamFromBeginning: true // Optional flag for livestreams which should start from the beginning (e.g. for Bundesliga). Default: false
};

API

const videoPlayer = new VideoPlayerBuilder(videoPlayerElement, config).withModules(modules).build();

// Callbacks
videoPlayer.on('paused', event => {});
videoPlayer.off('paused', event => {});
videoPlayer.onPlay(event => {});
videoPlayer.onDestroy(event => {});
videoPlayer.onError(event => {});

// Controls
await videoPlayer.play();
videoPlayer.pause();
await videoPlayer.destroy();
await videoPlayer.scheduleAd({
    url: 'https://www.domain.com/vast.xml',
    type: 'vast',
    scheduleTime: 60
});

// State
const config = videoPlayer.getConfig();
const currentTime = videoPlayer.getCurrentTime();
const duration = videoPlayer.getDuration();
const initialized = videoPlayer.isInitialized();
const playing = videoPlayer.isPlaying();
const autoplay = videoPlayer.isAutoplay();
const fullscreen = videoPlayer.isFullscreen();
const live = videoPlayer.isLive();
const muted = videoPlayer.isMuted();
const adActive = videoPlayer.isAdActive();
const overlayActive = videoPlayer.isOverlayActive();

// UI
videoPlayer.showOverlay(document.getElementById('overlay'));
videoPlayer.closeOverlay();

Player modules

Purpose

Modules are a great way to reduce bundle size, improve loading time and extend the players' functionality. This feature enables the client to load modules dynamically and only when needed, and gain more control over the featureset of the video player.

Location

All player modules are located at:

@weltn24/videoplayer/dist/module/ for external usage
videoplayer/module/ in the source code

Modules

These are the currently available modules:

active-tab-watcher: Pauses video when switching tabs.
advertisement: Shows advertisement via Ad Technology (Media Impact).
amp: Special amp event mapping module to use the player in <amp-video-iframe> (see /amp.html)
analytics: Enables tracking via Bitmovin Analytics.
anti-ad-block: Shows advertisement even if an ad blocker is used (Schnee von Morgen).
chrome-cast: Enables streaming via Chromecast.
end-screen: Shows a screen with related videos after a video has finished playing. The first video will be played automatically after a few seconds if the user does not cancel the process.
error-screen: Shows an error screen for the video player when something went wrong.
inf-online-measurement-manager: Enables tracking via INFOnline Measurement Manager.
nielsen-tracking: Enables tracking via Nielsen.
player-exposal: Exposes the video player instances to window.__videoPlayerInstances (e.g. used by A/B testing team).
polyfill: Provides JS polyfills, mainly required for IE.
tealium-tracking: Enables tracking via Tealium.
thumbnail: Shows thumbnails when hovered over the seekbar.
unmute-ribbon: Shows a ribbon to unmute the video when it's played automatically and muted.
virtual-reality: This is the required core module to play VR/360 videos.
welt-plus-end-screen: Shows a Welt Plus screen after a video has finished playing.

Theme

The player provides a WELT specific theme. It can be used in two different ways:

Import

@import 'node_modules/@weltn24/videoplayer/dist/theme/css/welt-videoplayer-theme.css';

Mixin

@use 'node_modules/@weltn24/videoplayer/dist/theme/scss/welt-videoplayer-theme' as theme;

@include theme.create-welt-video-player-theme();

Setup

Node

Run nvm use or install the node version specified in the .nvmrc file from here.

Install

This project uses yarn, you can install it from here. Just run yarn to install all required packages.

Authentication

There are two keys for the bitmovin player. One development key that allows any host URL and should never be published, and one production key that allows only localhost and welt.de. You have to retrieve them from passwords (or from a coworker) and store them in the .env file as shown in the .env.example file.

Tasks

yarn analyze        # Analyze the player and the player modules with the webpack bundle analyzer
yarn start          # Start a webpack dev server on port 9000
yarn build          # Compile all SCSS and Typescript files into the dist folder, used for production
yarn test           # Run all tests with karma and generate a coverage report in /coverage
yarn lint           # Lint all SCSS and Typescript files
yarn release        # Release a new npm package version

The development server starts the test-cockpit which contains the video player and different configuration options for it.