@melite/models-h3 0.1.4-alpha → 0.2.0-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,90 +1,21 @@
1
- import type { Context } from '@deepseek-ai/cordis';
1
+ import type { Context } from '@melite/comfyui-card-kit/card-definition';
2
2
  export declare const inject: string[];
3
- export declare const H3_LORA_ROWS: readonly [{
4
- readonly id: "h3_lightx2v_dareties";
5
- readonly filename: "h3/minimax_h3_fl2v_lightx2v_v0.1_dareties_v4_step600_comfy_fro.safetensors";
6
- readonly source_url: "https://huggingface.co/silveroxides/MiniMax-H3_tests/resolve/main/minimax_h3_fl2v_lightx2v_v0.1_dareties_v4_step600_comfy_fro.safetensors";
7
- readonly label: "LightX2V dareties v4";
8
- readonly category: "distill";
9
- readonly default_strength: 0.8;
10
- readonly steps: 4;
11
- }, {
12
- readonly id: "h3_lightx2v_turbo";
13
- readonly filename: "h3/minimax_h3_fl2v_lightx2v_turbo_4to8step_v0.1-v1.0_768p_v4_step600_dareties.safetensors";
14
- readonly source_url: "https://huggingface.co/silveroxides/MiniMax-H3_tests/resolve/main/experimental/minimax_h3_fl2v_lightx2v_turbo_4to8step_v0.1-v1.0_768p_v4_step600_dareties.safetensors";
15
- readonly label: "LightX2V Turbo 4-8 step";
16
- readonly category: "distill";
17
- readonly default_strength: 0.6;
18
- readonly steps: 8;
19
- readonly steps_min: 4;
20
- readonly steps_max: 8;
21
- }, {
22
- readonly id: "h3_turbo4_v1";
23
- readonly filename: "h3/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors";
24
- readonly source_url: "https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors";
25
- readonly label: "LightX2V Turbo 4-Step v1.0 (768p)";
26
- readonly category: "distill";
27
- readonly default_strength: 1;
28
- readonly steps: 4;
29
- }, {
30
- readonly id: "h3_turbo8_v1";
31
- readonly filename: "h3/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors";
32
- readonly source_url: "https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors";
33
- readonly label: "LightX2V Turbo 8-Step v1.0";
34
- readonly category: "distill";
35
- readonly default_strength: 1;
36
- readonly steps: 8;
37
- }, {
38
- readonly id: "h3_ref2v_turbo4";
39
- readonly filename: "h3/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors";
40
- readonly source_url: "https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors";
41
- readonly label: "LightX2V Ref Turbo 4-Step v0.1";
42
- readonly category: "distill";
43
- readonly default_strength: 1;
44
- readonly steps: 4;
45
- }, {
46
- readonly id: "h3_acc8_fl2va";
47
- readonly filename: "h3/MiniMax-H3-FL2VA-Acc-8Step_pruned_comfy.safetensors";
48
- readonly source_url: "https://huggingface.co/Kijai/MiniMax-H3-experimental/resolve/main/loras/MiniMax-H3-FL2VA-Acc-8Step_pruned_comfy.safetensors";
49
- readonly label: "Kijai FL2VA Acc 8-Step";
50
- readonly category: "distill";
51
- readonly default_strength: 1;
52
- readonly steps: 8;
53
- }, {
54
- readonly id: "h3_acc8_ref2va";
55
- readonly filename: "h3/MiniMax-H3-Ref2VA-Acc-8Step_pruned_comfy.safetensors";
56
- readonly source_url: "https://huggingface.co/Kijai/MiniMax-H3-experimental/resolve/main/loras/MiniMax-H3-Ref2VA-Acc-8Step_pruned_comfy.safetensors";
57
- readonly label: "Kijai Ref2VA Acc 8-Step";
58
- readonly category: "distill";
59
- readonly default_strength: 1;
60
- readonly steps: 8;
61
- }, {
62
- readonly id: "h3_larryvrh_v4_ema";
63
- readonly filename: "h3/minimax_h3_turbo_v4_step600_ema.safetensors";
64
- readonly source_url: "https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora/resolve/main/minimax_h3_turbo_v4_step600_ema.safetensors";
65
- readonly label: "Larryvrh Turbo v4-600 EMA";
66
- readonly category: "distill";
67
- readonly default_strength: 1;
68
- readonly steps: 6;
69
- readonly steps_min: 4;
70
- readonly steps_max: 8;
71
- }, {
72
- readonly id: "h3_pk_parasyte";
73
- readonly filename: "h3/H3-PK-Parasyte-Turbo.safetensors";
74
- readonly source_url: "https://huggingface.co/Plaguekind/H3-Lora/resolve/main/H3-PK-Parasyte-Turbo.safetensors";
75
- readonly label: "PK Parasyte Turbo";
76
- readonly category: "distill";
77
- readonly default_strength: 1.5;
78
- readonly steps: 8;
79
- readonly steps_min: 6;
80
- readonly steps_max: 8;
81
- }, {
82
- readonly id: "h3_taomate_3step";
83
- readonly filename: "h3/minimax_h3_taomate_3step_lora_avg_rank_19_bf16.safetensors";
84
- readonly source_url: "https://huggingface.co/Kijai/MiniMax-H3_comfy/resolve/main/loras/minimax_h3_taomate_3step_lora_avg_rank_19_bf16.safetensors";
85
- readonly label: "TaoMate 3-Step (refiner)";
86
- readonly category: "distill";
87
- readonly default_strength: 0.7;
88
- readonly steps: 3;
89
- }];
3
+ /** One catalog row's shape — the married columns are OPTIONAL by
4
+ * law (a row without shift_video declares no shift opinion; the
5
+ * schema's declared default owns), and the compose-side marriage
6
+ * reads both knobs through one dynamic key, so the table's row
7
+ * type names them. */
8
+ export interface H3LoraRow {
9
+ readonly id: string;
10
+ readonly filename: string;
11
+ readonly source_url: string;
12
+ readonly label: string;
13
+ readonly category: string;
14
+ readonly default_strength: number;
15
+ readonly steps: number;
16
+ readonly steps_min?: number;
17
+ readonly steps_max?: number;
18
+ readonly shift_video?: number;
19
+ }
20
+ export declare const H3_LORA_ROWS: readonly H3LoraRow[];
90
21
  export declare function apply(ctx: Context): void;
