Skip to content

Freecaster Player Documentation


This documentation provides comprehensive instructions on how to embed a Freecaster video player on a website, along with details on how to customize it to suit specific requirements.


By default the player won’t load the statistics module. In order to load it, you must set the embed attribute dnt (do not track) to false.
User consent is mandatory and required by GDPR legislation.

How to embed

To embed a video, you can use one of the two available embed methods below:

  1. Reference the Freecaster player script in the page (only once, even if multiple players are embedded):

    <script async src=""></script>

  2. Insert a <div> with the .freecaster-player class containing a data-video-id attribute that references the ID of the video you want to embed.
    That <div> will be automatically replaced by the video player when the web page loads.

    <div class="freecaster-player" data-video-id="ID_VIDEO" data-width="640" data-autoplay="true" data-muted="true" data-lang="fr-be" data-dnt="true"></div>

Insert an iframe using the following URL template:

<div style="height:0;padding-bottom:56.250%;position:relative;">
    <iframe src="" width="100%"
            height="100%" style="border:0;left:0;position:absolute;top:0;" frameborder="0" scrolling="no"

Acceptance environment

You must use instead of when testing on our acceptance environment.

Mandatory HTML Tags

In order to fully use the player, the following HTML tags must be present between <head>..</head> tags of your page:

  • <meta name="viewport" content="width=device-width, initial-scale=1.0">

This will ensure the player behave correctly responsively.

  • <meta charset="UTF-8">

This will ensure the document is properly encoded. Without it, you may encounter weird symbol in the player.

Available attributes

When embedding the player, you can provide additional attributes to modify the player configuration.

These attributes can be set using data-* attributes on the <div> tag (JavaScript embed), or by appending query strings in the iframe src attribute (iframe embed).

Attribute Expected value Default value Description
height number Set the height of the player.
width number Set the width of the player.
volume number Set the volume percentage of the player. The value used must be between 0 et 1 (see MDN). If the user specifically muted the sound, it will not "force" the next time he loads the player. There are limitations when used along with autoplay: See Google article for more information.
autoplay boolean false Enable/disable the autoplay. There are limitations when used along with autoplay (See Google article for more information) You must set muted="true" in to be sure for it to work.
autopause boolean true Enabled/disabled the automatic pause when the player is no longer visible in the viewport.
controls boolean true Enable/disable the control bar.
muted boolean false Enable/disable sound.
loop boolean false If set to true, the video will start over upon ending.
cast boolean false Enable/disable Chromecast/AirPlay.
watermark.enabled boolean false Enable/disable the watermark.
lang lang-country The lang provided by the user (language-country (RFC 5646)).
dnt boolean true Trackers (such as Google analytics, mux, youbora, ...) will be disabled.
noads boolean false Enable/disabled advertising.
thumbnails.src thumbnails URL Set specific thumbnails.
poster image URL Set a specific poster.
stretching fill, cover or none false Resize poster and video to fit player dimensions.
fill Will fit player dimensions without maintaining aspect ratio.
cover Will zoom and crop video to fill dimensions, maintaining aspect ratio.
none Displays the actual size of the video file. (Black borders).
subtitles.default_lang lang Set an active subtitle from the desired language (2 letter ISO-639-1 code).
subtitles.lang lang Only show the specified language (2 letter ISO-639-1 code).
subtitles.native boolean false Enable subtitles to be rendered by the browser supporting inline style or CSS rules within VTT file.
float_on_scroll boolean false When enabled, a floating video container will be displayed when the user scroll past the player.
multiplay boolean false Whether the player should pause if another player begins playback.
chapters.enabled boolean false Enable/disable chapters. hidden, dot, full_width hidden Specify the style to use for the timeline's cuepoints.
chapters.list [] [] The list of chapters.
audio_only boolean false Enable/disable minimal player UI. boolean false Enable Google Analytics (GA4) support. By default, window.dataLayer will be used to push events toward GA4. string Add Google Analytics (GA4) tag IDs to track. You can add multiple tags using , as separator.

JavaScript vs iframe parameters

When using the iframe method, you cannot use dashes (-), you must "camelCase" parameters.
Example: data-my-attribute="value" (JavaScript embed) will become ?myAttribute=value (iframe embed)


In order to use stretching, you must set height and width to 100%.

Chapters - list

The chapters.list takes an array of Chapter.
Here is an example payload:

  "id": "94f5fa50-a277-4fca-a311-b114ae344314",
  "start": 0,
  "end": 15000,
  "title": "Some title",
  "description": "Some description",
  "customData": { "someProperty": "some value" } // custom data forwarded as-is
  • start and end are expected to be in milliseconds.
  • customData can be specified and will be forwarded into the Chapter object.

