# ComfyUI-RogoAI-PromptRelay

**Wan2.2 I2V** と **LTX-Video 2.3** に対応した Prompt Relay ComfyUI カスタムノードです。

複数シーンを **Latent 空間で直接連結**することで、pixel連結方式と比べてキャラクターのドリフトを抑制し、長尺動画のIP一貫性を向上させます。

![RogoAI](https://img.shields.io/badge/RogoAI-Takeji-blue)
![ComfyUI](https://img.shields.io/badge/ComfyUI-Custom%20Node-orange)
![License](https://img.shields.io/badge/License-MIT-green)

---

## Prompt Relay とは

[Prompt Relay (arXiv:2604.10030)](https://arxiv.org/abs/2604.10030) は、NTU S-Lab の Gordon Chen らが提案した推論時プロンプトルーティング手法です。

動画生成モデルの **Cross-Attention** にペナルティ項 **C** を注入することで、各テキストプロンプトが担当する時間セグメントにのみ影響を与えます。

```
Attn(Q, K, V) = softmax(QKᵀ/√d - C(Q, K)) V
```

- **グローバルプロンプト** → ペナルティなし → 全フレームに影響
- **ローカルプロンプト** → ペナルティあり → 担当セグメントのみに影響

---

## Pixel連携 vs Latent連携

| | Pixel連携（従来） | Latent連携（Prompt Relay） |
|---|---|---|
| シーン接続 | VAEデコード → pixel → VAEエンコード | Latent空間で直接連結 |
| 情報ロス | VAE往復で劣化あり | 劣化なし |
| キャラドリフト | 蓄積しやすい | 抑制される |
| シーン境界 | ハードカット | スムーズなブレンド |

---

## 対応モデル

| モデル | フレーム数 | シーン数 | 備考 |
|--------|-----------|---------|------|
| **Wan2.2 I2V** | 81フレーム（約3秒） | 2〜3シーン | WanVideoWrapper経由 |
| **LTX-Video 2.3** | 最大993フレーム（約40秒） | 5〜8シーン以上 | Kijai workflow推奨 |

> **注意**: Wan2.2はWanVideoWrapperの81フレーム上限により、長尺のPrompt Relayには不向きです。長尺動画にはLTX-Video 2.3をお勧めします。

---

## ノード一覧

### `RogoAI Prompt Relay (Wan2.2 I2V)`

Wan2.2 I2V 用の Prompt Relay エンコードノードです。

**入力:**

| パラメータ | 型 | 説明 |
|-----------|-----|------|
| model | WANVIDEOMODEL | Wan2.2モデル |
| t5 | WANTEXTENCODER | T5テキストエンコーダー |
| global_prompt | STRING | 全シーン共通プロンプト（キャラクター・場所・照明） |
| negative_prompt | STRING | ネガティブプロンプト |
| local_prompt_1〜6 | STRING | 各シーンのプロンプト（1〜6シーン） |
| segment_lengths | STRING | 各シーンのlatentフレーム数（例: `7,7,7`） |
| frame_num | INT | 総フレーム数（デフォルト: 81） |
| width / height | INT | 解像度（デフォルト: 832×480） |
| epsilon | FLOAT | セグメント境界の減衰係数（デフォルト: 0.001） |
| force_offload | BOOLEAN | T5をオフロードするか |

**出力:**

| 出力 | 型 | 説明 |
|------|-----|------|
| model | WANVIDEOMODEL | Prompt Relayパッチ済みモデル |
| text_embeds | WANVIDEOTEXTEMBEDS | テキスト埋め込み |

---

### `RogoAI Prompt Relay Seg Calc`

フレーム数とシーン数からセグメント長を自動計算する補助ノードです。

**入力:**

| パラメータ | 型 | 説明 |
|-----------|-----|------|
| frame_num | INT | 総フレーム数 |
| num_segments | INT | シーン数（1〜6） |

**出力:**

| 出力 | 型 | 説明 |
|------|-----|------|
| segment_lengths | STRING | 自動計算されたセグメント長（例: `7,7,7`） |
| latent_frames | INT | latentフレーム総数 |

---

## インストール

### 方法1: ComfyUI Manager（推奨）
1. ComfyUI Manager を開く
2.「Custom Nodes」→「Install via Git URL」
3. 以下のURLを入力:
```
https://github.com/RogoAI-Takeji/ComfyUI-RogoAI-PromptRelay
```

### 方法2: 手動インストール

```powershell
cd <ComfyUIフォルダ>\custom_nodes
git clone https://github.com/RogoAI-Takeji/ComfyUI-RogoAI-PromptRelay
```

依存ライブラリは ComfyUI-WanVideoWrapper に含まれているため、追加インストールは不要です。

---

## 使い方

### 基本ワークフロー（Wan2.2）

```
[Load Wan Model] ──→ [RogoAI Prompt Relay (Wan2.2 I2V)] ──→ [WanVideo Sampler]
[Load T5]        ──→                                              ↓
[Load Image]     ──────────────────────────────────────→ [WanVideo I2V Encode]
```

### プロンプト設計のコツ

**グローバルプロンプト（短く・一貫性要素のみ）:**
```
A young woman with long black wavy hair and blue headphones,
sitting at a PC desk, realistic cinematic lighting.
```

**ローカルプロンプト（動作・カメラのみ）:**
```
Scene 1: She faces the camera directly with a calm expression.
Scene 2: She turns her head away, looking at the monitor.
Scene 3: She turns back to the camera with a slight smile.
```

### segment_lengths の計算

```
81フレーム → latent_frames = (81-1)÷4+1 = 21
3シーンで均等: 7,7,7
2シーンで均等: 11,10

※ RogoAI Prompt Relay Seg Calc ノードで自動計算できます
```

### 参照画像について

I2V の参照画像（first-frame）は **VAE latent として全フレームに影響**します。

- キャラクターの顔・外見一貫性のために**クローズアップ画像を推奨**
- グローバルプロンプトと参照画像の組み合わせがIP一貫性の二本柱です

---

## LTX-Video 2.3 での利用

LTX-Video 2.3 では [Kijai の ComfyUI-LTXVideo](https://github.com/kijai/ComfyUI-LTXVideo) の Prompt Relay workflow を使用することを推奨します（2026年4月19日公表）。

LTX-Video 2.3 が Wan2.2 より Prompt Relay の効果が高い理由：

| 要因 | Wan2.2 | LTX-Video 2.3 |
|------|--------|---------------|
| 空間トークン解像度 | 粗い（≈16px/token） | 細かい（≈8px/token） |
| Attention構造 | 空間・時間分離 | Full Spatiotemporal統合 |
| 蒸留 | あり | なし |
| 最大フレーム数 | 81（ComfyUI） | 993（約40秒） |

---

## 制限事項

- Wan2.2は81フレーム上限のため**2〜3シーンが現実的**
- 複数人物の同時アクション制御は困難（Cross-Attentionの空間解像度の制約）
- 激しい動きのシーンはPrompt Relay効果が出にくい場合があります

---

## 関連リポジトリ

- [ComfyUI-RogoAI-APIImageGen](https://github.com/RogoAI-Takeji/ComfyUI-RogoAI-APIImageGen) - Gemini / OpenAI gpt-image-2 画像生成ノード
- [ComfyUI-RogoAI-4DTimelapse](https://github.com/RogoAI-Takeji/ComfyUI-RogoAI-4DTimelapse) - 4Dタイムラプス生成ノード
- [ComfyUI-RogoAI-Music](https://github.com/RogoAI-Takeji/ComfyUI-RogoAI-Music) - ACE-Step音楽生成ノード

---

## 参考文献

```
@article{chen2026prompt,
  title={Prompt Relay: Inference-Time Temporal Control for Multi-Event Video Generation},
  author={Chen, Gordon and Huang, Ziqi and Liu, Ziwei},
  journal={arXiv preprint arXiv:2604.10030},
  year={2026}
}
```

---

## ライセンス

MIT License

---

## 老後AI (RogoAI) チャンネル

**「高齢者にはやり直す時間がない」**

YouTube: [老後AI](https://www.youtube.com/@RogoAI)
GitHub: [RogoAI-Takeji](https://github.com/RogoAI-Takeji)