@melite/models-h3 0.0.0-stage → 0.1.4-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,80 @@
1
+ export { spanOverlap, spanStanzaFrames } from './timelineContract.js';
2
+ export type FilmMixClipClass = 'dialogue' | 'sfx' | 'music';
3
+ /** One clip row — the card's audio_clips shape, post-parse. */
4
+ export interface FilmMixClip {
5
+ readonly src: string;
6
+ /** doc-anchored start (frames @24fps — the stamp, studio lanes, and tool face all speak doc). */
7
+ readonly start: number;
8
+ /** duration (frames; 0 = overlay-only, unsized). */
9
+ readonly dur: number;
10
+ readonly text: string;
11
+ readonly cls: FilmMixClipClass;
12
+ }
13
+ /** Parse raw audio_clips rows — the card's one law for what a clip
14
+ * IS: a src without a numeric start_frame refuses loud (never a
15
+ * silent misplacement); a row without src is junk and skips; the
16
+ * class auto law (text → dialogue, textless → music) rides here. */
17
+ export declare function parseFilmMixClips(rows: readonly unknown[]): FilmMixClip[];
18
+ /** One window's doc span + seam for the owner map. */
19
+ export interface FilmMixSpan {
20
+ /** doc-anchored span start (frames). */
21
+ readonly start: number;
22
+ /** doc-anchored span end (frames). */
23
+ readonly end: number;
24
+ /** 'cut' = the director's overlap-0 arm; anything else extends at 22f. */
25
+ readonly transition?: string;
26
+ }
27
+ /** One positioned clip — the overlay's currency. */
28
+ export interface FilmMixPlacement {
29
+ /** index into the clips array. */
30
+ readonly clip: number;
31
+ readonly cls: FilmMixClipClass;
32
+ /** film seat (seconds, ms-rounded). */
33
+ readonly filmSec: number;
34
+ /** overlay duration (seconds, ms-rounded; 0 = full-length, unfitted). */
35
+ readonly durSec: number;
36
+ }
37
+ /** One duck span (seconds, ms-rounded). */
38
+ export interface FilmMixSpanSec {
39
+ readonly start: number;
40
+ readonly end: number;
41
+ }
42
+ /** The mix manifest — everything the disk-side mix needs. */
43
+ export interface FilmMixManifest {
44
+ readonly placements: FilmMixPlacement[];
45
+ /** the film track ducks during every CONDITIONED span (the doubling
46
+ * case — the model reproduces what it hears pinned). */
47
+ readonly duckSpans: FilmMixSpanSec[];
48
+ /** the music sub-bus ducks under dialogue/sfx spans only (the
49
+ * score yields to speech and impacts; never to itself). */
50
+ readonly musicDuckSpans: FilmMixSpanSec[];
51
+ /** the in-graph MeliteAudioDuck string form ("a:b;c:d") — the
52
+ * retired tail's voice, kept for the walls. */
53
+ readonly duckSpanString: string;
54
+ readonly musicDuckSpanString: string;
55
+ readonly duckDb: number;
56
+ /** the total film duration (seconds, ms-rounded). */
57
+ readonly filmSec: number;
58
+ }
59
+ export interface FilmMixInput {
60
+ readonly spans: FilmMixSpan[];
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). */
65
+ readonly windowSecs: number[];
66
+ readonly duckDb?: number;
67
+ }
68
+ /** The duck span string — "start:end" at ms precision, ';'-joined. */
69
+ export declare function formatDuckSpan(start: number, end: number): string;
70
+ /** Per-window stanza seconds — THE compose-time windowSecs
71
+ * (computeFilmMix's ground truth): the render grid's own promise,
72
+ * 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
+ export declare function computeFilmMix(input: FilmMixInput): FilmMixManifest;
80
+ //# sourceMappingURL=filmMix.d.ts.map
package/lib/filmMix.js ADDED
@@ -0,0 +1,183 @@
1
+ // filmMix.ts — the film's audio mix, ONE math owner (roadmap §20).
2
+ //
3
+ // History: the original in-graph film tail died of its own backlog —
4
+ // every window's tensors stayed resident until the final CreateVideo
5
+ // (the OOM signature that killed attempt 002's film 3×, a 43h
6
+ // engine). The mix moved disk-side (estate filmMux, ffmpeg) for one
7
+
8
+ // every artifact traces to a composition of cards, never a harness
9
+ // side-effect). The tail returned IN-GRAPH in FILE form: windows
10
+ // save their own clips, an unload boundary orders + flushes, and the
11
+ // file tail decodes the saves back in — no tensor ever spans the
12
+ // boundary. This module stays the ONE placement-math owner both
13
+ // halves drive (the card's conditioning stamps and the film-time
14
+ // overlay read the same manifest), and now owns the CLOCK too
15
+ // (stanzaSecs — the compose-time windowSecs law).
16
+ //
17
+ // The two wrongs in the card's history (the +22f carry original,
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";
21
+ /** Parse raw audio_clips rows — the card's one law for what a clip
22
+ * IS: a src without a numeric start_frame refuses loud (never a
23
+ * silent misplacement); a row without src is junk and skips; the
24
+ * class auto law (text → dialogue, textless → music) rides here. */
25
+ export function parseFilmMixClips(rows) {
26
+ const clips = [];
27
+ // THE ROW-LEVEL NUMERIC RESTORE (attempt-035's wire family, the
28
+ // card-owed arm): audio_clips is undeclared on paramSchema (the
29
+ // agent plane owns it), so the dict-driven fill has no license —
30
+ // a stringified start_frame rode in and refused. The parse owns
31
+ // the int law, the parse restores the strict int-string (same
32
+ // grammar as the kit's numeric fill; scoped to these two rows).
33
+ const INT_STRING = /^[+-]?\d+$/;
34
+ const wireInt = (x) => (typeof x === 'string' && INT_STRING.test(x.trim()) ? Number(x.trim()) : x);
35
+ for (const c of rows) {
36
+ if (c === null || typeof c !== 'object')
37
+ continue;
38
+ const row = c;
39
+ row['start_frame'] = wireInt(row['start_frame']);
40
+ row['dur_frames'] = wireInt(row['dur_frames']);
41
+ const src = typeof row.src === 'string' ? row.src.trim() : '';
42
+ if (src === '') {
43
+ const positioned = row.start_frame !== undefined ||
44
+ row.dur_frames !== undefined ||
45
+ (typeof row.text === 'string' && row.text.trim() !== '') ||
46
+ (typeof row.class === 'string' && row.class.trim() !== '') ||
47
+ (typeof row.id === 'string' && row.id.trim() !== '') ||
48
+ (typeof row.name === 'string' && row.name.trim() !== '');
49
+ if (positioned) {
50
+ throw new Error('audio_clips: a positioned clip row has no src — the film mix cannot place a source-less row');
51
+ }
52
+ continue;
53
+ }
54
+ if (typeof row.start_frame !== 'number' || !Number.isFinite(row.start_frame)) {
55
+ throw new Error(`audio_clips: a clip with src but no numeric start_frame — the audio lanes own placement (re-add the clip)`);
56
+ }
57
+ const dur = typeof row.dur_frames === 'number' && Number.isFinite(row.dur_frames) && row.dur_frames > 0
58
+ ? row.dur_frames
59
+ : 0;
60
+ const text = typeof row.text === 'string' ? row.text.trim() : '';
61
+ const clsRaw = typeof row.class === 'string' ? row.class.trim().toLowerCase() : '';
62
+ if (clsRaw !== '' && clsRaw !== 'dialogue' && clsRaw !== 'sfx' && clsRaw !== 'music') {
63
+ throw new Error(`audio_clips: unknown class "${clsRaw}" — dialogue | sfx | music (omit for auto: text → dialogue, else music)`);
64
+ }
65
+ const cls = (clsRaw !== '' ? clsRaw : text !== '' ? 'dialogue' : 'music');
66
+ clips.push({ src, start: row.start_frame, dur, text, cls });
67
+ }
68
+ return clips;
69
+ }
70
+ const round3 = (v) => Math.round(v * 1000) / 1000;
71
+ /** The duck span string — "start:end" at ms precision, ';'-joined. */
72
+ export function formatDuckSpan(start, end) {
73
+ return `${round3(start)}:${round3(end)}`;
74
+ }
75
+ /** Per-window stanza seconds — THE compose-time windowSecs
76
+ * (computeFilmMix's ground truth): the render grid's own promise,
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) {
84
+ // INDEX-AWARE CARRY (the render's chainLike law, stated here so
85
+ // the clock and the stanza can never disagree): window 1 renders
86
+ // fresh; k≥2 carries spanOverlap — the same 22 the finalize
87
+ // trims off the saved clip. The stanza covers carry + span, the
88
+ // contribution to the film is stanza − carry, so the clock's
89
+ // window seats land where the saved frames actually are.
90
+ return spans.map((s, i) => spanStanzaFrames(s, i > 0 ? spanOverlap(s) : 0) / 24);
91
+ }
92
+ export function computeFilmMix(input) {
93
+ const { spans, clips, windowSecs } = input;
94
+ if (windowSecs.length !== spans.length) {
95
+ 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
+ }
97
+ const overlaps = spans.map(spanOverlap);
98
+ // THE OWNER MAP (the fixed point — see module header): the film
99
+ // seat of doc frame f owned by window w is
100
+ // w.filmStartSec + (f − w.docStart)/24, NO carry term (the trim
101
+ // already lives inside filmStartSec — each extend join trims the
102
+ // overlap off the film). Owning window: the LAST whose docStart ≤ f.
103
+ const filmStarts = [];
104
+ let elapsed = 0;
105
+ for (let i = 0; i < spans.length; i++) {
106
+ filmStarts.push(elapsed);
107
+ elapsed += windowSecs[i] - (i > 0 ? overlaps[i] : 0) / 24;
108
+ }
109
+ const filmSec = round3(elapsed);
110
+ // CONDITIONED clips (the stamp law's overlay half): every window
111
+ // whose generation span a clip rides HEARD that clip — one lane
112
+ // per CLASS, the FIRST clip in row order winning its class's lane
113
+ // when several of one class overlap one window. A clip with no
114
+ // dur (or a sub-0.1s overlap) cannot size a slice and stays
115
+ // overlay-only. The generation render starts at doc frame
116
+ // sf − carry (the carry head included).
117
+ const conditioned = new Set();
118
+ spans.forEach((span, i) => {
119
+ if (!Number.isFinite(span.start) || !Number.isFinite(span.end) || span.end <= span.start)
120
+ return;
121
+ const carry = i > 0 ? overlaps[i] : 0;
122
+ const genStart = span.start - carry;
123
+ const won = {};
124
+ for (let ci = 0; ci < clips.length; ci++) {
125
+ const clip = clips[ci];
126
+ if (clip.dur <= 0)
127
+ continue;
128
+ if (won[clip.cls] !== undefined)
129
+ continue;
130
+ const lo = Math.max(clip.start, genStart);
131
+ const hi = Math.min(clip.start + clip.dur, span.end);
132
+ if (hi - lo < 2.4)
133
+ continue;
134
+ won[clip.cls] = true;
135
+ conditioned.add(ci);
136
+ }
137
+ });
138
+ // PLACEMENTS: doc frame → film seat through the owner map.
139
+ const placements = clips.map((clip, ci) => {
140
+ let owner = 0;
141
+ for (let w = 0; w < spans.length; w++) {
142
+ if (clip.start >= spans[w].start)
143
+ owner = w;
144
+ }
145
+ const filmSeat = Math.max(0, filmStarts[owner] + (clip.start - spans[owner].start) / 24);
146
+ return {
147
+ clip: ci,
148
+ cls: clip.cls,
149
+ filmSec: round3(filmSeat),
150
+ durSec: clip.dur > 0 ? round3(clip.dur / 24) : 0,
151
+ };
152
+ });
153
+ // THE DUCK MATRIX (D-M-E): the film's generated audio yields
154
+ // during every conditioned span; the MUSIC bus ducks under the
155
+ // dialogue and sfx spans; dialogue and sfx ride at unity.
156
+ const spanOf = (ci) => {
157
+ const pl = placements[ci];
158
+ if (!conditioned.has(ci) || pl.durSec <= 0)
159
+ return null;
160
+ return { start: pl.filmSec, end: round3(pl.filmSec + pl.durSec) };
161
+ };
162
+ const duckSpans = [];
163
+ const musicDuckSpans = [];
164
+ for (let ci = 0; ci < clips.length; ci++) {
165
+ const s = spanOf(ci);
166
+ if (s === null)
167
+ continue;
168
+ duckSpans.push(s);
169
+ if (clips[ci].cls !== 'music')
170
+ musicDuckSpans.push(s);
171
+ }
172
+ const duckDb = typeof input.duckDb === 'number' && Number.isFinite(input.duckDb) ? input.duckDb : -14;
173
+ return {
174
+ placements,
175
+ duckSpans,
176
+ musicDuckSpans,
177
+ duckSpanString: duckSpans.map((s) => formatDuckSpan(s.start, s.end)).join(';'),
178
+ musicDuckSpanString: musicDuckSpans.map((s) => formatDuckSpan(s.start, s.end)).join(';'),
179
+ duckDb,
180
+ filmSec,
181
+ };
182
+ }
183
+ //# sourceMappingURL=filmMix.js.map
@@ -0,0 +1,10 @@
1
+ import type { PromptGraph, StripTable } from "@melite/comfyui-card-kit/graph";
2
+
3
+
4
+
5
+ export declare const H3_T4_STRIP: StripTable;
6
+ /** The t4-family strip pass (`if not is_t4r`). The i2v dead-branch
7
+ * node exists ONLY on t4r — the serialized graph's family marker —
8
+ * so the strip stays stateless per compose. */
9
+ export declare function finalizeH3(graph: PromptGraph): PromptGraph;
10
+ //# sourceMappingURL=finalize.d.ts.map
@@ -0,0 +1,38 @@
1
+ // finalize.ts — the h3 family's OWN t4 strip pass (`if not is_t4r`),
2
+
3
+ // strip is this family's serialization law: the t4 templates OMIT
4
+ // these pin defaults, so the engine would auto-fill them at
5
+ // serialization, and the t4r branch carries all of them explicitly
6
+ // (it never strips). It lived in the card kit as `finalizeH3` while
7
+ // the lane itself moved here; a finalize pass with no lane beside it
8
+ // is a second home, so it came too.
9
+ import { stripAutofill } from "@melite/comfyui-card-kit/graph";
10
+
11
+
12
+
13
+ export const H3_T4_STRIP = {
14
+ CLIPLoader: ['device'],
15
+ LTX_lora_loader: ['lora_ui'],
16
+ SeedVR2LoadDiTModel: [
17
+ 'attention_mode', 'blocks_to_swap', 'cache_model', 'offload_device',
18
+ 'swap_io_components'
19
+ ],
20
+ SeedVR2LoadVAEModel: [
21
+ 'cache_model', 'decode_tile_overlap', 'decode_tile_size',
22
+ 'decode_tiled', 'encode_tile_overlap', 'encode_tile_size',
23
+ 'encode_tiled', 'offload_device', 'tile_debug'
24
+ ],
25
+ SeedVR2VideoUpscaler: [
26
+ 'enable_debug', 'input_noise_scale', 'latent_noise_scale',
27
+ 'offload_device', 'prepend_frames', 'temporal_overlap'
28
+ ],
29
+ };
30
+ /** The t4-family strip pass (`if not is_t4r`). The i2v dead-branch
31
+ * node exists ONLY on t4r — the serialized graph's family marker —
32
+ * so the strip stays stateless per compose. */
33
+ export function finalizeH3(graph) {
34
+ if ('MiniMaxH3ImageToVideo.0' in graph)
35
+ return graph; // t4r strips nothing
36
+ return stripAutofill(graph, H3_T4_STRIP);
37
+ }
38
+ //# sourceMappingURL=finalize.js.map
package/lib/index.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ import type { Plugin } from "@deepseek-ai/cordis";
2
+ import type { ModelDecl } from "@melite/comfyui-cordis/model-contract";
3
+ export declare const DECL: ModelDecl;
4
+ export declare const family: Plugin;
5
+ export { finalizeH3, H3_T4_STRIP } from "./finalize.js";
6
+ export { assertOverlayGated } from "./actions.js";
7
+ //# sourceMappingURL=index.d.ts.map