Pixelle-Video 源码解析 #22：竖屏、横屏、方形视频：多尺寸适配是怎么实现的？

前面第 21 篇，我们分析了 Pixelle-Video 的视频模板系统，重点讲了 static_、image_、video_ 三类模板的区别。

这一篇继续沿着模板系统往下看一个更实际的问题：

竖屏、横屏、方形视频，Pixelle-Video 是怎么适配的？

短视频工具如果只能生成一种尺寸，实用性会很差。

因为不同平台的视频尺寸需求不一样：

text 复制代码

抖音 / TikTok / YouTube Shorts：
    更适合 9:16 竖屏

YouTube 横屏视频：
    更适合 16:9 横屏

Instagram / 部分社交内容：
    可以使用 1:1 方形

知识卡片 / 图文视频：
    也可能需要其他自定义尺寸

Pixelle-Video 的多尺寸适配，不是简单在最后把视频拉伸一下，而是从模板目录、画布尺寸、媒体尺寸、HTML 渲染、AI 素材生成、ffmpeg 合成多个层面共同完成。

它的核心思路可以概括为：

text 复制代码

模板路径决定画布尺寸
    ↓
HTMLFrameGenerator 根据模板尺寸渲染画面
    ↓
媒体生成可以读取模板中的 media size
    ↓
FrameProcessor 把图片 / 视频素材放入同尺寸画面
    ↓
VideoService 按模板画面尺寸生成 segment
    ↓
多个 segment 拼接成最终视频

一、多尺寸适配的入口不是参数，而是模板路径

很多视频工具会用一个参数控制尺寸，比如：

text 复制代码

ratio = 9:16
width = 1080
height = 1920

Pixelle-Video 的设计更偏模板驱动。

它的模板路径通常长这样：

text 复制代码

1080x1920/image_default.html
1920x1080/image_film.html
1080x1080/image_minimal_framed.html

这里的 1080x1920、1920x1080、1080x1080 不是普通分类名，而是直接代表视频画布尺寸。

在 config.example.yaml 中，默认模板是 1080x1920/image_default.html，配置注释也明确说明模板会决定视频比例和布局样式；示例中列出了竖屏 1080x1920、方形 1080x1080、横屏 1920x1080 三类模板目录。

所以 Pixelle-Video 的尺寸适配入口是：

text 复制代码

frame_template

而不是一个孤立的 aspect_ratio 参数。

这意味着：

text 复制代码

你选择了 1080x1920/image_default.html
    ↓
系统就知道最终画布是 1080x1920

你选择了 1920x1080/image_film.html
    ↓
系统就知道最终画布是 1920x1080

你选择了 1080x1080/image_minimal_framed.html
    ↓
系统就知道最终画布是 1080x1080

模板既决定样式，也决定尺寸。

二、parse_template_size：从目录名解析宽高

真正解析模板尺寸的函数是：

text 复制代码

parse_template_size()

它位于：

text 复制代码

pixelle_video/utils/template_util.py

源码逻辑很直接：它会取模板路径的父目录名，要求这个目录名包含 x，然后把它拆成 width 和 height 两个整数。函数注释中的示例包括 templates/1080x1920/default.html 返回 (1080, 1920)，1920x1080/modern.html 返回 (1920, 1080)。

简化理解就是：

python 复制代码

template_path = "1080x1920/image_default.html"

dir_name = "1080x1920"
width_str, height_str = dir_name.split("x")

width = 1080
height = 1920

如果目录名不符合 WIDTHxHEIGHT 格式，就会抛出错误。

所以自定义模板目录不能随便命名成：

text 复制代码

portrait/
vertical/
mobile/
shorts/

而应该命名成：

text 复制代码

1080x1920/
1920x1080/
1080x1080/

这是 Pixelle-Video 多尺寸适配最底层的约定。

三、竖屏、横屏、方形是如何判断的？

解析出宽高以后，Pixelle-Video 还会判断当前模板属于哪种方向。

