Freecaster Player Documentation

Introduction

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.

Statistics

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:

JavaScript Embed (recommended)Iframe Embed

Reference the Freecaster player script in the page (only once, even if multiple players are embedded):
```
<script async src="https://player.freecaster.com/freecaster/stable/fcplayer.js"></script>
```
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.
Example:
```
<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: https://player.freecaster.com/embed/VIDEO_ID.html
Example:

<div style="height:0;padding-bottom:56.250%;position:relative;">
    <iframe src="https://player.freecaster.com/embed/VIDEO_ID.html?width=640&autoplay=true&muted=true&dnt=true&lang=fr-be" width="100%"
            height="100%" style="border:0;left:0;position:absolute;top:0;" frameborder="0" scrolling="no"
            allow="fullscreen">
    </iframe>
</div>

Acceptance environment

You must use player.freecaster-uat.com instead of player.freecaster.com 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.
`chapters.style`	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.
`trackers.ga.enabled`	boolean	false	Enable Google Analytics (GA4) support. By default, `window.dataLayer` will be used to push events toward GA4.
`trackers.ga.tag_ids`	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)

Stretching

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 ${payload.data.title}`))

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.

Example: https://player.freecaster.com/embed/VIDEO_ID.html?start_time=100&end_time=500_

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

Limitation

This feature only works with VOD

Tip

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:

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')
```

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 playerInstance.id.
    if (playerInstance.id === '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"
         data-video-id="VIDEO_ID"
         data-multiplay="true"
         data-preload="none"
         data-muted="true"
         data-autoplay="false">
</div>

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))
})

Tips

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()`

Note

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.

Note

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:

Add the Google Analytics tag snippet into the pages you want to track.
Enable the plugin using trackers.ga.enabled (note: dnt flag must be set to false).
(optional) You can also add one or more Google Analytics tags using trackers.ga.tag_ids.

   <div class="freecaster-player" data-trackers.ga.enabled="true" data-trackers.ga.tag_ids="GA-XXXXXX,GA-XXXXXX"></div>

Events

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
youbora.data	Stores API response with plugin settings	Permanent	HTML Local Storage
youbora.dataTime	Stores timestamp of data response	Permanent	HTML Local Storage
youbora.host	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