【直播切片工作台】第37章:素材準備流水線 prepare
【直播切片工作台】第37章:素材准备流水线 prepare
prepare 負責下載直播源影片、合併相鄰片段,並以 FFmpeg 裁剪成本地影片切片,不調用 capcut-mate。成片總時長超過 10 分鐘時採用關鍵幀快速裁剪,否則使用精確重編碼;流程以固定進度曲線推進,並保留片段原有順序。
2026-11-18 8
版权
版权声明:
本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写 侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。
简介: 第37章“素材准备流水线 prepare”是直播切片成片阶段的前置重体力模块:专注下载源视频、合并相邻片段、用FFmpeg精准或快速裁剪本地切片;不调用CapCut-Mate,产出纯本地文件,为Builder两段式流水线夯实基础。(239字)
第37章:素材准备流水线 prepare
draft/prepare 包是成片阶段的重体力活承担者:下载直播源视频、合并相邻片段、用 ffmpeg 裁剪出本地切片。它"不调用 capcut-mate"(包注释的明确边界),产出纯本地文件,是 Builder 两段式流水线的前半段。
流程
Pipeline.Run 按固定进度曲线推进:15%(开始下载)→ 25%(下载完成)→ 25~50%(逐片段裁剪,线性推进)→ 50%(返回)。裁剪方式在进入循环前一次性决策:UseFastKeyframeCut 判断成片总时长是否超过 10 分钟。
flowchart TD
A[Pipeline.Run] --> B[校验 material/downloader/cutter]
B --> C[MkdirAll staging 与 record 目录]
C --> D[Download live_url → source.mp4<br/>进度15→25]
D --> E{总时长 > 10 分钟?}
E -- 是 --> F[CutVideoSegmentFast<br/>关键帧流拷贝 秒级]
E -- 否 --> G[CutVideoSegment<br/>精确重编码 慢]
F & G --> H[逐片段输出 clip_000.mp4...<br/>进度25→50线性]
H --> I[Session.ClipPaths]
实现
双模式裁剪的成本权衡是本包的灵魂。精确重编码从任意时间点起帧(音画同步精确,适合 ≤10 分钟的短视频),代价是 CPU 重;关键帧快速拷贝(-c copy 起于最近关键帧)几乎瞬时完成但存在前后数秒误差。10 分钟阈值把"用户对精度不敏感的长片"切到快车道——直播两小时回放剪 20 分钟合集,快速模式与精确模式的耗时可能相差一个数量级。决策函数是纯函数 UseFastKeyframeCut,且模式选择作为结构化字段(mode=precise/keyframe_copy)写入日志,事后可审计每个任务用了哪种方式。
MergeAdjacentClipRanges 的顺序语义。与第 33 章 mergeAdjacentClips1 共享 500ms 阈值,但注意其"严格保留入参顺序,不排序"的差异:next.StartTime >= cur.StartTime 才允许合并——时间上"回跳"的相邻项不合,注释点明动机"避免负 gap 误吞片段"。如果先排序再合并,LLM 返回的 [9,2,5] 索引会被静默重排,掩盖上游错误;保序合并让异常顺序自然断开为多个片段,问题显式暴露。
ResolveClipRanges 的回退链:clips1(LLM 精选)优先,为空回退 clips0(用户手选)——这正是一键成片"AI 选过段"与纯草稿"只给区间"两种任务形态统一的关键:同一个函数对两种输入给出一致行为。
文件命名即协议:clip_%03d.mp4 三位序号,序号顺序即成片顺序。VideosStep 直接按此顺序铺轨,StagingDir 里的 source.mp4 则是唯一全量副本,裁剪失败可重试而无需重新下载(Builder 上层若实现重试)。
进度回调的粒度:裁剪循环每完成一段调一次 ReportProgress,公式 25 + 25*(i+1)/len——即使单段失败,进度条也停在真实位置,配合 task 表的 updated_at 刷新避免被孤儿回收误杀(第 32 章的 20 分钟超时依赖进度写入同时刷新时间戳)。
📌 设计决策
- 阈值 10 分钟硬编码为常量:不做成配置的理由是它不是运维参数而是产品决策(超过 10 分钟的成片本质是"长剪辑",用户对秒级误差不敏感);升成配置反而诱导随意调参。
- 下载与裁剪解耦为两个接口:
FileDownloader/VideoSegmentCutter分别 mock,单测可只测裁剪逻辑而不伪造 HTTP;真实实现分别在 media 包与 storage 相关包。 - 关键帧模式全有或全无:不做"混合模式"(短片段精确、长片段快速),因为一个成片内混用两种精度会带来肉眼可见的不一致。
- 顺序保序合并且不排序:宁可多出片段也不掩盖顺序异常——正确性优先于片段数优化。
代码示例
片段 1 展示 Run 主流程与进度曲线(摘自 prepare/prepare.go,节选):
// Run 下载直播视频并按 Session.Clips 裁剪出本地切片。
func (p *Pipeline) Run(ctx context.Context, s *session.Session) error {
if s.Material == nil || s.Material.LiveURL == "" {
return fmt.Errorf("直播素材 live_url 为空")
}
if p.Downloader == nil || p.Cutter == nil {
return fmt.Errorf("下载器/裁剪器未配置")
}
if err := os.MkdirAll(s.StagingDir, 0o755); err != nil {
return fmt.Errorf("创建任务暂存目录失败: %w", err)
}
p.Logger.Info("开始下载直播视频",
zap.String("job_id", s.JobID),
zap.String("live_url", s.Material.LiveURL))
s.ReportProgress(15)
s.SourcePath = filepath.Join(s.StagingDir, "source.mp4")
if _, err := p.Downloader.Download(s.Material.LiveURL, s.SourcePath); err != nil {
return fmt.Errorf("下载直播视频失败: %w", err)
}
s.ReportProgress(25)
paths, err := p.cutClips(ctx, s)
if err != nil {
return err
}
s.ClipPaths = paths
s.ReportProgress(50)
return nil
}
片段 2 展示双模式决策与保序合并(摘自 prepare/prepare.go,节选):
const (
// ClipMergeGapMS 相邻片段间隔 ≤ 该值(毫秒)时合并后再 ffmpeg 裁剪。
ClipMergeGapMS = 500
// FastKeyframeCutMinDurationMS 成片总时长超过该值时改用关键帧快速裁剪。
// 10 分钟以内仍走精确重编码。
FastKeyframeCutMinDurationMS int64 = 10 * 60 * 1000
)
// UseFastKeyframeCut 成片总时长超过 10 分钟时使用关键帧快速裁剪。
func UseFastKeyframeCut(clips []model.ClipRange) bool {
return TotalClipDurationMS(clips) > FastKeyframeCutMinDurationMS
}
func (p *Pipeline) cutClips(ctx context.Context, s *session.Session) ([]string, error) {
clips := s.Clips
useFast := UseFastKeyframeCut(clips)
paths := make([]string, 0, len(clips))
for i, clip := range clips {
outPath := filepath.Join(s.StagingDir, fmt.Sprintf("clip_%03d.mp4", i))
startSec := float64(clip.StartTime) / 1000.0
endSec := float64(clip.EndTime) / 1000.0
var err error
if useFast {
err = p.Cutter.CutVideoSegmentFast(ctx, s.SourcePath, outPath, startSec, endSec)
} else {
err = p.Cutter.CutVideoSegment(ctx, s.SourcePath, outPath, startSec, endSec)
}
if err != nil {
return nil, fmt.Errorf("裁剪第 %d 段失败: %w", i, err)
}
paths = append(paths, outPath)
// 裁剪阶段本地进度:25 → 50,按片段数线性推进。
local := int16(25 + int(25*float64(i+1)/float64(len(clips))))
s.ReportProgress(local)
}
return paths, nil
}
// MergeAdjacentClipRanges 按列表顺序合并相邻片段:严格保留入参顺序,不排序。
func MergeAdjacentClipRanges(clips []model.ClipRange, maxGapMS int64) []model.ClipRange {
out := make([]model.ClipRange, 0, len(clips))
cur := clips[0]
for i := 1; i < len(clips); i++ {
next := clips[i]
gap := next.StartTime - cur.EndTime
// 列表顺序优先:时间上回跳的相邻项不合,避免负 gap 误吞片段。
if next.StartTime >= cur.StartTime && gap <= maxGapMS {
if next.EndTime > cur.EndTime {
cur.EndTime = next.EndTime
}
continue
}
out = append(out, cur)
cur = next
}
out = append(out, cur)
return out
}
小结
prepare 把 ffmpeg 的调用细节封装在两个接口之后,用 10 分钟阈值换取长片裁剪的数量级提速,用保序合并守住顺序异常的可见性。Session 上的 SourcePath/ClipPaths 是它留给后续步骤的全部遗产。
思考题
- 关键帧快速拷贝从最近关键帧起切,实际片段会比请求区间长数秒——字幕时间轴若按原始 clips 计算,是否会出现音画错位?CaptionsStep 需要感知裁剪模式吗?
- 下载源视频可能占任务总时长的一半以上,多任务并行时同一 live_url 会被重复下载多次。你会把 source.mp4 提升为 live 级共享缓存吗?缓存的失效与并发竞争如何处理?
项目信息
GitHub仓库:Chyona/live-mixer
來源:阿里雲開發者社區 AI · developer.aliyun.com