@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.
@@ -0,0 +1,17 @@
1
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
2
+ import type { H3Facts } from './actions.js';
3
+ export { solveWindowComposition, type WindowComposition } from './timelineContract.js';
4
+ /** The extend renderer: validates the bound entry, then composes the
5
+ * fresh-continuation chain plus the join. Like the swap and repair,
6
+ * the film path never reaches here (the card branches on a non-empty
7
+ * extend bag and refuses a bag under an armed reshoot, replace, or
8
+ * repair — one door per doc), and the emission ends in the
9
+ * joined-film SaveVideo.
10
+ * @param entry the extend mod's single bound entry
11
+ * @param p the walked doc params (the lora mod bag + SLA/shift knobs
12
+ * — the family plane this extension renders under)
13
+ * @param facts the family's lane facts (unet off the DECL row)
14
+ * @param g the run's graph builder
15
+ * @param runId the run tree's id (the join prefixes ride it) */
16
+ export declare function renderH3Extend(entry: Record<string, unknown>, p: Record<string, unknown>, facts: H3Facts, g: GraphBuilder, runId: string): void;
17
+ //# sourceMappingURL=extend.d.ts.map
package/lib/extend.js ADDED
@@ -0,0 +1,174 @@
1
+ import { chainSaveBoundaries, concatSavedFilms, filmJoinAudio } from './actions.js';
2
+ import { assertGridLength, solveWindowComposition, CONTEXT_OVERLAP_FRAMES, GRID_MAX_FRAMES, } from './timelineContract.js';
3
+ export { solveWindowComposition } from './timelineContract.js';
4
+ import { loadVideo, renderMaskedEditChain } from './chainEdit.js';
5
+ /** The extend entry's required seats (the reshoot/repair idiom: an
6
+ * armed doc with an empty seat refuses loud naming the seat). */
7
+ const REQUIRED_SEATS = [
8
+ ['source_clip', 'the clip whose seconds are extended — ONE staged leaf: the VHS loader + the core LoadVideo read it by staged name, and the timeline reads it back off the native VIDEO wire'],
9
+ ['extend_prompt', 'the continuation text — MOTION+SOUND for the appended seconds (the R2V prompt seat; agent-composed, user-confirmed)'],
10
+ ];
11
+ const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
12
+ const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
13
+ /** The extend renderer: validates the bound entry, then composes the
14
+ * fresh-continuation chain plus the join. Like the swap and repair,
15
+ * the film path never reaches here (the card branches on a non-empty
16
+ * extend bag and refuses a bag under an armed reshoot, replace, or
17
+ * repair — one door per doc), and the emission ends in the
18
+ * joined-film SaveVideo.
19
+ * @param entry the extend mod's single bound entry
20
+ * @param p the walked doc params (the lora mod bag + SLA/shift knobs
21
+ * — the family plane this extension renders under)
22
+ * @param facts the family's lane facts (unet off the DECL row)
23
+ * @param g the run's graph builder
24
+ * @param runId the run tree's id (the join prefixes ride it) */
25
+ export function renderH3Extend(entry, p, facts, g, runId) {
26
+ for (const [seat, what] of REQUIRED_SEATS) {
27
+ const v = entry[seat];
28
+ if (typeof v !== 'string' || v.trim() === '') {
29
+ throw new Error(`h3-timeline extend: '${seat}' names no media — ${what}; an extend needs both seats bound (source_clip, extend_prompt)`);
30
+ }
31
+ }
32
+ const seed = num(entry, 'seed', 0);
33
+ const steps = num(entry, 'steps', 6);
34
+ const overlapFrames = num(entry, 'overlap_frames', 39);
35
+ const resolution = str(entry, 'resolution') || '736p';
36
+ const statedFrames = Math.round(num(entry, 'extend_seconds', 56 / 24) * 24);
37
+ // THE COMPOSITION DOOR: one window keeps the landed grid law
38
+ // verbatim; beyond it the solver composes N uniform windows and
39
+ // refuses every non-exact landing by name. The solver ALWAYS
40
+ // carries the policy's 39f overlap (every law-home pins 39 —
41
+ // SKILL.md, the registry row, CONTEXT_OVERLAP_FRAMES, the refusal
42
+ // text); the entry knob never rides seam math. A multi-window
43
+ // extend under a knob ≠ 39 would compose exact-DELIVERY numbers
44
+ // the chain then stitches at a different carry — the exactness
45
+ // guarantee breaks silently — so it refuses loud instead (the
46
+ // dsh-docs audit's MED-1).
47
+ const composition = statedFrames <= GRID_MAX_FRAMES
48
+ ? { windows: 1, windowFrames: assertGridLength(statedFrames, 'h3-timeline extend'), deliveredFrames: statedFrames }
49
+ : solveWindowComposition(statedFrames, 'h3-timeline extend');
50
+ if (composition.windows > 1 && overlapFrames !== CONTEXT_OVERLAP_FRAMES) {
51
+ throw new Error(`h3-timeline extend: overlap_frames ${overlapFrames} — the multi-window composition law carries the policy's ${CONTEXT_OVERLAP_FRAMES}f context overlap (every law-home pins 39; the knob feeds only the single-window plan head); re-state overlap_frames 39`);
52
+ }
53
+ const clipSeconds = composition.windowFrames / 24;
54
+ // ── the staged media: the WHOLE prior clip on the VHS seat
55
+ // (force_rate 24 — the one clock) and its LAST FRAME as the
56
+ // in-graph anchor (negative batch index, engine core) ──
57
+ const [priorFrames, priorAudio] = loadVideo(g, str(entry, 'source_clip'));
58
+ const lastFrame = g.node('ImageFromBatch', {
59
+ image: priorFrames, batch_index: -1, length: 1,
60
+ }).out(0);
61
+ // ── THE SEAT'S OWN PLAN (clause 3): N continuation shots — the
62
+ // literal rules, plan_json_input stays UNWIRED (the plan node's
63
+ // source slicing is the swap's semantics, never a continuation's;
64
+ // the cure for the re-slice bug the unification's survey found) ──
65
+ const shots = Array.from({ length: composition.windows }, (_k, i) => ({
66
+ id: `extend-${i + 1}`, prompt: str(entry, 'extend_prompt'),
67
+ }));
68
+ const planJson = JSON.stringify({ shots });
69
+ const { trimmed, assemblePath } = renderMaskedEditChain(g, {
70
+ p, facts,
71
+ clipSeconds,
72
+ overlapFrames,
73
+ resolution, seed, steps,
74
+ roles: '',
75
+ sourceClip: str(entry, 'source_clip'),
76
+ windowStart: 0,
77
+ picture1: lastFrame,
78
+ srcFrames: priorFrames,
79
+ srcAudio: priorAudio,
80
+ planJson,
81
+ planFromSource: false,
82
+ denoise: 1,
83
+ // THE LATENT-CARRY TERMINAL (clause 4): N ≥ 2 windows assemble
84
+ // IN-CHAIN — ChainAssemble owns the seams under the policy's
85
+ // overlap (fresh content's soundtrack assembles from the
86
+ // checkpointed H3 sound); one window joins by file directly.
87
+ assemble: composition.windows >= 2
88
+ ? { audioSource: 'generated', filename: `${runId}/extend_chain` }
89
+ : null,
90
+ body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio }) => {
91
+ // The everywhere-generate mask: an all-white SolidMask sized
92
+ // to the chain's own geometry (nothing held — extended
93
+ // seconds are new content). `.out(0)`: a mask SEAT takes an
94
+ // output LINK `[key, slot]` — a bare node handle serializes
95
+ // `{"id": ...}` and the engine dies at reshape (the F10 burn,
96
+
97
+ const whiteMask = g.node('SolidMask', {
98
+ value: 1, width: cur.out(8), height: cur.out(9),
99
+ }).out(0);
100
+ // ── the fresh-continuation body: the anchor rides BOTH
101
+ // reference seats — the last frame as the pixel anchor
102
+ // (ref_image_0) and the whole clip as the motion identity
103
+ // (ref_video_0), the swap/repair spine's own seats ──
104
+ const r2v = g.node('MiniMaxH3ReferenceToVideo', {
105
+ prompt: str(entry, 'extend_prompt'),
106
+ width: cur.out(8), height: cur.out(9), length: cur.out(6),
107
+ ref_image_size: 'match',
108
+ clip, vae: vaeVideo, audio_vae: vaeAudio,
109
+ 'ref_images.ref_image_0': lastFrame,
110
+ 'ref_videos.ref_video_0': priorFrames,
111
+ 'ref_video_audios.ref_video_audio_0': mutedChainAudio,
112
+ });
113
+ const slice = g.node('H3SourceSlice', {
114
+ source_fps: 24, crop: 'center',
115
+ state: cur.out(0), latent: r2v.out(1),
116
+ audio_vae: vaeAudio, source_frames: priorFrames, source_audio: sliceAudio,
117
+ });
118
+ const edit = g.node('MiniMaxH3FantasticVideoEditLatent', {
119
+ grow: 0, keep_audio: false, megapixels: 0,
120
+ vae: vaeVideo, images: slice.out(0), mask: whiteMask,
121
+ audio_vae: vaeAudio, audio: slice.out(1),
122
+ }).out(0);
123
+ const target = g.node('MiniMaxH3ContexMaskedTarget', {
124
+ mask_meaning: 'white = generate',
125
+ audio_mode: 'generate all audio',
126
+ mask_conversion: 'H3 exact (causal/token max)',
127
+ target_latent: edit, mask: whiteMask,
128
+ }).out(0);
129
+ return { conditioning: r2v.out(0), targetLatent: target };
130
+ },
131
+ });
132
+ // ── THE JOIN (the file-join primitive; the initial raw boundary
133
+ // is the exception the latent carry cannot cross — clause 4) ──
134
+ if (assemblePath !== null) {
135
+ // MULTI-WINDOW: the prior re-muxes at x0 (the join grammar needs
136
+ // an output-dir file; the prior's frames + its own soundtrack
137
+ // ride verbatim — the extension never rewrites history); the
138
+ // ASSEMBLED extension rides the concat's append seat — an exact
139
+ // saved-file path (ChainAssemble's video_path output, wired:
140
+ // the DAG itself proves the assembly completed before the join).
141
+ const priorCreated = g.node('CreateVideo', {
142
+ images: priorFrames, audio: filmJoinAudio(g, priorAudio), fps: 24, bit_depth: 8,
143
+ });
144
+ const priorSaved = g.node('SaveVideo', {
145
+ video: priorCreated.out(), filename_prefix: `${runId}/x0`,
146
+ format: 'mp4', codec: 'h264',
147
+ }).out();
148
+ const after = chainSaveBoundaries(g, [priorSaved]);
149
+ concatSavedFilms(g, [`${runId}/x0`], after, `${runId}/extend_film`, {
150
+ append: assemblePath,
151
+ });
152
+ return;
153
+ }
154
+ // SINGLE-WINDOW (the landed shape): both parts save at prefixes,
155
+ // the boundary chain orders them, the concat joins, the container
156
+ // delivers <runId>/extend_film.
157
+ const newCreated = g.node('CreateVideo', {
158
+ images: trimmed.out(0), audio: filmJoinAudio(g, trimmed.out(1)), fps: 24, bit_depth: 8,
159
+ });
160
+ const newSaved = g.node('SaveVideo', {
161
+ video: newCreated.out(), filename_prefix: `${runId}/x1`,
162
+ format: 'mp4', codec: 'h264',
163
+ }).out();
164
+ const priorCreated = g.node('CreateVideo', {
165
+ images: priorFrames, audio: filmJoinAudio(g, priorAudio), fps: 24, bit_depth: 8,
166
+ });
167
+ const priorSaved = g.node('SaveVideo', {
168
+ video: priorCreated.out(), filename_prefix: `${runId}/x0`,
169
+ format: 'mp4', codec: 'h264',
170
+ }).out();
171
+ const after = chainSaveBoundaries(g, [newSaved, priorSaved]);
172
+ concatSavedFilms(g, [`${runId}/x0`, `${runId}/x1`], after, `${runId}/extend_film`);
173
+ }
174
+ //# sourceMappingURL=extend.js.map
package/lib/filmMix.d.ts CHANGED
@@ -3,7 +3,7 @@ export type FilmMixClipClass = 'dialogue' | 'sfx' | 'music';
3
3
  /** One clip row — the card's audio_clips shape, post-parse. */
