Pixelle-Video 视频模板开发完全指南：从内置模板到自定义 HTML 模板-港品优选

Pixelle-Video 视频模板开发完全指南：从内置模板到自定义 HTML 模板

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video

本指南系统讲解 Pixelle-Video（AI 全自动短视频引擎）中视频模板的设计体系与开发方法：模板以 HTML 定义视频画面的布局与样式，通过 Playwright 无头浏览器渲染为帧图像。读完本文，你将掌握模板命名规范、内置模板全览、模板变量与自定义参数 DSL、创建自定义模板的完整流程，以及尺寸适配、排版、图片处理与性能优化等实战技巧。

模板简介：HTML 即画面

在 Pixelle-Video 中，视频模板使用 HTML 定义视频画面的布局和样式，每个分镜的画面都是一个由模板渲染出的帧（Frame）。模板负责承载标题、正文文本、AI 生成的图片或视频背景，并决定成片的宽高比与视觉风格。

项目内置了覆盖不同视频尺寸和风格需求的预设模板，存放于 templates/ 目录下，按1080x1920（竖屏）、1920x1080（横屏）、1080x1080（方形）三个尺寸分组。

从源码结构看，模板渲染由 pixelle_video/services/frame_html.py 中的HTMLFrameGenerator类负责：它读取模板文件 → 做变量替换 → 用 Playwright 启动 Chromium 无头浏览器 → 按模板解析出的尺寸设置 viewport → 截图输出 PNG 帧图。而 pixelle_video/services/frame_processor.py 中的FrameProcessor则把"HTML 模板合成"作为每帧流水线的第 3 步（TTS → 图像/视频生成 → 模板合成 → 视频片段），最终再与 TTS 音频合并为带旁白的视频片段。

内置模板预览

竖屏模板（1080x1920）

适用于抖音、快手、小红书等短视频平台。以下为内置竖屏模板及其设计定位：

模板名称	文件	定位
static_default	static_default.html	默认静态模板，纯文字样式渲染，无需 AI 媒体
static_excerpt	static_excerpt.html	图文摘抄静态模板
Blur Card	image_blur_card.html	模糊背景卡片风格，适合图文内容展示
Cartoon	image_cartoon.html	卡通风格，适合轻松活泼的内容
Default	image_default.html	默认模板，简洁通用
Elegant	image_elegant.html	优雅风格，适合文艺、知性内容
Fashion Vintage	image_fashion_vintage.html	复古时尚风格，适合怀旧主题
Life Insights	image_life_insights.html	生活感悟风格，适合心灵鸡汤类内容
Modern	image_modern.html	现代简约风格，适合商务、科技内容
Neon	image_neon.html	霓虹灯风格，适合时尚、潮流内容
Psychology Card	image_psychology_card.html	心理学卡片风格，适合知识科普
Purple	image_purple.html	紫色主题，适合梦幻、神秘风格
Satirical Cartoon	image_satirical_cartoon.html	80 年代讽刺漫画风格，适合精神类小故事
Simple Black Background	image_simple_black.html	极简黑色背景，适合心灵鸡汤类内容
Simple Line Drawing	image_simple_line_drawing.html	简笔画，适合认知成长类内容
Book	image_book.html	图书解读，适合科普类内容
Long Text	image_long_text.html	长文本，适合励志鸡汤类内容
Excerpt	image_excerpt.html	图文摘抄，适合名人名言
Health Preservation	image_health_preservation.html	养生窍门，适合养生科普内容
Life Insights（亮色版）	image_life_insights_light.html	人生感悟，传递温暖与力量
Full	image_full.html	全屏模板，适合书单号
Healing	image_healing.html	治愈模板，适合疗愈类内容
Video_Default	video_default.html	默认动态模板（AI 视频背景）
Video_Healing	video_healing.html	治愈动态模板（AI 视频背景）

以 image_default.html 为样例，其结构是典型的"标题区 + 图片区 + 文本区 + 页脚"四段式布局，并利用装饰圆环、L 形角标、侧边圆点等纯 CSS 元素营造简约质感，说明内置模板大量使用 CSS 绘制装饰而非依赖图片资源。

横屏模板（1920x1080）

适用于 YouTube、B 站等视频平台：

模板名称	文件	定位
Ultrawide Minimal	image_ultrawide_minimal.html	超宽屏极简风格，适合桌面端观看
Wide Darktech	image_wide_darktech.html	暗黑科技风格，适合技术、游戏内容
Film	image_film.html	电影风格，沉浸式体验
Full	image_full.html	全屏显示，适合书单号
Book	image_book.html	图书解读，适合科普类内容

方形模板（1080x1080）

适用于 Instagram、微信朋友圈等平台：

