Use Bunny Player with Next.js

The Bunny Player is an iframe, and player.js gives you a Player object for talking to it over postMessage. Server rendering adds two constraints. player.js reads window the moment it’s imported, so it has to be imported in the browser. And it has to be loaded before the iframe finishes loading. player.js caches the iframe’s ready message when it’s imported, so a Player created afterwards still connects. If the iframe loads first, as server-rendered HTML can, the Player never becomes ready. The component below renders a placeholder on the server, loads player.js in an effect, then mounts the iframe and creates the Player in the same commit. It uses the App Router and works unchanged with the Pages Router. The React guide covers the client-only version.

Next.js example on GitHub

An App Router app built around this component, with custom controls and an event log. It plays a demo video after bun install and bun dev.

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 client component

components/bunny-player.tsx

"use client";

import { useEffect, useRef, useState, type CSSProperties } from "react";
import type { Player, TimeUpdate } from "player.js";

type PlayerJs = (typeof import("player.js"))["default"];

export type BunnyPlayerProps = {
  libraryId: string;
  videoId: string;
  /** Player parameters such as autoplay, muted, captions, or t. */
  params?: Record<string, string | number | boolean>;
  title?: string;
  onReady?: (player: Player) => void;
  onPlay?: () => void;
  onPause?: () => void;
  onEnded?: () => void;
  onTimeUpdate?: (time: TimeUpdate) => void;
};

const frameStyle: CSSProperties = {
  display: "block",
  width: "100%",
  height: "auto",
  aspectRatio: "16 / 9",
  border: 0,
  background: "#000",
};

export function BunnyPlayer({
  libraryId,
  videoId,
  params,
  title = "Video player",
  onReady,
  onPlay,
  onPause,
  onEnded,
  onTimeUpdate,
}: BunnyPlayerProps) {
  const iframeRef = useRef<HTMLIFrameElement>(null);
  const [playerjs, setPlayerjs] = useState<PlayerJs | null>(null);

  // Keep the latest callbacks without re-creating the player.
  const handlers = useRef({ onReady, onPlay, onPause, onEnded, onTimeUpdate });
  useEffect(() => {
    handlers.current = { onReady, onPlay, onPause, onEnded, onTimeUpdate };
  });

  // player.js reads window when imported, so load it in the browser only.
  useEffect(() => {
    let cancelled = false;
    import("player.js").then((mod) => {
      if (!cancelled) setPlayerjs(mod.default);
    });
    return () => {
      cancelled = true;
    };
  }, []);

  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}` : ""}`;

  useEffect(() => {
    const iframe = iframeRef.current;
    if (!playerjs || !iframe) return;

    // player.js has no teardown API. This flag stops stale listeners
    // from firing after the video changes or the component unmounts.
    let active = true;
    const player = new playerjs.Player(iframe);

    player.on("ready", () => active && handlers.current.onReady?.(player));
    player.on("play", () => active && handlers.current.onPlay?.());
    player.on("pause", () => active && handlers.current.onPause?.());
    player.on("ended", () => active && handlers.current.onEnded?.());
    player.on("timeupdate", (time) => active && handlers.current.onTimeUpdate?.(time));

    return () => {
      active = false;
    };
  }, [playerjs, src]);

  // Hold the space until player.js is loaded so the iframe cannot
  // finish loading before the Player exists.
  if (!playerjs) {
    return <div style={frameStyle} aria-hidden="true" />;
  }

  return (
    <iframe
      ref={iframeRef}
      src={src}
      title={title}
      style={frameStyle}
      allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
      allowFullScreen
    />
  );
}

The placeholder is a black box at the same aspect ratio. Swap in the video’s thumbnail if you want a poster while the script loads; Video storage structure has the URL.

Render it from a Server Component

The component is a Client Component, so a server-rendered page can pass it data fetched on the server:

app/lessons/[id]/page.tsx

import { BunnyPlayer } from "@/components/bunny-player";
import { getLesson } from "@/lib/lessons";

export default async function LessonPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const lesson = await getLesson(id);

  return (
    <main>
      <h1>{lesson.title}</h1>
      <BunnyPlayer
        libraryId={process.env.NEXT_PUBLIC_BUNNY_LIBRARY_ID!}
        videoId={lesson.videoId}
        params={{ autoplay: false, preload: true }}
      />
    </main>
  );
}

