Pixelle-Video 源码解析 #2：项目目录结构总览：从 WebUI 到视频生成引擎

上一篇我们从产品角度分析了 Pixelle-Video 解决的问题：它不是一个单纯的视频生成模型，而是一个把文案、配图、配音、BGM、模板和视频合成串起来的短视频自动化生产系统。

这一篇开始进入源码。

读一个开源项目，最忌讳一上来就钻进某个函数。尤其是 Pixelle-Video 这种“工作流型 AI 项目”，它不是靠单个算法完成任务，而是由 WebUI、配置系统、模型调用、素材生成、语音生成、模板渲染、视频合成等多个模块协作完成。

所以源码解析的第二篇，我们先不急着看具体代码逻辑，而是先看项目目录结构。

目录结构其实就是项目作者给我们的“架构地图”。
看懂目录，后面再分析文案生成、分镜处理、TTS、ComfyUI、ffmpeg 合成时，就不会迷路。

一、先看项目整体入口

Pixelle-Video 的官方启动方式很直接：克隆项目后，通过 uv run streamlit run web/app.py 启动 Web 界面，浏览器打开本地服务后，就可以在 WebUI 中配置 LLM、ComfyUI / RunningHub、API 媒体模型等参数。项目 README 中也明确写到，源码方式启动 Web 界面的入口是 web/app.py。

这说明 Pixelle-Video 的默认使用方式不是命令行工具，而是一个 Streamlit Web 应用。

也就是说，用户看到的是 WebUI，但真正做事的是后面的 pixelle_video 核心包。

我们可以先把它理解成三层：

用户层：web/
    负责页面展示、参数输入、按钮交互、进度显示

接口层：api/
    负责 REST API、任务管理、外部调用入口

核心层：pixelle_video/
    负责配置、模型、流水线、服务、视频生成逻辑

除了这三层，项目还包含一批资源目录，例如 templates/、workflows/、bgm/、resources/、docs/、packaging/windows/ 等。GitHub 仓库根目录中可以看到这些顶层目录。

这就是 Pixelle-Video 的大体结构：

Pixelle-Video/
├── web/                 # Streamlit WebUI
├── api/                 # FastAPI 接口层
├── pixelle_video/       # 核心业务代码
├── templates/           # 视频 HTML 模板
├── workflows/           # ComfyUI / API 工作流配置
├── bgm/                 # 背景音乐资源
├── resources/           # 静态资源、示例资源等
├── docs/                # 项目文档
├── packaging/windows/   # Windows 打包相关
├── config.example.yaml  # 配置文件示例
├── pyproject.toml       # Python 项目依赖配置
├── Dockerfile           # Docker 构建文件
└── docker-compose.yml   # Docker Compose 配置

接下来我们逐层分析。

二、web/：用户看到的 WebUI 入口

先看 web/ 目录。

当前仓库中的 web/ 目录包含 components、i18n、pages、pipelines、state、utils 以及入口文件 app.py。

它的大致结构可以这样理解：

web/
├── app.py          # Streamlit 主入口
├── components/     # 页面组件
├── pages/          # 页面模块
├── pipelines/      # Web 层对不同生成流程的封装
├── state/          # 页面状态管理
├── utils/          # Web 层工具函数
└── i18n/           # 多语言相关

这里最重要的是 app.py。

因为官方启动命令就是：

uv run streamlit run web/app.py

这说明 web/app.py 是用户访问 Pixelle-Video 的第一站。

一般来说，Streamlit 项目的主入口会负责几件事：

第一，初始化页面布局。

第二，加载配置。

第三，渲染侧边栏或主页面表单。

第四，读取用户输入。

第五，用户点击按钮后，调用后端生成逻辑。

第六，显示生成进度和最终视频。

Pixelle-Video README 中也介绍了 Web 界面的大体布局：打开 Web 界面后，可以看到三栏布局，包括系统配置、内容输入、语音设置、图像生成、视频模板、生成按钮和进度展示等内容。

所以，web/ 层并不是视频生成的核心，它更像是“操作台”。

用户在页面上选择模型、填写主题、选择模板、选择 BGM、点击生成，这些操作最终都会被转换成后端核心模块的调用。

可以把 web/ 理解成这样：

用户输入主题
    ↓
web/app.py 收集页面参数
    ↓
web/pipelines 或 web/utils 做页面层封装
    ↓
调用 pixelle_video 核心生成逻辑
    ↓
