FreeMoCap UI 桌面端全解析React/Electron 架构与多相机同步回放实战指南【免费下载链接】freemocapFree Motion Capture for Everyone ✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocapFreeMoCap UI 是 FreeMoCap 项目的桌面图形界面承担实时多相机流、录制与同步回放三大核心职责以React 19 TypeScript Material UI Redux Toolkit构建并通过Electron打包为跨平台桌面应用。本文以 freemocap-ui/README.md 为主线结合仓库内的源码与配置带你完整掌握其启动流程、页面功能、前后端通信协议以及逐帧锁定同步回放的核心实现原理。FreeMoCap UI 是什么FreeMoCapFree Motion Capture for Everyone是一个开源的无标记运动捕捉系统。freemocap-ui是其 React/Electron 桌面界面核心能力包括实时多相机流同时预览多路摄像头画面支持分辨率、帧率、曝光、旋转等参数配置录制一键开始/停止录制并将相机画面与时间戳写入本地磁盘同步回放浏览历史录制会话以逐帧精确同步的方式多相机回放。技术栈方面README 明确标注为React 19、TypeScript、Material UI、Redux Toolkit桌面打包基于Electron与 electron-vite。实际依赖声明可在 freemocap-ui/package.json 中确认react/react-dom为^19.1.0reduxjs/toolkit为^2.5.1electron为^35.0.3vite为^7.3.1。UI 本身只是一个壳真正的业务逻辑相机采集、标定、姿态估计运行在配套的 Python 后端服务中UI 通过 HTTP REST 与 WebSocket 两条通道与后端通信。快速启动环境准备仓库根目录是一个 monorepo 风格的组织freemocap/Python 后端、freemocap-ui/前端桌面应用、freemocap-docs/文档站。启动 UI 需要两个进程同时运行。第一步启动 Python 服务端# 在仓库根目录执行 python -m freemocap该命令启动 FastAPI 服务默认监听localhost:53117。端口并非写死的常量而是由 freemocap/api/server_constants.py 中的PREFERRED_PORT 53117指定起始端口配合MAX_PORT_ATTEMPTS 50向上逐个尝试直到找到可用端口Electron 主进程通过解析标准输出中的FREEMOCAP_PORTport哨兵行format_port_sentinel来发现实际端口。第二步启动前端 UIcd freemocap-ui npm install npm run dev # Vite dev server Electronnpm run dev实际执行的是cross-env NODE_ENVdevelopment vite见 freemocap-ui/package.json由vite-plugin-electron在启动 Vite 开发服务器的同时拉起 Electron 窗口。启动后 UI 默认认为 Python 服务运行在localhost:53117。若端口被占用导致实际端口偏移freemocap-ui/src/constants/server-urls.ts 中维护的ServerUrls单例DEFAULT_HOST localhost、DEFAULT_PORT 53117可通过setHost/setPort动态调整所有 API 地址均基于它生成。页面与核心功能应用内部通过 React Router 组织路由见 freemocap-ui/src/layout/content/BaseContentRouter.tsx核心页面如下。Cameras 页面/cameras实时多相机视图通过 WebSocket 接收后端的实时二进制帧流。功能点相机分辨率、帧率、曝光、旋转配置一键开始/停止录制画面以响应式网格展示支持拖拽排序与缩放。对应源码位于 freemocap-ui/src/components/camera-views/、freemocap-ui/src/components/control-panels/camera-config-panel/ 与 freemocap-ui/src/components/framerate-viewer/D3 实时 FPS 图表。Playback 页面/playback浏览并回放已录制的会话是本文档的核心章节包含两大组件Recording Browser与Synced Video Player。Recording Browser录制浏览器默认列出~/freemocap_data/recordings/下的全部录制会话目录实际位置由 Python 端get_default_freemocap_recordings_path()决定见 freemocap/system/default_paths.py按最新优先排序。每条记录展示相机流数量N cams磁盘占用总大小自动格式化为 KB/MB/GB录制时长与帧数从时间戳 CSV 读取有效 FPS相对时间如 2h ago、3d ago。从源码 freemocap-ui/src/components/playback/RecordingBrowser.tsx 可以看到它还支持文本过滤按名称模糊匹配多字段排序date / name / size / cameras / frames / duration六个字段升降序可切换手动加载任意目录在 Electron 环境下可通过系统目录选择器挑选任意文件夹加载录制行内状态徽章显示管线阶段完成情况x/y stages全部完成则显示 Blender ready、Legacy 旧版目录布局标记展开详情点击箭头展开RecordingStatusPanel展示该录制详细的管线状态标定、Blender 导出等Import Videos在桌面端通过 Electron IPC 导入视频。元数据来自后端GET /freemocap/playback/recordings接口返回的RecordingListEntry字段如video_count、total_size_bytes、total_frames、duration_seconds、fps、status_summary、layout_validation。Synced Video Player同步视频播放器将选中录制的所有相机流打开为响应式网格核心特性逐帧锁定同步所有相机在任意时刻都显示完全相同的帧号由单一权威计数器驱动逐相机叠加信息帧号右上角、绿色、相机 ID/文件名左下角、SMPTE 时间码右下角原生流畅播放基于HTMLVideoElement.play()硬件解码渲染配合 rAF 漂移校正循环维持同步逐帧步进←/→步进 1 帧Shift←/→步进 10 帧变速播放0.1× 至 8×任何速率下保持帧锁定快捷键Space播放/暂停、Home跳至开头、End跳至末尾、L循环。项目目录结构README 给出的顶层结构如下目录细节以当前仓库为准src/ ├── pages/ │ ├── CamerasPage.tsx # 实时相机视图 │ ├── PlaybackPage.tsx # 录制浏览器 → 同步播放器 │ └── WelcomePage.tsx # 首页/落地页 │ ├── components/ │ ├── playback/ │ │ ├── SyncedVideoPlayer.tsx # 核心逐帧锁定多视频播放器 │ │ ├── PlaybackControls.tsx # 走带控制条播放、跳转、步进、速度 │ │ ├── RecordingBrowser.tsx # 录制列表元数据 手动路径 │ │ └── index.ts # 统一导出 │ ├── camera-views/ # CameraView、CameraViewsGrid │ ├── camera-config-panel/ # 分辨率、帧率、曝光控制 │ ├── framerate-viewer/ # 实时 FPS D3 图表 │ ├── recording-info-panel/ # 录制路径、开始/停止、设置 │ ├── ui-components/ # Header、Footer、LeftPanel、ThemeToggle │ └── common/ # ErrorBoundary │ ├── services/ │ ├── server/ │ │ ├── ServerContextProvider.tsx # WebSocket 生命周期 │ │ └── server-helpers/ # URL 常量、WebSocket 管理、画布渲染、二进制帧解析 │ └── electron-ipc/ # Electron 主进程 ↔ 渲染进程 IPC │ ├── store/ │ ├── store.ts # Redux store 配置 │ ├── hooks.ts # useAppDispatch、useAppSelector │ └── slices/ │ ├── cameras/ # 相机状态、检测、配置 │ ├── recording/ # 录制状态、开始/停止 thunk │ ├── videos/ # 视频文件状态、文件夹选择 │ ├── framerate/ # FPS 跟踪数据 │ ├── log-records/ # 服务端日志 │ └── theme/ # 亮/暗模式 │ └── layout/ ├── AppContent.tsx # 顶层应用包装 ├── BaseContentRouter.tsx # React Router 路由 └── BasePanelLayout.tsx # 可拖拽面板布局react-resizable-panels实际仓库中该骨架保持完整播放相关文件位于 freemocap-ui/src/components/playback/包含PlaybackContext.tsx、PlaybackControls.tsx、RecordingBrowser.tsx、RecordingBrowserSection.tsx、SyncedVideoPlayer.tsx、ZoomableVideoTile.tsx、usePlaybackController.ts与index.ts。前后端通信协议UI 与 Python 服务端通过两条通道通信所有端点常量集中在 freemocap-ui/src/constants/server-urls.ts后端实现在 freemocap/api/http/playback/playback_router.py。HTTP REST基础地址默认为http://localhost:53117负责相机控制、录制管理与回放数据。回放相关关键端点端点说明GET /freemocap/playback/recordings列出全部录制会话及元数据大小、帧数、时长、FPSGET /freemocap/playback/{recording_id}/videos列出某录制的视频区分annotated/synchronized两种来源GET /freemocap/playback/{recording_id}/videos/{video_id}流式传输视频文件支持 HTTP Range 请求以便拖动跳转GET /freemocap/playback/{recording_id}/timestamps获取该录制所有视频的帧时间戳GET /freemocap/playback/{recording_id}/videos/{video_id}/timestamps获取单个视频的时间戳 CSV 信息GET /freemocap/playback/{recording_id}/status录制的健康/就绪状态Blender 输入、blend 文件、标注视频GET /freemocap/playback/{recording_id}/bundle一次调用返回视频、时间戳、标定、tracker schema 与状态摘要后端细节值得注意视频目录解析遵循synchronized_videos/优先、录制根目录兜底的策略_find_video_folder视频来源校验通过VideoGroupHelper检查所有视频是否可读且帧数一致_validate_video_source帧数/时长/FPS 优先从时间戳 CSV 计算无 CSV 时才回退到 OpenCVcv2.VideoCapture读取元数据_get_recording_stats其中use_cv2_fallbackFalse供列表接口避免逐个打开视频文件视频流返回FileResponse并针对.mp4 / .webm / .avi / .mov / .mkv设置对应Content-Type配合 Starlette 的 Range 支持实现浏览器原生拖动跳转recording_parent_directory查询参数可覆盖默认录制根目录且后端对路径穿越做了防护_resolve_recording_path。前端发起加载录制时RecordingBrowser.loadRecording会先调用playbackVideos获取视频列表把sources中preferred_source对应的视频流 URL拼接 HTTP base交给播放器若全部视频播放失败如编码不支持PlaybackPage.tsx 会自动回退到另一个可用且有效的视频来源。WebSocket实时二进制帧流地址为ws://localhost:53117/freemocap/websocket/connect常量WS_PATH /websocket/connect。每次帧事件会携带多帧载荷——每台相机一张 JPEG——外加 JSON 格式的日志消息。前端侧对应server-helpers/websocket-connection.ts与frame-processor二进制帧解析以及 freemocap/api/websocket/binary_keypoints_protocol.py二进制协议定义另有对应测试 freemocap/tests/test_binary_keypoints_protocol.py。同步回放架构深度解析README 概括了SyncedVideoPlayer保证所有相机视图逐帧精确同步的五个关键机制结合 freemocap-ui/src/components/playback/usePlaybackController.ts 的源码可以将每条机制落到具体实现1. 原生播放硬件解码所有video元素通过HTMLVideoElement.play()播放见 ZoomableVideoTile.tsx 中的video src{streamUrl} preloadauto muted playsInline利用浏览器硬件解码保证画面流畅。usePlaybackController的playAllVideos会给每个元素统一设置playbackRate后逐个play()。2. 权威计数器rAF 循环一个requestAnimationFrame循环tick以领导者视频leaderIdRef取videos[0]的currentTime为基准按公式newFrame leaderTime × fps计算当前帧。fps默认 30可在录制加载时用实际recordingFps覆盖fpsRef。所有叠加层显示的帧号都来自这个计数器而非各个视频元素自身——这就是单一事实来源。3. 漂移校正每个FOLLOWER_CHECK_INTERVAL 15个 rAF tick 执行一次检查跟随视频与领导者视频的currentTime差超过FOLLOWER_DRIFT_TOLERANCE_FRAMES 2帧即toleranceSec 2 / fps时强制把跟随视频currentTime拉回领导者的值同时校正各元素的playbackRate防止变速播放下速率漂移。这就是 README 中每约 3 个 tick结合 15 帧间隔与常规帧率理解漂移检测语义的源码对应物。4. 单一事实来源帧号叠加层frameOverlayRefs与时间叠加层timeOverlayRefs的文本由updateOverlays直接以 DOM 方式批量更新React 状态setCurrentFrame被刻意节流到约 200ms 一次REACT_UPDATE_INTERVAL_MS仅用于驱动控制条/滑块避免高频 setState 拖慢播放循环。时间显示支持timecodeSMPTEHH:MM:SS:FF与seconds两种格式有真实时间戳 CSV 时使用录制真实时间否则以~前缀标明是估算值。5. 暂停/步进直接设置 currentTime暂停pauseAllVideos后所有元素调用el.pause()步进与跳转走seekAllToFrame(frame)对所有视频元素直接赋值el.currentTime frame / fps全程不涉及play()保证暂停状态下多相机画面依然逐帧对齐。拖拽进度条时先暂停并记录播放状态提交后再恢复播放handleSeekDrag/handleSeekCommit。补充循环播放与视频源回退tick循环还处理了循环模式L键切换到达末尾时全部重置到 0 并重新播放。此外PlaybackPage监控erroredVideos若当前来源的所有视频均播放失败会自动切换到另一个available valid的来源如从annotated切到synchronized并在triedFallbackSourcesRef中记录避免重复尝试。网格布局方面SyncedVideoPlayer.tsx 使用react-grid-layoutnoCompactor、useGridLayout钩子支持手动指定列数、拖拽排序与缩放每个视频磁贴由ZoomableVideoTile渲染内置滚轮缩放平移useZoomTransform与错误遮罩。构建与打包npm run build # 生产构建renderer electron npm run build:unpack # 构建未打包应用用于测试npm run build实际执行tsc vite build electron-builder先做 TypeScript 类型检查再构建 Vite 产物最后调用 electron-builder 产出安装包npm run build:dev额外关闭 macOS 的hardenedRuntime与notarize便于本地开发调试打包配置见 freemocap-ui/electron-builder.json应用元数据、图标、目标平台等Electron 主进程源码位于 freemocap-ui/electron/main/窗口管理、IPC、Python 服务进程拉起与端口发现、依赖管理器、更新器等渲染进程通过preload暴露的window.apifreemocap-ui/electron/preload/index.ts与主进程通信端到端测试基于 Playwrightfreemocap-ui/playwright.config.ts通过npm run e2e运行。关键依赖一览包名用途react/react-domUI 框架mui/material组件库reduxjs/toolkit/react-redux状态管理react-router-dom客户端路由react-resizable-panels可拖拽面板布局react-grid-layout相机网格布局d3帧率图表electron桌面打包与运行时vite构建工具与开发服务器three/react-three/fiber3D 骨架可视化视口react-i18next国际化40 语言包位于 freemocap-ui/src/i18n/locales/延伸阅读后端回放接口完整实现freemocap/api/http/playback/playback_router.py服务端端口发现机制freemocap/api/server_constants.py前端播放控制器同步核心freemocap-ui/src/components/playback/usePlaybackController.ts录制目录结构定义freemocap/system/recording_structure/recording_structure.py架构文档freemocap-docs/docs/architecture/frontend-backend-communication.mdx、freemocap-docs/docs/architecture/backend-websocket-server.mdx小结FreeMoCap UI 采用前端壳 Python 服务端的经典架构前端用 React 19 构建交互界面通过 HTTP 管理录制元数据、通过 WebSocket 消费实时帧流回放模块则以原生播放 领导者视频 rAF 权威计数 周期性漂移校正的混合方案在流畅渲染与逐帧硬同步之间取得平衡——这套同步思路对任何多机位视频回放应用都具有直接借鉴价值。【免费下载链接】freemocapFree Motion Capture for Everyone ✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FreeMoCap UI 桌面端全解析：React/Electron 架构与多相机同步回放实战指南
FreeMoCap UI 桌面端全解析React/Electron 架构与多相机同步回放实战指南【免费下载链接】freemocapFree Motion Capture for Everyone ✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocapFreeMoCap UI 是 FreeMoCap 项目的桌面图形界面承担实时多相机流、录制与同步回放三大核心职责以React 19 TypeScript Material UI Redux Toolkit构建并通过Electron打包为跨平台桌面应用。本文以 freemocap-ui/README.md 为主线结合仓库内的源码与配置带你完整掌握其启动流程、页面功能、前后端通信协议以及逐帧锁定同步回放的核心实现原理。FreeMoCap UI 是什么FreeMoCapFree Motion Capture for Everyone是一个开源的无标记运动捕捉系统。freemocap-ui是其 React/Electron 桌面界面核心能力包括实时多相机流同时预览多路摄像头画面支持分辨率、帧率、曝光、旋转等参数配置录制一键开始/停止录制并将相机画面与时间戳写入本地磁盘同步回放浏览历史录制会话以逐帧精确同步的方式多相机回放。技术栈方面README 明确标注为React 19、TypeScript、Material UI、Redux Toolkit桌面打包基于Electron与 electron-vite。实际依赖声明可在 freemocap-ui/package.json 中确认react/react-dom为^19.1.0reduxjs/toolkit为^2.5.1electron为^35.0.3vite为^7.3.1。UI 本身只是一个壳真正的业务逻辑相机采集、标定、姿态估计运行在配套的 Python 后端服务中UI 通过 HTTP REST 与 WebSocket 两条通道与后端通信。快速启动环境准备仓库根目录是一个 monorepo 风格的组织freemocap/Python 后端、freemocap-ui/前端桌面应用、freemocap-docs/文档站。启动 UI 需要两个进程同时运行。第一步启动 Python 服务端# 在仓库根目录执行 python -m freemocap该命令启动 FastAPI 服务默认监听localhost:53117。端口并非写死的常量而是由 freemocap/api/server_constants.py 中的PREFERRED_PORT 53117指定起始端口配合MAX_PORT_ATTEMPTS 50向上逐个尝试直到找到可用端口Electron 主进程通过解析标准输出中的FREEMOCAP_PORTport哨兵行format_port_sentinel来发现实际端口。第二步启动前端 UIcd freemocap-ui npm install npm run dev # Vite dev server Electronnpm run dev实际执行的是cross-env NODE_ENVdevelopment vite见 freemocap-ui/package.json由vite-plugin-electron在启动 Vite 开发服务器的同时拉起 Electron 窗口。启动后 UI 默认认为 Python 服务运行在localhost:53117。若端口被占用导致实际端口偏移freemocap-ui/src/constants/server-urls.ts 中维护的ServerUrls单例DEFAULT_HOST localhost、DEFAULT_PORT 53117可通过setHost/setPort动态调整所有 API 地址均基于它生成。页面与核心功能应用内部通过 React Router 组织路由见 freemocap-ui/src/layout/content/BaseContentRouter.tsx核心页面如下。Cameras 页面/cameras实时多相机视图通过 WebSocket 接收后端的实时二进制帧流。功能点相机分辨率、帧率、曝光、旋转配置一键开始/停止录制画面以响应式网格展示支持拖拽排序与缩放。对应源码位于 freemocap-ui/src/components/camera-views/、freemocap-ui/src/components/control-panels/camera-config-panel/ 与 freemocap-ui/src/components/framerate-viewer/D3 实时 FPS 图表。Playback 页面/playback浏览并回放已录制的会话是本文档的核心章节包含两大组件Recording Browser与Synced Video Player。Recording Browser录制浏览器默认列出~/freemocap_data/recordings/下的全部录制会话目录实际位置由 Python 端get_default_freemocap_recordings_path()决定见 freemocap/system/default_paths.py按最新优先排序。每条记录展示相机流数量N cams磁盘占用总大小自动格式化为 KB/MB/GB录制时长与帧数从时间戳 CSV 读取有效 FPS相对时间如 2h ago、3d ago。从源码 freemocap-ui/src/components/playback/RecordingBrowser.tsx 可以看到它还支持文本过滤按名称模糊匹配多字段排序date / name / size / cameras / frames / duration六个字段升降序可切换手动加载任意目录在 Electron 环境下可通过系统目录选择器挑选任意文件夹加载录制行内状态徽章显示管线阶段完成情况x/y stages全部完成则显示 Blender ready、Legacy 旧版目录布局标记展开详情点击箭头展开RecordingStatusPanel展示该录制详细的管线状态标定、Blender 导出等Import Videos在桌面端通过 Electron IPC 导入视频。元数据来自后端GET /freemocap/playback/recordings接口返回的RecordingListEntry字段如video_count、total_size_bytes、total_frames、duration_seconds、fps、status_summary、layout_validation。Synced Video Player同步视频播放器将选中录制的所有相机流打开为响应式网格核心特性逐帧锁定同步所有相机在任意时刻都显示完全相同的帧号由单一权威计数器驱动逐相机叠加信息帧号右上角、绿色、相机 ID/文件名左下角、SMPTE 时间码右下角原生流畅播放基于HTMLVideoElement.play()硬件解码渲染配合 rAF 漂移校正循环维持同步逐帧步进←/→步进 1 帧Shift←/→步进 10 帧变速播放0.1× 至 8×任何速率下保持帧锁定快捷键Space播放/暂停、Home跳至开头、End跳至末尾、L循环。项目目录结构README 给出的顶层结构如下目录细节以当前仓库为准src/ ├── pages/ │ ├── CamerasPage.tsx # 实时相机视图 │ ├── PlaybackPage.tsx # 录制浏览器 → 同步播放器 │ └── WelcomePage.tsx # 首页/落地页 │ ├── components/ │ ├── playback/ │ │ ├── SyncedVideoPlayer.tsx # 核心逐帧锁定多视频播放器 │ │ ├── PlaybackControls.tsx # 走带控制条播放、跳转、步进、速度 │ │ ├── RecordingBrowser.tsx # 录制列表元数据 手动路径 │ │ └── index.ts # 统一导出 │ ├── camera-views/ # CameraView、CameraViewsGrid │ ├── camera-config-panel/ # 分辨率、帧率、曝光控制 │ ├── framerate-viewer/ # 实时 FPS D3 图表 │ ├── recording-info-panel/ # 录制路径、开始/停止、设置 │ ├── ui-components/ # Header、Footer、LeftPanel、ThemeToggle │ └── common/ # ErrorBoundary │ ├── services/ │ ├── server/ │ │ ├── ServerContextProvider.tsx # WebSocket 生命周期 │ │ └── server-helpers/ # URL 常量、WebSocket 管理、画布渲染、二进制帧解析 │ └── electron-ipc/ # Electron 主进程 ↔ 渲染进程 IPC │ ├── store/ │ ├── store.ts # Redux store 配置 │ ├── hooks.ts # useAppDispatch、useAppSelector │ └── slices/ │ ├── cameras/ # 相机状态、检测、配置 │ ├── recording/ # 录制状态、开始/停止 thunk │ ├── videos/ # 视频文件状态、文件夹选择 │ ├── framerate/ # FPS 跟踪数据 │ ├── log-records/ # 服务端日志 │ └── theme/ # 亮/暗模式 │ └── layout/ ├── AppContent.tsx # 顶层应用包装 ├── BaseContentRouter.tsx # React Router 路由 └── BasePanelLayout.tsx # 可拖拽面板布局react-resizable-panels实际仓库中该骨架保持完整播放相关文件位于 freemocap-ui/src/components/playback/包含PlaybackContext.tsx、PlaybackControls.tsx、RecordingBrowser.tsx、RecordingBrowserSection.tsx、SyncedVideoPlayer.tsx、ZoomableVideoTile.tsx、usePlaybackController.ts与index.ts。前后端通信协议UI 与 Python 服务端通过两条通道通信所有端点常量集中在 freemocap-ui/src/constants/server-urls.ts后端实现在 freemocap/api/http/playback/playback_router.py。HTTP REST基础地址默认为http://localhost:53117负责相机控制、录制管理与回放数据。回放相关关键端点端点说明GET /freemocap/playback/recordings列出全部录制会话及元数据大小、帧数、时长、FPSGET /freemocap/playback/{recording_id}/videos列出某录制的视频区分annotated/synchronized两种来源GET /freemocap/playback/{recording_id}/videos/{video_id}流式传输视频文件支持 HTTP Range 请求以便拖动跳转GET /freemocap/playback/{recording_id}/timestamps获取该录制所有视频的帧时间戳GET /freemocap/playback/{recording_id}/videos/{video_id}/timestamps获取单个视频的时间戳 CSV 信息GET /freemocap/playback/{recording_id}/status录制的健康/就绪状态Blender 输入、blend 文件、标注视频GET /freemocap/playback/{recording_id}/bundle一次调用返回视频、时间戳、标定、tracker schema 与状态摘要后端细节值得注意视频目录解析遵循synchronized_videos/优先、录制根目录兜底的策略_find_video_folder视频来源校验通过VideoGroupHelper检查所有视频是否可读且帧数一致_validate_video_source帧数/时长/FPS 优先从时间戳 CSV 计算无 CSV 时才回退到 OpenCVcv2.VideoCapture读取元数据_get_recording_stats其中use_cv2_fallbackFalse供列表接口避免逐个打开视频文件视频流返回FileResponse并针对.mp4 / .webm / .avi / .mov / .mkv设置对应Content-Type配合 Starlette 的 Range 支持实现浏览器原生拖动跳转recording_parent_directory查询参数可覆盖默认录制根目录且后端对路径穿越做了防护_resolve_recording_path。前端发起加载录制时RecordingBrowser.loadRecording会先调用playbackVideos获取视频列表把sources中preferred_source对应的视频流 URL拼接 HTTP base交给播放器若全部视频播放失败如编码不支持PlaybackPage.tsx 会自动回退到另一个可用且有效的视频来源。WebSocket实时二进制帧流地址为ws://localhost:53117/freemocap/websocket/connect常量WS_PATH /websocket/connect。每次帧事件会携带多帧载荷——每台相机一张 JPEG——外加 JSON 格式的日志消息。前端侧对应server-helpers/websocket-connection.ts与frame-processor二进制帧解析以及 freemocap/api/websocket/binary_keypoints_protocol.py二进制协议定义另有对应测试 freemocap/tests/test_binary_keypoints_protocol.py。同步回放架构深度解析README 概括了SyncedVideoPlayer保证所有相机视图逐帧精确同步的五个关键机制结合 freemocap-ui/src/components/playback/usePlaybackController.ts 的源码可以将每条机制落到具体实现1. 原生播放硬件解码所有video元素通过HTMLVideoElement.play()播放见 ZoomableVideoTile.tsx 中的video src{streamUrl} preloadauto muted playsInline利用浏览器硬件解码保证画面流畅。usePlaybackController的playAllVideos会给每个元素统一设置playbackRate后逐个play()。2. 权威计数器rAF 循环一个requestAnimationFrame循环tick以领导者视频leaderIdRef取videos[0]的currentTime为基准按公式newFrame leaderTime × fps计算当前帧。fps默认 30可在录制加载时用实际recordingFps覆盖fpsRef。所有叠加层显示的帧号都来自这个计数器而非各个视频元素自身——这就是单一事实来源。3. 漂移校正每个FOLLOWER_CHECK_INTERVAL 15个 rAF tick 执行一次检查跟随视频与领导者视频的currentTime差超过FOLLOWER_DRIFT_TOLERANCE_FRAMES 2帧即toleranceSec 2 / fps时强制把跟随视频currentTime拉回领导者的值同时校正各元素的playbackRate防止变速播放下速率漂移。这就是 README 中每约 3 个 tick结合 15 帧间隔与常规帧率理解漂移检测语义的源码对应物。4. 单一事实来源帧号叠加层frameOverlayRefs与时间叠加层timeOverlayRefs的文本由updateOverlays直接以 DOM 方式批量更新React 状态setCurrentFrame被刻意节流到约 200ms 一次REACT_UPDATE_INTERVAL_MS仅用于驱动控制条/滑块避免高频 setState 拖慢播放循环。时间显示支持timecodeSMPTEHH:MM:SS:FF与seconds两种格式有真实时间戳 CSV 时使用录制真实时间否则以~前缀标明是估算值。5. 暂停/步进直接设置 currentTime暂停pauseAllVideos后所有元素调用el.pause()步进与跳转走seekAllToFrame(frame)对所有视频元素直接赋值el.currentTime frame / fps全程不涉及play()保证暂停状态下多相机画面依然逐帧对齐。拖拽进度条时先暂停并记录播放状态提交后再恢复播放handleSeekDrag/handleSeekCommit。补充循环播放与视频源回退tick循环还处理了循环模式L键切换到达末尾时全部重置到 0 并重新播放。此外PlaybackPage监控erroredVideos若当前来源的所有视频均播放失败会自动切换到另一个available valid的来源如从annotated切到synchronized并在triedFallbackSourcesRef中记录避免重复尝试。网格布局方面SyncedVideoPlayer.tsx 使用react-grid-layoutnoCompactor、useGridLayout钩子支持手动指定列数、拖拽排序与缩放每个视频磁贴由ZoomableVideoTile渲染内置滚轮缩放平移useZoomTransform与错误遮罩。构建与打包npm run build # 生产构建renderer electron npm run build:unpack # 构建未打包应用用于测试npm run build实际执行tsc vite build electron-builder先做 TypeScript 类型检查再构建 Vite 产物最后调用 electron-builder 产出安装包npm run build:dev额外关闭 macOS 的hardenedRuntime与notarize便于本地开发调试打包配置见 freemocap-ui/electron-builder.json应用元数据、图标、目标平台等Electron 主进程源码位于 freemocap-ui/electron/main/窗口管理、IPC、Python 服务进程拉起与端口发现、依赖管理器、更新器等渲染进程通过preload暴露的window.apifreemocap-ui/electron/preload/index.ts与主进程通信端到端测试基于 Playwrightfreemocap-ui/playwright.config.ts通过npm run e2e运行。关键依赖一览包名用途react/react-domUI 框架mui/material组件库reduxjs/toolkit/react-redux状态管理react-router-dom客户端路由react-resizable-panels可拖拽面板布局react-grid-layout相机网格布局d3帧率图表electron桌面打包与运行时vite构建工具与开发服务器three/react-three/fiber3D 骨架可视化视口react-i18next国际化40 语言包位于 freemocap-ui/src/i18n/locales/延伸阅读后端回放接口完整实现freemocap/api/http/playback/playback_router.py服务端端口发现机制freemocap/api/server_constants.py前端播放控制器同步核心freemocap-ui/src/components/playback/usePlaybackController.ts录制目录结构定义freemocap/system/recording_structure/recording_structure.py架构文档freemocap-docs/docs/architecture/frontend-backend-communication.mdx、freemocap-docs/docs/architecture/backend-websocket-server.mdx小结FreeMoCap UI 采用前端壳 Python 服务端的经典架构前端用 React 19 构建交互界面通过 HTTP 管理录制元数据、通过 WebSocket 消费实时帧流回放模块则以原生播放 领导者视频 rAF 权威计数 周期性漂移校正的混合方案在流畅渲染与逐帧硬同步之间取得平衡——这套同步思路对任何多机位视频回放应用都具有直接借鉴价值。【免费下载链接】freemocapFree Motion Capture for Everyone ✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考