在 format_template_display_info() 中，源码根据宽高关系判断 orientation：如果 height > width，就是 portrait；如果 width > height，就是 landscape；如果二者相等，就是 square。同时它只把 1080x1920、1920x1080、1080x1080 这三种尺寸标记为标准尺寸。

可以理解成：

text 复制代码

1080x1920：
    height > width
    portrait 竖屏

1920x1080：
    width > height
    landscape 横屏

1080x1080：
    width == height
    square 方形

这个判断主要服务于 UI 展示和模板分组。

用户在 WebUI 里看到的不应该是一堆杂乱的 HTML 文件，而应该是按尺寸和方向组织好的模板列表。

四、模板列表如何按尺寸分组？

Pixelle-Video 提供了一组模板工具函数：

text 复制代码

list_available_sizes()
list_templates_for_size()
get_all_templates_with_info()
get_templates_grouped_by_size()
get_templates_grouped_by_size_and_type()

list_available_sizes() 会从模板资源目录中列出所有尺寸目录，只保留类似 WIDTHxHEIGHT 的合法目录；list_templates_for_size() 会列出某个尺寸目录下的所有 .html 模板；get_templates_grouped_by_size() 会按尺寸分组，并按方向优先级排序。

也就是说，Pixelle-Video 的模板列表大概是这样组织的：

text 复制代码

portrait:
    1080x1920/
        image_default.html
        image_modern.html
        static_simple.html

landscape:
    1920x1080/
        image_film.html
        image_full.html

square:
    1080x1080/
        image_minimal_framed.html

这就是多尺寸模板能在 WebUI 中比较清楚展示的基础。

五、自定义尺寸为什么也能支持？

虽然配置示例重点列出了 1080x1920、1920x1080、1080x1080 三个常见尺寸，但源码并没有把模板尺寸写死为这三种。

parse_template_size() 只要求目录名符合 WIDTHxHEIGHT，并做了一个基础 sanity check：宽高不能太小，也不能超过 10000。

所以理论上你也可以添加：

text 复制代码

data/templates/1080x1440/image_xhs.html
data/templates/720x1280/image_fast.html
data/templates/1440x1920/image_card.html

只要目录名符合格式，Pixelle-Video 就能解析出宽高。

不过要注意，虽然自定义尺寸可以被解析，但是否适合具体平台、是否适合 AI 图片 / 视频模型、是否适合 ffmpeg 合成，还要看后续工作流和模板设计。

所以更准确地说：

text 复制代码

Pixelle-Video 的模板尺寸解析是开放的
但平台兼容性和生成效果需要自己验证

六、模板资源如何支持默认模板和自定义模板？

Pixelle-Video 的资源系统支持默认资源和用户自定义资源。

模板默认放在：

text 复制代码

templates/

用户自定义模板可以放在：

text 复制代码

data/templates/

resolve_template_path() 会通过资源工具查找模板，并且注释中说明会优先检查 data/templates/，再检查默认 templates/。

底层的 os_util.py 也体现了这个设计：get_data_path() 会确保 data 目录存在，而模板、BGM、workflow 等资源都可以通过资源系统统一管理。

这对多尺寸适配很重要。

因为用户不一定只用项目自带模板。

如果要做自己的账号风格，往往需要自定义：

text 复制代码

竖屏知识卡片模板
横屏教程模板
方形社交媒体模板
小红书图文比例模板

通过 data/templates/，用户不需要直接改项目原始模板目录，也更适合 Docker 或长期部署。

七、resolve_template_path：模板路径如何被标准化？

用户传入的模板路径可能有多种形式：

text 复制代码

None
image_default.html
1080x1920/image_default.html
templates/1080x1920/image_default.html
data/templates/1080x1920/image_default.html

resolve_template_path() 负责把这些输入统一解析成真实模板文件路径。源码注释中说明：如果传入 None，默认使用 1080x1920/image_default.html；如果只传模板文件名，就默认放到 1080x1920 尺寸下；如果传 1080x1920/template.html，就使用指定尺寸；同时还兼容旧路径格式。

这说明 Pixelle-Video 对用户输入做了一层兼容。

比如：

text 复制代码

只传 image_modern.html
    ↓
默认理解为 1080x1920/image_modern.html

