YumCut视频流水线深度解析:从process_script到video_main的8个阶段源码剖析
YumCut视频流水线深度解析:从process_script到video_main的8个阶段源码剖析
YumCut 是一款免费开源的 AI 短视频生成工具,它能把一句话提示词变成可直接发布的 9:16 竖屏视频,用于 TikTok、Reels 和 YouTube Shorts,自动完成脚本、配音、字幕与水印。本文深入它的本地优先(Local-first)视频流水线源码,带你逐阶段看懂从 process_script 到 video_main 的 8 个执行阶段是如何协同工作的。
8个阶段速览:从提示词到成片的全景地图
整条流水线本质上是一个状态机:每个项目都有一个 ProjectStatus,从 process_script 一路推进到 process_video_main,最终进入 done。状态定义在 status.ts,各状态的界面文案与说明集中在 status-info.ts。
| 阶段 | 状态名 | 任务类型 | 阶段文件 | 核心产出 |
|---|---|---|---|---|
| 1 | process_script |
script | script-phase.ts | AI 脚本 + 多语言翻译 |
| 2 | process_audio |
audio | audio-phase.ts | TTS 配音音频 |
| 3 | process_transcription |
transcription | transcription-phase.ts | 逐字时间戳转写 |
| 4 | process_metadata |
metadata | metadata-phase.ts | 句子块 metadata |
| 5 | process_captions_video |
captions_video | captions-phase.ts | 透明字幕层 |
| 6 | process_images_generation |
images | images-phase.ts | 场景图片资产 |
| 7 | process_video_parts_generation |
video_parts | video-parts-phase.ts | 分镜片段视频 |
| 8 | process_video_main |
video_main | video-main-phase.ts | 最终成片 |
story 体验类型的完整顺序由 STORY_PIPELINE_ORDER 常量固定,见 project-pipeline.ts——8 个状态一一对应,顺序不可乱。
调度与分发:流水线的"大脑"
后台 daemon(index.ts)定时轮询数据库,领取任务后调用 executeJob,它先把任务类型映射回状态,再交给 executeForProject 通过一个大 switch 分发到具体阶段处理器,见 executor.ts 与 executor.ts。任何未处理的异常都会把项目置为 error 并记录原因,保证失败可追溯。
阶段一 process_script:AI 脚本生成与多语言翻译
流水线入口在 handleScriptPhase。它支持三种模式:
- AI 生成:调用
generateScript根据提示词写稿,支持"创作指导/规避指导"(guidance)注入; - 逐字模式(
useExactTextAsScript):用户提供的文案直接作为脚本; - 精修模式(
script_refinement):对已有脚本做 AI 改写,并可同步传播到各语言版本。
多语言项目的翻译目标在阶段内计算,由 translateScript 完成,见 script-phase.ts。脚本产出后项目会停在 process_script_validate,等待用户确认(或自动批准)才继续。
阶段二 process_audio:配音生成
handleAudioPhase 读取已批准的脚本,调用 generateVoiceovers 生成候选配音。阶段顶部声明了受支持的语音服务商:minimax、elevenlabs、inworld(audio-phase.ts)。内容语气(playful / angry / normal)会被转写成风格提示词,影响 TTS 的表达方式,见 audio-phase.ts。
阶段三 process_transcription:音频转写
配音选定后,handleTranscriptionPhase 调用 transcribeAudio 产出带时间戳的文字稿,并顺带生成句子级 metadata。该阶段按语言粒度推进:已完成的语言会被跳过,失败的单语言只会 markLanguageFailure 而不拖垮整条流水线,见 transcription-phase.ts。
阶段四 process_metadata:元数据与句子块
handleMetadataPhase 为每个语言工作区生成 transcript-blocks.json——后续字幕、图片、分镜全部以它为"节拍器"。它还会校验句子块数量是否合理,避免下游渲染错位。
阶段五 process_captions_video:透明字幕叠层
handleCaptionsPhase 渲染出一条带 Alpha 通道的透明字幕视频(out-alpha-validated.webm),而非把字幕直接烧进画面——这为阶段八的灵活合成留出了空间。所有语言字幕完成后,项目推进到 process_images_generation。
阶段六 process_images_generation:图片资产生成
handleImagesPhase 负责视觉素材:根据模板风格提示词(template.artStyle.prompt)调用 generateImages 批量出图,角色类项目还会走 character-cache 解析与缓存角色图,见 images-phase.ts。
阶段七 process_video_parts_generation:分镜片段渲染
handleVideoPartsPhase 把"文字 + 图片 + 时间戳"变成逐镜视频片段。它按内容语气加载不同的视频生成提示词文件(tone-angry.md 等,video-parts-phase.ts),并可选接入 lipsync(口型同步)渲染,最终产出 simple.1080p.mp4 主片段,渲染入口是 video.ts 中的 renderVideoParts。
阶段八 process_video_main:最终视频合成
最后的收口在 handleVideoMainPhase。它先校验三样输入是否齐备:metadata、分镜主视频、配音音频,见 video-main-phase.ts;然后调用 buildFinalVideo 完成合成——叠加背景音乐、字幕层与水印,逐语言产出成片,见 video-main-phase.ts。全部语言完成后,项目置为 done,视频即可下载与发布。
其他体验分支与部署要点
- 分支流水线:
character跳过图片生成阶段,rigger-animation只跑视频合成,image-generation只做图片,顺序定义见 project-pipeline.ts;分发处按projectExperience动态路由,见 executor.ts。 - 人工卡点:
process_script_validate与process_audio_validate是两个"等待用户确认"的暂停点,实现自动与人工审批两种工作流。 - FFmpeg 依赖:daemon 依赖 FFmpeg 7.1.1 以上版本渲染视频,启动时会校验版本,安装指南见 daemon-ffmpeg.md。
一句话总结:YumCut 用"状态机 + 任务队列 + 逐语言工作区"的设计,把复杂的视频生产拆成 8 个可独立重试、可暂停审批的阶段,这正是它能在低成本下批量产出多语言短视频的关键。





