JS Video Player & SDK

Main principles

Gcore JS Video Player (@gcorevideo/player) is a lightweight, customizable video player built on top of hls.js, dash.js, and native tag <video />. It supports LIVE and VOD playback with low-latency, adaptive protocols, and flexible embedding options.

Full SDK reference is available on https://github.com/G-Core/gcore-videoplayer-js/.

Interactive JS example:

Why use it?

• Supports HLS, LL-HLS, MPEG-DASH, LL-DASH, MP4.
• Works in all browsers, and on all PCs and mobile devices.
• Configurable via plugins.
• Full control with SDK methods, events, and error handling.
• Works with any source URL (not limited to Gcore Streaming Platform).

The player was originally created to support LL-HLS and LL-DASH with a latency of ±2-3 seconds, and VOD with different quality levels.

We developed a new version of the player from scratch using experience in working with video transcoding, video delivery over public network, and video playback.

Our architecture is based on the following blocks:

• Core of the player is Clappr module.
• hls.js to play HLS and LL-HLS on devices without native support.
• dash.js to play DASH and LL-DASH on devices without native support.
• Wrapper of <video /> element for native playback of video formats.

Various plugins (marked with PLUGIN keyword) are available to extend the core functionality with additional features. See full list of plugins, methods, and events in github.

Live demo

We prepared 2 live demo projects for you:

Vanilla JS

Vanilla JS version directly imported as a .js file into a web page. This demo is a real browser page that works as a permanent public example. It contains both Live and VOD players, external custom control buttons, and separate log panels so you can clearly see player events in real time.

What the demo shows:

• Live playback and VOD playback on the same page.
• Switching between different Live and VOD sources.
• Integration of custom external buttons such as Play, Pause, Mute, and volume control.
• Event logs for player lifecycle and playback events.
• Native JavaScript integration without a frontend framework.

Live demo: https://g-core.github.io/gcore-videoplayer-js/example/

Nuxt

Full implementation through installation and configuration of each plugin. All plugins are placed on a separate page, where you can select and enable/disable the necessary ones.

Pages:

• Home – player with configured plugins and sources.
• Settings – Settings and plugins to configure.
• Source – Video sources to play.

Live demo on vercel.app: https://gcore-videoplayer-js-nuxt.vercel.app/settings

Basic functions

Set video source

Controlling how and what your player plays is simple thanks to a set of built‑in functions you can configure at initialization. These options let you switch sources, enable autoplay, loop content, mute on start, and even show a preview image before playback begins.

You can use any video source URL, not just streams hosted on Gcore. The player supports standard formats like HLS (.m3u8) and MPEG-DASH (.mpd), Live and VOD. The player will automatically determine the source type and start playback.

You can define a single source to play, and also multiple sources in the configuration. Player will try them in order, use the first compatible one, and display an error stub if none can be played.

Simple way to start HLS playback:

LIVE, player detects type of video automatically (clickable link to the video):

const player = new Player({
  autoPlay: true,
  mute: true,
  sources: ["https://demo.gvideo.io/cmaf/2675_19146/master.m3u8"],
})

VOD, player detects type of video automatically (clickable link to the video):

const player = new Player({
  autoPlay: true,
  mute: true,
  sources: ["https://demo-public.gvideo.io/videos/2675_w6nGXEimHz4Z6t1j/master.m3u8"],
})

Advanced way to start playback with multiple sources:

Let’s say you want to serve users in different environments. Ideally, you want to deliver a DASH stream, but if the user’s device doesn’t support it, or if the stream fails, you want the player to fall back to HLS. You might also want to show a poster image before playback begins, such as a branded thumbnail or a title screen.

The poster field comes from the Poster plugin and defines which image is shown before playback starts.

You can configure all of this in the player setup:

LIVE (clickable link to the video):

const player = new Player({
  autoPlay: true,
  mute: true,
  playbackType: "live",
  priorityTransport: 'dash', // [dash|hls], "dash" is default value
  sources: [
    {
      source: "https://demo-public.gvideo.io/cmaf/2675_19146/index.mpd",
      mimeType: 'application/dash+xml',
    },
    {
      source: "https://demo-public.gvideo.io/cmaf/2675_19146/master.m3u8", 
      mimeType: 'application/x-mpegURL',
    }
  ],
  poster: { url: 'https://static.gvideo.co/videoplatform/posters/broadcast/21606/e0a5243fdd2ae36061b8cadfa5089fc8.jpeg' },
})

VOD (clickable link to the video):

const player = new Player({
  autoPlay: true,
  mute: true,
  playbackType: "vod",
  priorityTransport: 'dash', // [dash|hls], "dash" is default value
  sources: [
    {
      source: "https://demo-public.gvideo.io/videos/2675_w6nGXEimHz4Z6t1j/master.mpd",
      mimeType: 'application/dash+xml',
    },
    {
      source: "https://demo-public.gvideo.io/videos/2675_w6nGXEimHz4Z6t1j/master.m3u8", 
      mimeType: 'application/x-mpegURL',
    }
  ],
  poster: { url: 'https://static.gvideo.co/videoplatform/posters/video/11452407/eb4fba797fc1f41309e5b0b552319208.jpeg' },
})

