Video Players

ImpossibleFX renders personalized videos on demand and returns a standard video URL. You can use that URL as a source in any video player that accepts external media. See Rendering Videos for how to obtain render URLs and tokens.

This page covers the built-in ImpossibleFX Player and how to use render URLs with popular third-party players.

ImpossibleFX Player

The ImpossibleFX Player (FXPlayer) is a built-in HTML5 video player that handles rendering and playback in a single step. It streams via HLS using hls.js and includes custom controls, keyboard shortcuts, fullscreen support, and CTA overlays.

Authentication

There are two ways to use the player with ImpossibleFX rendering:

Token-based (recommended) — Your server makes the render request and obtains a token. The player then uses that token to stream the video. No API key is needed on the client — tokens do not require additional authentication. Pass the token as src and the player auto-detects it:

const player = new FXPlayer("player", {
  src: "v2:eu-west-1:abc123-def456-789",
  controls: true,
});

By default this streams via HLS. To play as MP4 instead, set format:

const player = new FXPlayer("player", {
  src: "v2:eu-west-1:abc123-def456-789",
  format: "mp4",
  controls: true,
});

Direct rendering — The player calls the render backend directly from the browser using the impossible config. This is simpler but means the projectId is exposed in client-side code. By default, projects allow unauthenticated rendering, so this works without an API key:

const player = new FXPlayer("player", {
  impossible: {
    projectId: "YOUR-PROJECT-ID",
    movie: "welcome-video",
    params: { name: "Alex" },
  },
});
player.play();

If your project is configured to require authentication, you must also provide an apiKey:

const player = new FXPlayer("player", {
  impossible: {
    projectId: "YOUR-PROJECT-ID",
    movie: "welcome-video",
    apiKey: "YOUR-API-KEY",
    params: { name: "Alex" },
  },
});

Quick setup

Include the player CSS and script, then create a player with your project details:

<link rel="stylesheet" href="https://cdn.impossible.io/fxplayer/v3/fxplayer.css" />
<script src="https://cdn.impossible.io/fxplayer/v3/fxplayer.js"></script>

<div id="player" style="width: 640px; height: 360px;"></div>

<script>
  const player = new fxplayer.FXPlayer("player", {
    impossible: {
      projectId: "YOUR-PROJECT-ID",
      movie: "welcome-video",
      params: {
        name: "Alex",
        company: "Acme Inc",
      },
    },
  });
  player.play();
</script>

The player makes the render request, streams the video via HLS, and starts playback automatically.

Installation

<link rel="stylesheet" href="https://cdn.impossible.io/fxplayer/v3/fxplayer.css" />
<script src="https://cdn.impossible.io/fxplayer/v3/fxplayer.js"></script>

npm install fxplayer

import { FXPlayer } from "fxplayer";
import "fxplayer/dist/fxplayer.css";

Creating a player

// Pass the ID of a container element
const player = new FXPlayer("player", options);

// Or pass the element directly
const el = document.getElementById("player");
const player = new FXPlayer(el, options);

The player creates a <video> element inside the container you provide.

Options

Impossible.io rendering options

Pass these inside the impossible object to configure server-side rendering:

Methods

Properties

Events

Listen to player events with on() and off():

player.on("ready", () => console.log("Video ready"));
player.on("timeupdate", ({ time, duration }) => {
  console.log(`${time}s / ${duration}s`);
});
player.on("error", ({ message }) => console.error(message));

Token-based playback

If you’ve already made a render request and have a token, pass it as src:

// HLS streaming (default)
const player = new FXPlayer("player", {
  src: "v2:eu-west-1:abc123-def456-789",
  controls: true,
});

// MP4 playback
const player = new FXPlayer("player", {
  src: "v2:eu-west-1:abc123-def456-789",
  format: "mp4",
  controls: true,
});

You can also set the token programmatically:

const player = new FXPlayer("player", { controls: true });
player.setToken("v2:eu-west-1:abc123-def456-789");
player.play();

Dynamic configuration

You can also configure the project and parameters after creating the player:

const player = new FXPlayer("player");
player.setMovie("YOUR-PROJECT-ID", "welcome-video");
player.setParams({ name: "Alex", company: "Acme Inc" });
player.play();

CTA overlays

The player supports Call-To-Action overlays that appear during or after playback. Use them for promotions, subscribe prompts, or end screens.

player.addCTA("promo", {
  content: '<div class="promo">50% off — use code SAVE50</div>',
  startTime: 5,
  endTime: 12,
  position: "center",
  dismissible: true,
});

CTA options

CTA methods

CTA events

CTA patterns

Timed promo — visible between 5s and 12s:

player.addCTA("promo", {
  content: '<div class="banner">Limited offer!</div>',
  startTime: 5,
  endTime: 12,
  position: "center",
});

Persistent pill — appears at 3s, stays until dismissed:

player.addCTA("subscribe", {
  content: '<div class="pill">Subscribe</div>',
  startTime: 3,
  position: "bottom",
  dismissible: true,
});

End screen — shown when the video finishes, pauses playback:

player.addCTA("end-screen", {
  content: '<div class="end">Thanks for watching! <button>Sign up</button></div>',
  position: "center",
  pauseOnShow: true,
  dismissible: false,
});

Subtitles

The player supports WebVTT subtitles with a built-in settings panel for font size, color, background, and position. Settings are persisted in localStorage.

Basic usage

const player = new FXPlayer("player", {
  src: "https://example.com/video.mp4",
  subtitles: {
    tracks: [
      { src: "english.vtt", srclang: "en", label: "English" },
      { src: "spanish.vtt", srclang: "es", label: "Español" },
    ],
  },
});