模板名称	文件	定位
Minimal Framed	image_minimal_framed.html	极简边框风格，适合社交媒体分享

这些模板的预览图可以在 docs/images/ 目录中找到对应尺寸的子目录（如 docs/images/1080x1920/），文档站点中的模板预览卡片即引用这些图片。

模板命名规范

模板文件名前缀决定了该模板在流水线中的媒体行为，pixelle_video/utils/template_util.py 中的get_template_type()会依据前缀判断模板类型：

static_*.html：静态模板
- 无需 AI 生成任何媒体内容，纯文字样式渲染；
- 适合快速生成、低成本场景；
- 在 frame_processor.py 中体现为needs_generation = frame.image_prompt is not None判断为否、跳过媒体生成步骤，直接进入模板合成。
image_*.html：图片模板
- 使用 AI 生成的图片作为背景/配图，调用 ComfyUI 图像生成工作流（或直连 API 提供商）；
- 适合需要视觉配图的内容；
- 若模板文件名不遵循static_/image_/video_前缀，get_template_type()会给出告警并默认按image类型处理。
video_*.html：视频模板
- 使用 AI 生成的视频作为背景，调用 ComfyUI 视频生成工作流（或直连 API 视频工作流）；
- 创建动态视频内容，增强表现力；
- 在 frame_processor.py 中，is_video_workflow通过工作流名是否含video_或模板类型是否为video判定，媒体类型随后决定合成分支：视频模板先渲染透明 HTML 叠加层（omit_background=True截图），再叠加到视频上，最后替换音频。

模板结构

模板位于 templates/ 目录，按尺寸分组：

templates/ ├── 1080x1920/ # 竖屏 │ ├── static_*.html # 静态模板 │ ├── image_*.html # 图片模板 │ └── video_*.html # 视频模板 ├── 1920x1080/ # 横屏 │ └── image_*.html # 图片模板 └── 1080x1080/ # 方形 └── image_*.html # 图片模板

尺寸即路径约定：视频尺寸由模板路径中的目录名解析而来。template_util.py 中的parse_template_size()从形如templates/1080x1920/default.html或1080x1920/default.html的路径中提取父目录名并拆分为宽高，同时做合法性校验（宽高须在 100～10000 像素之间）。这意味着创建自定义模板时，存放它的目录名必须形如WIDTHxHEIGHT，这是模板被正确渲染的前提。

此外，模板查找遵循"自定义优先、内置兜底"策略：resolve_template_path()支持None（回退默认1080x1920/image_default.html）、纯文件名（使用默认尺寸）、1080x1920/template.html相对路径以及templates/...旧式路径等多种输入格式；get_resource_path()会先查data/templates/再查内置templates/，因此你可以在data/templates/下覆盖同名模板或添加自定义模板而不改动仓库文件。

创建自定义模板

基本步骤

从templates/目录复制一个现有模板文件作为起点；
修改其中的 HTML 与 CSS 样式；
保存到对应尺寸目录下（目录名必须为WIDTHxHEIGHT格式），使用.html扩展名；
在配置（config.example.yaml 的template.default_template）或 Web 界面中选择该模板名称即可生效。

模板变量

模板支持以下 Jinja2 风格变量（由HTMLFrameGenerator.generate_frame()注入上下文，见 frame_html.py）：

变量	含义	说明
`{{ title }}`	视频标题	可选，取自`Storyboard.title`
`{{ text }}`	当前分镜的文本内容	必用，取自该帧的`narration`旁白文本
`{{ image }}`	当前分镜的图片	有则使用；支持相对路径、绝对路径与 HTTP URL

需要说明的是：模板变量的实际替换由 frame_html.py 中的_replace_parameters()完成（正则替换而非真正的 Jinja2 渲染）。图片路径在渲染前会被转换为file://URI（本地文件）或保持原样（HTTP/data/file 协议），确保无头浏览器能跨源加载。

除上述三个预设变量外，generate_frame()还通过ext参数注入扩展数据（如index帧序号），并透传StoryboardConfig.template_params中自定义参数。

示例模板

以下是一个可直接使用的竖屏静态模板：

<!DOCTYPE html> <html> <head> <style> body { width: 1080px; height: 1920px; margin: 0; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); display: flex; align-items: center; justify-content: center; font-family: 'Arial', sans-serif; } .content { text-align: center; color: white; padding: 40px; } .text { font-size: 48px; line-height: 1.6; } </style> </head> <body> <div class="content"> <div class="text">{{ text }}</div> </div> </body> </html>

如果希望模板中嵌入 AI 生成图片作为背景，只需在合适位置加入<img src="{{image}}">并配合object-fit: cover，参考内置的 image_default.html 图片容器写法。

自定义参数 DSL：让模板可配置

