feat: expose the latent upscaler as an upscale_model widget on Moxie MultiTrack Project Slow

The Slow node previously baked the upscaler checkpoint filename
(minimax_h3_latent_upscaler_3d_fp16.safetensors) into its settings with
no place on the node to choose it. The checkpoint is now a proper
upscale_model combo widget placed with the model components (after
audio_vae):

- options are None plus every file under ComfyUI/models/latent_upscale_models/
  (the bundled default is always kept selectable so the combo default is
  valid even before the checkpoint is downloaded)
- picking None (or an empty string, e.g. from a converted primitive
  socket) raises a clear error instead of silently falling back to the
  decode/RTX-resize/re-encode path this node exists to avoid
- workflows saved before the widget existed fall back to the bundled
  checkpoint, so they run unchanged
- engine untouched: the value flows through the existing
  kwargs.get('upscale_model') read; baked settings simply stop
  overriding it (base BAKED_PROJECT_SETTINGS copy pops the key)
- MoxieProject gains a _component_inputs() schema hook so subclasses can
  slot inputs in with the model components; base node schema unchanged
- tests: schema spot/ordering, folder listing without duplicates, widget
  passthrough, pre-widget fallback to the bundled checkpoint, None/empty
  rejection; CHANGELOG + multitrack-schema.md updated
This commit is contained in:
Z User 2026-10-14 22:37:59 +00:00
parent 5a3b03ef61
commit 43d5bf9a1e
4 changed files with 166 additions and 17 deletions

View File

@ -6,7 +6,7 @@
### ⚡ Improvements
- **Moxie MultiTrack Project Slow**: New project node variant that replaces the RTX VSR restore with a latent-upscale refine pass. The pipeline stays identical to Moxie MultiTrack Project — hidden half-resolution first pass with euler + beta sigmas from `steps` — but the low-resolution latent is upscaled to the final (editor) size by `minimax_h3_latent_upscaler_3d_fp16.safetensors` (from `ComfyUI/models/latent_upscale_models/`) and refined with a hidden 2-step euler pass at 0.33 denoise. Segments are saved at the project resolution, so the Video Combine restore passes through untouched and nothing in the node requires NVIDIA RTX VSR. End users still only set `steps` and `seed` (plus the shared `context_frames` overlap). The engine's first-pass downscale and upscale-skip logic were generalized (class hook + true size comparison) with zero behavior change for existing nodes.
- **Moxie MultiTrack Project Slow**: New project node variant that replaces the RTX VSR restore with a latent-upscale refine pass. The pipeline stays identical to Moxie MultiTrack Project — hidden half-resolution first pass with euler + beta sigmas from `steps` — but the low-resolution latent is upscaled to the final (editor) size by a latent upscaler checkpoint and refined with a hidden 2-step euler pass at 0.33 denoise. Segments are saved at the project resolution, so the Video Combine restore passes through untouched and nothing in the node requires NVIDIA RTX VSR. The upscaler is chosen in a new `upscale_model` dropdown on the node (placed with the model inputs; lists everything under `ComfyUI/models/latent_upscale_models/`, defaults to `minimax_h3_latent_upscaler_3d_fp16.safetensors`, and rejects `None` with a clear error since the node always upscales in latent space). End users still only set `steps` and `seed` (plus the shared `context_frames` overlap). The engine's first-pass downscale and upscale-skip logic were generalized (class hook + true size comparison) with zero behavior change for existing nodes.
- **MultiTrack Project**: The inter-segment context overlap is now configurable. The new `context_frames` widget (5 / 22 / 39 / 56 frames, default 22) chooses how many frames of the previous segment are copied in as continuation context for segments using Context or Context Swap continuity — previously this was fixed at 22 frames in code. Longer values hand off motion more smoothly but generate that many extra frames per continued segment (each continuation also generates 12 grid-alignment tail frames that are trimmed after decode). Values are the H3 temporal-grid lengths already offered by the Moxie context sampler nodes; existing workflows keep 22 and behave exactly as before. The same widget (between `steps` and `seed`) is also exposed on **Moxie MultiTrack Project** — its baked euler/beta sampling stack is unchanged, so end users still only need `steps` and `seed` unless they touch the overlap.

View File