把进度和结果显示回页面

因此，后面真正分析生成逻辑时，我们不能只停留在 web/，而是要继续往下追到 pixelle_video/。

三、api/：给外部系统调用的接口层

Pixelle-Video 不只是一个 WebUI 项目，它还有 api/ 目录。

当前 api/ 目录下包含 routers、schemas、tasks、app.py、config.py、dependencies.py 等文件和子目录。

可以大致理解为：

api/
├── app.py             # FastAPI 应用入口
├── routers/           # 路由定义
├── schemas/           # 请求和响应数据结构
├── tasks/             # 异步任务相关
├── config.py          # API 层配置
└── dependencies.py    # 依赖注入

这一层的意义很大。

如果只有 WebUI，Pixelle-Video 更像是一个本地工具。
但有了 API 层，它就可以被其他系统调用。

比如：

一个自媒体后台可以调用它批量生成短视频。

一个接单工具可以把客户需求转成视频生成任务。

一个自动化 Agent 可以每天生成几条选题视频。

一个 SaaS 系统可以把它封装成“输入主题，导出视频”的在线服务。

第三方技术文档中也整理过 Pixelle-Video 的 REST API 设计，包括视频生成、任务状态查询、健康检查、内容生成、TTS、图片生成、HTML 帧渲染、模板列表、工作流列表和文件服务等接口。

所以，api/ 层可以理解为 Pixelle-Video 的“开放入口”。

WebUI 是给人用的。
API 是给程序用的。

这也是这个项目值得二次开发的地方。

四、pixelle_video/：真正的核心引擎

接下来是最重要的目录：pixelle_video/。

当前 pixelle_video/ 目录下包含 config、models、pipelines、prompts、services、utils，以及 llm_presets.py、service.py、tts_voices.py 等文件。

可以先画成这样：

pixelle_video/
├── config/          # 配置加载、保存、结构定义
├── models/          # 核心数据模型
├── pipelines/       # 视频生成流水线
├── prompts/         # 提示词模板
├── services/        # LLM、TTS、媒体处理、视频合成等服务
├── utils/           # 通用工具函数
├── llm_presets.py   # LLM 预设模型配置
├── tts_voices.py    # TTS 音色配置
└── service.py       # 更高层的服务封装

这个目录就是整个 Pixelle-Video 的“大脑”。

如果说 web/ 负责“让用户点按钮”，api/ 负责“让外部系统调用”，那么 pixelle_video/ 就负责“真正把视频生成出来”。

从项目设计看，pixelle_video/ 至少承担这些职责：

生成或处理文案。

把文案拆成分镜。

根据分镜生成图片或视频素材。

生成语音解说。

渲染 HTML 视频帧。

调用 ffmpeg 或相关视频处理工具进行合成。

记录进度。

保存输出结果。

后面源码解析真正要深入的，也主要是这个目录。

五、config/：配置系统是 AI 项目的地基

在 pixelle_video/config/ 目录下，可以看到 loader.py、manager.py、schema.py 等文件。

pixelle_video/config/
├── loader.py
├── manager.py
└── schema.py

这一层非常重要。

因为 Pixelle-Video 是一个组合型 AI 应用，它不是只依赖一个模型。它可能同时依赖：

LLM 模型。

ComfyUI 服务地址。

RunningHub API Key。

TTS 工作流。

API 图像模型。

API 视频模型。

代理配置。

默认模板。

默认输出参数。

项目根目录中的 config.example.yaml 就展示了配置文件的大致结构，例如 LLM 的 api_key、base_url、model，以及 ComfyUI 的服务地址、API Key、RunningHub Key 和并发限制等配置。

所以，config/ 目录可以理解为整个项目的“控制面板后端”。

WebUI 上保存的模型配置，最终要落到配置文件中；生成视频时，各个服务也要从配置中读取 API Key、模型地址和默认参数。

对于二次开发者来说，这一层值得重点看。

因为你以后想增加新模型、新服务商、新默认参数，大概率都要先从配置系统入手。

六、models/：视频生成过程中的核心数据结构

pixelle_video/models/ 目录下目前包含 media.py、progress.py、storyboard.py。

pixelle_video/models/
├── media.py
├── progress.py
└── storyboard.py

这个目录看起来文件不多，但作用很关键。

AI 视频生成不是一步完成的，它中间会产生很多结构化数据。

比如：

一条视频的标题是什么？

总共有多少个分镜？

每个分镜对应哪一句旁白？

