Everything you need to run Loupe.

Loupe is a skin for a Video.js v10 player in React. Alongside the usual controls (play, seek, volume, speed, captions, fullscreen) it adds a contact sheet: all sampled thumbnails supplied by the storyboard, as a filmstrip under the video and as a full sheet you can open beneath it. Click or tap a frame to jump there, drag across frames with a mouse to scrub, move through them with the keyboard, and save the sheet as a one page PDF with timestamp links configured for the destination page. Frame jumps use an exact seek just inside the selected tile.

Save picks exports only the frames you mark. Use the tile checkbox, X on the focused frame, or SELECT on touch screens. Marks remain when you close the sheet. SAVE PICKS creates a linked PDF in time order: landscape uses one per row for 1–2 picks, two for 3–8, and three for 9 or more. Vertical uses up to three per row for 1–3 picks, four for 4–8, and five for more than eight. Images fit the printable area, with extra pages only when needed. With nothing marked, SAVE SHEET still saves every frame on one page.

Click any frame in the saved PDF and the video opens at that moment. The link is the page address with a t value in seconds, and the page passes it to the player as startTime.

The contact sheet shows three complete rows at rest. Mouse wheels and trackpads move in whole rows and pass scrolling to the page at the first or last row. On touch screens, a vertical swipe scrolls the sheet, settles on a whole row and passes scrolling to the page at either end; horizontal sheet paging is not used. A tap jumps to its frame, or marks it with SELECT on; dragging across frames scrubs only with a mouse. Touch scrubbing remains on the seek bar and filmstrip, not sheet tiles. It follows the playing frame; manual scrolling pauses following for five seconds. Frame number and time overlay the playing frame, the hovered frame and the focused frame while focus is in the sheet, not every tile. On touch, the current and focused frames show their number and time.

Loupe does not extract frames itself. It builds the sheet from the storyboard the video host already makes: one sprite image of evenly spaced frames, plus a JSON file saying where each frame sits.

The storyboard URL is fixed to Mux: https://image.mux.com/<playbackId>/storyboard.json. Playback goes through Mux's player element. An MP4 URL on its own carries no tile data, so there is no sheet. Using another host means changing four things: the source configuration, the poster URL, the storyboard fetch and normalisation, and the caption setup. The sprite must allow cross-origin canvas readback, or the PDF export cannot draw it.

This page's own storyboard, for reference: https://image.mux.com/gBOjab6Gxtqhq5m1OwwgpXBiY2HHp8JcgiogD7I01FEA/storyboard.json

If the storyboard fails to load, the video still plays with ordinary controls, but no filmstrip or sheet appears. The skin expects this shape:

{
  "url": "https://image.mux.com/<playbackId>/storyboard.jpg",
  "tile_width": 284,
  "tile_height": 160,
  "duration": 74.933,
  "tiles": [
    { "start": 0,     "x": 0,   "y": 0 },
    { "start": 1.529, "x": 284, "y": 0 }
  ]
}

This sample is trimmed: real responses contain one entry per tile, 50 for this video.

The skin reads url, tile_width, tile_height, duration and each tile's start (seconds), x and y (pixel offsets into the sprite).

Loupe is not a published package. There is nothing to npm install by name; it is source you copy into a React project that uses the @/ import alias for src/. The files it needs:

Then add its dependencies:

npm install @videojs/react@10.3.0 @videojs/mux-video@10.3.0 @radix-ui/react-dialog@^1.1.15 @radix-ui/react-slot@^1.2.4 class-variance-authority@^0.7.1 clsx@^2.1.1 tailwind-merge@^3.5.0 jspdf@^4.2.1

bun add @videojs/react@10.3.0 @videojs/mux-video@10.3.0 @radix-ui/react-dialog@^1.1.15 @radix-ui/react-slot@^1.2.4 class-variance-authority@^0.7.1 clsx@^2.1.1 tailwind-merge@^3.5.0 jspdf@^4.2.1

pnpm add @videojs/react@10.3.0 @videojs/mux-video@10.3.0 @radix-ui/react-dialog@^1.1.15 @radix-ui/react-slot@^1.2.4 class-variance-authority@^0.7.1 clsx@^2.1.1 tailwind-merge@^3.5.0 jspdf@^4.2.1

The demo's playback IDs live in src/lib/demo-sources.ts. ProofSheetPlayer has no fallback video: pass your own playbackId.

