tennis-training-hub/docs/media-architecture.md

Media Architecture

Responsibilities

Node 应用负责：

• 用户登录
• 训练计划与分析业务
• 视频库元数据写入
• 开发时 /media 同源代理

Go 媒体服务负责：

• 创建录制会话
• WebRTC 信令交换
• 接收分段上传
• 写入关键片段标记
• 会话 finalize
• 归档与回放资源生成

HTTP API

• POST /media/sessions
• POST /media/sessions/{id}/signal
• POST /media/sessions/{id}/segments?sequence={n}&durationMs={ms}
• POST /media/sessions/{id}/markers
• POST /media/sessions/{id}/finalize
• GET /media/sessions/{id}
• GET /media/sessions/{id}/playback
• GET /media/health

Session lifecycle

• created: 会话已建立，等待录制
• recording: 正在录制或接收分段
• streaming: WebRTC 连接已建立
• reconnecting: 摄像头或连接中断，客户端正在恢复
• finalizing: 会话完成，等待 worker 归档
• archived: 回放已生成
• failed: 上传、信令或归档失败

Storage model

每个会话目录包含：

• session.json: 会话状态和 marker 元数据
• segments/: 原始分段
• concat.txt: FFmpeg 拼接清单
• public/sessions/<id>/recording.webm
• public/sessions/<id>/recording.mp4

Archive flow

1. 浏览器 finalize
2. 会话状态变为 ArchiveQueued
3. worker 读取全部分段
4. 优先直接 concat，失败则重新编码为 WebM
5. 可用时生成 MP4 归档
6. 写回 playback URL 和文件大小

Constraints

• 当前为单机本地卷模型，不依赖对象存储
• 当前 WebRTC 仅用于浏览器到服务端的实时上行，不做多观众直播分发
• Safari 原生 MP4 录制不在当前目标内