每个分镜的图片提示词是什么？

每个分镜生成出来的图片或视频文件在哪里？

语音文件在哪里？

当前生成进度到了第几步？

这些数据如果不用统一结构管理，代码很快就会变得混乱。

所以，models/ 目录的意义在于：定义视频生成过程中的“中间数据格式”。

你可以把它理解成 Pixelle-Video 内部流转的对象模型：

主题 topic
    ↓
文案 script
    ↓
分镜 storyboard
    ↓
单帧 frame
    ↓
媒体 media
    ↓
进度 progress
    ↓
最终视频 output

尤其是 storyboard.py，从名字就能看出，它很可能对应“分镜脚本”这一核心概念。

短视频自动化生成的关键，不是直接从一句话跳到 MP4，而是中间要有一个结构化分镜层。

这个分镜层承上启下：

上游连接 LLM 文案生成。

下游连接图片、视频、TTS、模板渲染和视频合成。

七、pipelines/：视频生成流水线

pixelle_video/pipelines/ 是非常值得重点分析的目录。

当前该目录下包含 asset_based.py、base.py、custom.py、linear.py、standard.py 等文件。

pixelle_video/pipelines/
├── base.py
├── standard.py
├── linear.py
├── custom.py
└── asset_based.py

从命名上看，这里应该是不同生成模式的流水线实现。

可以先这样理解：

base.py：定义流水线基类或公共流程。

standard.py：标准视频生成流程。

linear.py：线性分镜式生成流程。

custom.py：自定义素材或自定义流程。

asset_based.py：基于已有素材的视频生成流程。

Pixelle-Video README 中提到，项目支持 AI 生成内容和固定文案内容，也支持自定义素材、图生视频、数字人口播、动作迁移等扩展模块。 这些能力如果落到代码层面，就很可能对应不同 pipeline。

为什么要有 pipeline？

因为不同视频生成模式虽然目标都是输出视频，但步骤不完全一样。

例如：

标准模式可能是：

主题 → LLM 文案 → 分镜 → 生图 → TTS → 模板渲染 → 视频合成

固定文案模式可能是：

已有文案 → 分句 → 生图 → TTS → 模板渲染 → 视频合成

自定义素材模式可能是：

用户上传图片/视频 → AI 分析素材 → 生成文案 → 匹配素材 → 合成视频

数字人口播模式可能是：

文案 → TTS/口播驱动 → 数字人视频 → 合成字幕和背景

如果把所有逻辑都写进一个函数，代码会很难维护。

所以 Pixelle-Video 使用 pipelines/ 目录来承载不同流程，是比较合理的架构设计。

后续源码解析中，standard.py 很适合作为第一个深入分析的入口。

八、services/：真正干活的能力模块

如果说 pipelines/ 是流程编排，那么 services/ 就是具体干活的模块。

当前 pixelle_video/services/ 目录下包含很多关键文件，例如 llm_service.py、tts_service.py、frame_html.py、frame_processor.py、video.py、image_analysis.py、video_analysis.py、api_media.py、comfy_base_service.py、history_manager.py、persistence.py 等。

可以整理成这样：

pixelle_video/services/
├── llm_service.py          # LLM 文案/结构化内容生成
├── tts_service.py          # 语音合成
├── comfy_base_service.py   # ComfyUI 基础调用能力
├── api_media.py            # API 媒体模型调用
├── frame_html.py           # HTML 帧模板处理
├── frame_processor.py      # 单帧处理
├── video.py                # 视频合成相关
├── image_analysis.py       # 图片分析
├── video_analysis.py       # 视频分析
├── media.py                # 媒体处理相关
├── history_manager.py      # 历史记录管理
└── persistence.py          # 持久化相关

这一层是源码解析的重点。

因为 Pixelle-Video 的核心能力，基本都落在这里。

比如：

llm_service.py 负责和大语言模型交互。

tts_service.py 负责生成旁白音频。

comfy_base_service.py 负责调用 ComfyUI 工作流。

frame_html.py 和 frame_processor.py 负责把模板渲染成视频帧。

video.py 负责把图片、视频、音频、字幕等素材合成最终视频。

image_analysis.py、video_analysis.py 则对应自定义素材分析、上传素材理解等扩展功能。

可以把 services/ 看成“能力仓库”。

pipelines/ 不直接关心每个能力的细节，而是按照流程把这些能力串起来。

这就是比较典型的分层设计：

