Skip to main content

Integrate the Flipbase player (v3)

v3 is a rewrite of the player in TypeScript. Nothing in the v2 embed API was removed — the same constructor, every v2 option, every v2 event name, including the misspelled scrubbTo that existing integrations listen for. v3 adds to that surface rather than replacing it, so moving a working v2 embed to v3 is a change of one URL. (One exception, if you pass theme as an object: see Migrating from v2.)

v3 is released, and nothing has been moved onto it

3.0.0 is a stable release. But /player/latest/ and /player/v2/ still serve v2 — the same bytes as each other, and the same bytes they served before v3 existed — and will until moving them is a deliberate decision. Nothing changes for an existing integration until you pin v3 yourself.

There is no /player/v3/ alias: that path returns 403. Pin an exact version instead, which is what you want anyway.

How to integrate the Player?​

Load from cdn.flipbase.com. A versioned path exists only there — app.flipbase.com does not serve one, so swapping the host turns a working embed into a 403. The old unversioned paths are the exception: they are served by both hosts, and an existing integration pointing at app keeps working exactly as it does today.

<head>
...
<!--
Load the JavaScript Player library in the HTML head section of your page
-->
<script src="https://cdn.flipbase.com/player/v3.0.0/player.min.js"></script>
</head>

<!--
Place the a video element(s) where you want to show the video player.
-->
<div id="video-player-element"></div>

<!-- Initialize the Player and provide your 'player_id' -->
<script>
const player = new FlipbasePlayer({
video_id: '5120293b-583b-4534-90dc-0f44cd51705e',
player_id: '95f4d94b-86c0-4e4a-b23d-484158efd1a4',
selector: 'video-player-element'
})

// Load the Flipbase player(s) manually
player.mount();

// Remove the Flipbase player(s) from the DOM
player.unmount();
</script>
new is optional

FlipbasePlayer is callable both ways, deliberately:

const a = new FlipbasePlayer({ selector, video_id, player_id }); // works
const b = FlipbasePlayer({ selector, video_id, player_id }); // also works

Both forms appear in the v2 documentation, so v3 declares both signatures and returns the same player object either way. Neither is deprecated; an integration written against one does not need changing.

On pinning a version

Pin the exact version, as above. From v3 onwards every version path is immutable — the bytes at /player/v3.0.0/ will never change — and each release publishes a manifest.json beside the bundle naming the commit it was built from and a SHA-384 integrity hash per file.

Because the bytes cannot change, you can hand the browser that hash and have it refuse anything else:

<script
src="https://cdn.flipbase.com/player/v3.0.0/player.min.js"
integrity="sha384-eBPjrM3yXYJtqW6tLbK4bK/Sha7yqVK2/fBgStXvM0fHGzrpXOq6TndocA3rTW6/"
crossorigin="anonymous"
></script>

The hash for any version is in its own manifest.json. Do not put an integrity attribute on /player/latest/ or /player/v2/: those paths move, and the browser would stop loading the player the moment they did.

That immutability was not true of v2: its exact-version paths predate the current release process and do not all contain the same build as /player/v2/.

What is new in v3​

The public API is the same, so this is mostly about what stopped being broken.

  • Seeking works. v2 threw ReferenceError on every scrub.
  • unmount() then mount() works. In v2 the second mount produced a player that looked right and did nothing.
  • Theming works. v2 validated the theme option and then ignored it, and built its stylesheet by string concatenation — two of its ten rule blocks were missing a brace and the browser discarded them silently.
  • Statistics can be turned off, with collectStatistics: false. There was no opt-out before, which matters where the embedding page has no consent basis for behavioural analytics on candidates.
  • 24 languages, selected with locale, with per-string overrides via labels.
  • Smaller: 66 kB minified, 24 kB gzipped, against v2's 144 kB — with every language included.

Two features were held back from 3.0.0 so that one build could be published everywhere, and they returned as their own minors. Both are now published: Overlays in 3.1.0, Subtitles in 3.2.0-alpha.0.

Overlays​

A logo and a presenter name, drawn over the video in any of four corners. Available from 3.1.0.

<script src="https://cdn.flipbase.com/player/v3.1.0/player.min.js"></script>
const player = new FlipbasePlayer({
video_id: '5120293b-583b-4534-90dc-0f44cd51705e',
player_id: '95f4d94b-86c0-4e4a-b23d-484158efd1a4',
selector: 'video-player-element',

logo: {
url: 'https://cdn.example.com/brand/logo.png',
position: 'top right', // or top left, bottom left, bottom right
size: 'medium', // small, medium, large
alt: '' // empty marks it decorative, which is usually right
},

presenter: {
name: 'Anna de Vries',
title: 'Recruiter · Flipbase',
position: 'bottom left',
size: 'medium'
}
});

Both are optional and take the same position and size. Only logo.url and presenter.name are needed to make each overlay appear; everything else falls back to a default. For the web component they flatten into attributes — logo-url, logo-position, presenter-name and the rest — so the common cases need no script.