4
4
  export interface FilmMixClip {
5
5
  readonly src: string;
6
- /** doc-anchored start (frames @24fps — the stamp, studio lanes, and tool face all speak doc). */
6
+ /** doc-anchored start (frames at the DOC CLOCK — the stamp, studio lanes, and tool face all speak doc). */
7
7
  readonly start: number;
8
8
  /** duration (frames; 0 = overlay-only, unsized). */
9
9
  readonly dur: number;
@@ -59,10 +59,16 @@ export interface FilmMixManifest {
59
59
  export interface FilmMixInput {
60
60
  readonly spans: FilmMixSpan[];
61
61
  readonly clips: FilmMixClip[];
62
- /** per-window rendered durations (seconds) — stanza length/24 at
63
- * compose time, probed durations disk-side. THE ground truth the
64
- * owner map accumulates (never re-derived from spans). */
62
+ /** per-window rendered durations (seconds) — stanza length at the
63
+ * doc clock at compose time, probed durations disk-side. THE
64
+ * ground truth the owner map accumulates (never re-derived from
65
+ * spans). */
65
66
  readonly windowSecs: number[];
67
+ /** the DOC CLOCK for the owner map's frames→seconds joins (the
68
+ * overlap trims). Unstated = DOC_FPS_DEFAULT — one clock with
69
+ * stanzaSecs and the stamps (journey audit AUDIO-2: this seat
70
+ * hardcoded /24 while the container played p.fps). */
71
+ readonly fps?: number;
66
72
  readonly duckDb?: number;
67
73
  }
68
74
  /** The duck span string — "start:end" at ms precision, ';'-joined. */
@@ -70,11 +76,19 @@ export declare function formatDuckSpan(start: number, end: number): string;
70
76
  /** Per-window stanza seconds — THE compose-time windowSecs
71
77
  * (computeFilmMix's ground truth): the render grid's own promise,
72
78
  * the deliverer's contract — SaveVideo hands back exactly stanza
73
- * frames at 24fps. No probe, no disk: the clock is pure at
74
- * compose. RAW fractions (frames/24, unrounded): the manifest sums
75
- * these into film starts, and rounding a SUM of rounded parts
76
- * compounds drift (the 3-window seat 7.416 ≠ 7.417 proof) — only
77
- * the final seats/spans round (ms, computeFilmMix's own law). */
78
- export declare function stanzaSecs(spans: readonly FilmMixSpan[]): number[];
79
+ * frames at the DOC CLOCK (fps, unstated = DOC_FPS_DEFAULT; the
80
+ * three-clock cure, journey audit AUDIO-2: this divisor hardcoded
81
+ * /24 while the container played p.fps — a 16fps film's manifest
82
+ * overbooked every window by 1.5x). No probe, no disk: the clock
83
+ * is pure at compose. RAW fractions (frames/fps, unrounded): the
84
+ * manifest sums these into film starts, and rounding a SUM of
85
+ * rounded parts compounds drift (the 3-window seat 7.416 ≠ 7.417
86
+ * proof) — only the final seats/spans round (ms,
87
+ * computeFilmMix's own law).
88
+ *
89
+ * @param spans the film windows, doc frames
90
+ * @param fps the DOC CLOCK (unstated docs pass DOC_FPS_DEFAULT —
91
+ * never a foreign default; the walk fills the same value) */
92
+ export declare function stanzaSecs(spans: readonly FilmMixSpan[], fps?: number): number[];
79
93
  export declare function computeFilmMix(input: FilmMixInput): FilmMixManifest;
80
94
  //# sourceMappingURL=filmMix.d.ts.map
package/lib/filmMix.js CHANGED
@@ -16,8 +16,8 @@
16
16
  //
17
17
  // The two wrongs in the card's history (the +22f carry original,
18
18
  // the start/24 first correction) stay dead in one place.
19
- import { spanOverlap, spanStanzaFrames } from "./timelineContract.js";
20
- export { spanOverlap, spanStanzaFrames } from "./timelineContract.js";
19
+ import { DOC_FPS_DEFAULT, spanOverlap, spanStanzaFrames } from './timelineContract.js';
20
+ export { spanOverlap, spanStanzaFrames } from './timelineContract.js';
21
21
  /** Parse raw audio_clips rows — the card's one law for what a clip
22
22
  * IS: a src without a numeric start_frame refuses loud (never a
23
23
  * silent misplacement); a row without src is junk and skips; the
@@ -75,36 +75,49 @@ export function formatDuckSpan(start, end) {
75
75
  /** Per-window stanza seconds — THE compose-time windowSecs
76
76
  * (computeFilmMix's ground truth): the render grid's own promise,
77
77
  * the deliverer's contract — SaveVideo hands back exactly stanza
78
- * frames at 24fps. No probe, no disk: the clock is pure at
79
- * compose. RAW fractions (frames/24, unrounded): the manifest sums
80
- * these into film starts, and rounding a SUM of rounded parts
81
- * compounds drift (the 3-window seat 7.416 ≠ 7.417 proof) — only
82
- * the final seats/spans round (ms, computeFilmMix's own law). */
83
- export function stanzaSecs(spans) {
78
+ * frames at the DOC CLOCK (fps, unstated = DOC_FPS_DEFAULT; the
79
+ * three-clock cure, journey audit AUDIO-2: this divisor hardcoded
80
+ * /24 while the container played p.fps — a 16fps film's manifest
81
+ * overbooked every window by 1.5x). No probe, no disk: the clock
82
+ * is pure at compose. RAW fractions (frames/fps, unrounded): the
83
+ * manifest sums these into film starts, and rounding a SUM of
84
+ * rounded parts compounds drift (the 3-window seat 7.416 ≠ 7.417
85
+ * proof) — only the final seats/spans round (ms,
86
+ * computeFilmMix's own law).
87
+ *
88
+ * @param spans the film windows, doc frames
89
+ * @param fps the DOC CLOCK (unstated docs pass DOC_FPS_DEFAULT —
90
+ * never a foreign default; the walk fills the same value) */
91
+ export function stanzaSecs(spans, fps = DOC_FPS_DEFAULT) {
84
92
  // INDEX-AWARE CARRY (the render's chainLike law, stated here so
85
93
  // the clock and the stanza can never disagree): window 1 renders
86
94
  // fresh; k≥2 carries spanOverlap — the same 22 the finalize
87
95
  // trims off the saved clip. The stanza covers carry + span, the
88
96
  // contribution to the film is stanza − carry, so the clock's
89
97
  // window seats land where the saved frames actually are.
90
- return spans.map((s, i) => spanStanzaFrames(s, i > 0 ? spanOverlap(s) : 0) / 24);
98
+ return spans.map((s, i) => spanStanzaFrames(s, i > 0 ? spanOverlap(s) : 0) / fps);
91
99
  }
92
100
  export function computeFilmMix(input) {
93
101
  const { spans, clips, windowSecs } = input;
102
+ // ONE CLOCK (journey audit AUDIO-2): the owner map's frames→seconds
103
+ // joins ride the doc clock the windowSecs were booked at — the
104
+ // overlap trims and the stanza durations must speak the same fps or
105
+ // the film seats drift window by window.
106
+ const fps = input.fps ?? DOC_FPS_DEFAULT;
94
107
  if (windowSecs.length !== spans.length) {
95
108
  throw new Error(`film mix: ${windowSecs.length} window duration(s) for ${spans.length} span(s) — the owner map needs one duration per window (never a guess)`);
96
109
  }
97
110
  const overlaps = spans.map(spanOverlap);
98
111
  // THE OWNER MAP (the fixed point — see module header): the film
99
112
  // seat of doc frame f owned by window w is
100
- // w.filmStartSec + (f − w.docStart)/24, NO carry term (the trim
113
+ // w.filmStartSec + (f − w.docStart)/fps, NO carry term (the trim
101
114
  // already lives inside filmStartSec — each extend join trims the
102
115
  // overlap off the film). Owning window: the LAST whose docStart ≤ f.
103
116
  const filmStarts = [];
104
117
  let elapsed = 0;
105
118
  for (let i = 0; i < spans.length; i++) {
106
119
  filmStarts.push(elapsed);
107
- elapsed += windowSecs[i] - (i > 0 ? overlaps[i] : 0) / 24;
120
+ elapsed += windowSecs[i] - (i > 0 ? overlaps[i] : 0) / fps;
108
121
  }
109
122
  const filmSec = round3(elapsed);
110
123
  // CONDITIONED clips (the stamp law's overlay half): every window
@@ -135,19 +148,22 @@ export function computeFilmMix(input) {
135
148
  conditioned.add(ci);
136
149
  }
137
150
  });
138
- // PLACEMENTS: doc frame → film seat through the owner map.
151
+ // PLACEMENTS: doc frame → film seat through the owner map — the
152
+ // SAME doc clock the windows spoke (AUDIO-2's placements half: the
153
+ // /24 literal here outlived the window cure and drifted every clip
154
+ // seat against its own fps-cut window).
139
155
  const placements = clips.map((clip, ci) => {
140
156
  let owner = 0;
141
157
  for (let w = 0; w < spans.length; w++) {
142
158
  if (clip.start >= spans[w].start)
143
159
  owner = w;
144
160
  }
145
- const filmSeat = Math.max(0, filmStarts[owner] + (clip.start - spans[owner].start) / 24);
161
+ const filmSeat = Math.max(0, filmStarts[owner] + (clip.start - spans[owner].start) / fps);
146
162
  return {
147
163
  clip: ci,
148
164
  cls: clip.cls,
149
165
  filmSec: round3(filmSeat),
150
- durSec: clip.dur > 0 ? round3(clip.dur / 24) : 0,
166
+ durSec: clip.dur > 0 ? round3(clip.dur / fps) : 0,
151
167
  };
152
168
  });
153
169
  // THE DUCK MATRIX (D-M-E): the film's generated audio yields
package/lib/index.d.ts CHANGED
@@ -1,7 +1,20 @@
1
1
  import type { Plugin } from "@deepseek-ai/cordis";
2
- import type { ModelDecl } from "@melite/comfyui-cordis/model-contract";
2
+ import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
3
3
  export declare const DECL: ModelDecl;
4
4
  export declare const family: Plugin;
5
5
  export { finalizeH3, H3_T4_STRIP } from "./finalize.js";
6
+ export { renderH3Swap } from "./swap.js";
7
+ export { renderH3Repair } from "./repair.js";
8
+ export { renderH3Extend } from "./extend.js";
9
+ export { refineArmed, renderH3Refine, renderH3RefineWindow, renderH3RefineWindows, refineWindowCount, refineWindowStarts, REFINE_UPSCALE_MODEL, REFINE_2X_OOM_FRAMES, REFINE_DEFAULT_CLIP_SECONDS } from "./refine.js";
10
+ export { refinePlaneSchema, REFINE_PLANE_KEYS } from "./schema.js";
11
+ export { MAX_COMPOSED_WINDOWS, SEAM_OVERLAP_FRAMES } from "./timelineContract.js";
12
+ export type { RefineWindowSeat } from "./refine.js";
13
+ export { H3_DEFAULT_LORA_ID, h3DefaultLoraEntry } from "./actions.js";
14
+ export { upscaleArmed, renderH3ChainUpscale } from "./chainUpscale.js";
15
+ export { reshootArmed } from "./reshoot.js";
16
+ export { RESOLUTION_SHORT_EDGE, planTierShape, admitCrossRegimeJoin, } from "./chainEdit.js";
6
17
  export { assertOverlayGated } from "./actions.js";
18
+ export { serveWindowSpec, type WindowSpecProjection } from "./windowSpec.js";
19
+ export { family as default };
7
20
  //# sourceMappingURL=index.d.ts.map