pipeline 负责“先做什么，后做什么”
service 负责“具体怎么做”
model 负责“数据怎么表示”
config 负责“参数从哪里来”
web/api 负责“外部怎么触发”

九、prompts/：AI 应用的隐藏核心

pixelle_video/ 下还有一个 prompts/ 目录。

这个目录虽然在目录名上不如 services/ 显眼，但对 AI 应用来说非常关键。

因为 LLM 生成文案、拆分镜、生成图片提示词，最终效果很大程度取决于 prompt。

Pixelle-Video 的视频生成流程中，README 明确提到“文案生成 → 配图规划 → 逐帧处理 → 视频合成”的模块化流程。 其中“文案生成”和“配图规划”基本都离不开 prompt。

所以 prompts/ 目录可以理解为：

prompts/
└── 存放文案生成、分镜生成、图片提示词生成等提示词模板

后面如果我们要分析：

Pixelle-Video 如何让 LLM 输出结构化分镜？

如何避免文案太散？

如何让每个画面都能对应一句旁白？

如何让图片提示词适合 AI 生图？

就一定要看 prompts/。

很多 AI 项目的核心竞争力，并不只在代码，而在 prompt 设计和结构化输出约束上。

Pixelle-Video 也一样。

十、templates/：视频样式的关键

templates/ 是视频最终视觉效果的重要来源。

Pixelle-Video README 中说明，视频模板有命名规范：static_*.html 表示静态模板，image_*.html 表示使用 AI 图片作为背景的图片模板，video_*.html 表示使用 AI 视频作为背景的视频模板；用户也可以在 templates/ 文件夹中创建自己的 HTML 模板。

这说明 Pixelle-Video 的视频样式并不是硬编码在 Python 里，而是抽离到了 HTML 模板中。

这点设计很有意思。

传统视频生成可能直接在 Python 中控制字幕、图片、背景、布局。

但 HTML 模板的好处是：

第一，视觉样式更容易调整。

第二，前端开发者也能参与模板设计。

第三，可以快速做出多种风格。

第四，适合生成固定结构的视频画面。

第五，可以把模板和业务逻辑分离。

例如，你可以有：

static_knowledge.html     # 纯文字知识类模板
image_story.html          # 图片背景故事类模板
video_cinematic.html      # 视频背景电影感模板

后续如果你想基于 Pixelle-Video 做自己的短视频账号矩阵，这个目录非常重要。

因为账号风格能不能固定，很大程度取决于模板系统。

十一、workflows/：连接 ComfyUI 和 API 模型

workflows/ 目录主要用于放工作流配置。

Pixelle-Video README 中提到，图像生成可以从下拉菜单选择 ComfyUI 工作流，支持本地部署和 RunningHub 云端工作流，也支持 api/... 形式的直连图像模型工作流；如果懂 ComfyUI，也可以把自己的工作流放到 workflows/ 文件夹。

这说明 workflows/ 是 Pixelle-Video 接入外部生成能力的桥梁。

它解决的是“如何把不同模型能力变成统一可调用流程”的问题。

比如：

生图可以走 ComfyUI。

视频生成可以走 DashScope Wan、Kling、Seedance 等 API。

TTS 可以走 Edge-TTS 或 Index-TTS。

自定义工作流可以由用户自己扩展。

这也是 Pixelle-Video 作为自动化引擎的优势：

它不把生成能力写死，而是通过工作流配置来组织能力。

对于二次开发者来说，如果想新增一种生图模型或视频生成模型，通常不应该一上来就改核心逻辑，而是先看它能不能通过 workflows/ 和配置系统接入。

十二、bgm/、resources/、output/：素材和结果

bgm/ 目录从名字就能看出来，是背景音乐目录。

Pixelle-Video README 中介绍了 BGM 的使用方式：可以选择无 BGM、内置音乐，也可以把自定义音乐文件放到 bgm/ 文件夹中。

resources/ 则更偏静态资源和项目内置资源。

output/ 虽然不一定作为仓库固定目录长期提交，但 README 中提到，视频生成完成后会自动显示预览，视频文件保存在 output/ 文件夹。

所以 Pixelle-Video 的文件流向可以这样理解：

输入：
主题、固定文案、图片、视频、BGM、配置参数

中间产物：
LLM 文案、分镜、图片、视频片段、TTS 音频、HTML 帧

输出：
output/ 下的最终视频文件

这对我们后面调试很重要。

如果生成失败，要知道去哪里看中间产物。

