{/* Camera Info */}
diff --git a/frontend/src/hooks/useCameraBindings.ts b/frontend/src/hooks/useCameraBindings.ts
index f8081d332..74b3e329a 100644
--- a/frontend/src/hooks/useCameraBindings.ts
+++ b/frontend/src/hooks/useCameraBindings.ts
@@ -5,6 +5,7 @@ import { ImageFeatures } from "@/lib/checkpointsApi";
import {
CameraRequest,
CameraRotation,
+ liveCameraFor,
PhysicalCamera,
physicalCameraKey,
rotatedDimensions,
@@ -43,10 +44,7 @@ export function useCameraBindings(
(c) => c.name.toLowerCase() === expectedName.toLowerCase(),
);
if (!robotCam) continue;
- const live =
- (robotCam.device_id &&
- availableCameras.find((c) => c.deviceId === robotCam.device_id)) ||
- availableCameras.find((c) => c.index === robotCam.camera_index);
+ const live = liveCameraFor(robotCam, availableCameras);
if (live) {
next[expectedName] = live.index;
changed = true;
diff --git a/frontend/src/hooks/useCameraStream.test.tsx b/frontend/src/hooks/useCameraStream.test.tsx
new file mode 100644
index 000000000..eb6c1f328
--- /dev/null
+++ b/frontend/src/hooks/useCameraStream.test.tsx
@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import React, { act } from "react";
+import { createRoot, Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { useCameraStream } from "./useCameraStream";
+
+let root: Root;
+let container: HTMLDivElement;
+const getUserMedia = vi.fn();
+const stop = vi.fn();
+
+const Preview = () => {
+ const { videoRef } = useCameraStream("cam", false, { width: 640, height: 480 });
+ return
;
+};
+
+const flush = () => act(async () => {});
+
+beforeEach(() => {
+ Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+ vi.useFakeTimers();
+ getUserMedia.mockReset().mockResolvedValue({ getTracks: () => [{ stop }] });
+ stop.mockReset();
+ Object.defineProperty(navigator, "mediaDevices", {
+ configurable: true,
+ value: { getUserMedia, addEventListener: vi.fn(), removeEventListener: vi.fn() },
+ });
+ vi.spyOn(HTMLMediaElement.prototype, "play").mockResolvedValue(undefined);
+ container = document.createElement("div");
+ root = createRoot(container);
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+});
+
+const requestedSize = (call: number) => {
+ const { width, height } = getUserMedia.mock.calls[call][0].video;
+ return [width.ideal, height.ideal];
+};
+
+test("opens at the recorded size and keeps a stream that delivers frames", async () => {
+ act(() => root.render(
));
+ await flush();
+ Object.defineProperty(container.querySelector("video")!, "readyState", { value: HTMLMediaElement.HAVE_CURRENT_DATA });
+ await act(async () => vi.advanceTimersByTime(5000));
+ expect(getUserMedia).toHaveBeenCalledTimes(1);
+ expect(requestedSize(0)).toEqual([640, 480]);
+ expect(stop).not.toHaveBeenCalled();
+});
+
+test("reopens at 1280x720 when the recorded size never delivers a frame", async () => {
+ act(() => root.render(
));
+ await flush();
+ await act(async () => vi.advanceTimersByTime(2500));
+ expect(stop).toHaveBeenCalledTimes(1);
+ expect(getUserMedia).toHaveBeenCalledTimes(2);
+ expect(requestedSize(1)).toEqual([1280, 720]);
+});
diff --git a/frontend/src/hooks/useCameraStream.ts b/frontend/src/hooks/useCameraStream.ts
index 1f44cf18b..bbf1a6f0f 100644
--- a/frontend/src/hooks/useCameraStream.ts
+++ b/frontend/src/hooks/useCameraStream.ts
@@ -15,6 +15,13 @@ import { useEffect, useRef, useState } from "react";
* device-exposure change (timing isn't guaranteed) — so we re-attempt on
* that event instead. Without this the hook would otherwise stay stuck on
* the error state until a full page reload.
+ *
+ * The stream is first requested at `size`, the capture size recording uses
+ * (browser default when omitted). A stream can also open cleanly yet never
+ * deliver a frame: some UVC cameras (e.g. Innomaker U20CAM on macOS) accept
+ * 640x480 in Firefox but stay silent until something starts them at a native
+ * resolution. If no frame arrives within STALL_TIMEOUT_MS we reopen at the
+ * next size in FALLBACK_SIZES, so cameras that stream at `size` are untouched.
*/
const MAX_RETRIES = 4;
const BASE_DELAY_MS = 300;
@@ -22,8 +29,21 @@ const BASE_DELAY_MS = 300;
// device (NotFoundError) and unsatisfiable constraints (OverconstrainedError)
// won't fix themselves on a retimed retry — those recover via `devicechange`.
const TRANSIENT_ERRORS = new Set(["NotReadableError", "AbortError"]);
+const STALL_TIMEOUT_MS = 2500;
+const FALLBACK_SIZES: CameraSize[] = [
+ { width: 1280, height: 720 },
+ { width: 1920, height: 1080 },
+];
+
+export interface CameraSize {
+ width: number;
+ height: number;
+}
+
+const sizeConstraints = (size: CameraSize | undefined): MediaTrackConstraints =>
+ size ? { width: { ideal: size.width }, height: { ideal: size.height } } : {};
-export function useCameraStream(deviceId: string, paused: boolean) {
+export function useCameraStream(deviceId: string, paused: boolean, size?: CameraSize) {
const videoRef = useRef
(null);
const [hasError, setHasError] = useState(false);
// Bumping this forces the stream effect to re-run (a clean retry).
@@ -53,20 +73,34 @@ export function useCameraStream(deviceId: string, paused: boolean) {
let cancelled = false;
let stream: MediaStream | null = null;
let retryTimer: ReturnType | null = null;
+ let stallTimer: ReturnType | null = null;
setHasError(false);
+ const attempts = [size, ...FALLBACK_SIZES];
- const start = async (attempt: number) => {
+ const stopStream = () => {
+ if (stream) stream.getTracks().forEach((t) => t.stop());
+ stream = null;
+ };
+
+ const start = async (attempt: number, sizeIndex: number) => {
try {
stream = await navigator.mediaDevices.getUserMedia({
- video: { deviceId: { exact: deviceId } },
+ video: { deviceId: { exact: deviceId }, ...sizeConstraints(attempts[sizeIndex]) },
});
if (cancelled) {
- stream.getTracks().forEach((t) => t.stop());
+ stopStream();
return;
}
- if (videoRef.current) {
- videoRef.current.srcObject = stream;
- await videoRef.current.play().catch(() => {});
+ const video = videoRef.current;
+ if (!video) return;
+ video.srcObject = stream;
+ video.play().catch(() => {});
+ if (sizeIndex < attempts.length - 1) {
+ stallTimer = setTimeout(() => {
+ if (cancelled || video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) return;
+ stopStream();
+ start(0, sizeIndex + 1);
+ }, STALL_TIMEOUT_MS);
}
} catch (err) {
if (cancelled) return;
@@ -74,7 +108,7 @@ export function useCameraStream(deviceId: string, paused: boolean) {
if (attempt < MAX_RETRIES && TRANSIENT_ERRORS.has(name)) {
// Exponential backoff: 300ms, 600ms, 1200ms, ...
retryTimer = setTimeout(
- () => start(attempt + 1),
+ () => start(attempt + 1, sizeIndex),
BASE_DELAY_MS * 2 ** attempt
);
} else {
@@ -82,14 +116,18 @@ export function useCameraStream(deviceId: string, paused: boolean) {
}
}
};
- start(0);
+ start(0, 0);
return () => {
cancelled = true;
if (retryTimer) clearTimeout(retryTimer);
- if (stream) stream.getTracks().forEach((t) => t.stop());
+ if (stallTimer) clearTimeout(stallTimer);
+ stopStream();
};
- }, [deviceId, paused, retryKey]);
+ // Depend on the size's numbers, not the object, so a caller passing a fresh
+ // literal each render doesn't restart the stream.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [deviceId, paused, retryKey, size?.width, size?.height]);
return { videoRef, hasError };
}
diff --git a/frontend/src/lib/cameraConfig.test.ts b/frontend/src/lib/cameraConfig.test.ts
index 8da735c36..ff3dce4a6 100644
--- a/frontend/src/lib/cameraConfig.test.ts
+++ b/frontend/src/lib/cameraConfig.test.ts
@@ -1,5 +1,5 @@
import { expect, test } from "vitest";
-import { CameraConfig, cameraRotation, normalizeCameraConfig, physicalCameraKey, rotatedDimensions, rotationForCamera, serializeCameras } from "./cameraConfig";
+import { CameraConfig, cameraRotation, normalizeCameraConfig, physicalCameraKey, previewDeviceId, rotatedDimensions, rotationForCamera, serializeCameras } from "./cameraConfig";
const camera: CameraConfig = { id: "wrist", name: "wrist", device_id: "usb-wrist", camera_index: 1, type: "opencv", width: 640, height: 480, fps: 30 };
test("old profiles default to zero without changing capture dimensions", () => {
@@ -27,3 +27,11 @@ test("rotation follows a physical camera across index drift and policy reassignm
expect(rotationForCamera(top, saved, overrides)).toBe(90);
expect(rotationForCamera({ deviceId: "unsaved", index: 5 }, saved, {})).toBe(0);
});
+test("a saved camera previews by its device ID, else by cv2 index in another browser", () => {
+ const firefox = [{ index: 0, deviceId: "ff-other" }, { index: 1, deviceId: "usb-wrist" }];
+ const safari = [{ index: 0, deviceId: "sf-other" }, { index: 1, deviceId: "sf-wrist" }];
+ expect(previewDeviceId(camera, firefox)).toBe("usb-wrist");
+ expect(previewDeviceId(camera, safari)).toBe("sf-wrist");
+ expect(previewDeviceId(camera, [])).toBe("usb-wrist");
+ expect(previewDeviceId({ ...camera, camera_index: 5 }, safari)).toBe("");
+});
diff --git a/frontend/src/lib/cameraConfig.ts b/frontend/src/lib/cameraConfig.ts
index 16b21a0f4..befcde3f0 100644
--- a/frontend/src/lib/cameraConfig.ts
+++ b/frontend/src/lib/cameraConfig.ts
@@ -89,7 +89,9 @@ export function cameraPreviewGeometry(width: number, height: number, rotation: C
top: "50%",
width: quarterTurn ? `${(width / height) * 100}%` : "100%",
height: quarterTurn ? `${(height / width) * 100}%` : "100%",
- objectFit: "contain",
+ // Crop, don't letterbox: a stream that fell back to another aspect ratio
+ // (see useCameraStream) should still show the recorded framing.
+ objectFit: "cover",
maxWidth: "none",
transform: `translate(-50%, -50%) rotate(${rotation}deg)`,
};
@@ -101,6 +103,33 @@ export interface PhysicalCamera {
deviceId: string;
}
+/**
+ * The live camera for a saved one. Browser device IDs differ per browser and
+ * origin, so an ID saved in Firefox is unknown to Safari (or to the Vite dev
+ * origin); fall back to the cv2 index, which every browser shares.
+ */
+export function liveCameraFor(
+ saved: Pick,
+ available: T[],
+): T | undefined {
+ return (
+ (saved.device_id ? available.find((c) => c.deviceId === saved.device_id) : undefined) ??
+ available.find((c) => c.index === saved.camera_index)
+ );
+}
+
+/**
+ * Browser device ID to preview a saved camera with. Until the live cameras
+ * have been listed, try the saved ID; afterwards "" means no camera matched.
+ */
+export function previewDeviceId(
+ saved: Pick,
+ available: PhysicalCamera[],
+): string {
+ if (available.length === 0) return saved.device_id;
+ return liveCameraFor(saved, available)?.deviceId ?? "";
+}
+
export function physicalCameraKey(camera: PhysicalCamera): string {
return camera.deviceId ? `device:${camera.deviceId}` : `index:${camera.index}`;
}