跳到正文
阿里雲開發者社區 AI·· 8 天前AI 評分38

剪映草稿流水線總覽:第36章

【直播切片工作台】第36章:剪映草稿流水线总览

AI 導讀

第36章梳理剪映草稿生成流水線,由 Request/Result、Pipeline、Recipe/Steps 和 Session 四個角色協作,將 clips 組裝成剪映草稿。流程包括準備素材、依序執行建立草稿、上傳切片及鋪設字幕三個步驟,再驗證並返回 draft_url;切片 tar 打包或上傳失敗不會阻斷草稿結果。

正文

2026-11-14 5

版权

版权声明:

本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写 侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

简介: 本章详解剪映草稿生成流水线设计:以`Request/Result`解耦入参、`Pipeline`准备素材、`Recipe/Steps`有序组装、`Session`共享状态,实现高内聚、可测试、易扩展的AI视频成片工程化架构。(239字)

第36章:剪映草稿流水线总览

从本章起进入成片阶段。internal/draft 包把"从 clips 到剪映草稿"的完整过程组织为四个协作角色:Request/Result(与任务模型解耦的入参出参)、Pipeline(素材准备)、Recipe/Steps(有序组装步骤)、Session(贯穿全程的可变状态)。本章先建立全局图景,后三章分别深入。

流程

Builder.Build 是流水线的总指挥:解析 clips(入参直给或从 project 的 clips1/clips0 反推)→ 500ms 合并相邻片段 → 校验 → 构造 Session → Prepare 下载裁剪 → 按顺序执行 Recipe 的三个 Step → 校验 draft_url → 打包上传切片 tar。

flowchart TD
    A[Request<br/>JobID/Material/Project/Clips] --> B[Build]
    B --> C{Clips 为空?}
    C -- 是 --> D[ResolveClipRanges<br/>从 clips1/clips0 解析]
    C -- 否 --> E[直接使用]
    D & E --> F[MergeAdjacentClipRanges<br/>间隙≤500ms 合并]
    F --> G[ValidateClipRanges]
    G --> H[构造 Session<br/>含 NewTimeline 空时间线]
    H --> I[Prepare.Run<br/>下载源视频+ffmpeg 裁剪]
    I --> J[Step1 CreateStep<br/>创建剪映草稿]
    J --> K[Step2 VideosStep<br/>上传切片+铺视频轨]
    K --> L[Step3 CaptionsStep<br/>按 ASR 铺字幕]
    L --> M{draft_url 非空?}
    M -- 是 --> N[PackAndUploadClipsTar<br/>失败不阻断]
    N --> O[Result: DraftURL + ClipsTarURL]
    M -- 空 --> P[报错]

实现

分层解耦是这个包最大的特点。Request 的注释明确"与任务模型无关"——JobID 只用于日志与目录命名,不强制是 task id;Progress 是一个 func(local int16) 回调,任务层负责把 0~100 的本地进度映射到全局 task.progress(独立任务直接透传,一键成片按阶段区间缩放)。Generator 接口因此可以被任何调用方使用:独立 draft Worker、一键成片 Worker、甚至未来的手动重放工具。

Recipe 的编译期安全:DefaultRecipe 返回三步——CreateStep → VideosStep → CaptionsStep,每步自持依赖(API client、Uploader、Logger),Recipe.Steps 为空时回落默认。Builder 尾部的 var _ steps.Step = steps.CreateStep{} 是接口实现断言,把"某步忘了实现 Step 接口"从运行期错误提前到编译期。

收尾的降级语义:PackAndUploadClipsTar 失败只记 Error 日志、ClipsTarURL 留空——草稿本体已成功,附带产物(供用户单独下载切片的 tar 包)不应拖垮主结果。而 s.DraftURL == "" 则是硬失败:三步全跑完却没产出 URL,说明步骤实现有 bug,宁可报错也不返回空壳成功。

NewGenerator 的依赖兜底链:Cutter 缺省回落 media.NewFFmpegConverter(""),Downloader 缺省走工厂函数——组合根可以全量注入,单测可以只注入关心的部分,其余落默认。

📌 设计决策

  • 准备与组装两段式:Prepare 产出本地文件(ClipPaths),Steps 消费本地文件并调用远端 API。文件系统是两段之间的"接口",让 ffmpeg 重活与 HTTP 调活可独立测试与重试。
  • Session 作为共享黑板:所有 Step 读写同一个 Session(草稿 ID、时间线、clip 路径),避免步骤间参数传递链条爆炸;代价是步骤执行顺序隐含数据依赖,必须由 Recipe 保证。
  • tar 包失败不阻断:附带产物与主产物的失败域隔离;用户仍能打开草稿,tar 可后续手动补。
  • Progress 回调而非进度对象:函数类型比接口更轻,任务层闭包捕获 task ID 即可,draft 包对"进度写到哪"零知识。