传 1920x1080/image_film.html
    ↓
按横屏模板解析

传 None
    ↓
使用默认竖屏 image_default.html

这种设计对普通用户更友好，因为默认就是竖屏短视频。

八、模板尺寸如何进入 HTMLFrameGenerator？

模板路径解析完成以后，会进入：

text 复制代码

HTMLFrameGenerator

在 HTMLFrameGenerator.__init__() 中，源码会加载 HTML 模板，然后调用 parse_template_size(template_path)，把模板路径中的尺寸解析成 self.width 和 self.height。

也就是说，HTML 渲染器本身知道当前画布大小。

流程是：

text 复制代码

frame_template
    ↓
resolve_template_path()
    ↓
templates/1080x1920/image_default.html
    ↓
HTMLFrameGenerator(template_path)
    ↓
parse_template_size(template_path)
    ↓
self.width = 1080
self.height = 1920

这一步很关键。

因为后面 Playwright 截图时，需要知道浏览器 viewport 应该设置成多大。

九、HTML 渲染如何保证画布尺寸？

HTMLFrameGenerator.generate_frame() 会使用 Playwright 启动 Chromium 页面，把 viewport 设置成模板解析出的宽高，然后访问临时 HTML 文件并截图输出 PNG。源码注释也说明，视频尺寸会在初始化时从模板路径自动确定。

所以：

text 复制代码

1080x1920 模板
    ↓
Playwright viewport = 1080x1920
    ↓
截图 PNG = 1080x1920

1920x1080 模板
    ↓
Playwright viewport = 1920x1080
    ↓
截图 PNG = 1920x1080

1080x1080 模板
    ↓
Playwright viewport = 1080x1080
    ↓
截图 PNG = 1080x1080

这就是 Pixelle-Video 多尺寸适配的核心之一：

不是最后强行裁剪，而是在 HTML 渲染阶段就生成正确尺寸的画面。

十、模板画布尺寸和 AI 媒体尺寸不是一回事

这里有一个很容易混淆的点：

text 复制代码

模板画布尺寸
    不一定等于 AI 图片 / 视频素材尺寸

模板画布尺寸决定最终视频画面，例如：

text 复制代码

1080x1920

但 AI 生成图片可能只需要：

text 复制代码

1024x1024

然后放在竖屏画布中的某个区域。

Pixelle-Video 在 HTMLFrameGenerator 中支持从模板 meta 标签解析媒体尺寸，例如：

html 复制代码

<meta name="template:media-width" content="1024">
<meta name="template:media-height" content="1024">

源码中的 _parse_media_size_from_meta() 会查找这两个 meta 标签，get_media_size() 则返回模板指定的媒体生成尺寸。

所以一套模板可以同时表达两个层次：

text 复制代码

画布尺寸：
    最终 frame / segment 的尺寸

媒体尺寸：
    AI 图片或视频素材生成尺寸

这对多尺寸适配非常重要。

例如竖屏短视频不一定要生成一张 1080x1920 的图片，也可以生成一张方图，然后由 HTML 模板决定它怎么摆放。

十一、media_width / media_height 从哪里来？

在 StoryboardConfig 中，有 media_width 和 media_height 字段，用来保存媒体生成尺寸；同时还有 frame_template 字段，用来保存模板路径。

在 StandardPipeline.initialize_storyboard() 中，Pixelle-Video 会把请求参数里的 media_width、media_height、media_workflow、frame_template、template_params 写入 StoryboardConfig。如果用户没有传 frame_template，源码里会使用默认值。

可以理解成：

text 复制代码

frame_template：
    决定最终画布和模板布局

media_width / media_height：
    决定 AI 图片 / 视频素材生成尺寸

两者最好配合使用，但不是同一个概念。

十二、FrameProcessor 如何把尺寸传给媒体生成？

进入单帧处理时，FrameProcessor._step_generate_media() 会把配置中的 media_width、media_height 传给 self.core.media()，同时传入当前 frame 的 image_prompt、media_workflow、media_type、output_path 等参数。

也就是说，AI 媒体生成的尺寸来自：