@ -1,6 +1,7 @@
from __future__ import annotations
import comfy.samplers
import folder_paths
from comfy_api.latest import io
from .nodes.project import (
@ -39,9 +40,9 @@ SLOW_PROJECT_SETTINGS_DELTA = {
# The first pass already runs at half the editor resolution, so the final
# size IS the editor size: a scale factor of 1.0 keeps the project
# manifest at the editor dimensions while the latent upscaler (target
# dimensions mode) bridges the half-res gap.
# dimensions mode) bridges the half-res gap. The upscaler checkpoint is
# NOT baked: the Slow node exposes an upscale_model widget instead.
"upscale_by": 1.0,
"upscale_model": SLOW_UPSCALE_MODEL,
}
@ -99,14 +100,23 @@ class MoxieProject(EasyMultiTrackProject):
def _baked_project_settings(cls) -> dict:
return dict(BAKED_PROJECT_SETTINGS)
@classmethod
def _component_inputs(cls) -> list:
"""Extra inputs subclasses slot in after the model components."""
return []
@classmethod
def _project_inputs(cls) -> list:
return [
inputs = [
TYPE_TRACKS_INFO.Input("tracks_info"),
io.Model.Input("model", tooltip="Diffusion model from Moxie Multimedia Loader (attention backend already applied)."),
io.Clip.Input("clip", tooltip="CLIP text encoder from Moxie Multimedia Loader."),
io.Vae.Input("video_vae", tooltip="Video VAE from Moxie Multimedia Loader."),
io.Vae.Input("audio_vae", tooltip="Audio VAE from Moxie Multimedia Loader (required to decode Moxie audio)."),
]
inputs.extend(cls._component_inputs())
inputs.extend(
[
io.String.Input("project_name", default="",
tooltip="Name of the project; used for output folders."),
io.Int.Input(
@ -139,6 +149,8 @@ class MoxieProject(EasyMultiTrackProject):
control_after_generate=io.ControlAfterGenerate.randomize,
),
]
)
return inputs
@classmethod
def define_schema(cls) -> io.Schema:
@ -201,15 +213,45 @@ class MoxieProjectSlow(MoxieProject):
Identical pipeline to MoxieProject (hidden half-resolution first pass,
euler + beta sampling from `steps`), except the low-resolution latent is
upscaled to the final size by the H3 latent upscaler model and refined
with a 2-step euler pass at 0.33 denoise. Segments are saved at the
project resolution, so the Video Combine RTX restore passes through
untouched - no NVIDIA RTX VSR is used anywhere.
upscaled to the final size by a latent upscaler model chosen in the
`upscale_model` widget and refined with a 2-step euler pass at 0.33
denoise. Segments are saved at the project resolution, so the Video
Combine RTX restore passes through untouched - no NVIDIA RTX VSR is
used anywhere.
"""
@classmethod
def _latent_upscaler_options(cls) -> list:
models = list(folder_paths.get_filename_list("latent_upscale_models"))
if SLOW_UPSCALE_MODEL not in models:
# Keep the bundled checkpoint selectable even before it is
# downloaded; the combo default must always be a valid option.
models.append(SLOW_UPSCALE_MODEL)
return ["None"] + models
@classmethod
def _component_inputs(cls) -> list:
return [
io.Combo.Input(
"upscale_model",
options=cls._latent_upscaler_options(),
default=SLOW_UPSCALE_MODEL,
tooltip=(
"Latent upscaler checkpoint that brings the hidden "
"half-resolution first pass to the final size before "
"the 2-step refine. Files live under "
"ComfyUI/models/latent_upscale_models/; None is "
"rejected because this node always upscales in latent "
"space instead of the RTX restore."
),
)
]
@classmethod
def _baked_project_settings(cls) -> dict:
settings = dict(BAKED_PROJECT_SETTINGS)
# The upscaler checkpoint comes from the upscale_model widget.
settings.pop("upscale_model", None)
settings.update(SLOW_PROJECT_SETTINGS_DELTA)
return settings
@ -229,10 +271,11 @@ class MoxieProjectSlow(MoxieProject):
description=(
"Build and execute a multi-track Moxie project with a "
"latent-upscale refine pass. Takes model, clip, video_vae and "
"audio_vae directly from the Moxie Multimedia Loader. The "
"audio_vae directly from the Moxie Multimedia Loader and an "
"upscale_model checkpoint from latent_upscale_models. The "
"first pass samples euler + beta sigmas from steps, the "
"half-resolution latent is upscaled to the final size with "
"the H3 latent upscaler model, and a 2-step euler pass at "
"the chosen latent upscaler, and a 2-step euler pass at "
"0.33 denoise refines it; set only steps and seed."
),
is_input_list=True,
@ -254,6 +297,18 @@ class MoxieProjectSlow(MoxieProject):
audio_vae = _first_input(kwargs.get("audio_vae"))
_require_moxie_components(model, clip, video_vae, audio_vae)
upscale_model = _first_input(kwargs.get("upscale_model"))
if upscale_model is None:
upscale_model = SLOW_UPSCALE_MODEL
upscale_model = str(upscale_model).strip()
if not upscale_model or upscale_model == "None":
raise ValueError(
"Moxie MultiTrack Project Slow always upscales the "
"half-resolution latent in latent space, so it needs a "
"model: pick a checkpoint in the upscale_model dropdown "
"(files under ComfyUI/models/latent_upscale_models/)."
)
sigmas_2nd = _denoise_truncated_sigmas(
model.get_model_object("model_sampling"),
BAKED_SCHEDULER,
@ -263,4 +318,5 @@ class MoxieProjectSlow(MoxieProject):
injected = dict(kwargs)
injected["sampler_2nd"] = comfy.samplers.sampler_object(BAKED_SAMPLER_NAME)
injected["sigmas_2nd"] = sigmas_2nd
injected["upscale_model"] = upscale_model
return super().execute(**injected)

View File

@ -268,7 +268,7 @@ custom 示例:
- `sampling_mode`: `single` 或 `dual`;`sampling_plan` 必须是当前节点可用预设。不要仅凭另一份流程中的值假设当前环境支持。
- `context_frames`(默认 `"22"`,可选 `"5"` / `"22"` / `"39"` / `"56"`)控制 Context / Context Swap 续接片段从上一段拷贝为延续上下文的视频帧数;取值必须落在 H3 时间潜空间网格(17k+5 帧)上,与 Moxie 上下文采样节点的选项一致。数值越大运动衔接越平滑,但每个续接片段会多生成等量帧(实际生成长度为 `任务长度 + context_frames + 12`,其中 12 帧为网格尾帧,解码后裁掉)。
- `Moxie MultiTrack Project`(`MoxieProject`)同样暴露同一个 `context_frames` 下拉,位于 `steps` 与 `seed` 之间;该节点的其余采样设置仍保持隐藏(euler + beta sigmas 由 `steps` 推导)。
- `Moxie MultiTrack Project Slow`(`MoxieProjectSlow`)是 Moxie 变体:参数与 `Moxie MultiTrack Project` 完全一致,但用潜空间放大替代 RTX VSR——隐藏的半分辨率一采之后,用 `models/latent_upscale_models/minimax_h3_latent_upscaler_3d_fp16.safetensors` 把潜空间升到最终(编辑器)尺寸,再以 2 步 euler、0.33 denoise 的隐藏二采精修;片段按项目分辨率保存,Video Combine 的 RTX 还原会直接跳过。
- `Moxie MultiTrack Project Slow`(`MoxieProjectSlow`)是 Moxie 变体:参数与 `Moxie MultiTrack Project` 完全一致,但用潜空间放大替代 RTX VSR——隐藏的半分辨率一采之后,用 `models/latent_upscale_models/` 下选定的潜空间放大模型把潜空间升到最终(编辑器)尺寸,再以 2 步 euler、0.33 denoise 的隐藏二采精修;片段按项目分辨率保存,Video Combine 的 RTX 还原会直接跳过。该节点在 `audio_vae` 之后新增 `upscale_model` 下拉(默认 `minimax_h3_latent_upscaler_3d_fp16.safetensors`,列出 `models/latent_upscale_models/` 全部检查点);选 `None` 会直接报错,因为该节点始终走潜空间放大。旧工作流没有该控件时自动回落到默认检查点。
- 编辑器分辨率是一采尺寸;`dual` 不会反算缩小一采。二采宽高分别为 `round(编辑器尺寸 * upscale_by / 32) * 32`,采用 Python `round` 就近对齐,恰好居中时取偶数,不是固定向上对齐。
- `upscale_by` 是 Project 的独立参数,默认 `1.250`,三位小数,步长 `0.001`;旧工作流保留已保存的值。两条放大路径及合并导出均使用放大并对齐后的尺寸。例如 `1344 × 768`、倍率 `1.250` 的二采为 `1664 × 960`。若用户指定最终输出尺寸,应同时核对编辑器尺寸与倍率,不能将编辑器尺寸直接当作双采样的最终尺寸。
- 单采样、仅一采预览保持编辑器尺寸;`upscale_by = 1.000` 不放大但可二采;纯音频项目(`32 × 32`)不放大。旧版反算缩小尺寸的一采检查点和上下文潜空间应重新生成后再按新规则续跑。

View File

@ -6280,10 +6280,44 @@ def test_moxie_project_slow_schema_mirrors_moxie_project(monkeypatch):
assert slow.display_name == "Moxie MultiTrack Project Slow"
assert slow.is_input_list is True
assert slow.enable_expand is True
assert list(slow_inputs) == list(base_inputs)
base_names = list(base_inputs)
# The Slow node adds exactly one widget: the upscale_model combo, placed
# with the model components (after audio_vae).
assert list(slow_inputs) == base_names[:5] + ["upscale_model"] + base_names[5:]
assert [out.name for out in slow.outputs] == [out.name for out in base.outputs]
assert "context_frames" in slow_inputs
assert slow_inputs["context_frames"].kwargs["options"] == ["5", "22", "39", "56"]
canonical = "minimax_h3_latent_upscaler_3d_fp16.safetensors"
upscale = slow_inputs["upscale_model"]
# The harness folder listing is empty, so only "None" plus the bundled
# default (always kept selectable) appear.
assert upscale.kwargs["options"] == ["None", canonical]
assert upscale.kwargs["default"] == canonical
def test_moxie_project_slow_upscale_model_lists_folder_without_duplicates(
monkeypatch,
):
module = _load_moxie_project(monkeypatch)
canonical = "minimax_h3_latent_upscaler_3d_fp16.safetensors"
monkeypatch.setattr(
module.folder_paths,
"get_filename_list",
lambda category: (
[canonical, "alt_upscaler.safetensors"]
if category == "latent_upscale_models"
else []
),
)
slow_inputs = {
port.name: port for port in module.MoxieProjectSlow.define_schema().inputs
}
assert slow_inputs["upscale_model"].kwargs["options"] == [
"None",
canonical,
"alt_upscaler.safetensors",
]
assert slow_inputs["upscale_model"].kwargs["default"] == canonical
def test_moxie_project_slow_bakes_latent_upscale_refine(monkeypatch):
@ -6321,6 +6355,7 @@ def test_moxie_project_slow_bakes_latent_upscale_refine(monkeypatch):
project_name=["demo"],
steps=["3"],
context_frames=["5"],
upscale_model=["my_upscaler.safetensors"],
seed=["7"],
)
@ -6340,10 +6375,8 @@ def test_moxie_project_slow_bakes_latent_upscale_refine(monkeypatch):
# Baked Slow settings reach the engine.
assert captured["sampling_mode"] == "dual"
assert captured["upscale_by"] == 1.0
assert (
captured["upscale_model"]
== "minimax_h3_latent_upscaler_3d_fp16.safetensors"
)
# The connected/picked upscale_model widget value wins over any default.
assert captured["upscale_model"] == "my_upscaler.safetensors"
assert captured["sampling_plan"] == "custom"
assert captured["disable_2nd_noise"] is False
# First pass unchanged: euler + beta from steps (3 -> 4 sigmas).
@ -6353,6 +6386,66 @@ def test_moxie_project_slow_bakes_latent_upscale_refine(monkeypatch):
assert captured["context_frames"] == ["5"]
def test_moxie_project_slow_defaults_to_bundled_upscaler(monkeypatch):
module = _load_moxie_project(monkeypatch)
captured = {}
def fake_execute(cls, **kwargs):
captured.update(kwargs)
return "sentinel-output"
monkeypatch.setattr(
module.EasyMultiTrackProject, "execute", classmethod(fake_execute)
)
model = types.SimpleNamespace(
get_model_object=lambda name: f"sampling:{name}"
)
module.MoxieProjectSlow.execute(
tracks_info=[{"tracks": []}],
model=[model],
clip=[types.SimpleNamespace()],
video_vae=[types.SimpleNamespace()],
audio_vae=[types.SimpleNamespace()],
project_name=["demo"],
steps=["3"],
context_frames=["5"],
seed=["7"],
)
# Workflows saved before the widget existed keep the bundled checkpoint.
assert (
captured["upscale_model"]
== "minimax_h3_latent_upscaler_3d_fp16.safetensors"
)
assert captured["sampling_mode"] == "dual"
assert captured["upscale_by"] == 1.0
def test_moxie_project_slow_rejects_missing_upscaler(monkeypatch):
module = _load_moxie_project(monkeypatch)
model = types.SimpleNamespace(
get_model_object=lambda name: f"sampling:{name}"
)
common = {
"tracks_info": [{"tracks": []}],
"model": [model],
"clip": [types.SimpleNamespace()],
"video_vae": [types.SimpleNamespace()],
"audio_vae": [types.SimpleNamespace()],
"project_name": ["demo"],
"steps": ["3"],
"context_frames": ["5"],
"seed": ["7"],
}
for upscale_model in (["None"], [""]):
with pytest.raises(ValueError, match="latent upscaler|latent_upscale_models"):
module.MoxieProjectSlow.execute(
upscale_model=upscale_model, **common
)
def test_moxie_project_slow_keeps_half_res_first_pass(monkeypatch):
module = _load_moxie_project(monkeypatch)
base = module.EasyMultiTrackProject