# 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 录制不在当前目标内