Use Bunny Player with JavaScript

With no framework, Bunny Player comes down to one function. It appends the iframe and returns a player.js Player for talking to it.

JavaScript example on GitHub

Vite and TypeScript, with custom controls and an event log. bun install && bun dev plays a demo video.

Quickstart

Install player.js

npm install player.js

pnpm add player.js

yarn add player.js

bun add player.js

player.js ships without types. Add a declaration file anywhere your tsconfig.json includes, for example player.js.d.ts. It covers the methods and events the Bunny Player supports:

player.js.d.ts

declare module "player.js" {
  export type PlayerEvent =
    | "ready"
    | "play"
    | "pause"
    | "ended"
    | "timeupdate"
    | "progress"
    | "seeked"
    | "error"
    | "playbackratechange";

  export type TimeUpdate = { seconds: number; duration: number };
  export type Progress = { percent: number; seconds: number; duration: number };
  /** Present when a command fails. Empty when the media itself errors. */
  export type PlayerError = { code: number; msg: string };

  export class Player {
    constructor(iframe: HTMLIFrameElement | string);

    on(event: "ready", callback: () => void): void;
    on(event: "timeupdate", callback: (data: TimeUpdate) => void): void;
    on(event: "progress", callback: (data: Progress) => void): void;
    on(event: "playbackratechange", callback: (rate: number) => void): void;
    on(event: "error", callback: (error?: PlayerError) => void): void;
    on(event: PlayerEvent, callback: (data?: unknown) => void): void;
    off(event: PlayerEvent, callback?: (...args: unknown[]) => void): void;
    supports(kind: "method" | "event", name: string | string[]): boolean;
    /** Send a raw command, for methods player.js does not expose such as setPlaybackRate. */
    send(message: { method: string; value?: unknown }): void;

    play(): void;
    pause(): void;
    mute(): void;
    unmute(): void;
    setVolume(percent: number): void;
    setCurrentTime(seconds: number): void;
    setLoop(loop: boolean): void;

    getPaused(callback: (paused: boolean) => void): void;
    getMuted(callback: (muted: boolean) => void): void;
    getVolume(callback: (percent: number) => void): void;
    getDuration(callback: (seconds: number) => void): void;
    getCurrentTime(callback: (seconds: number) => void): void;
    getLoop(callback: (loop: boolean) => void): void;
  }

  const playerjs: { Player: typeof Player };
  export default playerjs;
}

Create the player function

The Player has to exist before the iframe finishes loading. Creating both in one function takes care of the order.

src/bunny-player.ts

import playerjs, { type Player } from "player.js";

export type BunnyPlayerOptions = {
  libraryId: string;
  videoId: string;
  /** Player parameters such as autoplay, muted, captions, or t. */
  params?: Record<string, string | number | boolean>;
  title?: string;
};

export function createBunnyPlayer(
  container: HTMLElement,
  { libraryId, videoId, params, title = "Video player" }: BunnyPlayerOptions,
): Player {
  const query = new URLSearchParams(
    Object.entries(params ?? {}).map(([key, value]) => [key, String(value)]),
  ).toString();

  const iframe = document.createElement("iframe");
  iframe.src = `https://player.mediadelivery.net/embed/${libraryId}/${videoId}${query ? `?${query}` : ""}`;
  iframe.title = title;
  iframe.loading = "lazy";
  iframe.allow = "autoplay; encrypted-media; picture-in-picture; fullscreen";
  iframe.allowFullscreen = true;
  iframe.style.cssText = "display: block; width: 100%; aspect-ratio: 16 / 9; border: 0; background: #000;";
  container.append(iframe);

  return new playerjs.Player(iframe);
}

Mount it

src/main.ts

import { createBunnyPlayer } from "./bunny-player";

const player = createBunnyPlayer(document.querySelector("#player")!, {
  libraryId: "12345",
  videoId: "your-video-guid",
  params: { preload: true },
});

player.on("ready", () => console.log("ready"));

params takes any player parameter.

Control playback

player.on("ready", () => {
  document.querySelector("#toggle")!.addEventListener("click", () => {
    // Ask the player, because viewers can also use its own controls.
    player.getPaused((paused) => (paused ? player.play() : player.pause()));
  });
  document.querySelector("#restart")!.addEventListener("click", () => player.setCurrentTime(0));
});

Getters answer through a callback, since the value comes back from the iframe. Playback speed is missing from the npm build (0.1.0), and send() covers the gap:

player.send({ method: "setPlaybackRate", value: 1.5 });

Browsers block unmuted play() before the viewer has clicked anything. Mute first if playback has to start on its own. The Playback control API lists every method and event.

Track progress

timeupdate fires several times a second. Throttle it before it reaches your backend.

let lastSaved = 0;

player.on("timeupdate", ({ seconds, duration }) => {
  if (seconds - lastSaved < 5) return;
  lastSaved = seconds;
  void saveProgress(seconds, duration);
});

Pass the saved position back as params: { t: savedSeconds } to resume.

Use it without a bundler

We host a build of player.js that adds setPlaybackRate() and the playbackratechange event (Methods). Classic scripts run as the browser parses them, which puts both scripts ahead of the iframe’s load.

<head>
  <script src="https://assets.mediadelivery.net/playerjs/playerjs-latest.min.js"></script>
</head>
<body>
  <iframe
    id="player"
    src="https://player.mediadelivery.net/embed/12345/your-video-guid"
    allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
    allowfullscreen
  ></iframe>
  <script>
    const player = new playerjs.Player(document.querySelector("#player"));
    player.on("ready", () => console.log("ready"));
  </script>
</body>

Troubleshooting

The ready event never fires

The iframe loaded before player.js was listening. Module and defer scripts run after parsing, by which time an iframe in the HTML may be done. Create the iframe from script, as createBunnyPlayer does.A hidden tab also holds ready back until the viewer switches to it.

Events fire twice after replacing the video

Each Player leaves a message listener on window for good. Guard its handlers with a flag and flip it when you remove the iframe.

The iframe shows a 403

The library’s allowed domains, direct access block, or token authentication is rejecting the embed. See Embedding restrictions.

Documentation

Features

Manage Videos

Playback

Reference

JavaScript example on GitHub

Quickstart

Control playback

Track progress

Use it without a bundler

Troubleshooting

JavaScript example on GitHub

​Quickstart

​Control playback

​Track progress

​Use it without a bundler

​Troubleshooting

Quickstart

Control playback

Track progress

Use it without a bundler

Troubleshooting