scenario-text-overlay

シナリオのテキストオーバーレイ

概要

生成モデルは文字の種類を間違えることがあるため、正確さが必須のテキストはここで決定論的にレンダリングし、メディアに合成します。1つの JSON ペイロードで1つのオーバーレイを記述し、種類は2つから選べます。テキストレイヤー（ボックス内にスタイルを付けたプレーンテキスト）と、リッチレイヤー（グラデーション、縁取り、影、カードレイアウトを使った 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 スキルを参照してください。オーバーレイとコンテンツの合成はローカルではなく、プラットフォーム上で行います。画像では compose ツールの model_run と model_scenario-compose-image、動画では model_scenario-compose-video を使います（固定 ID です。それぞれが対応するメディア用の Scenario 固有の決定論的コンポジターであり、探索しても再度特定するだけになるためです）。レイヤーの仕様は 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、マルチパートのパス）
5. テンプレートを保存する	asset_update で metadata.description にペイロード JSON を設定し、asset_add_tags で text-overlay を追加します
6. 合成する	model_scenario-compose-image または model_scenario-compose-video の model_run を実行し、オーバーレイを上に重ねます

意味に合った書体を選ぶ

書体はメッセージの一部です。太く幅の狭いサンセリフ体はフック、価格、CTA を強く印象づけます。細身の幾何学的なサンセリフ体やグロテスク体は、中立的で上質な印象を与え、法的表示、ローワーサード、ネームプレートに適しています。セリフ体は編集や伝統を感じさせ、丸みのある書体は親しみやすくカジュアルな印象を与えます。メディアのアートディレクションに合わせ、対立させないようにしてください。カードごとに1つのファミリーを使い、書体を混ぜるのではなく、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 でアップロードし、ペイロード JSON を metadata.description として asset_update を実行してから、 ["text-overlay"] を指定して asset_add_tags を実行します（asset_update 自身の metadata.tags は タグ一式を置き換えます）。これでテンプレートがレンダリング結果とともにプラットフォーム上に保存され、PNG 自体にも tEXt チャンクとして埋め込まれます。
4. スポット動画に合成します。model_scenario-compose-video に対して model_schema_get を実行し、その後、 ベース動画を zIndex 0 に、スーパーをその上の画像レイヤーとして指定して model_run を実行します（レイヤーのフィールド： scenario-video-assembly）。続いて jobs_wait を実行し、その後 asset_display を実行します。
5. フランス語版は同じペイロードの value ひとつを編集するだけで、新しいテンプレートを作成する必要はありません。

よくある間違い

• 変更可能な文字列をテンプレートに埋め込むこと。バリエーションやローカライズは variables の編集で行います。アップロードしたペイロードが再現性の契約となります。
• &、<、> を含む値に {{var}} を使うこと。HTML エスケープされるため、文字どおりのエンティティ文字列として表示されます。{{{var}}} はエスケープを無効にする方法です（Mustache のルール全体についてはペイロードのリファレンスを参照）。
• 画像やフォントをリモート URL のままにすること。data: URI としてインライン化します（Google Fonts のリンクは例外です）。そうしないとレンダリングがネットワークに依存し、結果が変わってしまいます。
• アップロード前の目視確認を省くこと。フォントの解決方法はマシンごとに異なり、透明なキャンバス上の明るい色のテキストはプレビューで見えなくなります。まずコントラストのある背景に重ねてください。
• 代わりに生成モデルにテキストを描かせること。生成された文字はフレームごとに変化します。オーバーレイはまさにそれを避けるためのものです。
• カードを配置する余地を設けずに背景素材を生成すること。ベース画像や動画の作成時には、カードが表示されるすべてのフレームで、オーバーレイの領域をシンプルでテキストのない状態に保つよう指定してください（右側の 3 分の 1 を暗くする、上部の帯を空けるなど）。そうすることで、合成先が生成された文字や細部ではなく、静かな画素になります。
• オーバーレイを Pillow や ffmpeg でローカルに合成すること。合成は compose モデル上での model_run で行うため、完成したクリエイティブは各レイヤーとともにプラットフォーム上に保存されます。
• キャンバスのサイズを出力先と異なるものにすること。ターゲット解像度に合わせれば、後から拡大縮小せずにオーバーレイを 1:1 で合成でき、ぼやけません。生成モデルが正確なサイズを出せない場合、合成実行中にコンテンツレイヤーを拡大縮小できますが、オーバーレイは拡大縮小してはいけません。
• フォールバックがブラウザーと同じ結果になると期待すること。Pillow が描画できるのはプレーンテキストのみです。リッチレイヤーには Chromium 系ブラウザーがインストールされている必要があります。
• 固定サイズのボックスで wrap を信頼すること。テキストがボックスの下にはみ出す可能性があります。ボックスに収める必要がある場合は shrink（収まるか、明確にエラーになります）か clip を使ってください。