scenario-text-overlay

场景文字叠加层

概览

生成模型对文字的处理会出现偏差，因此这里会确定性地渲染必须准确呈现的文字，并将其合成到媒体上。一个 JSON 负载描述一个叠加层，分为两种类型：文字图层（框内的纯样式文字）或富文本图层（HTML/CSS 排版：渐变、描边、阴影、卡片布局）。两种类型都会在透明画布上严格替换 Mustache {{variables}}（缺少变量会导致渲染失败）。

scripts/overlay.py 会使用已安装的 Chromium 系浏览器（自动发现，支持两种类型）或 Pillow 回退方案（仅支持文字图层），将负载渲染为 PNG，把负载 JSON 嵌入 PNG，并输出路径。其模块包括：scripts/templating.py（严格 Mustache），scripts/html_render.py（浏览器引擎），scripts/pillow_render.py（回退方案）。逐字段说明和示例负载见 references/payloads.md。脚本需要 pip install chevron pillow。

连接方式和 MCP 核心循环：请参阅 scenario 技能。叠加层会在平台上与内容合成，而非本地合成：在合成工具上调用 model_run，静态图像使用 model_scenario-compose-image，视频使用 model_scenario-compose-video（固定 ID：两者分别是 Scenario 针对相应媒体的单一确定性合成器，因此发现它们只会再次推导出这些 ID），图层约定见 scenario-video-assembly。如果当前可用技能中缺少此处提及的同级技能，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；无人值守时，请根据工具架构继续操作，并注明这一缺口。

快速参考

步骤	详情
1. 编写负载	通过字段指定类型（text_template 或 html_template）；所有可变字符串都放在 variables 中
2. 渲染	python3 overlay.py --payload card.json --out card.png
3. 验证	打开 PNG：逐字检查字形、确认文本框位置正确、背景透明
4. 上传	upload_asset（类型为 image，通过 multipart 路径上传）
5. 持久化模板	asset_update 将 metadata.description 设为负载 JSON；asset_add_tags 添加 text-overlay
6. 合成	在 model_scenario-compose-image 或 model_scenario-compose-video 上调用 model_run，并将叠加层置于顶部

根据含义选择字体

字体本身就是信息的一部分：粗重的紧缩无衬线字体适合大声强调（吸引注意的文案、价格、行动号召），轻盈的几何无衬线或怪诞体无衬线字体显得中性且高级（法律声明、下三分之一字幕、人名牌），衬线字体传递编辑感或历史底蕴，圆润字形则显得友好随和。应与媒体的艺术指导相匹配，而非与之冲突；每张卡片使用一个字体家族，并通过 font_weight（100 到 900）和字号建立层次，而不是混用字体。font_family 可使用任意 Google Fonts 字体家族，因此上述每类字体都可以按名称使用；符合合同要求的品牌字体则通过 font_url 指定。文字只有清晰易读时才能传达含义，因此应在目标尺寸下检查扁平化预览，避免细微的字体差异变得平庸。

示例：本地化法律字幕

1. 载荷，其中可更改的行作为变量：

{
  "text_template": "{{disclaimer}}",
  "variables": [
    {
      "key": "disclaimer",
      "value": "EPA-estimated 310 mi. Actual range varies."
    }
  ],
  "font_family": "Inter",
  "font_weight": 500,
  "size": 34,
  "color": "#FFFFFF",
  "align": "center",
  "bbox": [{ "x": 86, "y": 1560, "w": 908, "h": 120 }],
  "canvas_width": 1080,
  "canvas_height": 1920,
  "overflow": "shrink"
}

2. 运行 python3 overlay.py --payload super.json --out super.png，然后打开 super.png：该行必须 按原文准确显示，并缩小到适合文本框的大小。
3. 使用 upload_asset 上传，然后调用 asset_update，将载荷 JSON 作为 metadata.description， 再调用 asset_add_tags 并传入 ["text-overlay"]（asset_update 自身的 metadata.tags 会替换 整个标签集）：现在模板与渲染结果一同保存在平台上，PNG 文件本身也通过 tEXt 块携带该载荷。
4. 将其合成到视频片段上：对 model_scenario-compose-video 调用 model_schema_get，然后调用 model_run， 将基础视频设为 zIndex 0，并将字幕作为位于其上方的图像图层（图层字段： scenario-video-assembly）；接着调用 jobs_wait，然后调用 asset_display。
5. 法语版本使用相同的载荷，只编辑一个 value，绝不新建模板。

常见错误

• 将可更改的字符串直接写入模板：不同版本和本地化应通过编辑 variables 完成；上传的载荷是可复现性的约定。
• 对包含 &、< 或 > 的值使用 {{var}}：它会进行 HTML 转义，因此渲染时会显示为字面实体文本； {{{var}}} 是原样输出的选项（完整 Mustache 规则：参阅载荷参考）。
• 将图像或字体保留为远程 URL：应内嵌为 data: URI（Google Fonts 链接除外）， 否则渲染会依赖网络，结果也会发生变化。
• 上传前跳过视觉检查：不同机器上的字体解析结果不同，而且透明画布上的浅色文本预览时会像空白一样； 先将其平铺到对比鲜明的背景上。
• 让生成模型直接绘制文本：生成的文字会逐帧变化；覆盖层正是为避免这种情况而设计的。
• 生成底图时没有为卡片留出空间：应在基础图像或视频的提示词中说明，覆盖层所在区域必须保持简单、无文字 （例如右侧三分之一为暗色、顶部留空），并确保卡片显示的每一帧都如此，这样合成结果会落在干净的像素上， 而不是生成的字样或细节上。
• 使用 Pillow 或 ffmpeg 在本地合并覆盖层：合成应通过合成模型上的 model_run 完成， 这样最终创意素材会与各图层一同保存在平台上。
• 将画布尺寸设为与目标尺寸不同的值：应匹配目标分辨率，让覆盖层以 1:1 比例合成，不会因后期缩放而模糊。 如果生成模型无法达到精确尺寸，内容图层可以在合成运行中缩放；覆盖层则不能缩放。
• 期望回退方案与浏览器效果一致：Pillow 只能绘制纯文本；丰富图层需要安装 Chromium 系列浏览器。
• 在固定文本框中信任 wrap：它会让文本溢出到框外；文本框大小必须严格遵守时，应使用 shrink（适配或明确报错） 或 clip。