React, React DOM, TypeScript and Tailwind v4 must already be configured. Include every copied TSX file in Tailwind scanning. Copy all player, glass, interaction, reduced-motion and forced-colors rules in order, including inherited tokens. Controls retain state-aware accessible names for screen readers. Player text uses one monospace face through --font-mono (JetBrains Mono in the demo). The PDF renderer also uses JetBrains Mono; load that face before exporting. Copy the SVG filters once per page and their two displacement maps.

Configure DEMO_BASE_URL and export destination paths for your deployment. Frame links append t=<seconds>; the destination must select the exported video and parse t into startTime. Preserve video identity in the URL if one path can show different sources. The demo parser accepts only finite nonnegative t values.

ProofSheetPlayer is the default export. This minimal TanStack example uses the same browser-only boundary as the demo; The playback ID below is the same Europa Clipper source used by the Home hero.

import { lazy, Suspense } from "react";
import { ClientOnly } from "@tanstack/react-router";
import { GlassRefraction } from "@/components/GlassRefraction";

// SSR: lazy loading alone does not disable server rendering.
const ProofSheetPlayer = lazy(() => import("@/components/ProofSheetPlayer"));

function Demo() {
  return (
    <>
      <GlassRefraction /> {/* once per page */}
      <ClientOnly fallback={null}>
      <Suspense fallback={null}>
        <ProofSheetPlayer
          playbackId="gBOjab6Gxtqhq5m1OwwgpXBiY2HHp8JcgiogD7I01FEA"
          title="Europa Clipper: NASA's Mission to Jupiter's Ocean Moon"
          aspectRatio={16 / 9}
          muted
        />
      </Suspense>
      </ClientOnly>
    </>
  );
}

The demo also wraps it in an error boundary that offers a page reload if the player's code fails to download (PlayerLoadBoundary.tsx). That is optional.

ClientOnly is the TanStack Router boundary used in this project. In another SSR framework, use its browser-only equivalent. In a client-rendered React application the boundary is unnecessary. GlassRefraction mounts once per page; the demo mounts it in the root. Demo players start muted, without autoplay or looping, while portable defaults are all false.

Thirteen props, all optional in the TypeScript signature. A nonempty playbackId is needed to render a player.

Light or dark chosen from the parent background. Every colour is a variable you can override. Pass theme to choose one explicitly. Otherwise, after mounting, the skin walks up from the player to the nearest ancestor with a fully opaque background colour, and picks light when that colour's relative luminance is above 0.5, dark otherwise. If no opaque background is found it uses dark. Each player decides for itself, so two players on one page can differ.

The variables are declared on .ps-player and .ps-player[data-theme="light"], so setting them on a parent element has no effect. To change them, edit those rules or override them with a selector that targets .ps-player.

The glass frame around the player has its own --glass-* variables on .ps-glass-frame, with light overrides on .ps-glass-frame[data-theme="light"].

Framed and frameless players share two black lift shadows: 28px down with 60px blur, and 6px down with 12px blur. Dark/photo use 60% and 40% opacity; light uses 18% and 12%. The inset top edge is white at 28%, fading at the ends, with other dark edges at 8%; light edges are black at 10%. These do not change player size or position, and disappear in forced colors.

Automatic background detection runs after mount and when theme changes, not continuously when ancestor classes/backgrounds change. Pass an explicit reactive theme when the host switches themes.

These groups share their shortcut data with the player's KEYS panel and the home page. Shortcuts work while focus is inside the player.

Click a frame or press S to move into the contact sheet. Esc, or a click on the video, moves back out.

Additional supported shortcuts: K play/pause; J/L seek -10/+10 seconds; 0–9 seek 0–90%; Home/End start/end; ? toggle keyboard help. S toggles the sheet. X marks the focused frame. Esc closes the active help panel, menu or sheet. Editable fields and surfaces with their own keyboard handling exclude normal player shortcuts; Alt/Ctrl/Meta combinations are ignored. Space on a button activates that button.

The KEYS button is hidden only on touch-primary devices matching hover: none and pointer: coarse, not by player width. The ? shortcut remains available with a keyboard.

Apache License 2.0. Copyright 2026 Milena Webb. Full text: apache.org/licenses/LICENSE-2.0.txt, also in the LICENSE file in the source.