tennis-training-hub/docs/frontend-recording.md

Frontend Recording Flow

UX goals

• Chrome 优先的低流量录制
• 录制和实时推流并行
• 断线后尽量自动恢复
• 移动端可直接使用

Browser pipeline

1. 用户启动摄像头预览
2. 点击开始录制时创建媒体会话
3. 复用已有预览流，避免重复申请摄像头
4. 同一条 MediaStream 同时接入：
   • MediaRecorder
   • RTCPeerConnection
5. 每 60 秒主动 requestData() 形成一个上传分段
6. 画面抽样比较生成自动 marker
7. 结束录制后 flush 队列并调用 finalize
8. 轮询归档状态，完成后把结果注册进视频库

Mobile adaptation

• 使用安全区样式 env(safe-area-inset-*)
• 底部固定导航
• 最小点击区域 44px
• 横屏时保留尽量大的预览画面
• 录制页容器使用 overscroll-behavior-y: contain，避免下拉刷新干扰

Reconnect behavior

• 摄像头 track 结束时触发重连
• 主动停止摄像头时使用 suppression 标志，避免误判为故障
• 重连过程：
  • 停止 recorder
  • 保留已上传和待上传分段
  • 重新获取摄像头
  • 重建 WebRTC 连接
  • 恢复 recorder

Video library sync

归档完成后前端调用 video.registerExternal，把回放资源登记到现有视频库中，避免重写整个视频管理模块。