text 复制代码

config.media_width
config.media_height

而不是直接从最终视频尺寸硬推。

这给了用户更大的灵活性：

text 复制代码

竖屏视频：
    画布 1080x1920
    插图 1024x1024

横屏视频：
    画布 1920x1080
    背景图 1920x1080

方形视频：
    画布 1080x1080
    插图 1024x1024

如果模板设计合理，AI 媒体尺寸可以和最终画布尺寸不同。

十三、image 模板中的尺寸适配

对于 image 模板，AI 图片会先生成 image_path，然后传入 HTML 模板。

流程是：

text 复制代码

image_prompt
    ↓
MediaService 生成 image_path
    ↓
HTMLFrameGenerator 用模板画布尺寸渲染
    ↓
图片被放入 HTML 布局中
    ↓
输出 composed_image_path
    ↓
create_video_from_image()
    ↓
segment.mp4

这里的关键是：

text 复制代码

AI 图片尺寸影响图片清晰度和构图
模板画布尺寸影响最终视频尺寸
CSS 布局决定图片如何适配画布

比如竖屏模板可以把方形图片放在上半部分，下面放大字幕；横屏模板可以把图片铺满背景，再叠加标题；方形模板可以做成社交媒体卡片。

所以 image 模板的多尺寸适配主要靠：

text 复制代码

模板目录尺寸
    +
HTML/CSS 布局
    +
媒体生成尺寸

三者配合。

十四、video 模板中的尺寸适配

video 模板会更复杂一些。

它通常会先生成 AI 视频素材 video_path，然后 HTML 模板生成透明 overlay，最后用 ffmpeg 把 overlay 叠加到视频上。

FrameProcessor 中，当模板类型是 video 或 workflow 名称包含 video_ 时，media_type 会被设置为 video。如果当前帧已经有 TTS 音频时长，还会把 duration 传给媒体生成服务。

后续在视频合成阶段，VideoService.overlay_image_on_video() 支持 contain、cover、stretch 三种缩放方式，用来把底层视频适配到 overlay 图片尺寸。

所以 video 模板的尺寸适配链路是：

text 复制代码

模板尺寸
    ↓
HTML overlay 尺寸

AI 视频素材尺寸
    ↓
可能和模板尺寸不一致

overlay_image_on_video()
    ↓
把视频缩放 / 裁剪 / 补边到 overlay 尺寸
    ↓
叠加字幕层

这说明 Pixelle-Video 在 video 模板中不是简单假设视频素材尺寸一定正确，而是在 ffmpeg 层做了适配。

十五、contain、cover、stretch 三种缩放方式怎么理解？

在视频 overlay 场景中，素材尺寸和模板尺寸可能不一致。

例如：

text 复制代码

AI 视频：1024x1024
模板画布：1080x1920

如果直接叠加，会尺寸不匹配。

overlay_image_on_video() 提供了三种缩放方式：

text 复制代码

contain：
    保持比例完整显示，可能出现黑边或留白。

cover：
    保持比例铺满目标画面，可能裁剪边缘。

stretch：
    强制拉伸到目标尺寸，可能变形。

源码中 contain 通过 scale + pad 实现，cover 通过 scale + crop 实现，stretch 则直接缩放到目标宽高。

实际使用建议：

text 复制代码

人物口播：
    优先 contain，避免裁掉脸。

风景 / 氛围素材：
    可以用 cover，让画面铺满。

抽象背景：
    可以接受 stretch，但要小心变形。

Pixelle-Video 默认在视频分支中使用 contain，这更保守，也更不容易裁掉主体。

十六、图片转视频时，最终尺寸来自哪里？

对于 image 或 static 模板，最终 segment 由：

text 复制代码

composed_image_path + audio_path

生成。

VideoService.create_video_from_image() 会把一张图片作为静态帧，并让输出视频持续时间等于音频时长；源码注释说明它适合从 storyboard frame 创建视频片段。

因为 composed_image_path 是 HTMLFrameGenerator 按模板画布尺寸渲染出来的，所以图片转视频的最终尺寸自然继承模板尺寸：

