Preload hosted player startup media

Author: richiemcilroy

apps/site/app/embed/[assetId]/page.tsx

@@ -14,6 +14,7 @@ import {
   instantPlaybackScript,
   playbackStateMessage,
   readyBootstrap,
+  startupPreloadHints,
   type PlaybackEngine,
   type StartupMode,
 } from "../../../lib/player-engine.ts";
@@ -136,6 +137,7 @@ export default async function EmbedPage({ params, searchParams }: EmbedPageProps
   const poster = ready?.poster_url;
   const message = playbackStateMessage(initialBootstrap, state);
   const edgeHint = playbackEdgeHint(initialBootstrap);
+  const preloadHints = startupPreloadHints(initialBootstrap, startupMode);
 
   const playerId = `rend-embed-${assetId}`;
   const sectionStyle = accent ? ({ "--rend-accent": accent } as CSSProperties) : undefined;
@@ -153,6 +155,17 @@ export default async function EmbedPage({ params, searchParams }: EmbedPageProps
           <link rel="preconnect" href={edgeHint.origin} crossOrigin="" />
         </>
       )}
+      {preloadHints.map((hint) => (
+        <link
+          key={`${hint.artifactPath}:${hint.url}`}
+          rel="preload"
+          as={hint.as}
+          href={hint.url}
+          type={hint.contentType}
+          crossOrigin="use-credentials"
+          data-rend-startup-preload={hint.artifactPath}
+        />
+      ))}
       <section
         id={playerId}
         className={sectionClassName}

apps/site/app/watch/[assetId]/page.tsx

@@ -7,6 +7,7 @@ import {
   safeWatchBootstrapMs,
   type WatchPlaybackBootstrapResponse,
 } from "../../../lib/watch-bootstrap.ts";
