Skip to main content

​
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 github.
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.
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: 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 Native JS Native JS version directly imported as .js file into a web page. Demo supports simplicity of integration with full set of plugins and rich methods of JS Player SDK. Live demo on codepen.io – https://codepen.io/dmitritz/pen/OPLdEab

​
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 elemeDescription
Background colorBackground of bottom play panel
Foreground colorColor of icons, play button, and timeline
Text colorColor of text
Hover colorColor of buttons under mouse pointer
Example of CSS can be found here: 
  <link rel="stylesheet" href="https://player.gvideo.co/v2/assets/2.26.9/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.

​
Native 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/2.26.9/index.js"></script>
Or import exact modules and plugins you need: 
<script type="module">
  import {
    Player,
    ...
  } from 'https://player.gvideo.co/v2/assets/2.26.9/index.js'
  ...
</script>
Description of how to use and the latest version is alwas available on github.

​
Use plugins

The following plugins extend the player’s capabilities:
CategoryFeatureDescription
PlaybackAudio tracksAllows selection of different audio tracks
Click to pauseEnables pausing by clicking on the player
ClipsEnables clipping segments from the video
DVR controlsEnables Digital Video Recorder (DVR) functionality
Picture in pictureEnables floating mini-player mode
Playback rateAdjusts playback speed
Quality levelsAllows manual or automatic video quality selection
Seek timeShows timestamp preview when hovering over the timeline
Skip timeAllows skipping forward 30s or backward 10s by tapping screen edges on mobile
Source controllerManages the auto-selection of playback sources
SubtitlesEnables closed captions or subtitles
Volume fadeSmoothly fades volume up when hovering on the player, and down when leaving
UIBig mute buttonAdds a larger mute button on top of the player
Context menuProvides a right-click menu with options
Error screenDisplays an error message if playback fails
Example UILoads an example user interface
FaviconDisplays a favicon for branding in the browser tab
Gear buttonAdds a settings button to the interface
Media controlsDisplays basic controls (play, pause, seek, etc.)
PosterDisplays a cover image before playback starts
SpinnerDisplays a loading animation while buffering
ThumbnailsShows preview images when hovering over the timeline
AnalyticsCMCDAdds Common Media Client Data support for analytics
Stats for nerdsDisplays 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.
CategoryMethodDescription
Playback controlplayer.play()Start playback
player.pause()Pause playback
player.stop()Stop playback and clear the current stream
Mute & volumeplayer.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 & timingplayer.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)
Cleanupplayer.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
})
CategoryEventDescription
PlaybackpauseTriggered when playback is paused
Seek & timeseekFired when the current time changes (programmatically or by user action)
AudiovolumeupdateFired when volume or mute state changes
ErrorserrorFired 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.
⌘I