如果想拿最终视频，要知道去哪里找输出文件。

如果想替换背景音乐，要知道放到哪个目录。

十三、docs/ 和 packaging/：文档与分发

docs/ 目录用于项目文档。

packaging/windows/ 则和 Windows 一键整合包有关。README 中也提到，Windows 用户可以下载一键整合包，无需安装 Python、uv 或 ffmpeg，解压后运行 start.bat 即可启动 Web 界面。

这说明项目不仅考虑了开发者，也考虑了普通用户。

从源码角度看：

docs/ 解决“怎么理解和使用项目”。

packaging/windows/ 解决“怎么把项目打包给不会配环境的人”。

对于一个 AI 工具项目来说，这两部分很现实。

因为很多 AI 开源项目不是不能用，而是环境太复杂，普通用户跑不起来。

Pixelle-Video 提供 Windows 整合包，说明它在产品化方面做了一些考虑。

十四、从目录结构看完整调用链路

现在我们可以把整个项目串起来了。

当用户打开 WebUI 并点击“生成视频”时，大致链路应该是：

web/app.py
    ↓
读取用户输入、配置、模板、BGM、工作流参数
    ↓
pixelle_video/config/
    ↓
加载 LLM、ComfyUI、TTS、API 媒体模型等配置
    ↓
pixelle_video/pipelines/
    ↓
选择标准流程、自定义素材流程、线性流程等
    ↓
pixelle_video/services/llm_service.py
    ↓
生成文案、分镜或提示词
    ↓
pixelle_video/services/comfy_base_service.py 或 api_media.py
    ↓
生成图片或视频素材
    ↓
pixelle_video/services/tts_service.py
    ↓
生成旁白音频
    ↓
templates/
    ↓
用 HTML 模板渲染画面
    ↓
pixelle_video/services/frame_processor.py / video.py
    ↓
合成最终视频
    ↓
output/
    ↓
WebUI 展示视频预览

这条链路就是 Pixelle-Video 的核心。

它不是一个“调用一次视频模型”的项目，而是一个多模块协作的短视频生成流水线。

这也是为什么它的目录结构会分得比较细：

WebUI 归 WebUI。

API 归 API。

配置归配置。

数据模型归数据模型。

流程编排归 pipeline。

具体能力归 service。

视觉样式归 templates。

模型工作流归 workflows。

输出结果归 output。

这种分层方式，对二次开发非常友好。

十五、读源码时应该从哪里开始？

如果你是第一次读 Pixelle-Video，我建议不要按照文件名从上到下读，而是按照调用链路读。

推荐顺序如下：

第一步，看 web/app.py。

了解页面入口在哪里，用户点击按钮后调用了什么。

第二步，看 pixelle_video/config/。

了解配置是怎么加载、保存、传递的。

第三步，看 pixelle_video/models/storyboard.py。

了解视频中间结构是怎么表示的。

第四步，看 pixelle_video/pipelines/standard.py。

了解标准视频生成流程。

第五步，看 pixelle_video/services/llm_service.py。

了解文案和分镜是怎么生成的。

第六步，看 pixelle_video/services/tts_service.py。

了解语音合成怎么接入。

第七步，看 pixelle_video/services/frame_html.py 和 frame_processor.py。

了解 HTML 模板如何变成画面帧。

第八步，看 pixelle_video/services/video.py。

了解最终视频如何合成。

第九步，看 templates/ 和 workflows/。

理解如何扩展视频风格和模型能力。

按照这个顺序读，比较符合真实生成流程，不容易迷路。

十六、总结

这一篇我们没有深入具体函数，而是从目录结构看 Pixelle-Video 的整体架构。

可以把它总结成一句话：

Pixelle-Video 的源码结构，是一个典型的“WebUI + API + 核心引擎 + 模板资源 + AI 工作流”的短视频自动化项目结构。

其中：

web/ 负责用户操作界面。

api/ 负责外部系统调用。

pixelle_video/config/ 负责配置管理。

pixelle_video/models/ 负责核心数据结构。

pixelle_video/pipelines/ 负责生成流程编排。

pixelle_video/services/ 负责具体能力实现。

prompts/ 负责 AI 提示词。

templates/ 负责视频视觉样式。

workflows/ 负责 ComfyUI 和 API 模型工作流。

bgm/ 负责背景音乐。

output/ 负责最终结果。

理解了这些目录，后面再分析源码就会清晰很多。