+import { startupPreloadHints } from "../../../lib/player-engine.ts";
 import { WatchInstantPlayer } from "./WatchInstantPlayer";
 
 type WatchPageProps = {
@@ -106,7 +107,9 @@ export default async function WatchPage({ params, searchParams }: WatchPageProps
   const [{ assetId }, query, headerStore] = await Promise.all([params, searchParams, headers()]);
   const initialBootstrap = decodeWatchBootstrapHeader(headerStore.get(WATCH_BOOTSTRAP_HEADER));
   const initialBootstrapMs = safeWatchBootstrapMs(headerStore.get(WATCH_BOOTSTRAP_MS_HEADER));
+  const startupMode = playerStartupMode(query.startupMode, query.startup);
   const edgeHint = playbackEdgeHint(initialBootstrap);
+  const preloadHints = startupPreloadHints(initialBootstrap, startupMode);
 
   return (
     <main className="rend-embed-page">
@@ -116,6 +119,17 @@ export default async function WatchPage({ params, searchParams }: WatchPageProps
           <link rel="preconnect" href={edgeHint.origin} crossOrigin="" />
         </>
       )}
+      {preloadHints.map((hint) => (
+        <link
+          key={`${hint.artifactPath}:${hint.url}`}
+          rel="preload"
+          as={hint.as}
+          href={hint.url}
+          type={hint.contentType}
+          crossOrigin="use-credentials"
+          data-rend-startup-preload={hint.artifactPath}
+        />
+      ))}
       <section className="rend-embed-shell" aria-label="Rend video player">
         <WatchInstantPlayer
           assetId={assetId}
@@ -124,7 +138,7 @@ export default async function WatchPage({ params, searchParams }: WatchPageProps
           initialBootstrap={initialBootstrap}
           initialBootstrapMs={initialBootstrapMs}
           playbackEngine={playerPlaybackEngine(query.playbackEngine, query.engine)}
-          startupMode={playerStartupMode(query.startupMode, query.startup)}
+          startupMode={startupMode}
           telemetryAppVersion={telemetryAppVersion()}
           telemetryEnabled={telemetryEnabled(query.telemetry)}
           telemetryOrganizationId={

apps/site/lib/player-engine.test.mts

@@ -1,6 +1,40 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { watchHeartbeatDelta } from "./player-engine.ts";
+import { startupPreloadHints, watchHeartbeatDelta } from "./player-engine.ts";
+
+const READY_BOOTSTRAP = {
+  status: "ready" as const,
+  asset_id: "00000000-0000-0000-0000-000000000001",
+  source_state: "uploaded",
+  playable_state: "hls_ready",
+  playback_url: "https://ash-1.play.rend.so/v/asset/hls/master.m3u8",
+  playback_content_type: "application/vnd.apple.mpegurl",
+  playback_token_expires_at: 1_800_000_000,
+  ttl_seconds: 900,
+  opener_url: "https://ash-1.play.rend.so/v/asset/opener.mp4",
+  opener_content_type: "video/mp4",
+  manifest_url: "https://ash-1.play.rend.so/v/asset/hls/master.m3u8",
+  manifest_content_type: "application/vnd.apple.mpegurl",
+  poster_url: "https://ash-1.play.rend.so/v/asset/thumbnail.jpg",
+  poster_content_type: "image/jpeg",
+  prefetch_hints: [
+    {
+      artifact_path: "hls/360p/index.m3u8",
+      url: "https://ash-1.play.rend.so/v/asset/hls/360p/index.m3u8",
+      content_type: "application/vnd.apple.mpegurl",
+    },
+    {
+      artifact_path: "hls/360p/init_360p.mp4",
+      url: "https://ash-1.play.rend.so/v/asset/hls/360p/init_360p.mp4",
+      content_type: "video/mp4",
+    },
+    {
+      artifact_path: "hls/master.m3u8",
+      url: "https://ash-1.play.rend.so/v/asset/hls/master.m3u8",
+      content_type: "application/vnd.apple.mpegurl",
+    },
+  ],
+};
 
 test("watch heartbeat waits for a real interval before emitting", () => {
   assert.deepEqual(watchHeartbeatDelta(null, 0), {
@@ -38,3 +72,36 @@ test("watch heartbeat clamps large deltas and reseeds after seeks", () => {
     deltaMs: null,
   });
 });
+
+test("startup preload hints prioritize manifest and startup media", () => {
+  assert.deepEqual(
+    startupPreloadHints(READY_BOOTSTRAP, "hls").map((hint) => [
+      hint.artifactPath,
+      hint.as,
+      hint.url,
+    ]),
+    [
+      [
+        "hls/master.m3u8",
+        "fetch",
+        "https://ash-1.play.rend.so/v/asset/hls/master.m3u8",
+      ],
+      [
+        "hls/360p/index.m3u8",
+        "fetch",
+        "https://ash-1.play.rend.so/v/asset/hls/360p/index.m3u8",
+      ],
+      [
+        "hls/360p/init_360p.mp4",
+        "fetch",
+        "https://ash-1.play.rend.so/v/asset/hls/360p/init_360p.mp4",
+      ],
+      ["thumbnail.jpg", "image", "https://ash-1.play.rend.so/v/asset/thumbnail.jpg"],
+    ]
+  );
+});
+
+test("startup preload hints include opener first only when requested", () => {
+  assert.equal(startupPreloadHints(READY_BOOTSTRAP, "hls")[0]?.artifactPath, "hls/master.m3u8");
+  assert.equal(startupPreloadHints(READY_BOOTSTRAP, "opener")[0]?.artifactPath, "opener.mp4");
+});

apps/site/lib/player-engine.ts

@@ -13,6 +13,13 @@ export type SourceSelection = {
   url: string;
 };
 
+export type StartupPreloadHint = {
+  artifactPath: string;
+  as: "fetch" | "image" | "video";
+  contentType?: string;
+  url: string;
+};
+
 export type AttachPlaybackOptions = {
   assetId: string;
   autoPlay: boolean;
@@ -78,6 +85,7 @@ const HLS_STARTUP_CONFIG = {
 const WATCH_HEARTBEAT_INTERVAL_MS = 10_000;
 const WATCH_HEARTBEAT_MAX_DELTA_MS = 30_000;
 const WATCH_HEARTBEAT_MIN_FORCED_DELTA_MS = 1_000;
+const MAX_STARTUP_PRELOAD_HINTS = 10;
 
 export function watchHeartbeatDelta(
   previousPositionMs: number | null,
@@ -170,6 +178,60 @@ export function playbackStateMessage(data: WatchPlaybackBootstrapResponse | null
   }
 }
 
+export function startupPreloadHints(
+  data: WatchPlaybackBootstrapResponse | null,
+  startupMode: StartupMode
+): StartupPreloadHint[] {
+  const ready = readyBootstrap(data);
+  if (!ready) return [];
+
+  const seen = new Set<string>();
+  const hints: StartupPreloadHint[] = [];
+  const push = (hint: StartupPreloadHint) => {
+    if (!hint.url || seen.has(hint.url) || hints.length >= MAX_STARTUP_PRELOAD_HINTS) return;
+    seen.add(hint.url);
+    hints.push(hint);
+  };
+
+  if (startupMode === "opener" && ready.opener_url) {
+    push({
+      artifactPath: "opener.mp4",
+      as: "video",
+      contentType: ready.opener_content_type ?? "video/mp4",
+      url: ready.opener_url,
+    });
+  }
+
+  if (ready.manifest_url) {
+    push({
+      artifactPath: "hls/master.m3u8",
+      as: "fetch",
+      contentType: ready.manifest_content_type ?? "application/vnd.apple.mpegurl",
+      url: ready.manifest_url,
+    });
+  }
+
+  for (const hint of ready.prefetch_hints) {
+    push({
+      artifactPath: hint.artifact_path,
+      as: "fetch",
+      contentType: hint.content_type,
+      url: hint.url,
+    });
+  }
+
+  if (ready.poster_url) {
+    push({
+      artifactPath: "thumbnail.jpg",
+      as: "image",
+      contentType: ready.poster_content_type,
+      url: ready.poster_url,
+    });
+  }
+
+  return hints;
+}
+
 function hlsSource(
   data: WatchPlaybackBootstrapReady,
   support: { nativeHls: boolean; hlsJs: boolean },