Use Bunny Player with Svelte and SvelteKit

The Bunny Player is an iframe, and player.js gives you a Player object for talking to it over postMessage. This guide builds a BunnyPlayer component with Svelte 5 runes that renders the iframe, forwards its events as callback props, and hands you that object. The component also works under SvelteKit server rendering. player.js is imported in onMount, because it reads window when imported, and the iframe renders only after the library is available, because player.js has to be loaded before the iframe finishes loading.

SvelteKit example on GitHub

A SvelteKit 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 component

src/lib/components/BunnyPlayer.svelte

<script lang="ts">
  import { onMount } from "svelte";
  import type { Player, TimeUpdate } from "player.js";

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

  type Props = {
    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;
  };

  let {
    libraryId,
    videoId,
    params = {},
    title = "Video player",
    onready,
    onplay,
    onpause,
    onended,
    ontimeupdate,
  }: Props = $props();

  let playerjs: PlayerJs | null = $state.raw(null);
  let iframe: HTMLIFrameElement | undefined = $state();

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

  onMount(async () => {
    // player.js reads window when imported, so load it in the browser only.
    playerjs = (await import("player.js")).default;
  });

  // Runs for every new iframe element, right after it is inserted
  // and before it has finished loading.
  $effect(() => {
    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 && onready?.(player));
    player.on("play", () => active && onplay?.());
    player.on("pause", () => active && onpause?.());
    player.on("ended", () => active && onended?.());
    player.on("timeupdate", (time) => active && ontimeupdate?.(time));

    return () => {
      active = false;
    };
  });
</script>

{#if playerjs}
  {#key src}
    <iframe
      bind:this={iframe}
      {src}
      {title}
      class="bunny-player"
      allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
      allowfullscreen
    ></iframe>
  {/key}
{:else}
  <!-- Hold the space until player.js is loaded so the iframe cannot
       finish loading before the Player exists. -->
  <div class="bunny-player" aria-hidden="true"></div>
{/if}

<style>
  .bunny-player {
    display: block;
    width: 100%;
    height: auto;
    aspect-ratio: 16 / 9;
    border: 0;
    background: #000;
  }
</style>

{#key src} replaces the iframe when the video changes, so the effect runs again with a fresh Player. The callback props are read inside the event handlers, so passing a new inline function doesn’t re-create the player.

Render a video

Load the video ID in +page.server.ts and pass it through data:

src/routes/lessons/[id]/+page.svelte

<script lang="ts">
  import BunnyPlayer from "$lib/components/BunnyPlayer.svelte";
  import { PUBLIC_BUNNY_LIBRARY_ID } from "$env/static/public";

  let { data } = $props();
</script>

<h1>{data.lesson.title}</h1>

<BunnyPlayer
  libraryId={PUBLIC_BUNNY_LIBRARY_ID}
  videoId={data.lesson.videoId}
  params={{ autoplay: false, preload: true }}
  onended={() => console.log("Video finished")}
/>

The library ID already appears in every embed URL, so a PUBLIC_ variable is fine. params accepts any player parameter, such as captions, t, or muted.

Control playback

onready hands you the Player. Keep it in state and call its methods from your own controls:

<script lang="ts">
  import type { Player } from "player.js";
  import BunnyPlayer from "$lib/components/BunnyPlayer.svelte";

  let player: Player | null = $state.raw(null);
  let playing = $state(false);
</script>

<BunnyPlayer
  libraryId="12345"
  videoId="your-video-guid"
  onready={(instance) => (player = instance)}
  onplay={() => (playing = true)}
  onpause={() => (playing = false)}
/>

<button onclick={() => (playing ? player?.pause() : player?.play())}>
  {playing ? "Pause" : "Play"}
</button>
<button onclick={() => player?.setCurrentTime(0)}>Restart</button>
<button onclick={() => player?.mute()}>Mute</button>

Getters take a callback, because the answer comes back from the iframe:

player?.getCurrentTime((seconds) => console.log(seconds));
player?.getDuration((seconds) => console.log(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 });

Browsers block unmuted play() until the viewer has interacted with the page, so call mute() first if playback has to start without a click. Playback control API lists every method and event.

Track progress

timeupdate fires several times a second with { seconds, duration }. Throttle it before writing to your backend, for example through an API route:

<script lang="ts">
  import BunnyPlayer from "$lib/components/BunnyPlayer.svelte";

  let { videoId, resumeAt }: { videoId: string; resumeAt?: number } = $props();
  let lastSaved = 0;

  async function save(seconds: number, duration: number) {
    await fetch(`/api/progress/${videoId}`, {
      method: "POST",
      body: JSON.stringify({ seconds, duration }),
    });
  }
</script>

<BunnyPlayer
  libraryId="12345"
  {videoId}
  params={resumeAt ? { t: resumeAt } : {}}
  ontimeupdate={({ seconds, duration }) => {
    if (seconds - lastSaved < 5) return;
    lastSaved = seconds;
    save(seconds, duration);
  }}
/>

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

Load player.js from the CDN instead

To skip the npm dependency, load the hosted build in src/app.html:

src/app.html

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

Replace the dynamic import in onMount with playerjs = window.playerjs and declare the global in src/app.d.ts:

src/app.d.ts

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

export {};

Troubleshooting

ReferenceError: window is not defined

player.js is being imported during server rendering. Keep import("player.js") inside onMount. A static import playerjs from "player.js" at the top of the script block runs on the server in SvelteKit.

onready never fires

The iframe finished loading before player.js was loaded. Render the iframe 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

Use Bunny Player with Svelte and SvelteKit

SvelteKit example on GitHub

Quickstart

Control playback

Track progress

Load player.js from the CDN instead

Troubleshooting

SvelteKit example on GitHub

​Quickstart

​Control playback

​Track progress

​Load player.js from the CDN instead

​Troubleshooting

Quickstart

Control playback

Track progress

Load player.js from the CDN instead

Troubleshooting