Pixelle-Video 的模板系统还支持自定义参数 DSL，语法为{{参数名:类型=默认值}}，由 frame_html.py 中的parse_template_parameters()解析：

{{param}}→ text 类型，无默认值；
{{param=value}}→ text 类型，带默认值；
{{param:type}}→ 指定类型，无默认值；
{{param:type=value}}→ 指定类型，带默认值。

支持的参数类型及默认值解析规则（见_parse_default_value()）：

类型	说明	无默认值时的取值
`text`	字符串	空字符串`''`
`number`	数值（含小数点按 float，否则 int）	`0`
`color`	颜色（自动补全`#`前缀）	`#000000`
`bool`	布尔（`true/1/yes/on`视为真）	`false`

title、text、image、index是预设参数名，不会作为自定义参数暴露。实际渲染时，若template_params传入了值则优先使用，否则回退占位符内默认值，再否则使用空字符串。

内置模板中已大量使用该 DSL，例如 image_default.html 页脚中的{{author=@Pixelle.AI}}、{{describe=Open Source Omnimodal AI Creative Agent}}、{{brand=Pixelle-Video}}，以及 static_default.html 的{{background=https://img.alicdn.com/...jpg}}背景图参数——后者意味着你可以通过template_params传入自定义背景图 URL 而无需改动模板文件。

这些参数可通过 HTTP API 自动发现：api/routers/frame.py 提供的GET /api/frame/template/params?template=1080x1920/image_default.html接口会返回模板的media_width、media_height与所有自定义参数的类型、默认值、标签；随后在视频生成请求中通过template_params传入实际值（参考 api/schemas/video.py 中VideoGenerateRequest.template_params的定义与示例）。

配置示例

在 config.example.yaml 中通过template.default_template设置全局默认模板：

template: # 默认帧模板：决定视频宽高比与布局风格 # - static_*.html: 静态模板（无 AI 媒体） # - image_*.html: 图片模板（AI 生成图片） # - video_*.html: 视频模板（AI 生成视频） default_template: "1080x1920/image_default.html"

而在 StoryboardConfig 中，frame_template字段（默认"1080x1920/default.html"）携带尺寸信息决定最终画面尺寸，template_params字典则用于覆盖模板自定义参数（如{"accent_color": "#ff0000"}）。

模板开发技巧

1. 响应式尺寸

确保模板的body（或最外层容器）尺寸与目标视频尺寸一致：

竖屏：width: 1080px; height: 1920px;
横屏：width: 1920px; height: 1080px;
方形：width: 1080px; height: 1080px;

渲染时HTMLFrameGenerator会按解析出的尺寸设置浏览器 viewport（device_scale_factor=1），因此超出视口的元素会被截断。注意：parse_template_size()的尺寸来源于目录名，而 frame_html.py 中的get_media_size()还会解析<meta name="template:media-width" content="1024">这类 meta 标签来决定AI 媒体（图/视频）的生成分辨率（未找到时回退 1024x1024）。即"画面尺寸"与"媒体生成尺寸"是两个独立维度，二者可不同。

2. 文本排版

使用合适的字体大小和行高，确保可读性（内置模板正文多在 42～48px、行高 1.6～2.0）；
为文字添加阴影或背景，提高对比度（如text-shadow、半透明背景卡片）；
控制文本长度，避免溢出；可配合min-height固定文本区高度，或用white-space: pre-line保留旁白中的换行（见 static_default.html）。

3. 图片处理

使用object-fit: cover确保图片填充容器（内置模板统一采用此写法）；
添加渐变或遮罩层提升文字可读性（如static_default.html中的gradient-overlay层）；
考虑图片加载失败的降级方案（如使用background参数提供兜底背景图）。

4. 性能优化

避免使用过于复杂的 CSS 动画（渲染是单帧截图，动画无意义且拖慢渲染）；
优化背景图片大小，控制 HTTP 请求资源体积；
使用系统字体或 Web 安全字体（内置模板采用'PingFang SC', 'Source Han Sans', 'Microsoft YaHei'等字体栈），避免依赖外部字体加载。

模板渲染的运行环境要求

模板依赖 Playwright 无头 Chromium 渲染，若在 Linux 服务器部署，需满足 frame_html.py 中说明的系统依赖：

安装fontconfig包（启动时会用fc-list自检并告警）；
建议安装基础字体：Ubuntu/Debian 执行sudo apt-get install -y fontconfig fonts-liberation fonts-noto-cjk，CentOS/RHEL 执行sudo yum install -y fontconfig liberation-fonts google-noto-cjk-fonts；
安装 Playwright 浏览器：playwright install --with-deps chromium。

缺少中文字体是"模板渲染出来是方块字"的最常见原因，中文字体（Noto CJK 系列）务必优先安装。

企业官网建设流程全解析