Chapters - events

When entering or leaving a chapter, the player will emit these events:

  • fc_chapter_user_enter: upon entering a chapter
  • fc_chapter_user_leave: upon leaving a chapter
  • fc_chapter_user_mark

You can listen to these events on the player instance.

Audio only

When embedding an audio player, enable the audio_only attribute if you wish to hide the poster.

playerInstance.on('fc_chapter_user_enter', (payload) => console.log(`Entering chapter ${}`))

Available query parameters

start_time, end_time

When sharing a link toward a specific video, you can provide parameters that will seek into start_time (TC IN) and stops at end_time (TC OUT).

The expected value for these query parameters is the time offset from the beginning of the video in seconds.


The video will start 100 seconds after the beginning and stop (pause) 400 seconds later (500 seconds after the beginning of the video).


This feature only works with VOD


You can get the current time position of a video using fcplayer().currentTime.

Player instance

There are various ways to obtain the instance of a player:

  1. By its ID

    You can specify an ID and use it to obtain the player instance.

    For example, given a JS embed:

    <div id="my-unique-id" class="freecaster-player" data-video-id="VIDEO_UUID"></div>

    You can get the player instance using the following method:

    const playerInstance = fcplayer('my-unique-id')

  2. By using the window._fcpr callback

    All player instances will pass through the push function of window._fcpr.

     window._fcpr = window._fcpr || []
     window._fcpr.push((playerInstance) => {
        // if you specified an id on the embed tag (div.freecaster-player), you can check it becomes available by 
        // compararing your ID with
        if ( === 'my-unique-id') {
            // the player you are looking for is ready to use.

The function, window.fcplayers() will return all the player instances that exist within the page.

Iframe embeds

Currently, there is no way to obtain a player instance when embedding a player using an iframe.

Multi-instance handling

When there are multiple players within the page, it is best to set the preload attribute to none. This prevents the browser from preloading videos that may not be within the user's viewport, thereby avoiding any impact on page performance. However, please note that if the videos have the autoplay attribute set to true, the browser will still preload the video regardless of its visibility in the viewport. This is due to standard browser behavior.

Extract from MDN Documentation

The autoplay attribute has precedence over preload. If autoplay is specified, the browser would obviously need to start downloading the video for playback.

Temporary solution

As a workaround, we can advise you to set preload to none and autoplay to false, and then programmatically play the video when it is in the user's viewport.

For example, a Freecaster JS embed would you like this:

<div class="freecaster-player"

Then, within your page, you can use the following script to play the video when it goes into the user's viewport:

// Initialize the window._fcpr object, which will receive a callback when a player is loaded. 
window._fcpr = window._fcpr || []
window._fcpr.push(player => {
  // Once the player is loaded, you can play the video by using the "togglePlay" function when it enters the user's viewport.
  // This essentially functions as an autoplay feature.
    player.once('viewenter', () => player.togglePlay(true))


You only need to insert this script once in your page, it will handle all Freecaster players.

Available properties

Non-exhaustive list of the player properties:

Property Description Usage Return example
currentTime Returns a float with the current playback position in seconds MDN fcplayer().currentTime true/false
currentTimecode Returns a string containing the current timecode fcplayer().currentTimecode "00:00:00:00"
currentTimestamp Returns an integer of the current timestamp (UTC) in milliseconds. This feature only works for DASH or HLS playlists with non-native configuration. fcplayer().currentTimestamp 1586161956320
live Whether the video is a live feed fcplayer().live true/false
container Returns the player's container HTMLElement fcplayer().container <div class="freecaster-player" ...>...</div>
version Returns the current player version fcplayer().version freecaster-player x.x.x (player vx.x.x)

Deprecated properties

Attribute Note
mute use muted instead
repeat use loop instead
aspectratio use ratio instead
playbackRateControls no longer exists
localization no longer exists
displaytitle no longer exists
displaydescription no longer exists
fc-token use video-id instead
locale use lang instead

Available methods

Non-exhaustive list of the player methods:

Method Description Usage Return example
seek Jump toward the inputted currentTime or currentTimestamp fcplayer().seek(120) (will jump toward the 120th second) true/false
fcplayer().seek(1598369613162) (will jump toward Tue Aug 25 2020 17:33:33 (CEST) true/false
setSrc Replaces the current source fcplayer().setSrc(newSource)
loadVideo Load a new video from the API, replaces the current video fcplayer().loadVideo('VIDEO_ID')
destroy Destroy the player instance and remove the element from the DOM fcplayer().destroy()
toggleFullScreen Toggles fullscreen mode fcplayer().toggleFullScreen()
togglePlay Toggles play/pause mode fcplayer().togglePlay()
setConfig Update the player's config fcplayer().setConfig({ tooltips: { enabled: true } })
fcplayer().setConfig('tooltips.enabled', true)
goBackToLive Seeks closer to live fcplayer().goBackToLive()


The seek method only works using an absolute timestamp if:

  • Live: the input timestamp is available within the DVR archive
  • VOD: fcplayer().config.start is provided by the api.


The source parameter's format for setSrc can be one of the following:

  • 'https://path/to/source/file.mp4'
  • { type: 'application/dash+xml', src: 'https://path/to/source/file.mpd'}

or an array:

     { type: 'application/x-mpegurl', src: 'https://path/to/source/file.m3u8'},
     { type: 'application/dash+xml', src: 'https://path/to/source/file.mpd'},
     { type: 'video/mp4', src: 'https://path/to/source/file.mp4'}

Google Analytics (GA4)

In order to use Google Analytics you must:

  1. Add the Google Analytics tag snippet into the pages you want to track.
  2. Enable the plugin using (note: dnt flag must be set to false).
  3. (optional) You can also add one or more Google Analytics tags using
   <div class="freecaster-player""true""GA-XXXXXX,GA-XXXXXX"></div> 


Standard events

Non-exhaustive list of standard events you can listen directly through the player instance:

Event Description Usage
waiting Fired when the player starts playback and when the player enters a buffering state. .on('waiting')
ended Fired when an item completes playback. .on('ended')
error Fired when a media error has occurred, causing the player to stop playback and go into idle mode. .on('error')
pause Fired when the player enters the paused state. .on('pause')
play Fired when the player enters the playing state. .on('play')
ratechanged Fired when the playback rate has been changed. .on('ratechanged')
loadstart This event occurs before the player begins loading a new video. .on('loadstart')
loadedmetadata This event occurs before the player has loaded a video metadata. .on('loadedmetadata')
seeking Fired after a seek has been requested either by scrubbing the controlbar or through the API. .on('seeking')
Seeking is often based on keyframe availability. The actual position the player will eventually seek to may differ from what was specified.
resize Fired when the player's on-page dimensions have changed. .on('resize')

Freecaster Player specific events

Event Description Usage
fullscreenenter Fired when the player enters fullscreen. .on('fullscreenenter')
fullscreenxit Fired when the player exits fullscreen. .on('fullscreenxit')
viewenter Fired when the player is viewable in the browser viewport. .on('viewenter')
viewleave Fired when the player is not viewable anymore in the browser viewport. .on('viewleave')
fcplayerDestroy Fired when the player instance is destroyed. .on('fcplayerDestroy')
fcplayerSrcChanged Fired when the video source has changed. .on('fcplayerSrcChanged')
fcplayerCountdownTick Fired each countdown seconds. .on('fcplayerCountdownTick')
fcplayerCountdownEnabled Fired when the countdown is enabled. .on('fcplayerCountdownEnabled')
fcplayerCountdownDisabled Fired when the countdown is disabled. .on('fcplayerCountdownDisabled')
fcplayerCountdownZero Fired when the countdown is over. .on('fcplayerCountdownZero')

Our player uses cookies and other related technologies (for convenience, all technologies are referred to as "cookies"). Third party services our player is using also make use of cookies. Below you will find information about the use of cookies by our player.

What are cookies?

A cookie is a small simple file that is sent along with pages of this website and stored by your browser on the hard drive of your computer or another device. The information stored therein may be returned to our servers or to the servers of the relevant third parties during a subsequent visit.

How to disable player cookies?

You can disable non-necessary analytics cookies by using the dnt embed parameter. However, this will have a negative impact on the player analytics.

Cookies list

Freecaster (necessary)

Name Purpose Expiry Type
to Store the time difference between the computer clock and the world clock in order to properly display the countdown for live events. 30 minutes HTML Local Storage

Youbora (analytics)

Name Purpose Expiry Type
youbora.accCode Stores the account code Permanent HTML Local Storage Stores API response with plugin settings Permanent HTML Local Storage
youbora.dataTime Stores timestamp of data response Permanent HTML Local Storage Stores the host where the events are send Permanent HTML Local Storage
youbora.offlineViews Stores analytics events that were not sent Permanent HTML Local Storage
youbora.session Stores a unique identifier for the current session Permanent HTML Local Storage
youbora.sessionExpire Expiration timestamp of the youbora.session cookie Permanent HTML Local Storage
youbora.youboraDeviceUUID Stores a unique device ID, generated randomly Permanent HTML Local Storage