bplayer-js

v1.3.4

Published

8 days ago

A lightweight HTML5 media player with custom controls, HLS, DASH, captions, keyboard shortcuts, and fullscreen support.

0High
0Medium
0Low

leanderdev

video player html5 hls dash captions fullscreen media plyr

BPlayer

BPlayer is a lightweight HTML5 media player with custom controls, HLS and MPEG-DASH support, captions, keyboard shortcuts, picture-in-picture, fullscreen, and persisted playback preferences.

Compatibility

BPlayer is designed for browsers. It depends on DOM media APIs and should be initialized client-side. If you use a framework with server-side rendering, import and create the player only in browser/client lifecycle code.

TypeScript

First-class types ship in the package — no @types/bplayer-js needed.

import BPlayer, { BPlayerInstance, BPlayerOptions, BPlayerSource } from 'bplayer-js'

const opts: BPlayerOptions = {
  controls: ['play', 'progress', 'volume', 'fullscreen'],
  chapters: [{ time: 0, label: 'Intro' }],
  shortcuts: true
}

const player: BPlayerInstance = new BPlayer('#player', opts)

player.on('progress:50', ({ currentTime, duration }) => {
  console.log(`Halfway: ${currentTime}/${duration}`)
})

// Strongly-typed setters
player.currentTime = 30
player.volume = 0.5

The types include every method, every event with its payload shape, and full coverage of the options bag (BPlayerOptions). Source maps for the JS bundles are not yet published (planned for a future minor).

Install

npm install bplayer-js

Basic Usage

Import the JavaScript and stylesheet, then create a player from a <video> or <audio> element.

import BPlayer from 'bplayer-js'
import 'bplayer-js/style.css'

const player = new BPlayer('#player')

player.on('ready', () => {
  console.log('BPlayer is ready')
})

<video id="player" poster="/poster.jpg">
  <source src="/video.mp4" type="video/mp4" />
  <track
    kind="captions"
    src="/captions.vtt"
    srclang="en"
    label="English"
    default
  />
</video>

You can also pass the media element directly:

const video = document.querySelector('video')
const player = new BPlayer(video)

Browser Global Usage

The UMD build exposes BPlayer on window.

<link rel="stylesheet" href="./dist/style.css" />
<script src="./dist/bplayer.umd.js"></script>

<video id="player">
  <source src="/video.mp4" type="video/mp4" />
</video>

<script>
  const player = new BPlayer('#player')
</script>

BPlayer also auto-initializes elements with the data-bplayer attribute after DOMContentLoaded.

<video data-bplayer>
  <source src="/video.mp4" type="video/mp4" />
</video>

CDN (jsDelivr / unpkg)

Once published, you can load BPlayer straight from a CDN without any build step:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bplayer-js/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/bplayer-js/dist/bplayer.umd.js"></script>

<video data-bplayer>
  <source src="/video.mp4" type="video/mp4" />
</video>

unpkg mirror: https://unpkg.com/bplayer-js/dist/bplayer.umd.js

Optional Streaming Libraries

HLS and DASH playback require hls.js and dashjs as optional peer dependencies. The UMD build does not bundle them — load them via separate <script> tags before bplayer.umd.js when you need streaming support:

<!-- Only required for HLS sources (.m3u8) in non-Safari browsers -->
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<!-- Only required for DASH sources (.mpd) -->
<script src="https://cdn.jsdelivr.net/npm/dashjs@4"></script>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bplayer-js/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/bplayer-js/dist/bplayer.umd.js"></script>

MP4/WebM sources work without those scripts. If you load an HLS/DASH stream without the matching library, BPlayer emits an error event with a clear message.

HLS and DASH

BPlayer automatically detects HLS and DASH from the <source> URL:

<video id="hls-player">
  <source src="/stream.m3u8" type="application/x-mpegURL" />
</video>

<video id="dash-player">
  <source src="/manifest.mpd" type="application/dash+xml" />
</video>

HLS playback uses hls.js when native HLS is not available. MPEG-DASH playback uses dashjs.

Options

