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.
- 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.
- 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"],
})
const player = new Player({
autoPlay: true,
mute: true,
sources: ["https://demo-public.gvideo.io/videos/2675_w6nGXEimHz4Z6t1j/master.m3u8"],
})
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' },
})
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/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()
}
})
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
yarn add @gcorevideo/player
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'))
<div id="container" style="width: 640px; height: 360px;"></div>
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>
<script type="module">
import {
Player,
...
} from 'https://player.gvideo.co/v2/assets/2.26.9/index.js'
...
</script>
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)
})
- 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")
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.
