Squashed 'vendor/dumas_minimax_h3_refmod/' content from commit 517e8c4

git-subtree-dir: vendor/dumas_minimax_h3_refmod
git-subtree-split: 517e8c419a8584fbf69fceb487bc39d83e6a6ec8
This commit is contained in:
2026-10-20 13:43:44 +00:00
commit 70d0672ee3
49 changed files with 7097 additions and 0 deletions
+56
View File
@@ -0,0 +1,56 @@
# RefMod v0.2.0 — Master, audio references and loader fixes
## Highlights
- **Extract H3 RefMod Master:** image/video and optional audio in one node,
sequential extraction with separate VAEs, a combined token budget and one
bundle output. Visual and audio references save as separate compatible files.
- **Integrated audio:** extract and load audio RefMods without installing
H3AudioMod. Includes an input-music and generated-video example in the README.
- **Save H3 RefMods:** a dedicated output node saves bundles without a connected
Preview or sampler. Supports prefixes, subfolders and copy deduplication.
- **Library and inspection:** search/filter the collection, select loader slots,
inspect metadata/token counts and optionally preview stored visual/audio latents.
## Fixes and maintenance
- Linked mod names no longer fail queue validation before upstream nodes run;
covers both the standard and Axis loaders.
- Recursive subfolder discovery and saving to registered external RefMod roots
respect ComfyUI's folder configuration.
- File changes invalidate loader caches; loaded tensors have a bounded cache.
- Step Curve no longer retains reference tensors between calls. Bridge injection
is scoped to the MODEL branch and restores conditioning after errors.
- Matching image/mask crops, bounded video sampling, runtime numeric/copy limits
and optional total-token budgets.
- Atomic file saves and explicit Master Created/Replaced destination logs.
- Removed sibling-pack imports and the startup dependency warning. Legacy
av_encoder inputs resolve through ComfyUI's native video VAE loader.
- Shared extraction helpers and grouped multi-reference MSE refinement; explicit
shuffle/subset options and experimental extraction presets.
## Known failure: voice transfer
**Audio support is not working voice cloning.** Music-reference conditioning has
produced an observed result, but current speaker-identity transfer tests failed.
The cause has not been isolated: H3/checkpoint behavior and the difference in how
RefMod presents audio references to text encoding both remain under investigation.
The visual mode named `training` refines a compressed latent; it does not train
H3 weights or learn a supervised control-to-target edit. The separate gradient
probe is experimental and does not establish full-checkpoint training support.
## Updating
Validation: all 39 regression tests passed before release, using ComfyUI's
embedded Python and real queue-validation modules. Previous audio codec checks
used the real H3 audio VAE; these checks do not establish voice-transfer quality.
Update the node pack and restart ComfyUI to register the new nodes and library.
Existing visual RefMods and legacy audio metadata remain readable. When using
Save H3 RefMods after an extractor, set the extractor's save option to false to
avoid writing twice. Master saves `name_visual` and `name_audio`; load both to
reconstruct a mixed bundle. Existing files at those destinations are replaced.
The old Bridge Disarm node is retained for workflow compatibility; disable or
bypass the bridge on its MODEL branch instead of relying on global state.
+12
View File
@@ -0,0 +1,12 @@
# v0.2.5 — RefMod creation and compatibility fixes
- Rename Extract nodes to Create, with unchanged node IDs. Full Reference and Compressed Reference replace the visible encode/training names; old mode values remain accepted. Rename the identity control to Refinement Steps.
- Add visual budget_policy: truncate preserves existing behavior; error stops before saving when the visual token budget is exceeded. Master inherits the option.
- Allow larger token/frame limits and preserve the requested frame count in the motion preset. Loader budgets default to 0 (disabled).
- Add experimental H3 RefMod Text Encode with numbered reference presentation and a reference map. Support compatible ClipProj encoders and native batched video-VAE output.
- Add optional full-video inspection with correct IMAGE output dimensions; retain the lightweight first-frame default.
- Add playable music/video README examples and exclude local tests from distribution.
Validation: 51 local regression tests passed; creation-label hooks checked with Node.js. Full GPU generation, projected-encoder quality and voice transfer remain unverified. Voice cloning is not claimed to work.
Text Encode already attaches references: do not inject the same bundle again with Apply/Bridge. Integrated Continuum samplers still need a dedicated integration to use this conditioning. Full visual previews and text/vision presentation increase memory use.
+15
View File
@@ -0,0 +1,15 @@
# v0.2.6 — RefMod bundles and compact loaders
- Save visual and audio references together in one `.safetensors`: choose `save_layout=bundle` in Master, or pack existing references with **Save H3 RefMod Bundle**.
- Select **All / Visual / Audio** per Loader/Axis slot, with independent modality strengths. Excluded components are not loaded.
- Loader and Axis now start with one visible slot. **+ Add RefMod** reveals more slots, up to eight, with each reference's controls grouped together. Removal clears the slot; connected slots are protected.
- The library recognizes combined files, and Config preserves unselected members. The bundle schema is documented in `BUNDLE_FORMAT.md` for third-party pickers.
- Includes RefMod-only dropdown refresh and clearer effective-setting logs added after v0.2.5.
Existing standalone files and workflow values remain supported. Master still defaults to separate files. Combined version-5 files require a bundle-aware reader.
Restart ComfyUI for the Python changes and refresh the browser for the compact interface.
Bundling does not add voice-to-character binding, audiovisual synchronization, or original-waveform passthrough. Voice transfer remains experimental and failed in previous tests.
Validation: 61 local Python regression tests passed, plus frontend checks for adding/removing slots, connected inputs, legacy workflow restoration, serialization and library selection. The user confirmed the compact interface works in ComfyUI. Full GPU generation quality was not validated for this release.