代码示例

片段 1 展示流水线总指挥(摘自 draft/builder.go,节选):

// Build 解析 clips → Prepare → 按 Recipe 执行 Steps,返回 draft_url。
func (b *Builder) Build(ctx context.Context, req Request) (*Result, error) {
   
    clips := req.Clips
    if len(clips) == 0 {
   
        if req.Project == nil {
   
            return nil, fmt.Errorf("clips 为空且未提供 project")
        }
        var err error
        clips, err = prepare.ResolveClipRanges(req.Project)
        if err != nil {
   
            return nil, err
        }
    }
    beforeMerge := len(clips)
    clips = prepare.MergeAdjacentClipRanges(clips, prepare.ClipMergeGapMS)
    b.Logger.Info("草稿裁剪前合并相邻片段",
        zap.String("job_id", req.JobID),
        zap.Int("clips_before", beforeMerge),
        zap.Int("clips_after", len(clips)),
    )
    if err := prepare.ValidateClipRanges(clips); err != nil {
   
        return nil, err
    }

    recipe := req.Recipe
    if len(recipe.Steps) == 0 {
   
        recipe = DefaultRecipe(b.API, b.Uploader, b.Logger)
    }

    s := &session.Session{
   
        JobID: req.JobID, Project: req.Project, Material: req.Material,
        StagingDir: req.StagingDir, RecordDir: req.RecordDir,
        Clips: clips, CanvasW: req.CanvasW, CanvasH: req.CanvasH,
        Timeline: session.NewTimeline(), Progress: req.Progress,
    }

    if err := b.Prepare.Run(ctx, s); err != nil {
   
        return nil, err
    }
    for _, step := range recipe.Steps {
   
        if err := step.Run(ctx, s); err != nil {
   
            return nil, fmt.Errorf("步骤 %s 失败: %w", step.Name(), err)
        }
    }
    if s.DraftURL == "" {
   
        return nil, fmt.Errorf("草稿组装完成但 draft_url 为空")
    }

    result := &Result{
   DraftURL: s.DraftURL}
    // 将本地 clip_XXX.mp4 打成 {jobID}.tar 并上传;失败仅记日志,不阻断草稿成功。
    clipsTarURL, err := PackAndUploadClipsTar(ctx, b.Uploader, s.StagingDir, s.JobID, s.ClipPaths)
    if err != nil {
   
        b.Logger.Error("切片 tar 打包上传失败", zap.String("job_id", s.JobID), zap.Error(err))
    } else {
   
        result.ClipsTarURL = clipsTarURL
    }
    return result, nil
}

片段 2 展示契约类型与默认 Recipe(摘自 draft/request.go 与 draft/recipe.go):

// Request 剪映草稿组装入参(与任务模型无关)。
type Request struct {
   
    JobID    string // 仅用于日志/目录命名,不强制是 task id
    Material *model.LiveMaterial
    Project  *model.VideoProject
    // Clips 为空时,若 Project 非空则从 clips1/clips0 解析并合并相邻片段。
    Clips            []model.ClipRange
    CanvasW, CanvasH int
    StagingDir       string
    RecordDir        string
    // Progress 可选:本地进度 0–100;由任务层映射到 task.progress。
    Progress func(local int16)
    // Recipe 为空时使用 DefaultRecipe。
    Recipe Recipe
}

// Recipe 有序组装步骤列表。
type Recipe struct {
   
    Steps []steps.Step
}

// DefaultRecipe 默认流水线:创建草稿 → 上传切片并添加主视频轨 → 按 ASR 添加同步字幕。
func DefaultRecipe(api CapCutMateAPI, uploader steps.ObjectUploader, logger *zap.Logger) Recipe {
   
    return Recipe{
   
        Steps: []steps.Step{
   
            steps.CreateStep{
   API: api, Logger: logger},
            steps.VideosStep{
   API: api, Uploader: uploader, Logger: logger},
            steps.CaptionsStep{
   API: api, Logger: logger},
        },
    }
}

小结

draft 包用"入参出参解耦 + 两段式流水 + 有序步骤 + 共享 Session"四件套,把一段混杂 ffmpeg、对象存储、远端 HTTP 的复杂流程驯服为可测试、可复用、可编排的纯组件。下一章进入 Prepare 的裁剪细节。

思考题

  1. 若在 Recipe 中插入一个 MusicStep(添加背景音乐),它对 Session 需要哪些新字段?时间线结构是否需要扩展?
  2. Build 在 Step 失败后直接返回,不做草稿清理——capcut-mate 侧会留下半成品草稿。你会如何设计补偿机制(回滚 API / 标记孤儿草稿定期清理)?

项目信息

  • GitHub仓库:Chyona/live-mixer

來源:阿里雲開發者社區 AI · developer.aliyun.com