@hyperframes/studio 0.8.206 → 0.8.207

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/dist/assets/hyperframes-player-Cm5aBiKq.js +478 -0
  2. package/dist/assets/{index-CwreIGoq.js → index-BF9YeBnC.js} +131 -131
  3. package/dist/assets/{index-BNuxGFZK.js → index-BrqAmMRt.js} +1 -1
  4. package/dist/{chunk-DAZTBGYM.js → chunk-HPIJDMWG.js} +4 -4
  5. package/dist/index.d.ts +1 -0
  6. package/dist/index.html +1 -1
  7. package/dist/index.js +144 -51
  8. package/dist/player.js +1 -1
  9. package/package.json +8 -8
  10. package/src/hooks/timelineEditingHelpers.test.ts +59 -0
  11. package/src/hooks/timelineEditingHelpers.ts +4 -5
  12. package/src/hooks/useGestureRecording.ts +5 -3
  13. package/src/player/components/PlayerControls.tsx +5 -2
  14. package/src/player/components/ShortcutsPanel.tsx +4 -2
  15. package/src/player/components/Timeline.test.ts +12 -0
  16. package/src/player/components/TimelineProvider.tsx +1 -0
  17. package/src/player/components/TimelineRuler.tsx +4 -7
  18. package/src/player/components/TimelineRulerPart.tsx +1 -0
  19. package/src/player/components/timelineClipDragPreview.test.ts +10 -0
  20. package/src/player/components/timelineClipDragPreview.ts +4 -5
  21. package/src/player/components/timelineRulerGeometry.ts +14 -3
  22. package/src/player/components/useTimelineClipDrag.ts +5 -2
  23. package/src/player/components/useTimelineProviderState.tsx +2 -1
  24. package/src/player/components/useTimelineTicks.ts +4 -1
  25. package/src/player/hooks/usePlaybackKeyboard.test.ts +19 -0
  26. package/src/player/hooks/usePlaybackKeyboard.ts +5 -2
  27. package/src/player/hooks/useShadowPreviewReload.ts +4 -1
  28. package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +21 -0
  29. package/src/player/lib/mediaFetch.test.ts +163 -0
  30. package/src/player/lib/mediaFetch.ts +98 -0
  31. package/src/player/lib/mediaProbe.test.ts +21 -1
  32. package/src/player/lib/mediaProbe.ts +4 -2
  33. package/src/player/lib/thumbnailVideoDecoder.test.ts +24 -1
  34. package/src/player/lib/thumbnailVideoDecoder.ts +3 -1
  35. package/src/player/lib/time.test.ts +13 -13
  36. package/src/player/lib/time.ts +4 -4
  37. package/src/utils/linkedClipPreferences.ts +2 -0
  38. package/dist/assets/hyperframes-player-lCVwx9d3.js +0 -478
@@ -6,6 +6,7 @@ import { liveTime, usePlayerStore } from "../store/playerStore";
6
6
  import { trackStudioEvent } from "../../utils/studioTelemetry";
7
7
  import { Tooltip } from "../../components/ui";
8
8
  import { useMountEffect } from "../../hooks/useMountEffect";
9
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
9
10
  import { ShortcutsButton } from "./ShortcutsPanel";
10
11
  import type { ShortcutSection } from "./studioShortcuts";
11
12
  import { SpeedMenu } from "./SpeedMenu";
@@ -167,6 +168,8 @@ interface PlayerControlsProps {
167
168
  shortcutSections?: readonly ShortcutSection[];
168
169
  }
169
170
 