Enable autoplay

To enable autoplay, set autoPlay: true. Don’t forget to combine it with mute: true to comply with most browser policies.

const player = new Player({
  autoPlay: true,
  sources: ["https://demo-public.gvideo.io/videos/2675_mvsPGvDVx0Hzbog/master.m3u8"],
})

Loop playback

Use the loop: true config option to repeat the video continuously.

const player = new Player({
  loop: true,
  playbackType: 'vod',
  sources: ["https://demo-public.gvideo.io/videos/2675_mvsPGvDVx0Hzbog/master.m3u8"],
})

Mute on start

Set mute: true to start playback without audio. This helps meet autoplay restrictions.

const player = new Player({
  mute: true,
  sources: ["https://demo-public.gvideo.io/videos/2675_mvsPGvDVx0Hzbog/master.m3u8"],
})

Set thumbnail

Use the Poster plugin and define an image using the poster.url setting. This image appears before playback starts and is helpful for branding, showing a preview, or providing visual context.

poster: {
  url: "https://static.gvideo.co/videoplatform/posters/video/11452143/6423b07877c27c372b205aa99fd13f42.jpeg",
  showForNoOp: true
}

How to customize

Make the player look and behave exactly how you want by applying custom styles or hiding built‑in interface elements before diving into specific tweaks.

How to set custom skin

Since the player’s UI is plugin-based, most interface elements expose class names that can be targeted directly. For complete control over layout and styling, it’s recommended that you define your styles in a scoped or external stylesheet.

Theme eleme	Description
Background color	Background of bottom play panel
Foreground color	Color of icons, play button, and timeline
Text color	Color of text
Hover color	Color of buttons under mouse pointer

Example of CSS can be found here:

  <link rel="stylesheet" href="https://player.gvideo.co/v2/assets/latest/index.css" />

How to hide UI components

The player interface is modular. Visual elements are enabled by activating corresponding plugins. The Media controls plugin handles the core of the UI — if it’s not selected, most visible components won’t appear. Each UI-related plugin can be toggled dynamically at runtime. Some plugins also act as containers and unlock access to additional components.

player.on('ready', () => {
  const mc = player.getPlugin('MediaControl')
  if (mc) {
    mc.disable()
  }
})

If you’re building a completely custom UI, you can disable the default controls (via plugin settings) and implement your interface on top of the core playback API.

Install and configure

Install via npm or yarn

The Gcore Player SDK doesn’t depend on any specific framework — it works with React, Vue, Svelte, plain JS, or even CMS platforms like WordPress and Tilda.

This section shows how to install and launch a minimal player in your environment.

Step 1. Install the SDK

Use npm or yarn to install the player package:

npm install @gcorevideo/player

or

yarn add @gcorevideo/player

Step 2. Import and configure the player

In your frontend app, import the player’s styles and core modules, register the plugins you need, and then initialize the player against your container element once it’s in the DOM by using code like this (adaptable to any framework):

import '@gcorevideo/player/dist/index.css'
import { Player, MediaControl, SourceController } from '@gcorevideo/player'
 
Player.registerPlugin(MediaControl)
Player.registerPlugin(SourceController)
 
const player = new Player({
  autoPlay: true,
  mute: true,
  sources: [{
	source: 'https://example.com/your-video.m3u8',
	type: 'application/x-mpegURL'
  }]
})
 
player.attachTo(document.getElementById('container'))

Step 3: Add container

Then, you must define your container element in HTML or your component:

<div id="container" style="width: 640px; height: 360px;"></div>

Set the container’s width and height explicitly with CSS or inline styles, like in the example. The player attaches only if the container has visible dimensions.

Vanilla JS

As alternative you can directly import native .js file into your HTML pages without installation.

Add module:

<script src="https://player.gvideo.co/v2/assets/latest/index.js"></script>

Or import exact modules and plugins you need:

<script type="module">
  import {
    Player,
    ...
  } from 'https://player.gvideo.co/v2/assets/latest/index.js'
  ...
</script>

Description of how to use and the latest version is alwas available on github.

Get the latest version

You can use the Gcore Player either with a fixed version or always pull the latest release.

Latest build (auto-update):

<script src="https://player.gvideo.co/v2/assets/latest/index.js"></script>

Use this option if you always want your integration to stay updated with the newest features and bug fixes, without manual changes.

Exact version (fixed, no surprises):

<script src="https://player.gvideo.co/v2/assets/latest/index.js"></script>

Use this when you need a stable environment (for production deployments, certification, or long QA cycles) where updates must be tested before rollout. All available versions are listed on npmjs.com/package/@gcorevideo/player.

Recommendation:

• Use exact versions in production for stability.
• Use latest during development or if you need automatic access to improvements.