const player = new BPlayer('#player', {
  autoplay: false,
  muted: false,
  volume: 1,
  clickToPlay: true,
  hideControls: true,
  resetOnEnd: false,
  seekTime: 10,
  controls: [
    'play-large',
    'play',
    'progress',
    'current-time',
    'duration',
    'mute',
    'volume',
    'settings',
    'cc',
    'pip',
    'fullscreen'
  ],
  speed: {
    selected: 1,
    options: [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
  },
  quality: {
    default: 720,
    options: [4320, 2880, 2160, 1440, 1080, 720, 576, 480, 360, 240]
  },
  keyboard: {
    focused: true,
    global: false
  },
  captions: {
    active: false,
    language: 'auto',
    update: false
  },
  fullscreen: {
    enabled: true,
    fallback: true,
    iosNative: false
  },
  storage: {
    enabled: true,
    key: 'bplayer'
  },
  loop: { active: false },
  ratio: '16:9',
  settings: ['captions', 'quality', 'speed', 'loop'],
  disableContextMenu: true,
  autopause: true
})

Plyr-Compatible Options

BPlayer accepts common Plyr option names so existing Plyr integrations can migrate without changing their configuration shape. Supported compatibility aliases include:

controls: ['captions'] maps to BPlayer's cc control.
loop: { active: true } maps to native media looping.
ratio, keyboard.enabled, fullscreen, captions, storage, settings, autopause, disableContextMenu, resetOnEnd, clickToPlay, seekTime, volume, muted, and autoplay are accepted.
player.source = { type, sources, poster, tracks } is supported and updates MP4, HLS, DASH, posters, and text tracks.
Unsupported provider-specific config such as YouTube/Vimeo options is accepted safely but has no effect on native HTML media playback.

Controls

The controls array controls which UI controls are rendered. Supported values:

play-large
play
rewind
fast-forward
progress
current-time
duration
mute
volume
settings
cc
captions
pip
airplay
download
fullscreen

Methods

await player.play()
player.pause()
player.togglePlay()
player.stop()
player.restart()
player.forward(10)
player.rewind(10)
player.toggleMute()
player.increaseVolume(0.1)
player.decreaseVolume(0.1)
player.toggleFullscreen()
player.enterFullscreen()
player.exitFullscreen()
await player.togglePIP()
player.airplay()
player.download()
player.toggleCaptions()
player.refreshCaptions()
player.setSource('/video.mp4')
player.setControls(['play', 'progress', 'fullscreen'])
player.destroy()

Properties

player.currentTime = 30
console.log(player.currentTime)

player.volume = 0.5
player.muted = true
player.speed = 1.25

console.log(player.duration)
console.log(player.playing)
console.log(player.paused)
console.log(player.fullscreen)
console.log(player.pip)
console.log(player.captionsEnabled)

Events

BPlayer includes a small event emitter.

player.on('play', () => {})
player.once('ready', () => {})
player.off('play')

Common events:

ready
play
pause
ended
timeupdate
durationchange
volumechange
seeking
seeked
progress
waiting
canplay
ratechange
fullscreenchange
pipchange
qualitychange
hlsloaded
dashloaded
error
destroy

Styling

BPlayer exposes CSS custom properties on the .bplayer root, scoped per player. Override them with a plain CSS rule on .bplayer (or any ancestor of your <video>) — no JS config needed, the variables update live.

.bplayer {
  /* Accent — drives the progress fill, AB-loop region, focus rings, etc. */
  --bplayer-color-main: #000000;

  /* Spacing & shape */
  --bplayer-control-spacing: 10px;
  --bplayer-control-radius: 4px;

  /* Typography */
  --bplayer-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --bplayer-font-size-base: 15px;
  --bplayer-font-size-small: 13px;
}

Theming the accent color

The accent color (--bplayer-color-main) drives every tinted surface of the player: progress bar fill, volume fill, focused button ring, AB-loop region, active menu option. Default is black; override per player, per page, or globally.

/* Single player, accent in red */
#promo-video.bplayer {
  --bplayer-color-main: #e53935;
}

/* Brand-wide: every BPlayer on the site picks it up */
:root {
  --bplayer-color-main: #1a73e8; /* Google blue */
}

Programmatic equivalent (no rebuild, applies on next render):

document.querySelector('.bplayer').style.setProperty('--bplayer-color-main', '#e53935')

If you change --bplayer-color-main you should keep --bplayer-color-main-rgb in sync — it's the comma-separated triplet used by rgba() overlays (e.g. the AB-loop highlight). Format is identical to CSS rgb() arguments:

.bplayer {
  --bplayer-color-main: #1a73e8;
  --bplayer-color-main-rgb: 26, 115, 232;
}