171
+ const compositionFps = () => useLinkedClipPreferences.getState().compositionFps;
172
+
170
173
  export const PlayerControls = memo(function PlayerControls({
171
174
  onTogglePlay,
172
175
  onSeek,
@@ -202,7 +205,7 @@ export const PlayerControls = memo(function PlayerControls({
202
205
  if (!timeDisplayRef.current) return;
203
206
  const t = currentTimeRef.current;
204
207
  timeDisplayRef.current.textContent =
205
- timeDisplayMode === "frame" ? formatFrameTime(t, duration) : formatTime(t);
208
+ timeDisplayMode === "frame" ? formatFrameTime(t, duration, compositionFps()) : formatTime(t);
206
209
  }, [duration, timeDisplayMode]);
207
210
 
208
211
  useMountEffect(() => {
@@ -212,7 +215,7 @@ export const PlayerControls = memo(function PlayerControls({
212
215
  const currentDuration = durationRef.current;
213
216
  const text =
214
217
  timeDisplayModeRef.current === "frame"
215
- ? formatFrameTime(time, currentDuration)
218
+ ? formatFrameTime(time, currentDuration, compositionFps())
216
219
  : formatTime(time);
217
220
  if (timeDisplayRef.current.textContent !== text) timeDisplayRef.current.textContent = text;
218
221
  };
@@ -3,6 +3,7 @@ import { formatTime, frameToSeconds } from "../lib/time";
3
3
  import { Popover, Tooltip } from "../../components/ui";
4
4
  import { flatActive, flatIdle } from "../../components/timelineToolbarStyles";
5
5
  import { usePlayerStore } from "../store/playerStore";
6
+ import { useCompositionFps } from "../../utils/linkedClipPreferences";
6
7
  import { DEFAULT_SHORTCUT_SECTIONS, type ShortcutSection } from "./studioShortcuts";
7
8
 
8
9
  interface ShortcutsPanelProps {
@@ -31,6 +32,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
31
32
  }: ShortcutsPanelProps) {
32
33
  const [showShortcuts, setShowShortcuts] = useState(false);
33
34
  const [jumpFrame, setJumpFrame] = useState("");
35
+ const compositionFps = useCompositionFps();
34
36
  // Focus lands on the scrolling body, not the frame input, so keyboard users can scroll and read it.
35
37
  const panelBodyRef = useRef<HTMLDivElement>(null);
36
38
 
@@ -38,8 +40,8 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
38
40
  if (disabled) return;
39
41
  const frame = Number.parseInt(jumpFrame, 10);
40
42
  if (!Number.isFinite(frame) || duration <= 0) return;
41
- onSeek(Math.min(duration, frameToSeconds(Math.max(0, frame))));
42
- }, [disabled, duration, jumpFrame, onSeek]);
43
+ onSeek(Math.min(duration, frameToSeconds(Math.max(0, frame), compositionFps)));
44
+ }, [compositionFps, disabled, duration, jumpFrame, onSeek]);
43
45
 
44
46
  const handleJumpSubmit = useCallback(
45
47
  (e: React.FormEvent) => {
@@ -4,6 +4,7 @@ import React, { act } from "react";
4
4
  import { createRoot } from "react-dom/client";
5
5
  import { afterEach } from "vitest";
6
6
  import { describe, it, expect, vi } from "vitest";
7
+ import { rulerTickText } from "./timelineRulerGeometry";
7
8
  import {
8
9
  Timeline,
9
10
  formatTimelineTickLabel,
@@ -1367,3 +1368,14 @@ describe("resolveTimelineAssetDrop", () => {
1367
1368
  ).toEqual({ start: 1.18, track: 8 });
1368
1369
  });
1369
1370
  });
1371
+
1372
+ describe("rulerTickText", () => {
1373
+ it("counts frames at the rate the ticks were laid out at", () => {
1374
+ expect(rulerTickText(2, 25, 10, 1)).toBe(50);
1375
+ expect(rulerTickText(2, 30_000 / 1_001, 10, 1)).toBe(60);
1376
+ });
1377
+
1378
+ it("shows time when the ruler is not counting frames", () => {
1379
+ expect(rulerTickText(2, undefined, 10, 1)).toBe("00:02");
1380
+ });
1381
+ });
@@ -48,6 +48,7 @@ export type TimelineCanvasState = Omit<
48
48
  totalH: number;
49
49
  effectiveDuration: number;
50
50
  majorTickInterval: number;
51
+ tickFrameRate: number | undefined;
51
52
  rangeSelection: TimelineRangeSelection | null;
52
53
  marqueeRect: Rect | null;
53
54
  resizingClip: ResizingClipState | null;
@@ -2,9 +2,7 @@ import { memo, type RefObject } from "react";
2
2
  import { useSettledScrollLeft } from "./useSettledScrollLeft";
3
3
  import type { TimelineTheme } from "./timelineTheme";
4
4
  import { RULER_H, getTimelineBeatEntries } from "./timelineLayout";
5
- import { formatTimelineTickLabel } from "./timelineRulerGeometry";
6
- import { usePlayerStore } from "../store/playerStore";
7
- import { secondsToFrame } from "../lib/time";
5
+ import { rulerTickText } from "./timelineRulerGeometry";
8
6
  import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
9
7
  import type { TimelineTimeRange } from "../lib/timelineClipIndex";
10
8
 
@@ -16,6 +14,7 @@ interface TimelineRulerProps {
16
14
  totalH: number;
17
15
  effectiveDuration: number;
18
16
  majorTickInterval: number;
17
+ tickFrameRate?: number;
19
18
  theme: TimelineTheme;
20
19
  beatAnalysis?: MusicBeatAnalysis | null;
21
20
  contentOrigin: number;
@@ -84,13 +83,13 @@ export const TimelineRuler = memo(function TimelineRuler({
84
83
  totalH,
85
84
  effectiveDuration,
86
85
  majorTickInterval,
86
+ tickFrameRate,
87
87
  theme,
88
88
  beatAnalysis,
89
89
  contentOrigin,
90
90
  renderTimeRange,
91
91
  scrollRef,
92
92
  }: TimelineRulerProps) {
93
- const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
94
93
  const beatTimes = beatAnalysis?.beatTimes ?? [];
95
94
  const beatStrengths = beatAnalysis?.beatStrengths ?? [];
96
95
  const beatEntries = getTimelineBeatEntries(beatTimes, beatStrengths, renderTimeRange);
@@ -194,9 +193,7 @@ export const TimelineRuler = memo(function TimelineRuler({
194
193
  fontSize: 10,
195
194
  }}
196
195
  >
197
- {timeDisplayMode === "frame"
198
- ? secondsToFrame(t)
199
- : formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
196
+ {rulerTickText(t, tickFrameRate, effectiveDuration, majorTickInterval)}
200
197
  </span>
201
198
  <div className="w-px" style={{ height: RULER_H, background: theme.tickMajor }} />
202
199
  </div>
@@ -13,6 +13,7 @@ export function TimelineRulerPart() {
13
13
  totalH={props.totalH}
14
14
  effectiveDuration={props.effectiveDuration}
15
15
  majorTickInterval={props.majorTickInterval}
16
+ tickFrameRate={props.tickFrameRate}
16
17
  theme={props.theme}
17
18
  beatAnalysis={props.beatAnalysis}
18
19
  contentOrigin={props.contentOrigin}
@@ -5,8 +5,10 @@ import {
5
5
  computeResizePreview,
6
6
  guideIfSaved,
7
7
  getTimelineDragOverlayPosition,
8
+ trimPreviewTime,
8
9
  type DragPreviewContext,
9
10
  } from "./timelineClipDragPreview";
11
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
10
12
  import type { DraggedClipState } from "./timelineClipDragTypes";
11
13
  import {
12
14
  commitDraggedClipMove,
@@ -937,3 +939,11 @@ describe("an audio clip stays inside its partner video", () => {
937
939
  expect(trim("end", 50, ["v"]).previewDuration).toBe(58);
938
940
  });
939
941
  });
942
+
943
+ describe("trimPreviewTime", () => {
944
+ it.each([25, 60])("shows the last frame of the clip at %s fps", (fps) => {
945
+ useLinkedClipPreferences.getState().setCompositionFps(fps);
946
+ expect(trimPreviewTime("end", 1, 2)).toBeCloseTo(3 - 1 / fps, 9);
947
+ useLinkedClipPreferences.getState().setCompositionFps(30);
948
+ });
949
+ });
@@ -27,7 +27,7 @@ import {
27
27
  } from "./timelineGroupEditing";
28
28
  import { groupMoveFloor, resolveGroupMovers } from "./timelineMultiDragPreview";
29
29
  import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
30
- import { STUDIO_PREVIEW_FPS } from "../lib/time";
30
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
31
31
  import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";
32
32
 
33
33
  /** Snap-target builder closure supplied by the hook (closes over refs + store). */
@@ -306,12 +306,11 @@ export function guideIfSaved(
306
306
  return off * pps < 1 ? target : null;
307
307
  }
308
308
 
309
- /** One frame: the last visible frame of a clip sits just before its end time. */
310
- const TRIM_END_FRAME_LEAD_S = 1 / STUDIO_PREVIEW_FPS;
311
-
312
309
  /** The composition time whose frame a trim shows: the edge being dragged. */
313
310
  export function trimPreviewTime(edge: "start" | "end", start: number, duration: number): number {
314
- return edge === "start" ? start : Math.max(start, start + duration - TRIM_END_FRAME_LEAD_S);
311
+ // One frame back: the last visible frame of a clip sits just before its end time.
312
+ const frame = 1 / useLinkedClipPreferences.getState().compositionFps;
313
+ return edge === "start" ? start : Math.max(start, start + duration - frame);
315
314
  }
316
315
 
317
316
  export interface ResizePreviewContext {
@@ -1,4 +1,4 @@
1
- import { formatTime, STUDIO_PREVIEW_FPS } from "../lib/time";
1
+ import { formatTime, secondsToFrame } from "../lib/time";
2
2
  import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
3
3
  import type { TimelineTimeRange } from "../lib/timelineClipIndex";
4
4
 
@@ -94,8 +94,8 @@ function tickSpacing(duration: number, pixelsPerSecond?: number, frameRate?: num
94
94
  return { majorInterval, subdivisions };
95
95
  }
96
96
 
97
- export function rulerFrameRate(mode: TimelineTimeDisplayMode): number | undefined {
98
- return mode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
97
+ export function rulerFrameRate(mode: TimelineTimeDisplayMode, fps: number): number | undefined {
98
+ return mode === "frame" ? fps : undefined;
99
99
  }
100
100
 
101
101
  /** Seconds between neighbouring ruler lines (minor ticks when drawn, else major): the snap grid. */
@@ -161,3 +161,14 @@ export function formatTimelineTickLabel(
161
161
  }
162
162
  return formatTime(safeTime);
163
163
  }
164
+
165
+ export function rulerTickText(
166
+ time: number,
167
+ frameRate: number | undefined,
168
+ duration: number,
169
+ majorInterval: number,
170
+ ): string | number {
171
+ return frameRate
172
+ ? secondsToFrame(time, frameRate)
173
+ : formatTimelineTickLabel(time, duration, majorInterval);
174
+ }
@@ -31,7 +31,7 @@ import type {
31
31
  } from "./timelineClipDragTypes";
32
32
  import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
33
33
  import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
34
- import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
34
+ import { isLinkedSelectionOn, useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
35
35
  import { useTimelineClipCapabilities } from "./timelineReadOnly";
36
36
  import { timelineClipFocusId } from "./timelineNavigationIdentity";
37
37
  import {
@@ -184,7 +184,10 @@ export function useTimelineClipDrag({
184
184
  // The ruler's line spacing at the current zoom; 0 with the magnet off, like the targets.
185
185
  const snapGridStep = useCallback(() => {
186
186
  if (!snapContextRef.current.enabled) return 0;
187
- const frameRate = rulerFrameRate(usePlayerStore.getState().timeDisplayMode);
187
+ const frameRate = rulerFrameRate(
188
+ usePlayerStore.getState().timeDisplayMode,
189
+ useLinkedClipPreferences.getState().compositionFps,
190
+ );
188
191
  return getTimelineGridStep(durationRef.current, ppsRef.current, frameRate);
189
192
  }, [durationRef, ppsRef]);
190
193
 
@@ -444,7 +444,7 @@ export function useTimelineProviderState({
444
444
  dragActive: draggedClip?.started === true || resizingClip != null,
445
445
  displayDuration,
446
446
  });
447
- const { major, minor, majorTickInterval } = useTimelineTicks(
447
+ const { major, minor, majorTickInterval, frameRate } = useTimelineTicks(
448
448
  displayDuration,
449
449
  pps,
450
450
  timeDisplayMode,
@@ -460,6 +460,7 @@ export function useTimelineProviderState({
460
460
  totalH: displayLayout.totalH,
461
461
  effectiveDuration,
462
462
  majorTickInterval,
463
+ tickFrameRate: frameRate,
463
464
  rangeSelection,
464
465
  marqueeRect,
465
466
  laneGapStrips,
@@ -1,5 +1,6 @@
1
1
  import { useMemo } from "react";
2
2
  import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
3
+ import { useCompositionFps } from "../../utils/linkedClipPreferences";
3
4
  import type { TimelineTimeRange } from "../lib/timelineClipIndex";
4
5
  import {
5
6
  generateTicks,
@@ -13,13 +14,15 @@ export function useTimelineTicks(
13
14
  timeDisplayMode: TimelineTimeDisplayMode,
14
15
  renderTimeRange?: TimelineTimeRange,
15
16
  ) {
16
- const frameRate = rulerFrameRate(timeDisplayMode);
17
+ const compositionFps = useCompositionFps();
18
+ const frameRate = rulerFrameRate(timeDisplayMode, compositionFps);
17
19
  const ticks = useMemo(
18
20
  () => generateTicks(duration, pixelsPerSecond, frameRate, renderTimeRange),
19
21
  [duration, frameRate, pixelsPerSecond, renderTimeRange],
20
22
  );
21
23
  return {
22
24
  ...ticks,
25
+ frameRate,
23
26
  majorTickInterval: getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate),
24
27
  };
25
28
  }
@@ -6,12 +6,14 @@ import { createRoot } from "react-dom/client";
6
6
  import { afterEach, describe, expect, it, vi } from "vitest";
7
7
  import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
8
8
  import { usePlayerStore } from "../store/playerStore";
9
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
9
10
 
10
11
  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
11
12
 
12
13
  afterEach(() => {
13
14
  document.body.innerHTML = "";
14
15
  usePlayerStore.getState().reset();
16
+ useLinkedClipPreferences.getState().setCompositionFps(30);
15
17
  });
16
18
 
17
19
  interface Spies {
@@ -304,3 +306,20 @@ describe("usePlaybackKeyboard — a focused native player owns its keys", () =>
304
306
  expect(event.defaultPrevented).toBe(true);
305
307
  });
306
308
  });
309
+
310
+ describe("usePlaybackKeyboard — frame step", () => {
311
+ it.each([
312
+ [25, 3],
313
+ [30_000 / 1_001, 3],
314
+ ])("ArrowRight at %s fps steps one frame of the composition", (fps, frame) => {
315
+ const { dispatch, spies } = setupHook();
316
+ useLinkedClipPreferences.getState().setCompositionFps(fps);
317
+ usePlayerStore.setState({ currentTime: frame / fps });
318
+
319
+ act(() => {
320
+ dispatch(keydown({ code: "ArrowRight", key: "ArrowRight" }));
321
+ });
322
+
323
+ expect(spies.seek).toHaveBeenCalledWith((frame + 1) / fps);
324
+ });
325
+ });
@@ -11,7 +11,8 @@ import { useCaptionStore } from "../../captions/store";
11
11
  import { shouldIgnorePlaybackShortcutEvent, SHUTTLE_SPEEDS } from "../lib/playbackShortcuts";
12
12
  import { canvasNudgeKeysClaimed } from "../../utils/canvasNudgeGate";
13
13
  import { usePlayerStore } from "../store/playerStore";
14
- import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
14
+ import { stepFrameTime } from "../lib/time";
15
+ import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
15
16
  import type { PlaybackAdapter } from "../lib/playbackTypes";
16
17
 
17
18
  interface UsePlaybackKeyboardParams {
@@ -53,7 +54,9 @@ export function usePlaybackKeyboard({
53
54
  (deltaFrames: number) => {
54
55
  const adapter = getAdapter();
55
56
  const currentTime = adapter?.getTime() ?? usePlayerStore.getState().currentTime;
56
- seek(stepFrameTime(currentTime, deltaFrames, STUDIO_PREVIEW_FPS));
57
+ seek(
58
+ stepFrameTime(currentTime, deltaFrames, useLinkedClipPreferences.getState().compositionFps),
59
+ );
57
60
  },
58
61
  [getAdapter, seek],
59
62
  );
@@ -8,6 +8,7 @@ import {
8
8
  isStudioManualEditGestureLiveIn,
9
9
  studioManualEditSavesIn,
10
10
  } from "../../components/editor/manualEditsDom";
11
+ import { refusedPreviewStatus } from "@hyperframes/core/studio-preview-mark";
11
12
  import { logReload } from "../../utils/reloadDebug";
12
13
  import {
13
14
  useTimelineSyncCallbacks,
@@ -131,7 +132,9 @@ export function useShadowPreviewReload({
131
132
  setPreviewReloading(false);
132
133
  const message = `The preview did not reload (${cause}). It was still waiting for ${waitingFor}. The previous preview is still showing.`;
133
134
  logReload("shadow-failed", { cause, waitingFor });
134
- console.error(`[studio] ${message}`);
135
+ const refused = refusedPreviewStatus(cause);
136
+ const pageMissingNow = refused !== null && refused < 500;
137
+ (pageMissingNow ? console.warn : console.error)(`[studio] ${message}`);
135
138
  onReloadFailedRef.current?.(message);
136
139
  },
137
140
  [stopPendingShadow, isRefreshingRef, pendingSeekRef],
@@ -5,6 +5,7 @@ import React, { act } from "react";
5
5
  import { createRoot } from "react-dom/client";
6
6
  import { afterEach, describe, expect, it, vi } from "vitest";
7
7
  import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
8
+ import { refusedPreviewMessage } from "@hyperframes/core/studio-preview-mark";
8
9
  import { usePlayerStore } from "../store/playerStore";
9
10
  import { isPreviewChanging } from "../previewReloading";
10
11
  import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
@@ -639,6 +640,26 @@ describe("shadow reload readiness and failure", () => {
639
640
  unmount(root);
640
641
  });
641
642
 
643
+ // An agent's edit moves the page away for a few saves: each reload is refused until it is back.
644
+ it.each([
645
+ [404, "warn"],
646
+ [500, "error"],
647
+ ] as const)("reports a reload the server refused with %i as a console %s", (status, level) => {
648
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
649
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
650
+ const onPreviewReloadFailed = vi.fn();
651
+ const { getApi, live, gen, root } = beginReload({ onPreviewReloadFailed });
652
+
653
+ act(() => getApi().onShadowError(gen, refusedPreviewMessage(status)));
654
+
655
+ expect(getApi().iframeRef.current).toBe(live);
656
+ expect(onPreviewReloadFailed).toHaveBeenCalledOnce();
657
+ const said = (spy: typeof warn) =>
658
+ spy.mock.calls.some(([text]) => String(text).includes(`(HTTP ${status})`));
659
+ expect([said(warn), said(error)]).toEqual([level === "warn", level === "error"]);
660
+ unmount(root);
661
+ });
662
+
642
663
  it("runs no load side effects for a superseded shadow", () => {
643
664
  const { getApi, gen, root } = beginReload();
644
665
  usePlayerStore.getState().setCurrentTime(7);
@@ -0,0 +1,163 @@
1
+ import { afterEach, describe, expect, it, vi } from "vitest";
2
+ import { MediaFetchError, mediaUrlSourceOptions, reportMediaFetchFailure } from "./mediaFetch";
3
+
4
+ const URL_WITH_PATH = "http://127.0.0.1:5190/api/projects/demo/preview/clips/take-1.mp4";
5
+
6
+ afterEach(() => {
7
+ vi.unstubAllGlobals();
8
+ vi.restoreAllMocks();
9
+ });
10
+
11
+ describe("mediaUrlSourceOptions", () => {
12
+ it("turns a network failure into a typed error without the URL", async () => {
13
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new TypeError("Failed to fetch")));
14
+ const { fetchFn } = mediaUrlSourceOptions("probe");
15
+
16
+ const error = await fetchFn(URL_WITH_PATH).catch((e: unknown) => e);
17
+
18
+ expect(error).toBeInstanceOf(MediaFetchError);
19
+ expect(error).toMatchObject({ reader: "probe", status: null, code: "TypeError" });
20
+ expect(String((error as Error).message)).not.toContain("take-1");
21
+ });
22
+
23
+ it("names the network code when the failure carries one", async () => {
24
+ const failure = Object.assign(new TypeError("fetch failed"), { cause: { code: "EBUSY" } });
25
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(failure));
26
+
27
+ const error = await mediaUrlSourceOptions("thumbnail")
28
+ .fetchFn(URL_WITH_PATH)
29
+ .catch((e) => e);
30
+
31
+ expect(error).toMatchObject({ reader: "thumbnail", code: "EBUSY" });
32
+ });
33
+
34
+ it("turns an HTTP error status into a typed error", async () => {
35
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 403 })));
36
+
37
+ const error = await mediaUrlSourceOptions("probe")
38
+ .fetchFn(URL_WITH_PATH)
39
+ .catch((e) => e);
40
+
41
+ expect(error).toMatchObject({
42
+ status: 403,
43
+ message: "probe range fetch failed: HTTP 403 after 0 retries",
44
+ });
45
+ });
46
+
47
+ it("lets a cancellation through untouched", async () => {
48
+ const abort = new DOMException("Aborted", "AbortError");
49
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(abort));
50
+
51
+ await expect(mediaUrlSourceOptions("probe").fetchFn(URL_WITH_PATH)).rejects.toBe(abort);
52
+ });
53
+
54
+ it("retries a network failure twice, then gives up and records the retries", () => {
55
+ const { getRetryDelay } = mediaUrlSourceOptions("probe");
56
+ const failure = new MediaFetchError("probe", null, "TypeError");
57
+
58
+ expect([1, 2, 3].map((attempt) => getRetryDelay(attempt, failure))).toEqual([0.5, 1, null]);
59
+ expect(failure).toMatchObject({
60
+ retries: 2,
61
+ message: "probe range fetch failed: network TypeError after 2 retries",
62
+ });
63
+ });
64
+
65
+ it("gives up on a body that breaks mid-read with the typed error, through a real mediabunny read", async () => {
66
+ const brokenBody = () =>
67
+ new Response(
68
+ new ReadableStream({
69
+ pull: (controller) => controller.error(new TypeError("network error")),
70
+ }),
71
+ {
72
+ status: 206,
73
+ headers: { "Content-Range": "bytes 0-65535/1000000", "Content-Length": "65536" },
74
+ },
75
+ );
76
+ vi.stubGlobal(
77
+ "fetch",
78
+ vi.fn(async () => brokenBody()),
79
+ );
80
+ vi.useFakeTimers();
81
+ const mb = await import("mediabunny");
82
+ const runnerListeners = process.listeners("unhandledRejection");
83
+ const unhandled: unknown[] = [];
84
+ process.removeAllListeners("unhandledRejection");
85
+ process.on("unhandledRejection", (reason) => unhandled.push(reason));
86
+ try {
87
+ const input = new mb.Input({
88
+ source: new mb.UrlSource(URL_WITH_PATH, mediaUrlSourceOptions("thumbnail")),
89
+ formats: mb.ALL_FORMATS,
90
+ });
91
+ const read = input.getDurationFromMetadata().catch((e: unknown) => e);
92
+ await vi.runAllTimersAsync();
93
+ const error = await read;
94
+ input.dispose();
95
+ await vi.runAllTimersAsync();
96
+
97
+ expect(error).toMatchObject({
98
+ name: "MediaFetchError",
99
+ message: "thumbnail range fetch failed: network TypeError after 2 retries",
100
+ });
101
+ for (const reason of unhandled) expect(reason).toBeInstanceOf(MediaFetchError);
102
+ } finally {
103
+ vi.useRealTimers();
104
+ process.removeAllListeners("unhandledRejection");
105
+ for (const listener of runnerListeners) process.on("unhandledRejection", listener);
106
+ }
107
+ });
108
+
109
+ it("counts mid-stream read failures, which always arrive as attempt 1", () => {
110
+ const { getRetryDelay } = mediaUrlSourceOptions("thumbnail");
111
+ const readError = new TypeError("network error");
112
+
113
+ expect([1, 1, 1].map((attempt) => getRetryDelay(attempt, readError))).toEqual([0.5, 1, null]);
114
+ });
115
+
116
+ it("does not retry a client error status", () => {
117
+ const failure = new MediaFetchError("probe", 404, null);
118
+
119
+ expect(mediaUrlSourceOptions("probe").getRetryDelay(1, failure)).toBeNull();
120
+ expect(failure.retries).toBe(0);
121
+ });
122
+
123
+ // mediabunny rethrows a failed read-ahead nobody awaits "so it doesn't get swallowed": that copy is typed too.
124
+ it("fails a real mediabunny read, and its unawaited read-ahead, with the typed error", async () => {
125
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 404 })));
126
+ const mb = await import("mediabunny");
127
+ const runnerListeners = process.listeners("unhandledRejection");
128
+ const unhandled: unknown[] = [];
129
+ process.removeAllListeners("unhandledRejection");
130
+ process.on("unhandledRejection", (reason) => unhandled.push(reason));
131
+ try {
132
+ const input = new mb.Input({
133
+ source: new mb.UrlSource(URL_WITH_PATH, mediaUrlSourceOptions("probe")),
134
+ formats: mb.ALL_FORMATS,
135
+ });
136
+ const error = await input.getDurationFromMetadata().catch((e: unknown) => e);
137
+ input.dispose();
138
+ await new Promise(setImmediate);
139
+
140
+ expect(error).toMatchObject({ name: "MediaFetchError", status: 404, retries: 0 });
141
+ expect(unhandled.length).toBeGreaterThan(0);
142
+ for (const reason of unhandled) expect(reason).toBeInstanceOf(MediaFetchError);
143
+ } finally {
144
+ process.removeAllListeners("unhandledRejection");
145
+ for (const listener of runnerListeners) process.on("unhandledRejection", listener);
146
+ }
147
+ });
148
+ });
149
+
150
+ describe("reportMediaFetchFailure", () => {
151
+ it("writes one scrubbed line for a typed failure and nothing for anything else", () => {
152
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
153
+ const failure = new MediaFetchError("thumbnail", null, "TypeError");
154
+ failure.setRetries(2);
155
+
156
+ reportMediaFetchFailure(failure);
157
+ reportMediaFetchFailure(new Error("Video source has no decodable video track"));
158
+
159
+ expect(warn.mock.calls).toEqual([
160
+ ["[Studio] thumbnail range fetch failed: network TypeError after 2 retries"],
161
+ ]);
162
+ });
163
+ });
@@ -0,0 +1,98 @@
1
+ export type MediaReader = "probe" | "thumbnail";
2
+
3
+ const describe = (
4
+ reader: MediaReader,
5
+ status: number | null,
6
+ code: string | null,
7
+ retries: number,
8
+ ) =>
9
+ `${reader} range fetch failed: ${status === null ? `network ${code}` : `HTTP ${status}`} after ${retries} retries`;
10
+
11
+ /** A media range fetch that gave up: which reader, the HTTP status or network code, and the retries. Never the URL. */
12
+ export class MediaFetchError extends Error {
13
+ override readonly name = "MediaFetchError";
14
+ retries = 0;
15
+
16
+ constructor(
17
+ readonly reader: MediaReader,
18
+ readonly status: number | null,
19
+ readonly code: string | null,
20
+ ) {
21
+ super(describe(reader, status, code, 0));
22
+ }
23
+
24
+ setRetries(retries: number): void {
25
+ this.retries = retries;
26
+ this.message = describe(this.reader, this.status, this.code, retries);
27
+ }
28
+ }
29
+
30
+ const MAX_RETRIES = 2;
31
+
32
+ const isAbort = (error: unknown) => (error as { name?: unknown } | null)?.name === "AbortError";
33
+
34
+ function networkCode(error: unknown): string {
35
+ const cause = (error as { cause?: { code?: unknown } } | null)?.cause;
36
+ if (typeof cause?.code === "string") return cause.code;
37
+ const name = (error as { name?: unknown } | null)?.name;
38
+ return typeof name === "string" ? name : "unknown";
39
+ }
40
+
41
+ const typedFailure = (reader: MediaReader, error: unknown) =>
42
+ isAbort(error) ? error : new MediaFetchError(reader, null, networkCode(error));
43
+
44
+ /** The body, failing a broken read with a MediaFetchError: mediabunny rethrows a body error as-is. */
45
+ function typedBody(
46
+ reader: MediaReader,
47
+ body: ReadableStream<Uint8Array>,
48
+ ): ReadableStream<Uint8Array> {
49
+ const source = body.getReader();
50
+ return new ReadableStream<Uint8Array>({
51
+ async pull(controller) {
52
+ try {
53
+ const { done, value } = await source.read();
54
+ if (done) controller.close();
55
+ else controller.enqueue(value);
56
+ } catch (error) {
57
+ controller.error(typedFailure(reader, error));
58
+ }
59
+ },
60
+ cancel: (reason) => source.cancel(reason),
61
+ });
62
+ }
63
+
64
+ /**
65
+ * Options for a mediabunny `UrlSource`. Its default retries a same-origin network failure
66
+ * forever and logs a bare `TypeError` each time; these retry twice and fail with a MediaFetchError.
67
+ */
68
+ export function mediaUrlSourceOptions(reader: MediaReader) {
69
+ let failures = 0;
70
+ const fetchFn = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
71
+ let response: Response;
72
+ try {
73
+ // oxlint-disable-next-line no-restricted-globals -- a media read, on the media's sockets like mediabunny's own
74
+ response = await fetch(input, init);
75
+ } catch (error) {
76
+ throw typedFailure(reader, error);
77
+ }
78
+ if (!response.ok) throw new MediaFetchError(reader, response.status, null);
79
+ if (!response.body) return response;
80
+ const { status, statusText, headers } = response;
81
+ return new Response(typedBody(reader, response.body), { status, statusText, headers });
82
+ };
83
+ // Counted per source: mediabunny passes 1 for every failed mid-stream read.
84
+ const getRetryDelay = (_previousAttempts: number, error: unknown): number | null => {
85
+ const clientError =
86
+ error instanceof MediaFetchError && error.status !== null && error.status < 500;
87
+ if (error instanceof MediaFetchError) error.setRetries(failures);
88
+ if (clientError || failures >= MAX_RETRIES) return null;
89
+ failures++;
90
+ return 0.5 * failures;
91
+ };
92
+ return { fetchFn, getRetryDelay };
93
+ }
94
+
95
+ export function reportMediaFetchFailure(error: unknown): void {
96
+ if (!(error instanceof MediaFetchError)) return;
97
+ console.warn(`[Studio] ${error.message}`);
98
+ }