text 复制代码

1080x1920 composed image
    ↓
1080x1920 segment.mp4

1920x1080 composed image
    ↓
1920x1080 segment.mp4

1080x1080 composed image
    ↓
1080x1080 segment.mp4

这就是 Pixelle-Video 多尺寸合成比较稳定的原因：

先生成正确尺寸的模板画面，再把它变成视频。

十七、最终拼接为什么要求尺寸一致？

Pixelle-Video 最后会把所有 frame 的 video_segment_path 拼接成最终视频。

VideoService.concat_videos() 支持两种方式：demuxer 和 filter。源码注释中说明，demuxer 快、不会重新编码，但要求片段格式一致；filter 慢一些，但能处理不同格式。

如果同一条视频里，有的 segment 是 1080x1920，有的是 1920x1080，就很容易拼接失败，或者最终结果异常。

所以 Pixelle-Video 的多尺寸适配是以"单个任务使用同一个 frame_template"为前提：

text 复制代码

整条竖屏视频：
    所有 frame 都使用 1080x1920 模板

整条横屏视频：
    所有 frame 都使用 1920x1080 模板

整条方形视频：
    所有 frame 都使用 1080x1080 模板

这样每个 segment 的画布尺寸一致，后续拼接更稳定。

十八、为什么不建议最后强行转换尺寸？

有些工具的做法是：先随便生成素材，最后统一拉伸成目标比例。

这种方式简单，但效果容易出问题：

text 复制代码

人物被拉胖
字幕位置错位
边缘被裁掉
画面主体被压缩
横屏硬裁成竖屏，内容丢失
竖屏硬拉成横屏，画面变形

Pixelle-Video 的思路更合理：

text 复制代码

先选目标尺寸模板
    ↓
从一开始就按这个画布布局
    ↓
AI 图片 / 视频只作为模板里的媒体素材
    ↓
最终 segment 自然就是目标尺寸

这样不会把尺寸适配压力全部压到最后一步。

尤其是短视频字幕很重要。

如果最后才裁剪，很可能把字幕裁掉。

如果一开始就在目标画布里设计字幕安全区，最终效果会稳定得多。

十九、多尺寸适配和模板类型的关系

不同模板类型下，多尺寸适配方式也不同。

1. static 模板

static 模板不生成 AI 媒体，只用 HTML / CSS / 文字生成画面。

text 复制代码

模板路径 1080x1920/static_simple.html
    ↓
HTML 直接渲染 1080x1920 画面
    ↓
图片 + TTS 音频
    ↓
竖屏 segment

它的尺寸适配最简单，主要靠 HTML/CSS。

2. image 模板

image 模板需要处理 AI 图片和画布之间的关系。

text 复制代码

AI 图片尺寸：
    可能是 1024x1024 或 1080x1920

模板画布尺寸：
    由 1080x1920 / 1920x1080 / 1080x1080 决定

HTML/CSS：
    决定图片如何 fit 到画布中

它的重点是布局。

3. video 模板

video 模板还要处理 AI 视频素材和 overlay 的尺寸关系。

text 复制代码

AI 视频素材
    ↓
overlay_image_on_video()
    ↓
适配到模板 overlay 尺寸
    ↓
叠加字幕层

它的重点是素材缩放、裁剪和字幕区域。

二十、多尺寸适配和 prompt 的关系

尺寸不只是技术问题，也会影响 prompt。

同样一句旁白，在竖屏、横屏、方形里，画面构图应该不一样。

例如：

text 复制代码

旁白：
    他站在城市天桥上，看着远处的灯光。

竖屏更适合：

text 复制代码

人物站在画面下方，城市灯光向上延伸，留出上方空间放标题。

横屏更适合：

text 复制代码

人物在画面左侧，右侧是宽阔城市夜景，适合横向构图。

方形更适合：

text 复制代码

人物居中，背景简洁，标题和字幕上下分布。

Pixelle-Video 当前的模板系统已经能表达画布尺寸和媒体尺寸，但 prompt 生成层还可以进一步增强：根据模板尺寸自动加入构图提示。

例如：

text 复制代码

