第39章:Recipe 三大步骤——创建、铺轨与字幕
第 36 章的总览图里,Recipe 是三个 Step 的有序列表。本章逐一拆解:CreateStep 创建空白草稿、VideosStep 上传切片并铺主视频轨、CaptionsStep 按 ASR 铺同步字幕。三步共享同一个 Step 接口契约与 Session 黑板,各自只做一件事。
流程
三步的进度分工:Prepare 占 0~50,CreateStep 落 70,VideosStep 落 85,CaptionsStep 落 95(Builder 收尾后任务层补满 100)。每步都有前置校验(Session 非空、API 非空、DraftURL 非空),形成"步骤未跑完就被调用"的快速失败。
flowchart TD
A[CreateStep] --> B[API.CreateDraft<br/>画布=Session.CanvasW/H]
B --> C[Session.DraftURL = resp.DraftURL<br/>进度70]
C --> D[VideosStep]
D --> E[逐切片:UploadFile →<br/>temp/draft/jobID/clip_XXX.mp4]
E --> F[Timeline.Advance 拿草稿起点<br/>毫秒×1000转微秒]
F --> G[API.AddVideos 批量铺轨<br/>写 ClipPlacements 进度85]
G --> H[CaptionsStep]
H --> I{EnableCaptions 开启<br/>且有 ASR 分句?}
I -- 否 --> J[跳过 不视为失败<br/>进度95]
I -- 是 --> K[分句断句+重叠裁剪<br/>映射到草稿微秒]
K --> L[API.AddCaptions 批量字幕<br/>进度95]
实现
CreateStep 只做一次远端调用 CreateDraft(canvasW, canvasH, recordDir) 并落 DraftURL。画布尺寸的决策已在任务创建时完成(draft.ResolveCanvasSize),Step 层零决策——"宽度高度在哪儿定"这个问题在整条链路上有且只有一个答案。
VideosStep 的双产物。buildVideoInfos 每段切片做三件事:算对象键、上传拿公网 URL、Timeline.Advance 领取草稿时间轴位置。产出同时是两个列表——VideoInfo(喂给 add_videos,含 URL 与微秒 start/end)与 ClipPlacement(源毫秒区间 ↔ 草稿微秒区间的映射)。AddVideos 是一次批量调用而非逐段调用:N 段切片一条请求,减少对 capcut-mate 的往返。响应的 TrackID/SegmentIDs 写入 Timeline 主轨状态,供未来步骤引用。
对象键 BuildDraftClipObjectKey 用 path.Join 而非 filepath.Join——注释点明"对象键统一使用正斜杠,避免 Windows 路径分隔符污染键名",这是 Go 在 Windows 上写对象存储的高频陷阱,一行选择躲掉一类事故。
CaptionsStep 的多重跳过语义。两种"跳过"都不是失败:项目 EnableCaptionsOff(用户显式关字幕)与 ASR 无分句(素材本无字幕可铺)都直接 ReportProgress(95) 返回。注释的措辞很讲究:"保证无 ASR 场景仍可产出草稿"——字幕是增强产物,不该让它把成片拖死。
字幕对齐算法(BuildCaptionsFromASR)分四层:先按 Placement 外层循环、分句内层循环找重叠;分句经 asr.SplitUtteranceForCaptions 按"标点/字数"预断句(长句切成多屏);子片段与切片区间做重叠裁剪(clamp 到 [SourceStartMS, SourceEndMS]),保证字幕不越出对应视频段;最后换算 DraftStartUS + (overlapStartMS - SourceStartMS) * 1000。纯函数、双层防御(裁剪后再校验 end > start)、可独立测试。
字幕样式的常量族:黄色字黑描边、字号 10、TransformY=-360(画面下方)、字体"得意黑"——注释说明与 capcut-mate 文档示例对齐。样式硬编码而非配置,与"这是产品默认审美"的定位一致。
📌 设计决策
- 一次批量 add_videos:N+1 次 HTTP 变 1 次,降低草稿中途失败的概率面;代价是单段失败需整批重来(但对象键幂等,重传无害)。
- 字幕默认开启但可关:
EnableCaptions开关落在 project 而非请求参数——草稿与一键成片共用同一开关,行为全局一致。 - 跳过不等于失败:把"没有字幕数据"归为正常分支,任务仍走 completed 路径;若当失败处理,无 ASR 素材将永远无法出草稿。
- 断句与裁剪分离:
SplitUtteranceForCaptions管"一屏多少字",重叠裁剪管"不许越界",两个关注点独立演化。
代码示例
片段 1 展示 VideosStep 的上传与时间轴领取(摘自 steps/videos.go,节选):
// buildVideoInfos 将本地切片上传到对象存储,组装 add_videos 所需的 VideoInfo 列表,
// 同时生成源时间轴 ↔ 草稿时间轴的 ClipPlacement,供字幕同步使用。
func buildVideoInfos(ctx context.Context, s *session.Session, uploader ObjectUploader, logger *zap.Logger) ([]capcutmate.VideoInfo, []session.ClipPlacement, error) {
infos := make([]capcutmate.VideoInfo, 0, len(s.ClipPaths))
placements := make([]session.ClipPlacement, 0, len(s.ClipPaths))
for i, localPath := range s.ClipPaths {
objectKey := BuildDraftClipObjectKey(s.JobID, localPath)
videoURL, err := uploader.UploadFile(ctx, localPath, objectKey)
if err != nil {
return nil, nil, fmt.Errorf("上传第 %d 段切片失败: %w", i, err)
}
durMS := s.Clips[i].EndTime - s.Clips[i].StartTime
if durMS <= 0 {
return nil, nil, fmt.Errorf("第 %d 段时长无效", i)
}
durUS := durMS * 1000 // 毫秒 → 微秒
startUS := s.Timeline.Advance(durUS)
endUS := startUS + durUS
infos = append(infos, capcutmate.VideoInfo{
VideoURL: videoURL, Start: startUS, End: endUS, Volume: 1,
})
placements = append(placements, session.ClipPlacement{
SourceStartMS: s.Clips[i].StartTime, SourceEndMS: s.Clips[i].EndTime,
DraftStartUS: startUS, DraftEndUS: endUS,
})
}
return infos, placements, nil
}
// BuildDraftClipObjectKey 生成草稿切片对象键:temp/draft/{jobID}/{文件名}。
// 对象键统一使用正斜杠,避免 Windows 路径分隔符污染键名。
func BuildDraftClipObjectKey(jobID, localPath string) string {
name := filepath.Base(localPath)
id := strings.TrimSpace(jobID)
if id == "" {
id = "unknown"
}
return path.Join(storage.SubDirTemp, "draft", id, name)
}
片段 2 展示字幕的重叠裁剪与坐标换算(摘自 steps/captions.go,节选):
// BuildCaptionsFromASR 将 live_asr JSON 分句映射到草稿字幕时间轴。
// 长句会先按标点/字数断句并切分时间,再与切片重叠裁剪,避免字幕越出对应视频段。
func BuildCaptionsFromASR(liveASRJSON string, placements []session.ClipPlacement) []capcutmate.CaptionItem {
utterances := asr.FormatUtterancesForAPI(liveASRJSON)
if len(utterances) == 0 || len(placements) == 0 {
return nil
}
out := make([]capcutmate.CaptionItem, 0)
for _, p := range placements {
for _, u := range utterances {
if u.EndTime <= p.SourceStartMS || u.StartTime >= p.SourceEndMS {
continue // 分句与切片无重叠则跳过
}
for _, seg := range asr.SplitUtteranceForCaptions(u) {
if seg.EndTime <= p.SourceStartMS || seg.StartTime >= p.SourceEndMS {
continue
}
// 重叠裁剪:clamp 到切片源区间
overlapStartMS := seg.StartTime
if overlapStartMS < p.SourceStartMS {
overlapStartMS = p.SourceStartMS
}
overlapEndMS := seg.EndTime
if overlapEndMS > p.SourceEndMS {
overlapEndMS = p.SourceEndMS
}
if overlapEndMS <= overlapStartMS {
continue
}
draftStartUS := p.DraftStartUS + (overlapStartMS-p.SourceStartMS)*1000
draftEndUS := p.DraftStartUS + (overlapEndMS-p.SourceStartMS)*1000
if draftEndUS > p.DraftEndUS {
draftEndUS = p.DraftEndUS
}
if draftEndUS <= draftStartUS {
continue
}
out = append(out, capcutmate.CaptionItem{
Start: draftStartUS, End: draftEndUS, Text: strings.TrimSpace(seg.Text)})
}
}
}
return out
}
小结
三步各持 API 与 Logger、共写一个 Session:Create 定锚点、Videos 铺画面并留下映射坐标、Captions 沿映射补文本。批量调用、跳过语义、重叠裁剪三处细节决定了这条流水线的健壮性下限。
思考题
- VideosStep 上传一半失败时,已上传的对象残留在
temp/draft/{jobID}/——结合第 35 章的清理机制,这些对象级残留该由谁负责回收?对象存储没有 mtime 排序清理的便利,你会设计什么生命周期规则? - 字幕样式(字号/颜色/字体)硬编码常量若要开放给用户自定义,改动会波及哪些层(model、API、Step、前端)?值得吗?
项目信息
- GitHub仓库:Chyona/live-mixer