第38章:草稿会话与时间线
draft/session 是一个只有两个文件、不足百行的"叶子包",却是整个草稿流水线的中枢神经。包注释道出存在理由:"作为叶子包供 draft / prepare / steps 引用,避免循环依赖"。本章解析 Session 共享上下文与 Timeline 时间轴抽象。
流程
Session 的字段随流水线阶段逐步被填充:Builder 构造基础字段 → Prepare 写入 SourcePath/ClipPaths → VideosStep 写入 ClipPlacements(源时间轴到草稿时间轴的映射)与视频轨道 → CaptionsStep 读取 ClipPlacements 完成字幕对齐 → 最终写入 DraftURL。
flowchart LR
subgraph Session[Session 共享黑板]
A[JobID/Project/Material<br/>Builder 初始化] --> B[SourcePath/ClipPaths<br/>Prepare 写入]
B --> C[ClipPlacements<br/>VideosStep 写入]
C --> D[Timeline.Tracks<br/>各 Step 追加]
D --> E[DraftURL<br/>CreateStep 写入]
end
F[VideosStep] -->|铺轨时 Advance| G[Timeline.CursorUS 游标前移]
C -. 映射依据 .-> H[CaptionsStep<br/>ASR 毫秒 → 草稿微秒]
z
ClipPlacement 是字幕同步的钥匙。ASR 分句的时间戳在源视频时间轴上(毫秒),而 add_videos 把切片依次首尾相接铺到草稿主轨(微秒)——两个坐标系完全不同。VideosStep 铺完每段切片后记录一条 Placement:SourceStartMS/EndMS(来自 Session.Clips)与 DraftStartUS/EndUS(来自 Timeline.Advance 返回值)。CaptionsStep 对每条 ASR 分句,先找到其源时间落入的 Placement,再按线性偏移换算草稿位置——(asrMS - SourceStartMS) * 1000 + DraftStartUS。这个四字段结构体,就是两个时间轴之间的全部翻译协议。
Timeline 的极简游标模型。主视频轨"顺序拼接"的语义被压缩成一个 Advance(durationUS) (startUS) 方法:返回推进前的游标并前移。任何"我要在主轨末尾追加 X 微秒"的步骤,都先 Advance 拿起点。TrackState 用 map 按名字索引,七个轨道名常量(main_video/subtitle/tts/bgm/pip/sticker/effect)构成命名约定——注释明说这是"便于后续轨道对齐"的前瞻设计,当前只用到前两个。
防御性 nil 处理。ReportProgress 与 Timeline 的所有方法都带 s/t == nil 守卫——Progress 回调本身是可选的,Session 在单测中可以不设 Progress 直接跑;Timeline 的 nil 方法返回零值不 panic。这让测试构造 Session 时不必初始化每个字段。
包的位置学。session 不 import draft/prepare/steps 中任何一个,只依赖 model——正因为它是依赖图的叶子,谁都能引用它而不会成环。这是 Go 项目破解循环依赖的经典手法:把共享类型下沉到独立小包。
📌 设计决策
- 黑板模式而非管道传参:步骤间数据依赖通过 Session 字段隐式传递,新增步骤不需要修改函数签名链;代价是依赖关系藏在字段注释里(
ClipPlacements 由 VideosStep 写入),编译器不检查读写顺序。 - 毫秒/微秒双单位显式标注:
MS/US后缀强制每个字段的单位可读,杜绝"这个数到底是毫秒还是微秒"这类经典事故;换算只发生在 Placement 消费点。 - 游标只前进:Timeline 不支持插入、回退、重叠检测——草稿的当前需求是纯顺序拼接,保持最小功能面。
- 轨道常量前瞻但不过度:预留 tts/bgm/pip 等名字但无对应逻辑,扩展时改 Step 不改基础设施。
代码示例
片段 1 展示 Session 与 Placement 契约(摘自 session/session.go,完整核心):
// ClipPlacement 描述一段 add_videos 切片在源素材与草稿时间轴上的对应关系。
// 字幕步骤据此把 ASR(源时间轴,毫秒)映射到草稿轨道(微秒),保证与视频切片同步。
type ClipPlacement struct {
// SourceStartMS / SourceEndMS 源视频时间范围(毫秒),与 Session.Clips 一致。
SourceStartMS int64
SourceEndMS int64
// DraftStartUS / DraftEndUS 草稿主时间轴位置(微秒),与 add_videos 的 start/end 一致。
DraftStartUS int64
DraftEndUS int64
}
// Session 贯穿 Prepare 与各 Step 的可变上下文。
type Session struct {
JobID string // 仅用于日志与目录命名,不绑定任务模型
Project *model.VideoProject
Material *model.LiveMaterial
StagingDir string
RecordDir string
SourcePath string
ClipPaths []string
Clips []model.ClipRange
// ClipPlacements 由 VideosStep 写入:每段切片在源时间轴与草稿时间轴的映射。
ClipPlacements []ClipPlacement
DraftURL string
CanvasW int
CanvasH int
Timeline *Timeline
// Progress 可选:报告本地进度(0-100),由调用方映射。
Progress func(local int16)
}
// ReportProgress 安全调用进度回调。
func (s *Session) ReportProgress(local int16) {
if s != nil && s.Progress != nil {
s.Progress(local)
}
}
片段 2 展示时间轴游标与轨道(摘自 session/timeline.go,完整核心):
// Track 名称约定,便于后续字幕/音频/PIP 等轨道对齐。
const (
TrackMainVideo = "main_video"
TrackSubtitle = "subtitle"
TrackTTS = "tts"
TrackBGM = "bgm"
TrackPIP = "pip"
TrackSticker = "sticker"
TrackEffect = "effect"
)
// Timeline 草稿时间轴状态(微秒)。
type Timeline struct {
CursorUS int64
Tracks map[string]*TrackState
}
// Advance 将游标前移 durationUS 微秒,返回推进前的起点。
func (t *Timeline) Advance(durationUS int64) (startUS int64) {
if t == nil {
return 0
}
startUS = t.CursorUS
t.CursorUS += durationUS
return startUS
}
// EnsureTrack 返回命名轨道,不存在则创建。
func (t *Timeline) EnsureTrack(name string) *TrackState {
if t == nil {
return nil
}
if t.Tracks == nil {
t.Tracks = make(map[string]*TrackState)
}
if tr, ok := t.Tracks[name]; ok {
return tr
}
tr := &TrackState{
Name: name}
t.Tracks[name] = tr
return tr
}
小结
session 包证明了"中枢不等于复杂":一个结构体、一张时间轴、一个四字段映射结构,撑起了三步流水线的全部状态传递。下沉为叶子包的决策同时解决了循环依赖与测试构造两个问题。
思考题
- 若引入 BGMStep 想在成片开头铺 3 秒片头,主视频轨需要整体后移 3 秒——只支持前进的 CursorUS 模型还能胜任吗?你会改为"先收集、后计算偏移"的两阶段方案吗?
- 黑板模式下,若 CaptionsStep 被误放到 VideosStep 之前执行,
ClipPlacements为空导致字幕全部落在 0 位置——如何在 Recipe 层面静态保证步骤顺序(初始化函数签名、依赖声明、还是测试断言)?
项目信息
- GitHub仓库:Chyona/live-mixer