Use plugins

The following plugins extend the player’s capabilities:

Category	Feature	Description
Playback	Audio tracks	Allows selection of different audio tracks
	Click to pause	Enables pausing by clicking on the player
	Clips	Enables clipping segments from the video
	DVR controls	Enables Digital Video Recorder (DVR) functionality
	Picture in picture	Enables floating mini-player mode
	Playback rate	Adjusts playback speed
	Quality levels	Allows manual or automatic video quality selection
	Seek time	Shows timestamp preview when hovering over the timeline
	Skip time	Allows skipping forward 30s or backward 10s by tapping screen edges on mobile
	Source controller	Manages the auto-selection of playback sources
	Subtitles	Enables closed captions or subtitles
	Volume fade	Smoothly fades volume up when hovering on the player, and down when leaving
UI	Big mute button	Adds a larger mute button on top of the player
	Context menu	Provides a right-click menu with options
	Error screen	Displays an error message if playback fails
	Example UI	Loads an example user interface
	Favicon	Displays a favicon for branding in the browser tab
	Gear button	Adds a settings button to the interface
	Media controls	Displays basic controls (play, pause, seek, etc.)
	Poster	Displays a cover image before playback starts
	Spinner	Displays a loading animation while buffering
	Thumbnails	Shows preview images when hovering over the timeline
Analytics	CMCD	Adds Common Media Client Data support for analytics
	Stats for nerds	Displays detailed performance stats for debugging

For a full list and detailed descriptions of every plugin, see the Plugin Reference in our GitHub repository.

SDK overview

Gcore Video Player is configured through a single object called PlayerConfig. This object defines the player’s behavior, including video sources, playback type, preferred streaming protocol, autoplay and mute settings, poster image, and enabled plugins.

Methods overview

Once the player is initialized, you can use its instance methods to control playback. You don’t need to deal with the internal architecture—most features are exposed via simple methods.

Category	Method	Description
Playback control	player.play()	Start playback
	player.pause()	Pause playback
	player.stop()	Stop playback and clear the current stream
Mute & volume	player.mute()	Mute audio
	player.unmute()	Unmute audio
	player.setVolume(0.5)	Set volume (0.0 – 1.0)
	player.isMuted()	Check if player is muted
	player.getVolume()	Get current volume value
Seek & timing	player.getCurrentTime()	Get current playback position (in seconds)
	player.getDuration()	Get total media duration (in seconds)
	player.seek(120)	Jump to a specific time (e.g. 120 seconds = 2 min)
Cleanup	player.destroy()	Release resources and disconnect player before removing DOM container

For a full list of methods see the Player class in our GitHub repository.

Events overview

The player emits events throughout the playback lifecycle. You can track user interaction, update your interface, or synchronize video playback with other actions in your app.

One of the most common events is play, which triggers when playback begins—either automatically or after user interaction:

player.on("play", () => {
  // Called when playback starts
})

Category	Event	Description
Playback	pause	Triggered when playback is paused
Seek & time	seek	Fired when the current time changes (programmatically or by user action)
Audio	volumeupdate	Fired when volume or mute state changes
Errors	error	Fired when playback fails or media cannot be loaded

For a complete list of player events and their parameters, refer to the PlayerEvent class documentation.

Errors overview

Gcore Video Player emits a standardized error event whenever playback fails. This event returns a PlaybackError object containing details such as error code, message, severity, and source:

player.on("error", (error) => {
  console.warn("Playback error:", error.message)
})

The most common playback errors include:

• Invalid or unreachable video URLs
• Missing or corrupted media metadata
• Unrecognized formats or codec issues

Most non-fatal errors can be handled by showing fallback UI, retrying playback, or switching to a backup stream. We recommend using the SourceController plugin to automate fallback logic and recovery scenarios. You can find additional insights in the PlaybackError reference.

Debug overview

If the video doesn’t start, buffers indefinitely, or behaves unexpectedly, you can enable logs to investigate the issue.

Enable debug output:

Use the built-in tracer utility to print internal logs to the browser console:

import { Logger, LogTracer } from "@gcorevideo/utils"
Logger.enable("*")
const tracer = new LogTracer("your-app-name")

This will show detailed output about player lifecycle events, source selection, buffering status, and error messages, which are helpful when debugging unsupported formats or network failures.

Integrate with observability tools:

Gcore Player supports integration with remote logging platforms like Sentry for production setups. You can send structured metadata (browser, device, resolution, etc.) and playback errors to help identify user-side issues at scale — see the Sentry integration and server-side logging examples.

Limits

Views Statistics

This player does not collect or send usage statistics from end user devices. Viewing statistics are available from CDN data. See the apidocs section Get unique viewers via CDN.

Missing the feature you need?

We are extremely customer-oriented. If you see a lack of functionality, it means the player can be modified to suit your requirements.

If something is missing in the player, it means there were no requirements for implementation. Contact us and we will come up with a suitable solution.