【直播切片工作台】第39章:Recipe 三大步骤创建铺轨与字幕

简介: 本章详解Recipe自动化视频生成的三大核心步骤:CreateStep创建草稿、VideosStep批量上传并精准铺轨、CaptionsStep基于ASR智能对齐字幕。三步解耦、共享Session,强调批量调用、安全跳过与重叠裁剪,保障流程健壮高效。(239字)

第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 沿映射补文本。批量调用、跳过语义、重叠裁剪三处细节决定了这条流水线的健壮性下限。

思考题

  1. VideosStep 上传一半失败时,已上传的对象残留在 temp/draft/{jobID}/——结合第 35 章的清理机制,这些对象级残留该由谁负责回收?对象存储没有 mtime 排序清理的便利,你会设计什么生命周期规则?
  2. 字幕样式(字号/颜色/字体)硬编码常量若要开放给用户自定义,改动会波及哪些层(model、API、Step、前端)?值得吗?

项目信息

  • GitHub仓库:Chyona/live-mixer
相关文章
|
6天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
7991 19
|
6天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2528 12
|
1天前
|
人工智能 安全 应用服务中间件
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
NGINX曝出两个高危漏洞(CVE-2026-123633和CVE-2026-123007),CVSS 9.2分,均属HTTP/2内存安全缺陷,无需认证即可远程执行代码。影响自2015年起的多个版本,静态站点亦受威胁。修复版本为开源版1.30.7/1.31.9。(239字)
1235 0
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
|
4天前
|
传感器 安全 区块链
Windows 电脑运行安卓应用教程:开源工具 ApkStart 双击 APK 即装、独立窗口运行
ApkStart 是一款开源Windows工具,让安卓APP像原生软件一样运行:双击APK即安装、生成真实图标、独立窗口启动、开始菜单可搜索。无需传统模拟器,内置QEMU运行时,支持数据互通、ARM兼容与命令行操作。(239字)
|
9天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
9天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
22天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
10648 59
|
5天前
|
人工智能 弹性计算 开发工具
零成本玩各大模型!DeepSeek Harness dsh-our-free-model 插件,13 个厂商模型直接用
总结一下:装这个插件,你不用注册、不用绑卡、不用填一个 Key,就能在 DeepSeek Harness 里用上 DeepSeek V4.1 Flash、Kimi K3 这一批前沿模型,而且是白嫖的、还不限量。三步搞定:下载插件,复制包含 `package.json` 的插件目录路径,在「添加插件」里粘贴路径安装并重启。无论是在阿里云 ECS 上通过命令行部署的 Web 版,还是本地的 Electron 桌面端,都能顺利跑通,快速搭建一套零成本的免费模型使用环境。
1156 1
|
8天前
|
Linux API iOS开发
【DSH】DeepSeek Harness新手保姆教程(下载+安装+配置+使用,2026最新实测)
DeepSeek Harness(dsh)是DeepSeek AI开源的智能体框架,秉持“一切皆插件”理念,支持读文件、改代码、跑命令、处理表格、联网搜索等操作。免费开源,兼容Windows/macOS/Linux,提供桌面端与网页端,可灵活安装插件扩展能力。

热门文章

最新文章