Worth knowing:

  • Two overlays pinned to the same corner stack rather than overlapping.
  • A bottom overlay lifts clear of the control bar while it is on screen.
  • The layer is inert, so clicking a logo plays the video like clicking anywhere else on it.
  • logo.url must be an http(s) or data:image/* URL. Anything else is refused with a warning and the logo is dropped — the value usually comes from a configuration UI, and the player runs inside someone else's page.
  • A logo that fails to load leaves no trace rather than a broken-image icon.
  • position also accepts hyphenated and camelCase spellings (top-right, topRight). size shrinks automatically on a narrow player.
  • presenter.title defaults to Recruiter. Omitting it does not give you the name alone — pass title: '' for that.

3.1.0-alpha.0 is also still published and still immutable. It is the same feature, superseded; pin 3.1.0.

Subtitles​

Captions, supplied by you rather than by the API. Available from 3.2.0-alpha.0.

Still a prerelease

3.2.0-alpha.0 is published and immutable, and nothing is pinned to it. Use it to try subtitles; pin 3.1.0 or 3.0.0 for anything you are shipping.

<script src="https://cdn.flipbase.com/player/v3.2.0-alpha.0/player.min.js"></script>

The simplest form is a URL to a WebVTT file:

const player = new FlipbasePlayer({
video_id: '5120293b-583b-4534-90dc-0f44cd51705e',
player_id: '95f4d94b-86c0-4e4a-b23d-484158efd1a4',
selector: 'video-player-element',

subtitles: 'https://cdn.example.com/subs/en.vtt'
});

More usefully, hand it cues directly — which is the shape a transcription service already returns:

subtitles: [
{
language: 'en', // required, BCP-47
label: 'English', // default: the language's own name
kind: 'subtitles', // or 'captions'
default: true, // show this one from the start
cues: [
{ start: 0.4, end: 3.2, text: 'Hi, I am Bram.' },
{ start: 3.4, end: 6.8, text: 'We build video for recruitment.', speaker: 'Bram' }
]
},
{ language: 'nl', src: 'https://cdn.example.com/subs/nl.vtt' }
]

start and end are seconds, not timecode strings. A track takes either inline cues or a src, not both. A speaker becomes a WebVTT voice span, which is announced by screen readers and stylable through ::cue(v[voice='Bram']).

One track gets a toggle in the control bar; several get a menu with an Off entry. Nothing is shown unless a track is flagged default — turning subtitles on for every viewer is your decision, not the player's.

Worth knowing:

  • Cues are rendered by the browser, through a <track> element, not drawn by the player. That keeps the OS-level caption preferences a viewer has set — size, colour, background — and it is what keeps cues visible in fullscreen on iPhone, where the native player takes over.
  • Inline cues are served from a blob, so they are same-origin and need no CORS. Prefer them.
  • A cross-origin src is contagious. It forces crossorigin onto the <video> element, and the video then needs CORS headers of its own — which presigned URLs do not send. Either serve the .vtt from the embedding page's own origin, or pass cues instead.
  • Cues are lifted clear of the control bar on Chrome, Edge and Safari. Firefox keeps its own placement, because a browser only reserves room for its own native controls and ours are not native.
  • Unusable cues — no text, an end before its start, a non-finite time — are dropped with a warning. A broken subtitle never stops a video playing.
  • Cue text is escaped, so <, & and --> in a transcript are safe.

For the web component, subtitles-url (with optional subtitles-language and subtitles-label) covers the single-file case. A cue array cannot be an attribute, so inline cues go through the subtitles property:

document.querySelector('flipbase-player').subtitles = [{ language: 'en', cues }];

Options​

Everything below is in 3.0.0 unless the row says otherwise. The list is taken from the player's published type surface, so it is the whole of it — an option not named here is not an option.

OptionTypeDefaultWhat it does
selectorString—Id of the element to render into.
elementHTMLElement—The element itself, instead of selector.
video_idString—The video's UUID.
player_idString—The player configuration id.
signatureString—Playback signature, for secure mode.
themeString | ObjectplainA built-in theme name — plain, flipbase or ocean — or an object overriding individual colour tokens.
localeStringenLanguage of the control labels. 24 languages; regional tags resolve to their base language.
labelsObject—Per-string overrides. Takes precedence over locale.
collectStatisticsBooleantrueRegisters the view-statistics plugin. Set false where you have no consent basis for behavioural analytics.
pluginsArray—Extra plugins to register at construction.
apiBaseUrlStringhttps://app.flipbase.comOverride the API origin.
mutedBooleanfalseStart muted, for autoplay policies that require it.
logoObject—Logo overlay. 3.1.0 — see Overlays.
presenterObject—Presenter overlay. 3.1.0 — see Overlays.
subtitlesString | Object | Array—A .vtt URL, one track, or several. 3.2.0-alpha.0 — see Subtitles.

Theme tokens, for theme as an object: primaryColor, buttonColor, secondarySliderColor, playButtonBackground, playButtonHover, buttonHover, loadingBackground. Each also exists as a --flipbase-* custom property on the player root, so a host stylesheet can set it instead.

secondaryColor is accepted and published as --flipbase-secondary-color, but the default stylesheet never reads it — neither did v2's — so setting it changes nothing on its own.

Values that are not valid CSS colours are ignored with a warning rather than applied.

Events​

Subscribe with player.on(name, listener). on returns an unsubscribe function; player.off(name, listener) also works.

EventListener arguments
initialized—
play—
pause—
playing—
canplay—
waiting—
ended—
error(error)
timeupdate(currentTime, progress)
progress(progress)
loadedmetadata(duration)
fullscreenchange(isFullscreen)
volumechange(volume)
subtitlechange(trackId) — null when off. 3.2.0-alpha.0
scrubbTo(seconds)
scrubbingstarted(currentTime)
scrubbingended(currentTime, delta)
destroy—

scrubbTo, scrubbingstarted and scrubbingended keep v2's spelling on purpose. They are part of the public contract and will not be renamed in v3.

The error argument is an object with code, a message already translated into the viewer's locale, and status where there was an HTTP status. code is one of no-video-id, no-player-id, no-element, not-found, network, malformed-response, processing-timeout, playback.

Methods​

MethodWhat it does
mount()Render the player into its element.
unmount()Remove it from the DOM. mount() afterwards works.
destroy()Tear down for good; emits destroy.
play()Returns a promise.
pause()
togglePlay()
toggleVolume()Mute/unmute.
updateVolume(level)
enterFullscreen()
exitFullscreen()
toggleFullscreen()
selectSubtitle(trackId)Show a track by id, or null to turn subtitles off. 3.2.0-alpha.0
getState()A read-only snapshot of player state.
addPlugin(registration)
removePlugin(name)
on(event, listener)Returns an unsubscribe function.
off(event, listener)

There is also a read-only cid property, the player instance's own id.

Secure mode​

Unchanged from v2. Pass the signature property to the constructor; see the v2 page for how to build the signature string.

Testing against staging​

From 3.0.0 the player is built against an environment, so there are two copies of every release:

Loads fromTalks to
productioncdn.flipbase.comapp.flipbase.com
stagingcdn.stg.flipbase.comapp.stg.flipbase.com
<script src="https://cdn.stg.flipbase.com/player/v3.0.0/player.min.js"></script>

A video recorded through the staging recorder exists only in the staging database, so the staging player is the one that can play it. Before 3.0.0 the player had no notion of environment and always queried production.

Browser Support​

Chrome 87+, Firefox 78+, Safari 15+, Edge 88+, iOS Safari 15+. That is the browserslist the player is built and type-checked against, and the end-to-end suite runs on Chromium, Firefox, WebKit and an iPhone profile on every release — so it is the matrix that is actually tested, not an aspiration.

What the published bundle needs is a shorter list, and it is the more useful way to think about an unusual browser. v3.0.0 and v3.2.0-alpha.0 use:

  • Optional chaining (?.) — the newest syntax in either bundle. There are no class static blocks, logical assignment operators or Array.prototype.at.
  • fetch and AbortController, for the one API call the player makes.
  • ResizeObserver, to lay the control bar out against the player's own width rather than the viewport's.
  • async/await, globalThis, URL, Promise.

ResizeObserver and optional chaining are the two that bite, and both land around Safari 13.1 / Chrome 80 / Firefox 74. A browser between there and the supported floor will probably run the player; nothing tests it, so nothing promises it.

Internet Explorer 11 is not supported, and v2 genuinely was: it is transpiled to ES5, ships core-js polyfills and still sniffs the user agent for MSIE. If you need IE11, stay on v2.

Migrating from v2​

Change the script URL. That is the whole migration for most integrations:

- <script src="https://cdn.flipbase.com/player/v2/player.min.js"></script>
+ <script src="https://cdn.flipbase.com/player/v3.0.0/player.min.js"></script>

Every method, option, event name and flipbase-player-* CSS class is kept — all fourteen v2 methods and all thirteen v2 events, under their v2 names. The things to check are the ones that were broken rather than absent in v2: if you worked around the theming or the remount behaviour, those workarounds are now acting on a player that behaves correctly.

There is one shape change, and it is in theme:

A v2 theme object does not carry over whole

v2's theme object was nested — sliders, buttons and play_button each held their own colours. v3's tokens are flat. Passing a v2 theme object to v3 keeps primaryColor, buttonColor, secondaryColor and secondarySliderColor, and logs Unknown theme key "sliders" (and the same for the other two) while dropping those colours.

The flat equivalents are playButtonBackground, playButtonHover, buttonHover and loadingBackground — see Options. A theme passed as a name ('plain', 'flipbase') needs no change; 'ocean' is new in v3.