# ComfyUI-H3-Continuum 3.8.3 — V3.8X2 ## mainのLoader保存・復元修正(2026-09-21、3.8.3以降) 現行V3.8X2ワークフローは、音声を **Core Load Audio**、動画を **Core Load Video → H3 Continuum Video Adapter** に変更しました。Video Adapterは24fpsへの変換(Force Rate初期値24)とIMAGE/AUDIO出力だけを担当し、**Enableやファイル選択UIはありません**。動画を使わない場合はAdapter、または動画入力グループ全体をBypassしてください。Load VideoだけをBypassして必須入力のAdapterをONに残す構成は避けてください。 画像は **H3 Continuum Load ImageとEnable Imageを維持**します。Issue #23の継承されたmode setterへの委譲と、描画・保存中のwidget配列差し替え廃止を適用します。EnableはCoreの欄の後ろに配置し、画像ファイルとBypassの保存はCoreに委ねます。旧Audio/VideoノードIDは既存workflow用の非推奨互換ノードとして残します。登録IDは互換用2個を含め10個で、Sampler設定・Sampling・Decode Cache・Finalize・既存Run Storage契約は変更しません。 更新後はComfyUI再起動と画面の再読み込みが必要です。既に保存JSONから消えたファイル名やOFF状態は推測で復元できないため、一度選び直して保存してください。既存ユーザーworkflowや保存済みTakeは自動変更しません。上流ノードの種類変更でRun Storageが新revisionになることはあるため、過去Runの再開には元workflowを保管してください。 検証範囲は[Loader修正記録](docs/LOADER_PERSISTENCE_REPAIR.md)を参照してください。CPU回帰テストと実ブラウザ確認は別です。Windows Core 0.36.0 / frontend 1.53.6のタブ切替確認は未実施で、Release/tag・Registry公開も別作業です。以下の旧Loader画像は互換ノードの説明です。 ## Timeline Video — main上のExperimental機能 従来の動画IMAGE入力を**`Timeline Video Frames`**と表示し、末尾に省略可能な設定**`Video Reference Mode`**を1項目追加しました。新しい設定を持たない既存Workflow/APIは、初期値の**`Repeat Reference`**で従来動作を維持します。 - **`Repeat Reference`**:従来のVideo Guide契約です。各physical生成groupで、同じ先頭側の上限付き参照を使います。短い素材を自動ループ/Stretchしません。 - **`Follow Timeline`**:各physical出力groupの時間位置に対応する24fps参照区間を使います。Continuationの過去prefixを二重消費しません。素材終了後は動画参照なしで続行し、利用可能な終端区間にはH3 frame-grid整列分だけ短いpaddingを行う場合があります。 これは`Prompt Format = Timeline`とは別の設定です。新しいsocketやLoaderは増やさず、元動画のAudioも自動使用しません。参照動画はsoft conditioningであり、motionをframe単位で完全コピーする機能ではありません。また、decode済みIMAGE batch全体をsystem RAMへ保持するため、長尺入力のRAM削減機能ではありません。 接続は既存のままです。 ```text Core Load Video → H3 Continuum Video Adapter → Timeline Video Frames ``` 公式V3.8X2 Workflow本体は変更せず、比較用Experimental Workflowを別名で追加しています。 - [Follow Timeline JSON](examples/workflows/MiniMax_H3_Continuum_V38X2_Timeline_Experimental_Follow.json)/[ZIP](examples/workflows/MiniMax_H3_Continuum_V38X2_Timeline_Experimental_Follow.zip) - [Repeat Reference JSON](examples/workflows/MiniMax_H3_Continuum_V38X2_Timeline_Experimental_Repeat.json)/[ZIP](examples/workflows/MiniMax_H3_Continuum_V38X2_Timeline_Experimental_Repeat.zip) ローカル受入ではFull CPU `1424 passed / 1 skipped / 0 failed`、ブラウザ保存・再読込、Follow/Repeatの`2 × 5秒` GPUテストがPASSしました。両方とも704×416、24fps、240フレーム、映像10秒、32kHz stereo音声10秒で、OOM/NaN/allocation failure/crashはありません。FollowはChunk 2で後半区間へ切り替わり、Repeatは同じ先頭側参照を維持しました。RTX 5060 Ti 16 GBで観測した最大VRAMは約15.6~15.7 GiBで、16 GBの余裕は小さい条件です。これは機能・mode分離の受入結果であり、一般的な速度や主観画質の保証ではありません。詳細は[Timeline Video Experimental](docs/TIMELINE_VIDEO_EXPERIMENTAL.md)を参照してください。 > **V3.8X2**はpackage metadata `3.8.3`の製品名・Workflow名です。現在の`main`には3.8.3以降のLoader保存・復元修正が入り、公式WorkflowはCore Load AudioとCore Load Video → H3 Continuum Video Adapterを使用します。旧Continuum Audio/Video Loader IDは保存Workflow互換用として残します。Reference Images 4~9と内蔵Decode Cache Helperを含み、Timeline Videoは`main`上のExperimental機能です。旧V3.8.0は[`v3.8.0`タグ](https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum/tree/v3.8.0)から導入できます。 ## V3.8X2 公式Workflow - **標準名:** [JSON](examples/workflows/MiniMax_H3_Continuum_V38X2.json)/[ZIP](examples/workflows/MiniMax_H3_Continuum_V38X2.zip) - **Helper明示名:** [JSON](examples/workflows/MiniMax_H3_Continuum_V38X2+Decode_Cache_Helper.json)/[ZIP](examples/workflows/MiniMax_H3_Continuum_V38X2+Decode_Cache_Helper.zip) 2つの名称は**同じ公式graph**を収録した配布上の別名で、異なる設定のWorkflowではありません。どちらも内蔵Decode Cache Helperと9枚Reference Image用の接続を含み、Helperの保存値は`Auto / RAM 256MB / Disk 8GB / reset_token 0`です。各ZIPには、対応する名前のJSONだけを収録します。既存projectでは従来のV3.8X Workflowも引き続き使用できます。 ## Reference Image 9枚使用時のメモリ注意 Reference Image 1~3はSamplerへ直接接続し、任意の4~9は`H3 Continuum Reference Images`を経由して`Reference Images (Optional)`へ接続します。9枚すべてを使う構成は高負荷であり、通常の最低要件ではありません。 受入テストでは、**RTX 5060 Ti 16 GB/RAM 64 GB**環境で、9枚の元画像を各**約0.30 MP**に抑えた条件で完走しました。`512 × 608`出力、`3 × 5秒`、Spectrum Off、LoRA Off、Sage Attention、Balanced 22-frame continuityで、Sampling中のVRAMは`16,311 MiB`中の約**15.0~15.5 GiB**でした。16 GB環境では余裕がほとんどありません。 多数、特に9枚を使う場合は、読み込み・接続前に元画像のコピーを約0.30 MPへ縮小してください。Sampler内の通常のconditioning用Resizeは引き続き行われますが、小さい入力ファイルにすることで読み込み・前処理時の負荷を抑えられます。高解像度参照、大きな出力、追加wrapper、同時GPU処理では、より高性能なGPUと多いシステムRAMが必要になる可能性があります。9枚は任意であり、3枚より常に高画質になる保証はありません。 ## 内蔵 Decode Cache Helper ### 重要:新規生成が一律に速くなる機能ではありません **キャッシュの手動クリア**:普段は操作不要です。Helperの「キャッシュをクリア」ボタンを押すと、次回QueueでこのHelperのキャッシュを破棄し、通常Decodeからやり直します。ボタンは即時削除や自動Queueを行いません。内部の`reset_token`は保存・API互換用に残り、押すたびに1増えます(INT上限では0へ戻ります)。作成・読込・複製だけでは変更しません。JavaScriptが使えない環境やAPI版では、従来どおり`reset_token`の値を変更してください。 **短縮するのは、変更していないlatentを再びデコードする時間です。Sampling(生成計算)自体は高速化しません。** 初回は通常Decodeとキャッシュ保存を行うためMISSとなり、保存・照合の負荷で遅くなる場合があります。毎回ランダムシードで異なるlatentを新規生成する使い方では、基本的にMISSとなり、この機能による短縮は期待できません。 具体的に再利用できる場面: - **Continueでチャンクを追加**:既存チャンクのlatentを保持し、出力時にもう一度Decodeする場合、保存済みの既存部分だけを再利用します。追加チャンクは初回MISSです。 - **Fix/部分再生成**:変更していないチャンクのlatentがそのまま再入力される場合、その部分だけを再利用します。再生成してlatentが変わった部分はMISSです。 - **Complete/Resumeで再出力**:Samplingをやり直さず、保存済みlatentから全体を再Decodeする場合に有効です。単なる既存動画ファイルの再生ではありません。 - **Decode以降のリトライ、Finalizeや出力設定の変更**:Helperへ同じlatent・Decode関連情報が再入力され、Decodeが再実行される場合に有効です。 - **固定シードで同条件を再生成**:生成後のlatentが完全に一致した場合だけ再利用できます。同じシードだけではHITを保証しません。 これらの操作名そのものが有効条件ではありません。**各Video/Audioの入力latentの内容・shape・dtype、Decode関連メタデータ、VAE識別情報が一致し、そのHelperにキャッシュが残っていること**がHITの条件です。ComfyUIが上流/出力をそのまま再利用してDecode自体を実行しない場合、Helperによる追加のDecode短縮はありません。Helperを接続し、`Auto`または`RAM`で使ってください。レポートの`hit`は再利用、`miss`は通常Decode、`off`/`bypass`はキャッシュ再利用なしを表します。 キャッシュはPythonプロセス内の利用に限られ、再起動後は再利用しません。上限による退避・破棄やVAE識別情報の変化でもMISSになります。モード、RAM/Disk予算、`reset_token`を変更すると、この実装ではHelperキャッシュをクリアします。`reset_token = 0`を維持することは、毎回リセットする意味ではありません。 `H3DecodeCacheHelper`をContinuumパッケージ内に収録し、UI上は`MiniMax H3/Continuum/Helpers`の独立公開ノードとして残します。インストール対象はContinuumだけです。現行パッケージはVideo Adapterと互換用旧Audio/Video Loaderを含む計10 IDを登録します。Sampler、Finalize、Assembly Plan、Core Decode、既存Sampler widget/socketの先頭契約は変更せず、Timeline Videoのmode widgetだけをoptional末尾へ追加します。 Samplerの`video_latents`/`audio_latents`と同じVideo/Audio VAEをHelperへ接続し、Helperの`images`/`audio`をFinalizeへ接続します。Samplerの`assembly_plan`はFinalizeへ直接接続したままです。[公式V3.8X2 Workflow](examples/workflows/MiniMax_H3_Continuum_V38X2.json)は保存済みgraphと設定を維持します。このgraphにはCore VAE Decodeノードがないため、Core直結へ戻すにはCore Video/Audio Decodeを追加してFinalizeへ再配線するか、旧V3.8XのCore直結graphを開いてください。Helperを単に削除しても自動では戻りません。 `Auto`は全physical groupのVideo Decodeをプロセス専用Diskへ、小さなAudio Decodeを上限付きRAMへ保存します。`Off`はnative Decodeを使い、Helper Cacheを破棄します。Cache障害時はnative Decodeへ戻りますが、native DecodeのOOMやQueue中断は再試行しません。Python再起動後にCacheファイルを再利用しません。移行時は同じ`H3DecodeCacheHelper` IDを提供する旧単独addonと内蔵版を同時登録しないでください。内蔵版の導入確認後に旧addonを無効化または撤去します。 736×416(0.306MP)、3×5秒、Euler/simple 6 steps、Turbo FL2V v1.2、ウォーム、Video 3/3 HITの1条件では、Full Run Totalの**機構推定中心値は約47秒/約24.5%短縮**でした。直接A/Bの1ペアは50.887秒/26.46%、Samplingを伴わないComplete/Resumeの2ペアは平均46.309秒/79.826%短縮でした。これは限定条件の観測値で、反復された一般平均や無条件の20%以上高速化保証ではありません。初回MISSは遅くなる場合があり、新規Samplingは高速化せず、latentまたはVAE識別情報が変わればMISSになります。 MiniMax H3を複数チャンクで連続生成し、直前チャンク末尾の**映像latent / 音声latentを直接**次チャンクへ継承するComfyUIカスタムノードです。チャンク間でVideo/Audio VAEのDecode→Encodeは行いません。 ## インストール・更新 新規導入: ```bash cd ComfyUI/custom_nodes git clone https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum.git ``` 既存のGit導入を更新: ```bash cd ComfyUI/custom_nodes/ComfyUI-H3-Continuum git pull --ff-only origin main ``` ComfyUIを再起動してください。Managerから導入した場合はManagerのUpdateを使い、同じノードを重複配置しないでください。 旧V3.8.0を別フォルダへ導入する場合: ```bash cd ComfyUI/custom_nodes git clone --branch v3.8.0 --single-branch https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum.git ComfyUI-H3-Continuum-v3.8.0 ``` Continuumのcheckoutは同時に1つだけ有効にしてください。ComfyUI Managerの**Update**は`main`を更新するため、過去tagの選択には使いません。 V3.8X2 Workflow:[JSON](examples/workflows/MiniMax_H3_Continuum_V38X2.json)/[同じJSONを含むZIP](examples/workflows/MiniMax_H3_Continuum_V38X2.zip)。Spectrum対応の1本で、保存状態ではSpectrumとTurbo LoRAはどちらもOFFです。[LightX2V Turbo](https://github.com/ModelTC/Minimax-H3-Turbo)にも切り替えられます。完全なgraphを開くにはSpectrum・rgthree・KJNodesが必要です。ComfyUI-Easy-Useは不要です。 ## プロンプト・スキルのダウンロード - [LLM用システムプロンプトZIP](H3-Continuum-LLM-System-Prompt-v1.zip):Continuum向けプロンプト作成のシステム指示と詳細資料。 - [Continuum専用プロンプトスキルZIP](H3-Continuum-Skill-v1.zip):Codexなどで使う、チャンク構成に対応した汎用プロンプト作成スキル。 - [Continuum Dance DirectorスキルZIP](minimax-h3-continuum-dance-director.zip):主役のダンサー1人を対象に、チャンク間の身体動作とカメラの連続性を考慮した長尺ダンス用プロンプトを作成するスキル。 いずれも任意のプロンプト作成支援資料で、ComfyUIのカスタムノードではありません。ZIPを展開し、同梱の案内に従って利用してください。Samplerを変更するものではなく、生成動作や画質を保証するものでもありません。 ## V3.8の公開範囲 H3 Continuumは、長尺映像を最初からやり直さずに生成・確認・部分再生成・再開するProduction Samplerです。V3.8は`Main / Production`と`Advanced`の2層に整理しました。 現行V3.8X2で検索可能なノードIDは次の10個です。旧Audio/Video Loaderは保存Workflow互換用で、新規WorkflowはCore LoaderとVideo Adapterを使います。 - `H3 Continuum Sampler V3.8` - `H3 Continuum Finalize` - `H3 Continuum Load Image` - `H3 Continuum Load Audio` - `H3 Continuum Load Video` - `H3 Continuum Video Adapter` - `H3 Continuum Second Pass` - `H3 Continuum Reference Audios` - `H3 Continuum Reference Images` - `Decode Cache Helper` Main Sampler内の`Show Advanced Settings`/`Hide Advanced Settings`で詳細設定を開閉します。旧node property `H3 Continuum View`を含む保存Workflowは対応する開閉状態へ移行し、旧propertyを削除します。これは表示状態だけの変更です。Python input、widget順、保存済みwidget値、backend引数、Sampling identity、Run Storage identityは変更しません。Frontend extensionが読み込まれない場合も、Python定義の全widgetが表示された状態で実行できます。 V3.8X2公式Workflowの標準経路は`Sampler V3.8 -> Decode Cache Helper -> Finalize -> Create Video -> Save Video`です。HelperはMISSしたentryをCore Video/Audio Decodeへ委譲します。Core Decodeへ直接つなぐ手動構成も使用できますが、Decode結果のcacheはありません。Finalizeの`IMAGE`/`AUDIO`出力をCoreの`Create Video`で`VIDEO`へまとめてから保存します。Save、Upscalerは外付けとし、外部latent processorやupscalerはSecond Passをbridgeとして接続します。外部processorが変更できるのはVideo LATENTの空間解像度だけで、physical group、B/C/T、finite値、First Pass Audio、元のAssembly Planを維持する必要があります。Finalizeは公開`IMAGE`/`AUDIO`型を受け取り、特定decoder classへ依存しません。SageAttention、Sol-Attn、Spectrumは外部MODEL wrapperのままです。詳細は[V3.8 Open Integration Contract](docs/V38_OPEN_INTEGRATION_CONTRACT.md)を参照してください。旧Hi-Res FixはV3.8X2標準Workflowに含めません。 ### Reference Audio 1/2/3 `H3 Continuum Reference Audios`は、最大3本の単独Reference Audioを1本の`Audio References (Optional)` socketへまとめます。入力は間を空けずに接続し、Promptでは接続順どおりに`