Subtitle options

Pass these inside the subtitles object:

SubtitleTrack

Each track object has:

Adding tracks dynamically

player.addSubtitleTrack({
  src: "https://example.com/french.vtt",
  srclang: "fr",
  label: "Français",
});

Settings panel

When subtitles are configured, the player shows a CC button and a settings (gear) button in the control bar. The settings panel lets viewers customize:

• Track — choose between available subtitle tracks or turn them off
• Font size — 50% to 200%
• Font color — White, Yellow, Cyan, Green
• Background — Black (75%, 50%, 25% opacity) or transparent
• Position — Bottom or Top

All settings are saved to localStorage and restored on next visit.

Impossible.io integration

When using the player with Impossible.io rendering, subtitle VTT files can be lazily loaded — the player fetches the VTT URL only when the viewer enables subtitles.

const player = new FXPlayer("player", {
  impossible: {
    projectId: "YOUR-PROJECT-ID",
    movie: "welcome-video",
    params: { name: "Alex" },
  },
  subtitles: {
    tracks: [
      { src: "auto", srclang: "en", label: "English" },
    ],
  },
});

Poster images

Set a custom poster image from any URL:

const player = new FXPlayer("player", {
  src: "https://example.com/video.mp4",
});

// Set poster from a URL
await player.setPosterUrl("https://example.com/poster.jpg");

This works alongside the static poster option — use poster for a known URL at construction time, and setPosterUrl() when the poster URL is determined later.

Examples

JW Player

JW Player is a widely-used commercial video player with HLS support, analytics, and ad integrations.

Using a token-based URL:

<div id="player"></div>

<script src="https://cdn.jwplayer.com/libraries/YOUR-PLAYER-KEY.js"></script>
<script>
  const token = "v2:eu-west-1:abc123-def456-789";

  jwplayer("player").setup({
    sources: [
      {
        file: `https://render.impossible.io/v2/render/${token}.m3u8`,
        type: "hls",
      },
    ],
    width: 640,
    height: 360,
  });
</script>

You can also use a direct URL instead of tokens — just pass the v1 render URL as the file source.

Video.js

Video.js is the most popular open-source HTML5 video player, with a large plugin ecosystem and full HLS/DASH support.

Using a token-based URL:

<link href="https://vjs.zencdn.net/8.10.0/video-js.css" rel="stylesheet" />
<script src="https://vjs.zencdn.net/8.10.0/video.min.js"></script>

<video
  id="my-video"
  class="video-js"
  controls
  width="640"
  height="360"
>
</video>

<script>
  const token = "v2:eu-west-1:abc123-def456-789";

  const player = videojs("my-video", {
    sources: [
      {
        src: `https://render.impossible.io/v2/render/${token}.mp4`,
        type: "video/mp4",
      },
    ],
  });
</script>

You can also use a direct URL as the source — just pass the v1 render URL in the <source> tag.

HLS streaming with Video.js:

Video.js includes HLS support via its built-in VHS (Video.js HTTP Streaming) library:

const token = "v2:eu-west-1:abc123-def456-789";

const player = videojs("my-video", {
  sources: [
    {
      src: `https://render.impossible.io/v2/get/${token}.m3u8`,
      type: "application/x-mpegURL",
    },
  ],
});

Wistia

Wistia is a video platform focused on marketing and analytics. You can embed external video URLs using Wistia’s iframe embed or their Player API.

Using a token-based URL with an iframe:

<iframe
  src="https://fast.wistia.net/embed/iframe/WISTIA-VIDEO-ID"
  width="640"
  height="360"
  allowfullscreen
></iframe>

To use ImpossibleFX videos with Wistia, upload the rendered video via the Wistia Upload API:

# 1. Render the video
TOKEN=$(curl -s -X POST https://render.impossible.io/v2/render/YOUR-PROJECT-ID \
  -H "Content-Type: application/json" \
  -d '{"movie": "welcome-video", "params": {"name": "Alex"}}' \
  | jq -r '.token')

# 2. Upload the render URL to Wistia
curl -X POST "https://upload.wistia.com/api/v1/medias" \
  -H "Authorization: Bearer YOUR-WISTIA-API-TOKEN" \
  -d "url=https://render.impossible.io/v2/render/${TOKEN}.mp4"

Wistia will fetch the video from the render URL and host it on their platform, giving you access to their analytics, heatmaps, and embed tools. You can also pass a direct URL instead of the token-based URL.

Vimeo

Vimeo is a professional video hosting platform. Since Vimeo’s player only plays Vimeo-hosted content, the integration involves uploading your rendered video to Vimeo, then embedding it with their player.

Upload via the Vimeo API:

# 1. Render the video
TOKEN=$(curl -s -X POST https://render.impossible.io/v2/render/YOUR-PROJECT-ID \
  -H "Content-Type: application/json" \
  -d '{"movie": "welcome-video", "params": {"name": "Alex"}}' \
  | jq -r '.token')

# 2. Create a video on Vimeo with a pull URL
curl -X POST "https://api.vimeo.com/me/videos" \
  -H "Authorization: Bearer YOUR-VIMEO-ACCESS-TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"upload\": {
      \"approach\": \"pull\",
      \"link\": \"https://render.impossible.io/v2/render/${TOKEN}.mp4\"
    },
    \"name\": \"Personalized Video for Alex\"
  }"

Vimeo will pull the rendered video from the ImpossibleFX URL and host it. The response includes the Vimeo video URI which you can use to build an embed:

<iframe
  src="https://player.vimeo.com/video/VIMEO-VIDEO-ID"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
></iframe>

You can also pass a direct URL as the link value instead of the token-based URL.