Use Bunny Player with Astro

Astro renders the Bunny Player iframe on the server and ships no JavaScript until you ask for some. This guide asks for very little: a <bunny-player> custom element that attaches player.js and turns the player’s events into DOM events.

Astro example on GitHub

Custom controls and an event log around this component. 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 component

The embed URL waits in data-src until the element has a Player listening. An iframe with src in the HTML can finish loading first, and then ready never arrives.

src/components/BunnyPlayer.astro

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

const { libraryId, videoId, params = {}, title = "Video player" } = Astro.props;

const query = new URLSearchParams(
  Object.entries(params).map(([key, value]) => [key, String(value)]),
).toString();
const src = `https://player.mediadelivery.net/embed/${libraryId}/${videoId}${query ? `?${query}` : ""}`;
---

<bunny-player>
  <iframe
    data-src={src}
    title={title}
    loading="lazy"
    allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
    allowfullscreen></iframe>
</bunny-player>

<script>
  // Astro runs this in the browser only, so player.js can read window on import.
  import playerjs, { type Player } from "player.js";

  class BunnyPlayerElement extends HTMLElement {
    player: Player | null = null;

    connectedCallback() {
      const iframe = this.querySelector("iframe");
      if (this.player || !iframe?.dataset.src) return;

      iframe.src = iframe.dataset.src;
      const player = new playerjs.Player(iframe);
      this.player = player;

      player.on("ready", () => this.emit("ready", player));
      player.on("play", () => this.emit("play"));
      player.on("pause", () => this.emit("pause"));
      player.on("ended", () => this.emit("ended"));
      player.on("timeupdate", (time) => this.emit("timeupdate", time));
    }

    private emit(type: string, detail?: unknown) {
      this.dispatchEvent(new CustomEvent(type, { detail }));
    }
  }

  customElements.define("bunny-player", BunnyPlayerElement);
</script>

<style>
  bunny-player {
    display: block;
  }

  iframe {
    display: block;
    width: 100%;
    aspect-ratio: 16 / 9;
    border: 0;
    background: #000;
  }
</style>

Add it to a page

src/pages/index.astro

---
import BunnyPlayer from "../components/BunnyPlayer.astro";
---

<BunnyPlayer
  libraryId={import.meta.env.PUBLIC_BUNNY_LIBRARY_ID}
  videoId={import.meta.env.PUBLIC_BUNNY_VIDEO_ID}
  params={{ preload: true }}
/>

params takes any player parameter.

Control playback

ready hands over the Player as event.detail.

<BunnyPlayer libraryId={libraryId} videoId={videoId} />
<button type="button" id="toggle">Play / pause</button>
<button type="button" id="restart">Restart</button>

<script>
  import type { Player } from "player.js";

  document.querySelector("bunny-player")!.addEventListener("ready", (event) => {
    const player = (event as CustomEvent<Player>).detail;

    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));
  });
</script>

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.

import type { TimeUpdate } from "player.js";

let lastSaved = 0;

document.querySelector("bunny-player")!.addEventListener("timeupdate", (event) => {
  const { seconds, duration } = (event as CustomEvent<TimeUpdate>).detail;
  if (seconds - lastSaved < 5) return;
  lastSaved = seconds;
  void saveProgress(seconds, duration);
});

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

Signed embed URLs

With embed view token authentication on, sign the URL in the page frontmatter and pass token and expires through params. Render that page on demand. A prerendered page hands every visitor the same token, and it expires. The signing code is in Sign embed URLs on the server.

Load player.js from the CDN instead

We host a build of player.js that adds setPlaybackRate() and the playbackratechange event (Methods). Load it in your layout’s <head> with is:inline, which keeps Astro from bundling it and runs it ahead of the component’s script.

<script is:inline src="https://assets.mediadelivery.net/playerjs/playerjs-latest.min.js"></script>

Swap the import for const playerjs = window.playerjs and declare the global.

declare global {
  interface Window {
    playerjs: (typeof import("player.js"))["default"];
  }
}

Troubleshooting

The ready event never fires

The iframe loaded before player.js was listening. Keep the URL in data-src and let the element set src.A hidden tab also holds ready back until the viewer switches to it.

Controls stop working after a view transition

<ClientRouter /> runs page scripts once, leaving your ready listener on the previous page’s element. Register it inside an astro:page-load listener.

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

Astro example on GitHub

Quickstart

Control playback

Track progress

Signed embed URLs

Load player.js from the CDN instead

Troubleshooting

Astro example on GitHub

​Quickstart

​Control playback

​Track progress

​Signed embed URLs

​Load player.js from the CDN instead

​Troubleshooting

Quickstart

Control playback

Track progress

Signed embed URLs

Load player.js from the CDN instead

Troubleshooting