The library ID already appears in every embed URL, so a NEXT_PUBLIC_ variable is fine. params accepts any player parameter.

Control playback

Callback props are functions, so the component that passes them has to be a Client Component too. onReady hands you the Player:

components/lesson-player.tsx

"use client";

import { useState } from "react";
import type { Player } from "player.js";
import { BunnyPlayer } from "@/components/bunny-player";

export function LessonPlayer({ libraryId, videoId }: { libraryId: string; videoId: string }) {
  const [player, setPlayer] = useState<Player | null>(null);
  const [playing, setPlaying] = useState(false);

  return (
    <>
      <BunnyPlayer
        libraryId={libraryId}
        videoId={videoId}
        onReady={setPlayer}
        onPlay={() => setPlaying(true)}
        onPause={() => setPlaying(false)}
      />
      <button onClick={() => (playing ? player?.pause() : player?.play())}>
        {playing ? "Pause" : "Play"}
      </button>
      <button onClick={() => player?.setCurrentTime(0)}>Restart</button>
    </>
  );
}

Getters take a callback, because the answer comes back from the iframe: player.getCurrentTime((seconds) => ...). The player.js package on npm (0.1.0) has no playback speed method, so send the command directly. The build bunny.net hosts adds setPlaybackRate(), getPlaybackRate() and the playbackratechange event from version 0.1.2; see Methods.

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

Playback control API lists every method and event.

Save progress with a Server Action

timeupdate fires several times a second with { seconds, duration }. Throttle it before calling a Server Action:

app/actions.ts

"use server";

export async function saveProgress(videoId: string, seconds: number, duration: number) {
  // Persist to your database, keyed by the signed-in user.
}

components/lesson-player.tsx

"use client";

import { useRef } from "react";
import { saveProgress } from "@/app/actions";
import { BunnyPlayer } from "@/components/bunny-player";

export function LessonPlayer({ libraryId, videoId, resumeAt }: { libraryId: string; videoId: string; resumeAt?: number }) {
  const lastSaved = useRef(0);

  return (
    <BunnyPlayer
      libraryId={libraryId}
      videoId={videoId}
      params={resumeAt ? { t: resumeAt } : undefined}
      onTimeUpdate={({ seconds, duration }) => {
        if (seconds - lastSaved.current < 5) return;
        lastSaved.current = seconds;
        void saveProgress(videoId, seconds, duration);
      }}
    />
  );
}

Pass the saved position back as the t parameter to resume from there.

Sign embed URLs on the server

If the library uses embed view token authentication, the iframe URL needs a token and expires pair. Compute them in the Server Component, where the library’s security key stays, and pass them through params:

<BunnyPlayer
  libraryId={libraryId}
  videoId={lesson.videoId}
  params={{ token, expires }}
/>

Load player.js from the CDN instead

To skip the npm dependency, load the hosted build in the root layout with beforeInteractive, so window.playerjs exists before anything hydrates:

app/layout.tsx

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://assets.mediadelivery.net/playerjs/playerjs-latest.min.js"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  );
}

Replace the dynamic import with setPlayerjs(window.playerjs) and declare the global:

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

Keep the placeholder. beforeInteractive does not guarantee the script has run before a server-rendered iframe finishes loading, so the gate is still needed with the hosted build.

Troubleshooting

ReferenceError: window is not defined

player.js is being imported on the server. Keep import("player.js") inside useEffect. A static import playerjs from "player.js" at the top of a Client Component still runs during server rendering.

onReady never fires

The iframe finished loading before player.js was loaded, which happens when the iframe is part of the server-rendered HTML. Render it only after player.js has loaded, as the component above does. A Player created after that still connects, because player.js caches the iframe’s ready message.ready is also delayed while the tab is hidden, and fires once it becomes visible.

Events fire twice after changing the video

Every Player adds a message listener to window that is never removed. The active flag in the effect cleanup keeps stale instances quiet, so check that yours flips it.

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

Next.js example on GitHub

Quickstart

Control playback

Save progress with a Server Action

Sign embed URLs on the server

Load player.js from the CDN instead

Troubleshooting

Next.js example on GitHub

​Quickstart

​Control playback

​Save progress with a Server Action

​Sign embed URLs on the server

​Load player.js from the CDN instead

​Troubleshooting

Quickstart

Control playback

Save progress with a Server Action

Sign embed URLs on the server

Load player.js from the CDN instead

Troubleshooting