竖屏模板：
    vertical composition, clean space at bottom for subtitles

横屏模板：
    wide cinematic composition, subject on left third

方形模板：
    centered composition, balanced layout

这会让 AI 配图和模板更匹配。

二十一、多尺寸适配和字幕安全区

短视频里，字幕不是可有可无的装饰。

尤其是竖屏视频，底部常常会被平台 UI 挡住：

text 复制代码

抖音 / TikTok 右侧按钮
底部标题区
评论输入栏
平台水印

所以多尺寸模板设计时，要考虑字幕安全区。

Pixelle-Video 的 HTML 模板系统支持自定义参数，占位符语法类似 {``{param:type=default}}，并支持 text、number、color、bool 等类型；这些参数可以被替换到最终 HTML 中。

这意味着可以在模板里做一些可调节参数：

html 复制代码

{{subtitle_bottom:number=260}}
{{subtitle_width:number=860}}
{{title_top:number=120}}
{{safe_area_enabled:bool=true}}

然后让用户根据平台调整字幕位置。

这比把字幕位置写死更适合多平台发布。

二十二、多尺寸适配的完整链路

把前面内容串起来，Pixelle-Video 的多尺寸适配链路是：

text 复制代码

【模板选择】
frame_template = 1080x1920/image_default.html
    ↓
【路径解析】
resolve_template_path()
    ↓
真实模板文件路径
    ↓
【尺寸解析】
parse_template_size()
    ↓
width = 1080
height = 1920
    ↓
【HTML 渲染】
HTMLFrameGenerator
    ↓
Playwright viewport = 1080x1920
    ↓
composed_image_path
    ↓
【媒体生成】
media_width / media_height
    ↓
AI 图片或视频素材
    ↓
【单段合成】
image:
    composed image + audio → segment

video:
    AI video + overlay → segment
    ↓
【最终拼接】
所有 segment 尺寸一致
    ↓
concat_videos()
    ↓
final.mp4

这条链路说明：

Pixelle-Video 的尺寸不是最后才处理，而是从模板选择开始就贯穿整个生成过程。

二十三、自定义多尺寸模板怎么做？

如果你想给 Pixelle-Video 添加自己的尺寸模板，可以按下面步骤。

第一，选择尺寸目录：

text 复制代码

data/templates/1080x1920/
data/templates/1920x1080/
data/templates/1080x1080/

或者自定义：

text 复制代码

data/templates/1080x1440/

第二，按模板类型命名：

text 复制代码

static_my_card.html
image_my_story.html
video_my_overlay.html

第三，确保 HTML 中按目标尺寸设计布局。

例如竖屏模板要考虑：

text 复制代码

顶部标题
中间图片 / 视频区域
底部字幕安全区
左右平台按钮遮挡

横屏模板要考虑：

text 复制代码

左图右文
全屏背景
底部字幕
电影字幕条

方形模板要考虑：

text 复制代码

中心构图
上下标题字幕
卡片边距
社交平台裁切

第四，如果需要控制 AI 素材尺寸，可以在模板里加入：

html 复制代码

<meta name="template:media-width" content="1024">
<meta name="template:media-height" content="1024">

第五，使用模板参数暴露可调配置：

html 复制代码