package/lib/mods/loras.js CHANGED
@@ -1,12 +1,23 @@
1
1
  export const inject = ['comfyui'];
2
2
  export const H3_LORA_ROWS = [
3
- { id: 'h3_lightx2v_dareties', filename: 'h3/minimax_h3_fl2v_lightx2v_v0.1_dareties_v4_step600_comfy_fro.safetensors', source_url: 'https://huggingface.co/silveroxides/MiniMax-H3_tests/resolve/main/minimax_h3_fl2v_lightx2v_v0.1_dareties_v4_step600_comfy_fro.safetensors', label: 'LightX2V dareties v4', category: 'distill', default_strength: 0.8, steps: 4 },
4
- { id: 'h3_lightx2v_turbo', filename: 'h3/minimax_h3_fl2v_lightx2v_turbo_4to8step_v0.1-v1.0_768p_v4_step600_dareties.safetensors', source_url: 'https://huggingface.co/silveroxides/MiniMax-H3_tests/resolve/main/experimental/minimax_h3_fl2v_lightx2v_turbo_4to8step_v0.1-v1.0_768p_v4_step600_dareties.safetensors', label: 'LightX2V Turbo 4-8 step', category: 'distill', default_strength: 0.6, steps: 8, steps_min: 4, steps_max: 8 },
5
- { id: 'h3_turbo4_v1', filename: 'h3/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors', source_url: 'https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors', label: 'LightX2V Turbo 4-Step v1.0 (768p)', category: 'distill', default_strength: 1, steps: 4 },
6
- { id: 'h3_turbo8_v1', filename: 'h3/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors', source_url: 'https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors', label: 'LightX2V Turbo 8-Step v1.0', category: 'distill', default_strength: 1, steps: 8 },
7
- { id: 'h3_ref2v_turbo4', filename: 'h3/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors', source_url: 'https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors', label: 'LightX2V Ref Turbo 4-Step v0.1', category: 'distill', default_strength: 1, steps: 4 },
8
- { id: 'h3_acc8_fl2va', filename: 'h3/MiniMax-H3-FL2VA-Acc-8Step_pruned_comfy.safetensors', source_url: 'https://huggingface.co/Kijai/MiniMax-H3-experimental/resolve/main/loras/MiniMax-H3-FL2VA-Acc-8Step_pruned_comfy.safetensors', label: 'Kijai FL2VA Acc 8-Step', category: 'distill', default_strength: 1, steps: 8 },
9
- { id: 'h3_acc8_ref2va', filename: 'h3/MiniMax-H3-Ref2VA-Acc-8Step_pruned_comfy.safetensors', source_url: 'https://huggingface.co/Kijai/MiniMax-H3-experimental/resolve/main/loras/MiniMax-H3-Ref2VA-Acc-8Step_pruned_comfy.safetensors', label: 'Kijai Ref2VA Acc 8-Step', category: 'distill', default_strength: 1, steps: 8 },
3
+ // ── THE MARRIED SHIFT COLUMN (SOTA limb 2, H3_TIMELINE_RESERACH
4
+
5
+ // training contract — the 8-step LightX2V variants and every
6
+ // ref2v tune run shift_video 12.0, the 4-step fl2v tunes 6.0.
7
+ // The column rides the SAME marriage law as steps (stated on the
8
+ // entry first, else this default, max across the bag); a row with
9
+ // NO column declares no shift opinion and the schema's declared
10
+ // default 8 (native) owns. larryvrh v4 stays column-less BY
11
+ // DESIGN: his README and the research table put him at
12
+ // native/default. shift_audio is 3.0 across every source — the
13
+ // schema's own declared default already speaks it (no column). ──
14
+ { id: 'h3_lightx2v_dareties', filename: 'h3/minimax_h3_fl2v_lightx2v_v0.1_dareties_v4_step600_comfy_fro.safetensors', source_url: 'https://huggingface.co/silveroxides/MiniMax-H3_tests/resolve/main/minimax_h3_fl2v_lightx2v_v0.1_dareties_v4_step600_comfy_fro.safetensors', label: 'LightX2V dareties v4', category: 'distill', default_strength: 0.8, steps: 4, steps_min: 4, steps_max: 4, shift_video: 6 },
15
+ { id: 'h3_lightx2v_turbo', filename: 'h3/minimax_h3_fl2v_lightx2v_turbo_4to8step_v0.1-v1.0_768p_v4_step600_dareties.safetensors', source_url: 'https://huggingface.co/silveroxides/MiniMax-H3_tests/resolve/main/experimental/minimax_h3_fl2v_lightx2v_turbo_4to8step_v0.1-v1.0_768p_v4_step600_dareties.safetensors', label: 'LightX2V Turbo 4-8 step', category: 'distill', default_strength: 0.6, steps: 8, steps_min: 4, steps_max: 8, shift_video: 12 },
16
+ { id: 'h3_turbo4_v1', filename: 'h3/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors', source_url: 'https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors', label: 'LightX2V Turbo 4-Step v1.0 (768p)', category: 'distill', default_strength: 1, steps: 4, steps_min: 4, steps_max: 4, shift_video: 6 },
17
+ { id: 'h3_turbo8_v1', filename: 'h3/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors', source_url: 'https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors', label: 'LightX2V Turbo 8-Step v1.0', category: 'distill', default_strength: 1, steps: 8, steps_min: 8, steps_max: 8, shift_video: 12 },
18
+ { id: 'h3_ref2v_turbo4', filename: 'h3/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors', source_url: 'https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/loras/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors', label: 'LightX2V Ref Turbo 4-Step v0.1', category: 'distill', default_strength: 1, steps: 4, steps_min: 4, steps_max: 4, shift_video: 12 },
19
+ { id: 'h3_acc8_fl2va', filename: 'h3/MiniMax-H3-FL2VA-Acc-8Step_pruned_comfy.safetensors', source_url: 'https://huggingface.co/Kijai/MiniMax-H3-experimental/resolve/main/loras/MiniMax-H3-FL2VA-Acc-8Step_pruned_comfy.safetensors', label: 'Kijai FL2VA Acc 8-Step', category: 'distill', default_strength: 1, steps: 8, steps_min: 8, steps_max: 8, shift_video: 12 },
20
+ { id: 'h3_acc8_ref2va', filename: 'h3/MiniMax-H3-Ref2VA-Acc-8Step_pruned_comfy.safetensors', source_url: 'https://huggingface.co/Kijai/MiniMax-H3-experimental/resolve/main/loras/MiniMax-H3-Ref2VA-Acc-8Step_pruned_comfy.safetensors', label: 'Kijai Ref2VA Acc 8-Step', category: 'distill', default_strength: 1, steps: 8, steps_min: 8, steps_max: 8, shift_video: 12 },
10
21
 
11
22
  // 15k-vote leaderboard + the authors' own READMEs): larryvrh's
12
23
  // v4-600 EMA is the crowd's #1 (1112 Elo at 6 steps; his README:
@@ -16,12 +27,30 @@ export const H3_LORA_ROWS = [
16
27
  // steps / 12-3 shift / er_sde beta57 (the strength contract
17
28
  // allows 0–2 — 1.5 is the designed point, not a typo). ──
18
29
  { id: 'h3_larryvrh_v4_ema', filename: 'h3/minimax_h3_turbo_v4_step600_ema.safetensors', source_url: 'https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora/resolve/main/minimax_h3_turbo_v4_step600_ema.safetensors', label: 'Larryvrh Turbo v4-600 EMA', category: 'distill', default_strength: 1, steps: 6, steps_min: 4, steps_max: 8 },
19
- { id: 'h3_pk_parasyte', filename: 'h3/H3-PK-Parasyte-Turbo.safetensors', source_url: 'https://huggingface.co/Plaguekind/H3-Lora/resolve/main/H3-PK-Parasyte-Turbo.safetensors', label: 'PK Parasyte Turbo', category: 'distill', default_strength: 1.5, steps: 8, steps_min: 6, steps_max: 8 },
30
+ { id: 'h3_pk_parasyte', filename: 'h3/H3-PK-Parasyte-Turbo.safetensors', source_url: 'https://huggingface.co/Plaguekind/H3-Lora/resolve/main/H3-PK-Parasyte-Turbo.safetensors', label: 'PK Parasyte Turbo', category: 'distill', default_strength: 1.5, steps: 8, steps_min: 6, steps_max: 8, shift_video: 12 },
31
+
32
+ // Matching as Adversarial Distillation (Yu et al., ByteDance +
33
+ // Texas A&M, arXiv:2610.02188). Rank-128 over the attn/ff modules
34
+ // of all 50 transformer blocks + 2 token refiners; turns the
35
+ // 50-step teacher into a 4-step generator at 1344x768 with native
36
+ // stereo audio. The paper's EMA checkpoint (`lora_critic`,
37
+ // iteration 800 of the main run) in ComfyUI's key layout, 2.0 GB;
38
+ // the higher-bench `full_critic` twin stays unboarded until the
39
+ // velocity arena rules (one row, one paper). LICENCE: the MiniMax
40
+ // H3 community licence — the base weights' own class; the V1
41
+ // region exclusion precedent applies. STRENGTH 1: distillation
42
+ // adapters are designed at full strength (the lightx2v convention
43
+ // above). The paper's no-CFG + shift 12/2 spelling matches what
44
+ // the composed arms already pin (no cfg knob exists on this
45
+ // card). The adaln guard rides the arena's first stacked load: a
46
+ // dense LoRA silently drops 51 adaln_proj keys on a pruned base —
47
+ // watch the load log (roadmap, H3 velocity rows). ──
48
+ { id: 'h3_dmad_4step', filename: 'h3/dmad_minimax_h3_4step_lora_critic_comfyui.safetensors', source_url: 'https://huggingface.co/ZhengmingYu/DMAD/resolve/main/minimax_h3/dmad_minimax_h3_4step_lora_critic_comfyui.safetensors', label: 'DMAD 4-Step (ByteDance/TAMU)', category: 'distill', default_strength: 1, steps: 4, steps_min: 4, steps_max: 4, shift_video: 12 },
20
49
  // ── THE REFINER (the second-pass instrument — see the refiner
21
50
  // design in the ledger): solo it is retired-tier (arena 935),
22
51
  // but 3 steps @ 0.7 over a non-accelerated draft "closes" the
23
52
  // generation without smearing (the TaoMate refiner recipe). ──
24
- { id: 'h3_taomate_3step', filename: 'h3/minimax_h3_taomate_3step_lora_avg_rank_19_bf16.safetensors', source_url: 'https://huggingface.co/Kijai/MiniMax-H3_comfy/resolve/main/loras/minimax_h3_taomate_3step_lora_avg_rank_19_bf16.safetensors', label: 'TaoMate 3-Step (refiner)', category: 'distill', default_strength: 0.7, steps: 3 },
53
+ { id: 'h3_taomate_3step', filename: 'h3/minimax_h3_taomate_3step_lora_avg_rank_19_bf16.safetensors', source_url: 'https://huggingface.co/Kijai/MiniMax-H3_comfy/resolve/main/loras/minimax_h3_taomate_3step_lora_avg_rank_19_bf16.safetensors', label: 'TaoMate 3-Step (refiner)', category: 'distill', default_strength: 0.35, steps: 3, steps_min: 3, steps_max: 6, shift_video: 6 },
25
54
  ];
26
55
  export function apply(ctx) {
27
56
  ctx.effect(() => ctx.comfyui.registerFlavor({
@@ -0,0 +1,123 @@
1
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
2
+ import type { OutputHandle } from '@melite/comfyui-card-kit/graph';
3
+ import type { H3Facts } from './actions.js';
4
+ /** The learned 3D-conv upscale weights (the schema's upscale_model
5
+ * seat carries this same single option — one file, one spelling, no
6
+ * hand-spelled alternatives). */
7
+ export declare const REFINE_UPSCALE_MODEL = "minimax_h3_latent_upscaler_3d_bf16.safetensors";
8
+ /** The 2x pass's measured memory ceiling, in frames at the film clock
9
+ * (24 fps). The friction report's §12.2/§13.2 sweep on the operator's
10
+ * box: 56 f and 90 f pass at 2x (2688×1536, 48 kHz); 141 f OOMs,
11
+ * needing 1.06 GiB more with 20.13 GiB already resident. H3's memory
12
+ * grows monotonically with the window, so a window past the measured
13
+ * OOM point cannot fit at this variant — the door refuses it by name
14
+ * instead of burning a render to find out. */
15
+ export declare const REFINE_2X_OOM_FRAMES = 141;
16
+
17
+
18
+
19
+
20
+ export declare const REFINE_DEFAULT_CLIP_SECONDS = 3.75;
21
+ /** The arm predicate: BAG PRESENCE — the same law as the
22
+ * replace/repair/extend/reshoot arms (a commission is armed when
23
+ * its bag is a NON-EMPTY ARRAY). Absent or empty bag = the compose
24
+ * never sees the chain (byte-stable graphs).
25
+ * @param p the gated compose doc
26
+ * @returns true when the refine bag carries at least one entry */
27
+ export declare function refineArmed(p: Record<string, unknown>): boolean;
28
+ /** ONE refine window's loader + save seats (the loop's coordinate).
29
+ * Frames at the film clock (24 fps) — the loader's own units. */
30
+ export interface RefineWindowSeat {
31
+ /** the window's frame cap (the loader's `frame_load_cap`) */
32
+ cap: number;
33
+ /** the window's first frame (the loader's `skip_first_frames`) */
34
+ skip: number;
35
+ /** frames trimmed off this window's OWN head (k≥2 carries the
36
+ * previous window's tail; 0 = the first window, no carry) */
37
+ overlapFrames: number;
38
+ /** this window's SaveVideo prefix (the run tree's own spelling) */
39
+ prefix: string;
40
+ }
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+
54
+
55
+
56
+ export declare function renderH3RefineWindow(entry: Record<string, unknown>, p: Record<string, unknown>, facts: H3Facts, g: GraphBuilder, seat: RefineWindowSeat): OutputHandle;
57
+ /** The refine renderer: validates the bound entry, then composes
58
+ * the standalone single-window second pass. Like the swap, the film
59
+ * path never reaches here (the card branches on a non-empty refine
60
+ * bag, and a bag under an armed reshoot — or beside any edit arm —
61
+ * refuses loud: one door per doc), and the emission ends in
62
+ * SaveVideo (the extend terminal's own file law — no
63
+ * ChainAssemble: a refine has no loop lineage to assemble).
64
+ * @param entry the refine mod's single bound entry
65
+ * @param p the walked doc params (the lora mod bag + scheduler knobs
66
+ * — the family plane this refine renders under)
67
+ * @param facts the family's lane facts (unet off the DECL row)
68
+ * @param g the run's graph builder
69
+ * @param runId the run tree's id (the refine filename rides it) */
70
+ export declare function renderH3Refine(entry: Record<string, unknown>, p: Record<string, unknown>, facts: H3Facts, g: GraphBuilder, runId: string): void;
71
+
72
+
73
+
74
+
75
+
76
+
77
+
78
+
79
+
80
+
81
+
82
+
83
+
84
+
85
+
86
+
87
+
88
+
89
+
90
+
91
+
92
+
93
+
94
+
95
+
96
+
97
+
98
+
99
+
100
+
101
+
102
+ export declare function renderH3RefineWindows(entry: Record<string, unknown>, p: Record<string, unknown>, facts: H3Facts, g: GraphBuilder, runId: string, loop: {
103
+ windows: number;
104
+ overlapFrames: number;
105
+ }): OutputHandle;
106
+ /** The loop's ARITHMETIC (one owner, the card and the wall both read
107
+ * it): how many windows cover `totalSeconds`, and where each starts.
108
+ * `count = ceil((total − overlap) / (clip − overlap))`, clamped to at
109
+ * least one; the last window may overrun the source (the loader
110
+ * stops at the file's own end).
111
+ * @param totalSeconds the stated length of the source film
112
+ * @param clipSeconds the single window's length
113
+ * @param overlapSeconds the carried overlap
114
+ * @returns the window count (≥ 1) */
115
+ export declare function refineWindowCount(totalSeconds: number, clipSeconds: number, overlapSeconds: number): number;
116
+ /** Where each window starts (seconds), in film order.
117
+ * @param count the window count from {@link refineWindowCount}
118
+ * @param clipSeconds the single window's length
119
+ * @param overlapSeconds the carried overlap
120
+ * @param startSeconds the first window's offset
121
+ * @returns the window start offsets, film order */
122
+ export declare function refineWindowStarts(count: number, clipSeconds: number, overlapSeconds: number, startSeconds?: number): number[];
123
+ //# sourceMappingURL=refine.d.ts.map
package/lib/refine.js ADDED
@@ -0,0 +1,301 @@
1
+ import { chainSaveBoundaries, concatSavedFilms, filmJoinAudio } from './actions.js';
2
+ import { h3MaskedEditPlane, loadVideo } from './chainEdit.js';
3
+ import { MAX_COMPOSED_WINDOWS } from './timelineContract.js';
4
+ /** The learned 3D-conv upscale weights (the schema's upscale_model
5
+ * seat carries this same single option — one file, one spelling, no
6
+ * hand-spelled alternatives). */
7
+ export const REFINE_UPSCALE_MODEL = 'minimax_h3_latent_upscaler_3d_bf16.safetensors';
8
+ /** The 2x pass's measured memory ceiling, in frames at the film clock
9
+ * (24 fps). The friction report's §12.2/§13.2 sweep on the operator's
10
+ * box: 56 f and 90 f pass at 2x (2688×1536, 48 kHz); 141 f OOMs,
11
+ * needing 1.06 GiB more with 20.13 GiB already resident. H3's memory
12
+ * grows monotonically with the window, so a window past the measured
13
+ * OOM point cannot fit at this variant — the door refuses it by name
14
+ * instead of burning a render to find out. */
15
+ export const REFINE_2X_OOM_FRAMES = 141;
16
+
17
+
18
+
19
+
20
+ export const REFINE_DEFAULT_CLIP_SECONDS = 3.75;
21
+ /** The refine entry's required seats (the reshoot idiom: an armed
22
+ * doc with an empty seat refuses loud naming the seat). */
23
+ const REQUIRED_SEATS = [
24
+ ['source_clip', 'the clip whose frames the second pass refines — ONE staged leaf: the VHS loader reads it by staged name at the film clock, and the encode seats read its frames + soundtrack'],
25
+ ['refine_prompt', 'the refine text — what the upscaled frames should hold (agent-composed, user-confirmed; rides the CLIPTextEncode positive seat — the node refuses without model + positive)'],
26
+ ];
27
+ const num = (e, key, d) => typeof e[key] === 'number' ? e[key] : d;
28
+ /** The arm predicate: BAG PRESENCE — the same law as the
29
+ * replace/repair/extend/reshoot arms (a commission is armed when
30
+ * its bag is a NON-EMPTY ARRAY). Absent or empty bag = the compose
31
+ * never sees the chain (byte-stable graphs).
32
+ * @param p the gated compose doc
33
+ * @returns true when the refine bag carries at least one entry */
34
+ export function refineArmed(p) {
35
+ const bag = p.refine;
36
+ return Array.isArray(bag) && bag.length > 0;
37
+ }
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+ export function renderH3RefineWindow(entry, p, facts, g, seat) {
54
+ for (const [seat, what] of REQUIRED_SEATS) {
55
+ const v = entry[seat];
56
+ if (typeof v !== 'string' || v.trim() === '') {
57
+ throw new Error(`h3-timeline refine: '${seat}' names no media — ${what}; a refine needs both seats bound (source_clip, refine_prompt)`);
58
+ }
59
+ }
60
+ const denoise = num(entry, 'denoise', 0.32);
61
+ if (denoise >= 1) {
62
+ throw new Error(`h3-timeline refine: denoise ${denoise} >= 1 — a second pass is a refine, never a re-render (the partial-denoise window is 0.05–0.50; a full-noise sigma discards the learned upscaled latent and the vendored node throws — that is a reshoot, and the reshoot door exists)`);
63
+ }
64
+ const seed = num(entry, 'seed', 0);
65
+ const steps = num(entry, 'steps', 6);
66
+
67
+ // three sizing modes and a [1, 4] multiplier. A stated seat rides
68
+ // verbatim (the knob bounds are the card's own); absent keeps the
69
+ // shipped 2x so every existing doc composes byte-identically.
70
+ const upMode = entry['mode'] ?? 'scale by multiplier';
71
+ const upScale = entry['scale'] ?? 2.0;
72
+ // ── THE WINDOW (F24's cure, round 6): a refine refines a WINDOW of
73
+
74
+ // frame of the source and hand the full latent to the 2x handoff,
75
+ // so any clip past ~90 f died engine-side (141 f OOM, §13.2). The
76
+ // window is the loader's own two seats: frame_load_cap stops the
77
+ // read and skip_first_frames offsets it — VHS trims the soundtrack
78
+ // by the same window (load_video_nodes.py: `start_time =
79
+ // skip_first_frames * target_frame_time`, `lazy_get_audio(video,
80
+ // start_time, frame_load_cap * target_frame_time)`), so the encode
81
+ // seats read the WINDOW's frames and the WINDOW's audio, in sync.
82
+ // A long film is covered by advancing start_seconds window by
83
+ // window (the card's section states the stepping law).
84
+ const clipSeconds = seat.cap / 24;
85
+ if (!Number.isInteger(seat.cap) || seat.cap < 1) {
86
+ throw new Error(`h3-timeline refine: a ${seat.cap} f window — a refine window needs frames (the loop's cap is the loader's frame_load_cap at 24 fps; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
87
+ }
88
+ if (!Number.isInteger(seat.skip) || seat.skip < 0) {
89
+ throw new Error(`h3-timeline refine: a window starting at frame ${seat.skip} — a window starts at or after the clip's first frame (the loop's skip is the loader's skip_first_frames)`);
90
+ }
91
+ const windowFrames = seat.cap;
92
+ const skipFrames = seat.skip;
93
+
94
+ // the measured OOM is a function of the WINDOW first and the upscale
95
+ // factor second — H3's memory grows with the frame count through the
96
+ // learned 3D upscaler and the sampler. The first cut guarded only
97
+ // `scale by multiplier` ≥ 2, so a target-dimensions or megapixels
98
+ // window walked past the same ceiling into the measured OOM with no
99
+ // refusal. Only a same-size multiplier pass (< 2, the capacity cure)
100
+ // is exempt: its upscaler is the identity, which is what made 144 f
101
+ // fit at 1x. The other two modes size from the source and cannot be
102
+ // judged ≤ 1x before the read, so they take the ceiling.
103
+ const sameSize = upMode === 'scale by multiplier' && upScale < 2;
104
+ if (!sameSize && windowFrames > REFINE_2X_OOM_FRAMES) {
105
+ const named = upMode === 'scale by multiplier' ? `${upScale}x` : upMode;
106
+ throw new Error(`h3-timeline refine: a ${windowFrames} f window at ${named} — the 2x pass was measured OOM at ${REFINE_2X_OOM_FRAMES} f and green at ${REFINE_DEFAULT_CLIP_SECONDS * 24} f (2688×1536, 48 kHz; H3 memory grows with the window, so a wider window cannot fit — the ceiling belongs to the WINDOW, whichever sizing mode upsizes). Cut clip_seconds to ${(REFINE_2X_OOM_FRAMES / 24).toFixed(2)} s or less and cover the rest window by window, or lower scale to 1 for a same-size pass`);
107
+ }
108
+ // ── the staged media (the shared loader law, force-rate-24 VHS —
109
+ // never a private LoadVideo pair) + the family's own plane ──
110
+ // (the REQUIRED_SEATS loop above proved source_clip a non-empty
111
+ // string — the cast restates the proven, never a fallback: there
112
+ // is no default clip, and the sibling str() fallback would be a
113
+ // dead branch here, uncovered by any honest door)
114
+ const [srcFrames, srcAudio] = loadVideo(g, entry['source_clip'], windowFrames, skipFrames);
115
+ const { sigmaModel, samplerSel, clip, vaeVideo, vaeAudio } = h3MaskedEditPlane(g, p, facts, clipSeconds);
116
+ // ── the split-stream encode (the node's own contract:
117
+ // _resolve_h3_sources rebuilds native joint AV from plain 24ch
118
+ // video + the matching audio latent) ──
119
+ const videoLatent = g.node('VAEEncode', { pixels: srcFrames, vae: vaeVideo }).out(0);
120
+ const audioLatent = g.node('VAEEncodeAudio', { audio: srcAudio, vae: vaeAudio }).out(0);
121
+ const positive = g.node('CLIPTextEncode', {
122
+ text: entry['refine_prompt'], clip,
123
+ }).out(0);
124
+ const noise = g.node('RandomNoise', { noise_seed: seed }).out(0);
125
+ const sched = g.node('BasicScheduler', {
126
+ model: sigmaModel, scheduler: p.sched_name,
127
+ steps, denoise,
128
+ }).out(0);
129
+ // ── THE HANDOFF (the report-named chain: learned 2x upscale +
130
+ // the low-sigma refinement pass, one node — its output is final/
131
+ // decode-ready, no external guider or second sampler) ──
132
+ // THE CAPACITY SEATS ride the handoff verbatim — the window above is
133
+ // what keeps a 2x pass inside memory; a ≤1x pass sizes its own.
134
+ const upscaled = g.node('MinimaxH3LatentUpscaler3DRefineHandoff', {
135
+ latent: videoLatent, audio_latent: audioLatent,
136
+ noise, sampler: samplerSel, sigmas: sched,
137
+ model: sigmaModel, positive,
138
+ model_name: REFINE_UPSCALE_MODEL,
139
+ // THE FLAT CLASS (F23 blocker, round-6 audit): THIS handoff
140
+ // declares `mode` as a plain combo and `scale` as its OWN required
141
+ // top-level FLOAT (production /object_info + the vendored
142
+ // minimax_h3_refine.py:349-353) — there is no `mode.scale` seat on
143
+ // it. The dotted spelling belongs to MinimaxH3LatentUpscaler3D
144
+ // (COMFY_DYNAMICCOMBO_V3, chainUpscale.ts), a DIFFERENT node; the
145
+ // round-5 cure crossed the two and reintroduced
146
+ // required_input_missing on this member.
147
+ mode: upMode, scale: upScale,
148
+ // Multiplier mode ignores these (the film's own note at its
149
+ // handoff mount) — they ride the upscaler's own defaults.
150
+ width: 1280, height: 704, megapixels: 1,
151
+ keep_proportion: true, align: 32,
152
+ lock_audio: true, cfg: 1.0, device: 'cuda', precision: 'bf16',
153
+ offload_after_upscale: false,
154
+ }).out(0);
155
+ // ── decode + the film tail's file law ──
156
+ let vdec = g.node('VAEDecode', { samples: upscaled, vae: vaeVideo }).out(0);
157
+ let adec = g.node('VAEDecodeAudio', { samples: upscaled, vae: vaeAudio }).out(0);
158
+ if (seat.overlapFrames > 0) {
159
+ // THE CARRIED HEAD (the loop's seam law): a k≥2 window's opening
160
+ // overlap is the previous window's tail re-rendered, so this
161
+ // window's OWN clip never replays it — the film's finalize node,
162
+ // hard audio trim (the carried seam leaves picture AND sound).
163
+ const fin = g.node('MiniMaxH3FiniteSegmentFinalize', {
164
+ sampled_latent: upscaled, images: vdec, audio: adec,
165
+ iteration: 1, overlap_frames: seat.overlapFrames, trim_audio_head: true,
166
+ });
167
+ vdec = fin.out(1);
168
+ adec = fin.out(2);
169
+ }
170
+ const created = g.node('CreateVideo', {
171
+ images: vdec, audio: filmJoinAudio(g, adec), fps: 24, bit_depth: 8,
172
+ });
173
+ return g.node('SaveVideo', {
174
+ video: created.out(), filename_prefix: seat.prefix,
175
+ format: 'mp4', codec: 'h264',
176
+ }).out(0);
177
+ }
178
+ /** The refine renderer: validates the bound entry, then composes
179
+ * the standalone single-window second pass. Like the swap, the film
180
+ * path never reaches here (the card branches on a non-empty refine
181
+ * bag, and a bag under an armed reshoot — or beside any edit arm —
182
+ * refuses loud: one door per doc), and the emission ends in
183
+ * SaveVideo (the extend terminal's own file law — no
184
+ * ChainAssemble: a refine has no loop lineage to assemble).
185
+ * @param entry the refine mod's single bound entry
186
+ * @param p the walked doc params (the lora mod bag + scheduler knobs
187
+ * — the family plane this refine renders under)
188
+ * @param facts the family's lane facts (unet off the DECL row)
189
+ * @param g the run's graph builder
190
+ * @param runId the run tree's id (the refine filename rides it) */
191
+ export function renderH3Refine(entry, p, facts, g, runId) {
192
+ const clipSeconds = num(entry, 'clip_seconds', REFINE_DEFAULT_CLIP_SECONDS);
193
+ const startSeconds = num(entry, 'start_seconds', 0);
194
+ if (!(clipSeconds > 0)) {
195
+ throw new Error(`h3-timeline refine: clip_seconds ${clipSeconds} — a refine window needs frames (the seat is the loader's frame_load_cap: seconds × 24 at the film clock; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
196
+ }
197
+ if (!(startSeconds >= 0)) {
198
+ throw new Error(`h3-timeline refine: start_seconds ${startSeconds} — a window starts at or after the clip's first frame (the seat is the loader's skip_first_frames); advance it window by window to cover a long film`);
199
+ }
200
+ renderH3RefineWindow(entry, p, facts, g, {
201
+ cap: Math.max(1, Math.round(clipSeconds * 24)),
202
+ skip: Math.round(startSeconds * 24),
203
+ overlapFrames: 0,
204
+ prefix: `${runId}/refine`,
205
+ });
206
+ }
207
+
208
+
209
+
210
+
211
+
212
+
213
+
214
+
215
+
216
+
217
+
218
+
219
+
220
+
221
+
222
+
223
+
224
+
225
+
226
+
227
+
228
+
229
+
230
+
231
+
232
+
233
+
234
+
235
+
236
+
237
+
238
+ export function renderH3RefineWindows(entry, p, facts, g, runId, loop) {
239
+ if (!Number.isInteger(loop.windows) || loop.windows < 1) {
240
+ throw new Error(`h3-timeline refine: ${loop.windows} windows — a refine loop renders at least one window (the count derives from total_seconds and the window step)`);
241
+ }
242
+ if (loop.windows > MAX_COMPOSED_WINDOWS) {
243
+ throw new Error(`h3-timeline refine: ${loop.windows} windows — the film's composed-window ceiling is ${MAX_COMPOSED_WINDOWS} (${(MAX_COMPOSED_WINDOWS * (REFINE_DEFAULT_CLIP_SECONDS - 22 / 24)).toFixed(2)} s at the default window); refine a shorter film or raise clip_seconds inside the measured ${REFINE_2X_OOM_FRAMES} f ceiling`);
244
+ }
245
+ if (!Number.isInteger(loop.overlapFrames) || loop.overlapFrames < 0) {
246
+ throw new Error(`h3-timeline refine: overlap ${loop.overlapFrames} f — the carried overlap is a whole frame count at or above zero (the film's own seam is 22 f)`);
247
+ }
248
+ const clipSeconds = num(entry, 'clip_seconds', REFINE_DEFAULT_CLIP_SECONDS);
249
+ if (!(clipSeconds > 0)) {
250
+ throw new Error(`h3-timeline refine: clip_seconds ${clipSeconds} — a refine window needs frames (the seat is the loader's frame_load_cap: seconds × 24 at the film clock; the safe default is ${REFINE_DEFAULT_CLIP_SECONDS} s = 90 f)`);
251
+ }
252
+ const startFrames = Math.round(num(entry, 'start_seconds', 0) * 24);
253
+ const cap = Math.max(1, Math.round(clipSeconds * 24));
254
+ const step = cap - loop.overlapFrames;
255
+ if (step <= 0) {
256
+ throw new Error(`h3-timeline refine: overlap ${loop.overlapFrames} f against a ${cap} f window — a carried overlap shorter than the window is the only walk that advances (step ${step} f)`);
257
+ }
258
+ const prefixes = [];
259
+ const saves = [];
260
+ for (let k = 0; k < loop.windows; k += 1) {
261
+ const prefix = `${runId}/refine_w${k}`;
262
+ saves.push(renderH3RefineWindow(entry, p, facts, g, {
263
+ cap, skip: startFrames + k * step,
264
+ overlapFrames: k === 0 ? 0 : loop.overlapFrames,
265
+ prefix,
266
+ }));
267
+ prefixes.push(prefix);
268
+ }
269
+ const boundary = chainSaveBoundaries(g, saves);
270
+ return concatSavedFilms(g, prefixes, boundary, `${runId}/refine`);
271
+ }
272
+ /** The loop's ARITHMETIC (one owner, the card and the wall both read
273
+ * it): how many windows cover `totalSeconds`, and where each starts.
274
+ * `count = ceil((total − overlap) / (clip − overlap))`, clamped to at
275
+ * least one; the last window may overrun the source (the loader
276
+ * stops at the file's own end).
277
+ * @param totalSeconds the stated length of the source film
278
+ * @param clipSeconds the single window's length
279
+ * @param overlapSeconds the carried overlap
280
+ * @returns the window count (≥ 1) */
281
+ export function refineWindowCount(totalSeconds, clipSeconds, overlapSeconds) {
282
+ const step = clipSeconds - overlapSeconds;
283
+ if (!(step > 0)) {
284
+ throw new Error(`h3-timeline refine: overlap ${overlapSeconds} s against a ${clipSeconds} s window — a carried overlap shorter than the window is the only walk that advances (step ${step} s)`);
285
+ }
286
+ if (!(totalSeconds > 0)) {
287
+ throw new Error(`h3-timeline refine: total_seconds ${totalSeconds} — an auto walk states the source film's length (the compose door cannot stat the staged clip: the window count needs a number, never a guess)`);
288
+ }
289
+ return Math.max(1, Math.ceil((totalSeconds - overlapSeconds) / step));
290
+ }
291
+ /** Where each window starts (seconds), in film order.
292
+ * @param count the window count from {@link refineWindowCount}
293
+ * @param clipSeconds the single window's length
294
+ * @param overlapSeconds the carried overlap
295
+ * @param startSeconds the first window's offset
296
+ * @returns the window start offsets, film order */
297
+ export function refineWindowStarts(count, clipSeconds, overlapSeconds, startSeconds = 0) {
298
+ const step = clipSeconds - overlapSeconds;
299
+ return Array.from({ length: count }, (_, k) => startSeconds + k * step);
300
+ }
301
+ //# sourceMappingURL=refine.js.map
@@ -0,0 +1,15 @@
1
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
2
+ import type { H3Facts } from './actions.js';
3
+ /** The repair renderer: validates the bound entry, then composes the
4
+ * masked second-pass chain. Like the swap, the film path never
5
+ * reaches here (the card branches on a non-empty repair bag, refuses
6
+ * a bag under an armed reshoot or replace — one door per doc), and
7
+ * the emission ends in MiniMaxH3ChainAssemble.
8
+ * @param entry the repair mod's single bound entry
9
+ * @param p the walked doc params (the lora mod bag + SLA/shift knobs
10
+ * — the family plane this repair renders under)
11
+ * @param facts the family's lane facts (unet off the DECL row)
12
+ * @param g the run's graph builder
13
+ * @param runId the run tree's id (the assemble filename rides it) */
14
+ export declare function renderH3Repair(entry: Record<string, unknown>, p: Record<string, unknown>, facts: H3Facts, g: GraphBuilder, runId: string): void;
15
+ //# sourceMappingURL=repair.d.ts.map