docs add camera startup fallback changelog

client/src/lib/camera.ts

@@ -9,6 +9,13 @@ export type CameraZoomState = {
   focusMode: string;
 };
 
+export type CameraRequestResult = {
+  stream: MediaStream;
+  appliedFacingMode: "user" | "environment";
+  audioEnabled: boolean;
+  usedFallback: boolean;
+};
+
 type NumericRange = {
   min: number;
   max: number;
@@ -66,6 +73,98 @@ export function getCameraVideoConstraints(
   }
 }
 
+function normalizeVideoConstraintCandidate(candidate: MediaTrackConstraints | true) {
+  if (candidate === true) {
+    return { label: "camera-any", video: true as const };
+  }
+
+  return {
+    label: JSON.stringify(candidate),
+    video: candidate,
+  };
+}
+
+function createFallbackVideoCandidates(
+  facingMode: "user" | "environment",
+  isMobile: boolean,
+  preset: CameraQualityPreset,
+) {
+  const base = getCameraVideoConstraints(facingMode, isMobile, preset);
+  const alternateFacing = facingMode === "environment" ? "user" : "environment";
+  const lowRes = {
+    facingMode,
+    width: { ideal: isMobile ? 640 : 960 },
+    height: { ideal: isMobile ? 360 : 540 },
+  } satisfies MediaTrackConstraints;
+  const lowResAlternate = {
+    facingMode: alternateFacing,
+    width: { ideal: isMobile ? 640 : 960 },
+    height: { ideal: isMobile ? 360 : 540 },
+  } satisfies MediaTrackConstraints;
+  const anyCamera = {
+    width: { ideal: isMobile ? 640 : 960 },
+    height: { ideal: isMobile ? 360 : 540 },
+  } satisfies MediaTrackConstraints;
+
+  const candidates = [
+    normalizeVideoConstraintCandidate(base),
+    normalizeVideoConstraintCandidate({
+      ...base,
+      frameRate: undefined,
+    }),
+    normalizeVideoConstraintCandidate(lowRes),
+    normalizeVideoConstraintCandidate(lowResAlternate),
+    normalizeVideoConstraintCandidate(anyCamera),
+    normalizeVideoConstraintCandidate(true),
+  ];
+
+  const deduped = new Map<string, { video: MediaTrackConstraints | true }>();
+  candidates.forEach((candidate) => {
+    if (!deduped.has(candidate.label)) {
+      deduped.set(candidate.label, { video: candidate.video });
+    }
+  });
+  return Array.from(deduped.values());
+}
+
+export async function requestCameraStream(options: {
+  facingMode: "user" | "environment";
+  isMobile: boolean;
+  preset: CameraQualityPreset;
+  audio?: false | MediaTrackConstraints;
+}) {
+  const videoCandidates = createFallbackVideoCandidates(options.facingMode, options.isMobile, options.preset);
+  const audioCandidates = options.audio ? [options.audio, false] : [false];
+  let lastError: unknown = null;
+
+  for (const audio of audioCandidates) {
+    for (let index = 0; index < videoCandidates.length; index += 1) {
+      const video = videoCandidates[index]?.video ?? true;
+      try {
+        const stream = await navigator.mediaDevices.getUserMedia({ video, audio });
+        const videoTrack = stream.getVideoTracks()[0] || null;
+        const settings = (
+          videoTrack && typeof (videoTrack as MediaStreamTrack & { getSettings?: () => unknown }).getSettings === "function"
+            ? (videoTrack as MediaStreamTrack & { getSettings: () => unknown }).getSettings()
+            : {}
+        ) as Record<string, unknown>;
+        const appliedFacingMode = settings.facingMode === "user" ? "user" : settings.facingMode === "environment" ? "environment" : options.facingMode;
+
+        return {
+          stream,
+          appliedFacingMode,
+          audioEnabled: stream.getAudioTracks().length > 0,
+          usedFallback: index > 0 || audio === false && Boolean(options.audio),
+        } satisfies CameraRequestResult;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error("无法访问摄像头");
+}
+
 export function getLiveAnalysisBitrate(preset: CameraQualityPreset, isMobile: boolean) {
   switch (preset) {
     case "economy":

client/src/lib/changelog.ts

@@ -8,6 +8,22 @@ export type ChangeLogEntry = {
 };
 
 export const CHANGE_LOG_ENTRIES: ChangeLogEntry[] = [
+  {
+    version: "2026.03.16-camera-startup-fallbacks",
+    releaseDate: "2026-03-16",
+    repoVersion: "a211562",
+    summary: "修复部分设备上摄像头因后置镜头约束、分辨率约束或麦克风不可用而直接启动失败的问题。",
+    features: [
+      "live-camera 与 recorder 改为共用分级降级的摄像头请求流程，会在当前画质失败时自动降分辨率、降约束并回退到兼容镜头",
+      "当设备不支持默认后置摄像头或当前镜头不可用时，页面会自动切换到实际可用的镜头方向，避免直接报错后卡死在未启动状态",
+      "recorder 预览启动不再被麦克风权限或麦克风设备异常整体拖死；麦克风不可用时会自动回退到仅视频模式",
+      "兼容模式命中时前端会给出明确提示，方便区分“已自动降级成功”与“仍然无法访问摄像头”的场景",
+    ],
+    tests: [
+      "pnpm build",
+      "部署后线上 smoke: 待补记公开站点前端资源 revision 与 `/live-camera`、`/recorder` 摄像头启动结果",
+    ],
+  },
   {
     version: "2026.03.16-live-analysis-viewer-full-sync",
     releaseDate: "2026-03-16",

client/src/pages/LiveCamera.tsx

@@ -17,7 +17,7 @@ import { Slider } from "@/components/ui/slider";
 import { Switch } from "@/components/ui/switch";
 import { formatDateTimeShanghai } from "@/lib/time";
 import { toast } from "sonner";
-import { applyTrackZoom, type CameraQualityPreset, getCameraVideoConstraints, getLiveAnalysisBitrate, readTrackZoomState } from "@/lib/camera";
+import { applyTrackZoom, type CameraQualityPreset, getLiveAnalysisBitrate, readTrackZoomState, requestCameraStream } from "@/lib/camera";
 import {
   ACTION_WINDOW_FRAMES,
   AVATAR_PRESETS,
@@ -1221,20 +1221,24 @@ export default function LiveCamera() {
       if (streamRef.current) {
         streamRef.current.getTracks().forEach((track) => track.stop());
       }
-
+      const { stream, appliedFacingMode, usedFallback } = await requestCameraStream({
-      const constraints: MediaStreamConstraints = {
+        facingMode: nextFacing,
-        video: getCameraVideoConstraints(nextFacing, mobile, preset),
+        isMobile: mobile,
-        audio: false,
+        preset,
-      };
+      });
-
-      const stream = await navigator.mediaDevices.getUserMedia(constraints);
       streamRef.current = stream;
+      if (appliedFacingMode !== nextFacing) {
+        setFacing(appliedFacingMode);
+      }
       if (videoRef.current) {
         videoRef.current.srcObject = stream;
         await videoRef.current.play();
       }
       await syncZoomState(preferredZoom, stream.getVideoTracks()[0] || null);
       setCameraActive(true);
+      if (usedFallback) {
+        toast.info("当前设备已自动切换到兼容摄像头模式");
+      }
       toast.success("摄像头已启动");
     } catch (error: any) {
       toast.error(`摄像头启动失败: ${error?.message || "未知错误"}`);

client/src/pages/Recorder.tsx

@@ -31,7 +31,7 @@ import {
   recognizeActionFrame,
   stabilizeActionFrame,
 } from "@/lib/actionRecognition";
-import { applyTrackZoom, getCameraVideoConstraints, readTrackZoomState } from "@/lib/camera";
+import { applyTrackZoom, readTrackZoomState, requestCameraStream } from "@/lib/camera";
 import { formatDateTimeShanghai } from "@/lib/time";
 import {
   Activity,
@@ -420,8 +420,10 @@ export default function Recorder() {
         streamRef.current = null;
       }
 
-      const stream = await navigator.mediaDevices.getUserMedia({
+      const { stream, appliedFacingMode, audioEnabled, usedFallback } = await requestCameraStream({
-        video: getCameraVideoConstraints(nextFacingMode, mobile, preset),
+        facingMode: nextFacingMode,
+        isMobile: mobile,
+        preset,
         audio: {
           echoCancellation: true,
           noiseSuppression: true,
@@ -438,6 +440,9 @@ export default function Recorder() {
 
       suppressTrackEndedRef.current = false;
       streamRef.current = stream;
+      if (appliedFacingMode !== nextFacingMode) {
+        setFacingMode(appliedFacingMode);
+      }
       if (liveVideoRef.current) {
         liveVideoRef.current.srcObject = stream;
         await liveVideoRef.current.play();
@@ -445,6 +450,12 @@ export default function Recorder() {
       await syncZoomState(preferredZoom, stream.getVideoTracks()[0] || null);
       setCameraError("");
       setCameraActive(true);
+      if (usedFallback) {
+        toast.info("当前设备已自动切换到兼容摄像头模式");
+      }
+      if (!audioEnabled) {
+        toast.warning("麦克风不可用，已切换为仅视频模式");
+      }
       return stream;
     } catch (error: any) {
       const message = error?.message || "无法访问摄像头";

docs/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Tennis Training Hub - 变更日志
 
+## 2026.03.16-camera-startup-fallbacks (2026-03-16)
+
+### 功能更新
+
+- 修复部分设备在 `/live-camera` 和 `/recorder` 中因默认后置镜头、分辨率或帧率约束不兼容而直接启动摄像头失败的问题
+- 摄像头请求现在会自动按当前画质、去掉高约束、低分辨率、备用镜头、任意可用镜头依次降级重试
+- `/recorder` 在麦克风不可用或麦克风权限未给出时，会自动回退到仅视频模式，不再让整次预览启动失败
+- 如果实际启用的是兼容镜头或降级模式，页面会显示提示，帮助区分“自动修复成功”与“仍然无法访问摄像头”
+
+### 测试
+
+- `pnpm build`
+- 部署后线上 smoke：待补记公开站点前端资源 revision 与 `/live-camera`、`/recorder` 摄像头启动结果
+
+### 线上 smoke
+
+- 待本次部署完成后补记
+
+### 仓库版本
+
+- `a211562`
+
 ## 2026.03.16-live-analysis-viewer-full-sync (2026-03-16)
 
 ### 功能更新