{{accent_color:color=#ff6600}}
{{subtitle_bottom:number=240}}
{{font_size:number=46}}

第六，在 WebUI 或配置中选择：

text 复制代码

1080x1920/image_my_story.html

这样 Pixelle-Video 就能从模板路径解析尺寸，并按你的模板布局生成视频。

二十四、常见问题排查

1. 模板尺寸解析失败

检查模板所在目录是否是 WIDTHxHEIGHT 格式。

正确：

text 复制代码

1080x1920/image_default.html

错误：

text 复制代码

vertical/image_default.html
mobile/image_default.html

parse_template_size() 会从父目录名解析宽高，如果目录名不符合格式会抛出错误。

2. 只写模板文件名，为什么默认变成竖屏？

这是 resolve_template_path() 的设计：如果只传模板名，会默认使用 1080x1920 尺寸；如果传 None，则使用默认 1080x1920/image_default.html。

所以想用横屏，要明确传：

text 复制代码

1920x1080/image_film.html

3. 自定义模板不显示

检查：

text 复制代码

是否放在 data/templates/尺寸目录下
尺寸目录是否符合 WIDTHxHEIGHT
文件是否以 .html 结尾
文件名前缀是否是 static_ / image_ / video_

模板列表函数只会列出合法尺寸目录下的 .html 文件。

4. 竖屏视频里图片被裁掉

这通常是模板 CSS 问题。

如果 AI 图片是方图，而模板把它设置成全屏 cover，上下或左右就可能被裁剪。

可以在模板中改成 contain，或者调整图片容器比例。

5. 视频 overlay 后人物被裁掉

如果 video 模板中素材尺寸和 overlay 尺寸差异大，overlay_image_on_video() 的缩放策略会影响结果。contain 保留完整画面但可能留白，cover 铺满但可能裁剪，stretch 可能变形。

6. 最终拼接失败

优先检查所有 segment 的尺寸、编码、音频轨是否一致。concat_videos() 默认使用 demuxer，速度快但要求格式一致；格式差异较大时可以考虑 filter 模式。

7. 中文显示不正常

HTMLFrameGenerator 在 Linux 下会检查 fontconfig，并在缺少字体时提示安装字体依赖。中文模板最好确保系统有 CJK 字体，否则可能出现缺字或显示效果差。

二十五、这套多尺寸设计的优点

Pixelle-Video 的多尺寸适配设计有几个明显优点。

1. 模板驱动，逻辑简单

用户选择哪个模板，就决定了最终尺寸和布局。

2. 支持常见平台尺寸

配置示例中已经列出竖屏、横屏、方形三类常见尺寸，默认模板也是竖屏。

3. 支持自定义尺寸

只要目录名符合 WIDTHxHEIGHT 格式，就可以扩展自己的尺寸。

4. 画布尺寸和媒体尺寸分离

最终视频可以是竖屏，但 AI 插图可以是方图。

这让模板布局更灵活。

5. HTML/CSS 控制布局

懂前端的人可以直接通过 CSS 调整图片位置、字幕区、边距、遮罩和安全区。

6. image / video / static 都能复用

三类模板都可以按尺寸目录组织，不需要为每种尺寸单独改 pipeline。

二十六、这套多尺寸设计的局限

当然，这套设计也有一些局限。

1. 依赖目录命名约定

尺寸信息藏在目录名里。

如果目录名写错，系统就无法解析。

2. 模板和媒体 workflow 没有强约束

一个竖屏模板可能搭配了一个只适合方图的工作流。

系统可以运行，但效果不一定好。

3. prompt 未必自动适配构图

竖屏、横屏、方形对应不同构图逻辑。

当前更依赖 prompt_prefix 和模板布局，后续可以进一步根据尺寸自动增强 prompt。

4. 平台安全区需要模板作者自己考虑

系统能渲染不同尺寸，但不会自动知道每个平台 UI 会挡住哪里。

5. 混合尺寸片段不适合放在同一条视频里

最终拼接最好保证所有 segment 尺寸一致，否则容易出现拼接或编码问题。

二十七、二次开发可以怎么优化？

如果基于 Pixelle-Video 做产品化，多尺寸适配可以继续增强。

1. 增加平台预设

让用户选择：

text 复制代码

抖音 / TikTok
YouTube Shorts
YouTube 横屏
Instagram Square
小红书图文视频

系统自动选择推荐尺寸、模板和字幕安全区。

2. 增加模板能力声明

为每个模板配一个 metadata 文件：

json 复制代码

{
  "size": "1080x1920",
  "orientation": "portrait",
  "safe_area": {
    "top": 120,
    "bottom": 280,
    "right": 140
  },
  "recommended_media_size": "1024x1024",
  "recommended_prompt_prefix": "vertical composition..."
}

这样就不用完全依赖目录和文件名约定。

3. 根据尺寸自动增强 prompt

例如：

text 复制代码

竖屏：
    vertical composition, subject centered, leave space for subtitles

横屏：
    cinematic wide shot, subject on left third

方形：
    centered composition, balanced layout

让 AI 生成素材时就考虑最终画布。

4. 增加尺寸兼容检查

生成前检查：

text 复制代码

模板尺寸
媒体尺寸
workflow 支持的比例
视频模型支持的 ratio
最终拼接方式

如果不匹配，提前提醒用户。

5. 增加自动重排版

同一个内容可以自动生成三版：

text 复制代码

竖屏版
横屏版
方形版

每一版使用不同模板，而不是简单裁剪同一个视频。

这对多平台分发很有价值。

二十八、源码阅读建议

如果你要阅读 Pixelle-Video 的多尺寸适配源码，建议按这个顺序：

text 复制代码

1. config.example.yaml
   看 template.default_template，以及 1080x1920 / 1920x1080 / 1080x1080 的配置说明。

2. pixelle_video/utils/template_util.py
   看 parse_template_size()、resolve_template_path()、format_template_display_info()。

3. pixelle_video/utils/template_util.py
   看 list_available_sizes()、list_templates_for_size()、get_templates_grouped_by_size()。

4. pixelle_video/services/frame_html.py
   看 HTMLFrameGenerator 如何从模板路径解析 width / height，并用 Playwright 渲染 PNG。

5. pixelle_video/services/frame_html.py
   看 template:media-width 和 template:media-height 如何声明媒体尺寸。

6. pixelle_video/models/storyboard.py
   看 StoryboardConfig 中 frame_template、media_width、media_height 的关系。

7. pixelle_video/pipelines/standard.py
   看 initialize_storyboard() 如何把 frame_template 和 media size 写入 config。

8. pixelle_video/services/frame_processor.py
   看 media_width / media_height 如何传给 MediaService。

9. pixelle_video/services/video.py
   看 create_video_from_image()、overlay_image_on_video()、concat_videos() 如何完成最终合成。

这样读下来，就能完整理解：

text 复制代码

模板尺寸
    ↓
HTML 渲染尺寸
    ↓
AI 媒体尺寸
    ↓
segment 尺寸
    ↓
最终视频尺寸

二十九、总结

这一篇我们分析了 Pixelle-Video 的多尺寸适配设计。

它的核心不是最后把视频强行裁成竖屏、横屏或方形，而是从模板路径开始就决定画布尺寸。

完整链路可以总结为：

text 复制代码

frame_template = 1080x1920/image_default.html
    ↓
resolve_template_path()
    ↓
parse_template_size()
    ↓
width = 1080
height = 1920
    ↓
HTMLFrameGenerator 设置对应 viewport
    ↓
渲染 composed_image_path
    ↓
FrameProcessor 生成 image_path / video_path
    ↓
VideoService 合成 segment
    ↓
concat_videos() 拼接最终视频

从源码看，Pixelle-Video 的多尺寸适配有几个关键点：

text 复制代码

模板目录名使用 WIDTHxHEIGHT 格式。
parse_template_size() 从父目录名解析画布宽高。
format_template_display_info() 根据宽高判断 portrait / landscape / square。
默认模板是 1080x1920/image_default.html。
resolve_template_path() 支持 None、文件名、尺寸路径和旧路径格式。
HTMLFrameGenerator 根据模板尺寸设置渲染画布。
模板 meta 标签可以声明 AI 媒体生成尺寸。
StoryboardConfig 同时保存 frame_template 和 media_width / media_height。
FrameProcessor 把 media_width / media_height 传给媒体生成服务。
图片模式依赖 composed image 的尺寸生成 segment。
视频模式通过 overlay_image_on_video() 把视频素材适配到 overlay 尺寸。
最终拼接要求各 segment 尺寸和格式尽量一致。

一句话总结：

Pixelle-Video 的竖屏、横屏、方形适配，本质是用 WIDTHxHEIGHT/template.html 这种模板路径约定，把画布尺寸、HTML 渲染、AI 媒体生成和 ffmpeg 合成串成一条链路，让不同平台尺寸从生成开始就被纳入设计，而不是最后临时裁剪。