Full variable reference

Accent

| Variable | Default | Used by | |---|---|---| | --bplayer-color-main | #000000 | progress fill, volume fill, AB-loop region, active menu item, focus ring | | --bplayer-color-main-rgb | 0, 0, 0 | rgba() overlays (must stay in sync with --bplayer-color-main) | | --bplayer-range-fill-bg | var(--bplayer-color-main) | filled portion of progress / volume track |

Scrubber (the dot on the track)

| Variable | Default | Used by | |---|---|---| | --bplayer-range-thumb-bg | #fff | scrubber fill | | --bplayer-range-thumb-border | var(--bplayer-color-main) | scrubber border color | | --bplayer-range-thumb-border-width | 0 | set to 2px for an outlined dot | | --bplayer-range-thumb-height | 13px (drives width too) | scrubber diameter | | --bplayer-range-track-height | 5px | track thickness |

Central play button (the big circle when paused)

| Variable | Default | Used by | |---|---|---| | --bplayer-play-large-bg | rgba(0,0,0,0.5) | background | | --bplayer-play-large-color | #fff | icon color | | --bplayer-play-large-size | 64px | diameter (icon auto-scales) |

Captions

| Variable | Default | Used by | |---|---|---| | --bplayer-captions-bg | rgba(0,0,0,0.75) | caption pill background | | --bplayer-captions-color | #fff | caption text color | | --bplayer-captions-font-size | 18px | caption text size (mobile: scales down to 14px) |

Spinner / loading

| Variable | Default | Used by | |---|---|---| | --bplayer-spinner-color | #fff | spinner stroke color | | --bplayer-spinner-size | 36px | spinner diameter |

Controls bar

| Variable | Default | Used by | |---|---|---| | --bplayer-controls-bg | rgba(255,255,255,0.92) | bar background | | --bplayer-controls-color | rgba(0,0,0,0.7) | icon color (idle) | | --bplayer-control-spacing | 10px | gap between buttons | | --bplayer-control-radius | 4px | button corner radius |

Overlays

| Variable | Default | Used by | |---|---|---| | --bplayer-badge-bg | rgba(0,0,0,0.7) | toast, stats panel, context menu, shortcuts overlay | | --bplayer-tooltip-bg | rgba(0,0,0,0.9) | hover tooltip on the progress bar | | --bplayer-focus-ring | 0 0 0 2px var(--bplayer-color-main) | visible keyboard focus ring |

Typography

| Variable | Default | Used by | |---|---|---| | --bplayer-font-family | system stack | every label and time display | | --bplayer-font-size-base | 15px | captions, time, settings | | --bplayer-font-size-small | 13px | tooltips |

Recipe: branded player

.bplayer {
  --bplayer-color-main: #1a73e8;
  --bplayer-color-main-rgb: 26, 115, 232;

  /* Outlined scrubber so it pops on light tracks */
  --bplayer-range-thumb-bg: #fff;
  --bplayer-range-thumb-border: #1a73e8;
  --bplayer-range-thumb-border-width: 2px;

  /* Slightly transparent play-large with brand color */
  --bplayer-play-large-bg: rgba(26, 115, 232, 0.85);
  --bplayer-play-large-color: #fff;

  /* Dark captions on light brand */
  --bplayer-captions-bg: rgba(26, 115, 232, 0.95);
  --bplayer-captions-color: #fff;
  --bplayer-captions-font-size: 20px;

  /* Rounded controls */
  --bplayer-control-radius: 9999px;
}

Recipe: minimal monochrome

.bplayer {
  --bplayer-color-main: #111;
  --bplayer-color-main-rgb: 17, 17, 17;
  --bplayer-play-large-bg: rgba(17, 17, 17, 0.85);
  --bplayer-play-large-color: #fff;
  --bplayer-range-thumb-bg: #111;
  --bplayer-range-thumb-border-width: 0;
  --bplayer-spinner-color: #111;
  --bplayer-control-radius: 0;
}

Build

npm run build

The build writes:

dist/bplayer.mjs
dist/bplayer.umd.js
dist/style.css

Publishing

Before publishing, make sure you are logged in to npm:

npm login

Then run:

npm run build
npm pack --dry-run
npm publish

For a scoped package, update name in package.json and publish with the correct access level:

npm publish --access public

License

MIT