@melite/models-h3 0.2.0-alpha → 0.2.3-rc.4

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.
package/lib/extend.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
2
2
  import type { H3Facts } from './actions.js';
3
3
  export { solveWindowComposition, type WindowComposition } from './timelineContract.js';
4
+ export { LAST_FRAME_BATCH_INDEX } from './timelineContract.js';
4
5
  /** The extend renderer: validates the bound entry, then composes the
5
6
  * fresh-continuation chain plus the join. Like the swap and repair,
6
7
  * the film path never reaches here (the card branches on a non-empty
package/lib/extend.js CHANGED
@@ -1,15 +1,47 @@
1
1
  import { chainSaveBoundaries, concatSavedFilms, filmJoinAudio } from './actions.js';
2
- import { assertGridLength, solveWindowComposition, CONTEXT_OVERLAP_FRAMES, GRID_MAX_FRAMES, } from './timelineContract.js';
2
+ import { assertGridLength, solveWindowComposition, CONTEXT_OVERLAP_FRAMES, GRID_MAX_FRAMES, LAST_FRAME_BATCH_INDEX, resolveCarryOverlap } from './timelineContract.js';
3
+ import { outputNameTailOf } from './schema.js';
3
4
  export { solveWindowComposition } from './timelineContract.js';
4
- import { loadVideo, renderMaskedEditChain } from './chainEdit.js';
5
+ // the last-frame spelling re-exported from its ONE home (timelineContract —
6
+ // actions.ts reads it there too; the public face keeps this name)
7
+ export { LAST_FRAME_BATCH_INDEX } from './timelineContract.js';
8
+ import { contexMaskedTarget, loadVideo, renderMaskedEditChain, resolvePlanTier, sheetRefSlots } from './chainEdit.js';
9
+
10
+
11
+
12
+
13
+
14
+
15
+
5
16
  /** The extend entry's required seats (the reshoot/repair idiom: an
6
17
  * armed doc with an empty seat refuses loud naming the seat). */
7
18
  const REQUIRED_SEATS = [
8
19
  ['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
20
  ['extend_prompt', 'the continuation text — MOTION+SOUND for the appended seconds (the R2V prompt seat; agent-composed, user-confirmed)'],
10
21
  ];
11
- const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
12
- const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
22
+ /** Reads one optional number seat: absent falls to the documented
23
+ * default; a stated non-number REFUSES — a defaulting fallback would
24
+ * swallow a bypassed door's wrong-typed value as a silent error. */
25
+ const statedNumber = (p, k, d) => {
26
+ const v = p[k];
27
+ if (v === undefined)
28
+ return d;
29
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
30
+ throw new Error(`h3-timeline extend: '${k}' is stated as ${JSON.stringify(v)} — a number seat carries a number (absent falls to ${d}); a wrong-typed value never silently defaults`);
31
+ }
32
+ return v;
33
+ };
34
+ /** Reads one required seat NARROWED by its own refusal — the seat
35
+ * is a string or the door never composes (no fallback arm exists:
36
+ * a validated seat re-read through a forgiving helper would be a
37
+ * second, weaker validator below the law). */
38
+ const requiredSeat = (entry, seat, what) => {
39
+ const v = entry[seat];
40
+ if (typeof v !== 'string' || v.trim() === '') {
41
+ throw new Error(`h3-timeline extend: '${seat}' names no media — ${what}; an extend needs both seats bound (source_clip, extend_prompt)`);
42
+ }
43
+ return v;
44
+ };
13
45
  /** The extend renderer: validates the bound entry, then composes the
14
46
  * fresh-continuation chain plus the join. Like the swap and repair,
15
47
  * the film path never reaches here (the card branches on a non-empty
@@ -23,17 +55,42 @@ const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
23
55
  * @param g the run's graph builder
24
56
  * @param runId the run tree's id (the join prefixes ride it) */
25
57
  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)`);
58
+ // THE RAIL ADMISSION LAW (friction-2-infra D-01): this arm derives
59
+ // its own anchors (ref_image_0 = the prior clip's last frame,
60
+ // ref_video_0 = the whole clip) and the chain spine reads exactly
61
+ // one stated rail here — ref_images, the SHEET (P0-1: operator
62
+
63
+ // the AI, they are input slots", wired at the first free slot
64
+ // after the anchor). The FILM-lane rails ref_videos/ref_audios
65
+ // reach no conditioning on this arm — the audit's silent-no-op
66
+ // class — so they refuse LOUD here at the compose door, teaching
67
+ // the recipe-of-record instead of dropping the rail silently.
68
+ // (The audit's "ref_images is read by nothing" half was stale at
69
+ // write time: P0-1 had landed the sheet seat a week earlier; the
70
+ // correction rides this row's receipt.)
71
+ const STATED_RAILS = [
72
+ ['ref_videos', 'motion guides'],
73
+ ['ref_audios', 'voice references'],
74
+ ];
75
+ for (const [rail, what] of STATED_RAILS) {
76
+ const stated = p[rail];
77
+ if (Array.isArray(stated) && stated.length > 0) {
78
+ throw new Error(`h3-timeline extend: ${rail} is stated (${what}) but the extend arm serves no such rail — its anchors are derived (ref_image_0 IS the prior clip's last frame, ref_video_0 the whole clip) and the one stated image rail it reads is ref_images (the identity sheet, slot 1 after the anchor); a stated ${rail} reaches no conditioning on this arm (the pixel-proven no-op class). The recipe of record: identity rides the prior clip itself (or the ref_images sheet), per-window pins ride the calls lane's keyframes, and motion/voice guides ride the film lane's windows. Leave ${rail} unstated`);
30
79
  }
31
80
  }
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);
81
+ // NO FALLBACK READS: every required seat narrows through its own
82
+ // refusal (a validated seat re-read through a forgiving helper is
83
+ // a second, weaker validator below the law — a silent error). An
84
+ // absent optional seat falls to its documented default; a STATED
85
+ // seat of the wrong type refuses loud (the schema walk types every
86
+ // lawful doc, so a wrong-typed value means a bypassed door).
87
+ const sourceClipSeat = requiredSeat(entry, 'source_clip', REQUIRED_SEATS[0][1]);
88
+ const extendPromptSeat = requiredSeat(entry, 'extend_prompt', REQUIRED_SEATS[1][1]);
89
+ const seed = statedNumber(entry, 'seed', 0);
90
+ const steps = statedNumber(entry, 'steps', 6);
91
+ const overlapFrames = resolveCarryOverlap(entry);
92
+ const resolution = resolvePlanTier(entry, p);
93
+ const statedFrames = Math.round(statedNumber(entry, 'extend_seconds', 56 / 24) * 24);
37
94
  // THE COMPOSITION DOOR: one window keeps the landed grid law
38
95
  // verbatim; beyond it the solver composes N uniform windows and
39
96
  // refuses every non-exact landing by name. The solver ALWAYS
@@ -51,28 +108,60 @@ export function renderH3Extend(entry, p, facts, g, runId) {
51
108
  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
109
  }
53
110
  const clipSeconds = composition.windowFrames / 24;
111
+ // ── THE WINDOW ROSTER (friction-2-infra D-03 R4b: extend had no
112
+ // per-segment roster, so figure count and scale drift were
113
+ // structurally unreachable — one prompt minted every window and
114
+ // "the same girl twice at two scales" had no lever). The roster is
115
+ // a TEXT seat, one prompt per line, exactly one line per composed
116
+ // window; window i rides line i. ABSENT (or empty) the standing
117
+ // law holds: the one extend_prompt serves EVERY window. A wrong
118
+ // line count or a blank line refuses LOUD at this door, naming
119
+ // both numbers — the exactness law's own voice. Per-window SEED
120
+ // stays the engine's own derivation (base_seed + the chain's
121
+ // per-window advance) — the roster is a prompt seat, never a seed
122
+ // matrix. ──
123
+ const rosterRaw = entry['window_prompts'];
124
+ if (rosterRaw !== undefined && typeof rosterRaw !== 'string') {
125
+ throw new Error(`h3-timeline extend: 'window_prompts' is stated as ${JSON.stringify(rosterRaw)} — the roster is a text seat, one prompt per line; a wrong-typed value never silently reads as unbound`);
126
+ }
127
+ let roster = null;
128
+ if (typeof rosterRaw === 'string' && rosterRaw.trim() !== '') {
129
+ const lines = rosterRaw.split('\n').map((l) => l.trim());
130
+ if (lines.at(-1) === '')
131
+ lines.pop(); // ONE trailing newline — the textarea's own artifact
132
+ for (const [i, line] of lines.entries()) {
133
+ if (line === '') {
134
+ throw new Error(`h3-timeline extend: window_prompts line ${i + 1} is blank — every composed window needs its own prompt line; a blank line never silently falls to extend_prompt`);
135
+ }
136
+ }
137
+ if (lines.length !== composition.windows) {
138
+ throw new Error(`h3-timeline extend: window_prompts states ${lines.length} ${lines.length === 1 ? 'line' : 'lines'} but the composition serves ${composition.windows} ${composition.windows === 1 ? 'window' : 'windows'} — one line per window (window i rides line i); leave window_prompts unstated and the one extend_prompt serves every window`);
139
+ }
140
+ roster = lines;
141
+ }
54
142
  // ── the staged media: the WHOLE prior clip on the VHS seat
55
143
  // (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'));
144
+ // in-graph anchor (a positive out-of-band index the engine clamps
145
+ // to the final row — see LAST_FRAME_BATCH_INDEX) ──
146
+ const [priorFrames, priorAudio] = loadVideo(g, sourceClipSeat);
58
147
  const lastFrame = g.node('ImageFromBatch', {
59
- image: priorFrames, batch_index: -1, length: 1,
148
+ image: priorFrames, batch_index: LAST_FRAME_BATCH_INDEX, length: 1,
60
149
  }).out(0);
61
150
  // ── THE SEAT'S OWN PLAN (clause 3): N continuation shots — the
62
151
  // literal rules, plan_json_input stays UNWIRED (the plan node's
63
152
  // source slicing is the swap's semantics, never a continuation's;
64
153
  // the cure for the re-slice bug the unification's survey found) ──
65
154
  const shots = Array.from({ length: composition.windows }, (_k, i) => ({
66
- id: `extend-${i + 1}`, prompt: str(entry, 'extend_prompt'),
155
+ id: `extend-${i + 1}`, prompt: roster ? roster[i] : extendPromptSeat,
67
156
  }));
68
157
  const planJson = JSON.stringify({ shots });
69
- const { trimmed, assemblePath } = renderMaskedEditChain(g, {
158
+ const { trimmed, assemblePath, planShape } = renderMaskedEditChain(g, {
70
159
  p, facts,
71
160
  clipSeconds,
72
161
  overlapFrames,
73
162
  resolution, seed, steps,
74
163
  roles: '',
75
- sourceClip: str(entry, 'source_clip'),
164
+ sourceClip: sourceClipSeat,
76
165
  windowStart: 0,
77
166
  picture1: lastFrame,
78
167
  srcFrames: priorFrames,
@@ -87,7 +176,7 @@ export function renderH3Extend(entry, p, facts, g, runId) {
87
176
  assemble: composition.windows >= 2
88
177
  ? { audioSource: 'generated', filename: `${runId}/extend_chain` }
89
178
  : null,
90
- body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio }) => {
179
+ body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio, refImages }) => {
91
180
  // The everywhere-generate mask: an all-white SolidMask sized
92
181
  // to the chain's own geometry (nothing held — extended
93
182
  // seconds are new content). `.out(0)`: a mask SEAT takes an
@@ -102,33 +191,67 @@ export function renderH3Extend(entry, p, facts, g, runId) {
102
191
  // (ref_image_0) and the whole clip as the motion identity
103
192
  // (ref_video_0), the swap/repair spine's own seats ──
104
193
  const r2v = g.node('MiniMaxH3ReferenceToVideo', {
105
- prompt: str(entry, 'extend_prompt'),
194
+ prompt: extendPromptSeat,
106
195
  width: cur.out(8), height: cur.out(9), length: cur.out(6),
107
196
  ref_image_size: 'match',
108
197
  clip, vae: vaeVideo, audio_vae: vaeAudio,
109
198
  'ref_images.ref_image_0': lastFrame,
110
199
  'ref_videos.ref_video_0': priorFrames,
111
200
  'ref_video_audios.ref_video_audio_0': mutedChainAudio,
201
+ // THE SHEET (P0-1): the pixel anchor owns slot 0 — the
202
+ // declared sheet follows (the seam pin below is untouched:
203
+ // it rides the conditioning AFTER the r2v, not this slot).
204
+ ...sheetRefSlots(refImages, 1),
112
205
  });
113
206
  const slice = g.node('H3SourceSlice', {
114
207
  source_fps: 24, crop: 'center',
115
208
  state: cur.out(0), latent: r2v.out(1),
116
209
  audio_vae: vaeAudio, source_frames: priorFrames, source_audio: sliceAudio,
117
210
  });
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,
211
+ const target = contexMaskedTarget(g, { vaeVideo, vaeAudio }, {
212
+ frames: slice.out(0), audio: slice.out(1), mask: whiteMask, keepAudio: false,
213
+ });
214
+
215
+ // ref_image ride above is a SOFT prior — the model is free to
216
+ // introduce new content in the appended clip's FIRST frame, and
217
+ // the poncho burn did exactly that (a second figure at full
218
+ // size on the first extended frame: a hard pop, no entry). Pin
219
+ // the source's LAST frame at frame_idx 0 through the same
220
+ // H3-native guide lane the reshoot pins its warp with
221
+ // (MiniMaxH3AddGuide, one frame → guide_frames 1): the first
222
+ // appended frame is then FORCED to be the clip's last frame,
223
+ // so anything new must develop from it frame by frame instead
224
+ // of appearing whole.
225
+ const guided = g.node('MiniMaxH3AddGuide', {
226
+ positive: r2v.out(0),
227
+ vae: vaeVideo,
228
+ latent: target,
229
+ image: lastFrame,
230
+ frame_idx: 0,
128
231
  }).out(0);
129
- return { conditioning: r2v.out(0), targetLatent: target };
232
+ return { conditioning: guided, targetLatent: target };
130
233
  },
131
234
  });
235
+
236
+ // run-89976b95026b-8f22c399): the raw prior joins the chain's
237
+ // output at the CHAIN PLAN'S OWN SHOT GEOMETRY — the plan node
238
+ // derives the canvas from the SOURCE'S OWN FRAMES (its aspect)
239
+ // under the stated tier, so an extension whose tier short edge
240
+ // differs from the prior's own (the burn: a 1344×768 source under
241
+ // the default 736p tier rendered the extension at 1280×736 and the
242
+ // engine's concat refused `Expected size 768 but got size 736`)
243
+ // aligns HERE instead of crashing mid-render. The canvas is read
244
+ // off the plan's own width/height outputs — never assumed from a
245
+ // declared width/height row — and nearest-exact keeps the align
246
+ // pixel-verbatim when the plan canvas already equals the source's
247
+ // own (the extension never rewrites history). ──
248
+ const alignedPrior = g.node('ImageScale', {
249
+ image: priorFrames,
250
+ width: planShape.width,
251
+ height: planShape.height,
252
+ upscale_method: 'nearest-exact',
253
+ crop: 'disabled',
254
+ }).out(0);
132
255
  // ── THE JOIN (the file-join primitive; the initial raw boundary
133
256
  // is the exception the latent carry cannot cross — clause 4) ──
134
257
  if (assemblePath !== null) {
@@ -139,14 +262,17 @@ export function renderH3Extend(entry, p, facts, g, runId) {
139
262
  // saved-file path (ChainAssemble's video_path output, wired:
140
263
  // the DAG itself proves the assembly completed before the join).
141
264
  const priorCreated = g.node('CreateVideo', {
142
- images: priorFrames, audio: filmJoinAudio(g, priorAudio), fps: 24, bit_depth: 8,
265
+ images: alignedPrior, audio: filmJoinAudio(g, priorAudio), fps: 24, bit_depth: 8,
143
266
  });
144
267
  const priorSaved = g.node('SaveVideo', {
145
268
  video: priorCreated.out(), filename_prefix: `${runId}/x0`,
146
269
  format: 'mp4', codec: 'h264',
147
270
  }).out();
148
271
  const after = chainSaveBoundaries(g, [priorSaved]);
149
- concatSavedFilms(g, [`${runId}/x0`], after, `${runId}/extend_film`, {
272
+
273
+ // film is BORN named (`extend_film_<slug>`) — x0/x1 parts stay
274
+ // machinery prefixes (chain intermediates).
275
+ concatSavedFilms(g, [`${runId}/x0`], after, `${runId}/extend_film${outputNameTailOf(p)}`, {
150
276
  append: assemblePath,
151
277
  });
152
278
  return;
@@ -162,13 +288,13 @@ export function renderH3Extend(entry, p, facts, g, runId) {
162
288
  format: 'mp4', codec: 'h264',
163
289
  }).out();
164
290
  const priorCreated = g.node('CreateVideo', {
165
- images: priorFrames, audio: filmJoinAudio(g, priorAudio), fps: 24, bit_depth: 8,
291
+ images: alignedPrior, audio: filmJoinAudio(g, priorAudio), fps: 24, bit_depth: 8,
166
292
  });
167
293
  const priorSaved = g.node('SaveVideo', {
168
294
  video: priorCreated.out(), filename_prefix: `${runId}/x0`,
169
295
  format: 'mp4', codec: 'h264',
170
296
  }).out();
171
297
  const after = chainSaveBoundaries(g, [newSaved, priorSaved]);
172
- concatSavedFilms(g, [`${runId}/x0`, `${runId}/x1`], after, `${runId}/extend_film`);
298
+ concatSavedFilms(g, [`${runId}/x0`, `${runId}/x1`], after, `${runId}/extend_film${outputNameTailOf(p)}`);
173
299
  }
174
300
  //# sourceMappingURL=extend.js.map
package/lib/filmMix.d.ts CHANGED
@@ -7,13 +7,20 @@ export interface FilmMixClip {
7
7
  readonly start: number;
8
8
  /** duration (frames; 0 = overlay-only, unsized). */
9
9
  readonly dur: number;
10
+ /** the SOURCE in-point (frames at the DOC CLOCK; 0 = play from the
11
+ * head — the only behavior before the field existed). One TTS
12
+ * source can contribute its middle: the conditioning slice AND the
13
+ * pristine overlay both start here. */
14
+ readonly srcIn: number;
10
15
  readonly text: string;
11
16
  readonly cls: FilmMixClipClass;
12
17
  }
13
18
  /** Parse raw audio_clips rows — the card's one law for what a clip
14
19
  * 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. */
20
+ * silent misplacement); a row that states anything without src
21
+ * refuses loud (never a silent phantom row); only the contentless
22
+ * row (no stated key at all) is junk and skips; the class auto law
23
+ * (text → dialogue, textless → music) rides here. */
17
24
  export declare function parseFilmMixClips(rows: readonly unknown[]): FilmMixClip[];
18
25
  /** One window's doc span + seam for the owner map. */
19
26
  export interface FilmMixSpan {
@@ -71,6 +78,26 @@ export interface FilmMixInput {
71
78
  readonly fps?: number;
72
79
  readonly duckDb?: number;
73
80
  }
81
+
82
+
83
+
84
+
85
+
86
+
87
+
88
+
89
+
90
+
91
+
92
+
93
+
94
+
95
+
96
+
97
+
98
+
99
+
100
+ export declare function chooseLaneClips(clips: readonly FilmMixClip[], spanStart: number, spanEnd: number, genStart: number): Partial<Record<FilmMixClipClass, number>>;
74
101
  /** The duck span string — "start:end" at ms precision, ';'-joined. */
75
102
  export declare function formatDuckSpan(start: number, end: number): string;
76
103
  /** Per-window stanza seconds — THE compose-time windowSecs
package/lib/filmMix.js CHANGED
@@ -20,8 +20,10 @@ import { DOC_FPS_DEFAULT, spanOverlap, spanStanzaFrames } from './timelineContra
20
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
- * silent misplacement); a row without src is junk and skips; the
24
- * class auto law (text → dialogue, textless → music) rides here. */
23
+ * silent misplacement); a row that states anything without src
24
+ * refuses loud (never a silent phantom row); only the contentless
25
+ * row (no stated key at all) is junk and skips; the class auto law
26
+ * (text → dialogue, textless → music) rides here. */
25
27
  export function parseFilmMixClips(rows) {
26
28
  const clips = [];
27
29
  // THE ROW-LEVEL NUMERIC RESTORE (attempt-035's wire family, the
@@ -38,6 +40,7 @@ export function parseFilmMixClips(rows) {
38
40
  const row = c;
39
41
  row['start_frame'] = wireInt(row['start_frame']);
40
42
  row['dur_frames'] = wireInt(row['dur_frames']);
43
+ row['in_frames'] = wireInt(row['in_frames']);
41
44
  const src = typeof row.src === 'string' ? row.src.trim() : '';
42
45
  if (src === '') {
43
46
  const positioned = row.start_frame !== undefined ||
@@ -49,6 +52,19 @@ export function parseFilmMixClips(rows) {
49
52
  if (positioned) {
50
53
  throw new Error('audio_clips: a positioned clip row has no src — the film mix cannot place a source-less row');
51
54
  }
55
+ // THE SOURCE-LESS ROW LAW (F3-06, R-P3-16): the old whitelist
56
+ // refused only six "positioning" keys and let every OTHER
57
+ // stated key take the silent `continue` — {gain: 0.5} beside a
58
+ // lawful film COMPOSED as a phantom no-op (the run completed,
59
+ // the row performed nothing, nothing said so). A row that
60
+ // states ANYTHING and carries no src places nothing and mixes
61
+ // nothing: refuse it in its own voice. The blank law stays the
62
+ // only tolerance — a row with NO stated key is still skippable
63
+ // authoring junk.
64
+ const stated = Object.keys(row).some((k) => row[k] !== undefined);
65
+ if (stated) {
66
+ throw new Error('audio_clips: a clip row has no src — the film mix cannot mix a source-less row; state src or drop the row');
67
+ }
52
68
  continue;
53
69
  }
54
70
  if (typeof row.start_frame !== 'number' || !Number.isFinite(row.start_frame)) {
@@ -57,17 +73,80 @@ export function parseFilmMixClips(rows) {
57
73
  const dur = typeof row.dur_frames === 'number' && Number.isFinite(row.dur_frames) && row.dur_frames > 0
58
74
  ? row.dur_frames
59
75
  : 0;
76
+
77
+ // in_frames — where in the SOURCE the clip starts. Absent or 0 =
78
+ // the head, byte-identical to every film composed before the
79
+ // field existed; a negative or non-numeric value refuses loud
80
+ // (an in-point is a real seat, never a silent clamp — the same
81
+ // law as start_frame).
82
+ let srcIn = 0;
83
+ if (row.in_frames !== undefined) {
84
+ if (typeof row.in_frames !== 'number' || !Number.isFinite(row.in_frames) || row.in_frames < 0) {
85
+ throw new Error(`audio_clips: a clip with in_frames ${JSON.stringify(row.in_frames)} — the source in-point must be a non-negative number of frames (omit to play from the head)`);
86
+ }
87
+ srcIn = row.in_frames;
88
+ }
60
89
  const text = typeof row.text === 'string' ? row.text.trim() : '';
61
90
  const clsRaw = typeof row.class === 'string' ? row.class.trim().toLowerCase() : '';
62
91
  if (clsRaw !== '' && clsRaw !== 'dialogue' && clsRaw !== 'sfx' && clsRaw !== 'music') {
63
92
  throw new Error(`audio_clips: unknown class "${clsRaw}" — dialogue | sfx | music (omit for auto: text → dialogue, else music)`);
64
93
  }
65
94
  const cls = (clsRaw !== '' ? clsRaw : text !== '' ? 'dialogue' : 'music');
66
- clips.push({ src, start: row.start_frame, dur, text, cls });
95
+ clips.push({ src, start: row.start_frame, dur, srcIn, text, cls });
67
96
  }
68
97
  return clips;
69
98
  }
70
99
  const round3 = (v) => Math.round(v * 1000) / 1000;
100
+ /** The minimum overlap (frames at the DOC CLOCK) that can size a
101
+ * slice for the stamp pin — the audio slice node's 0.1s floor. */
102
+ const SLICE_FLOOR_FRAMES = 2.4;
103
+
104
+
105
+
106
+
107
+
108
+
109
+
110
+
111
+
112
+
113
+
114
+
115
+
116
+
117
+
118
+
119
+
120
+
121
+
122
+ export function chooseLaneClips(clips, spanStart, spanEnd, genStart) {
123
+ const starters = {};
124
+ const crossers = {};
125
+ for (let ci = 0; ci < clips.length; ci++) {
126
+ const clip = clips[ci];
127
+ if (clip.dur <= 0)
128
+ continue;
129
+ const lo = Math.max(clip.start, genStart);
130
+ const hi = Math.min(clip.start + clip.dur, spanEnd);
131
+ if (hi - lo < SLICE_FLOOR_FRAMES)
132
+ continue;
133
+ const bucket = clip.start >= spanStart && clip.start < spanEnd ? starters : crossers;
134
+ const row = (bucket[clip.cls] ??= []);
135
+ row.push(ci);
136
+ }
137
+ const lanes = {};
138
+ for (const cls of ['dialogue', 'sfx', 'music']) {
139
+ const started = starters[cls];
140
+ if (started !== undefined && started.length > 1) {
141
+ const named = started.map((ci) => `"${clips[ci].src}"`).join(' and ');
142
+ throw new Error(`audio_clips: two ${cls} clips start inside one window (doc frames ${spanStart}–${spanEnd}) — ${named}; one lane per class per window: end the first inside the window, merge the rows, or move the seam`);
143
+ }
144
+ const winner = started?.[0] ?? crossers[cls]?.[0];
145
+ if (winner !== undefined)
146
+ lanes[cls] = winner;
147
+ }
148
+ return lanes;
149
+ }
71
150
  /** The duck span string — "start:end" at ms precision, ';'-joined. */
72
151
  export function formatDuckSpan(start, end) {
73
152
  return `${round3(start)}:${round3(end)}`;
@@ -121,31 +200,22 @@ export function computeFilmMix(input) {
121
200
  }
122
201
  const filmSec = round3(elapsed);
123
202
  // CONDITIONED clips (the stamp law's overlay half): every window
124
- // whose generation span a clip rides HEARD that clip — one lane
125
- // per CLASS, the FIRST clip in row order winning its class's lane
126
- // when several of one class overlap one window. A clip with no
127
- // dur (or a sub-0.1s overlap) cannot size a slice and stays
128
- // overlay-only. The generation render starts at doc frame
129
- // sf − carry (the carry head included).
203
+ // whose generation span a clip rides HEARD that clip — the lane
204
+ // law lives in chooseLaneClips (starts-inside owns the lane; a
205
+ // crosser owns only an uncontested window; two starters refuse).
206
+ // A clip with no dur (or a sub-0.1s overlap) cannot size a slice
207
+ // and stays overlay-only. The generation render starts at doc
208
+ // frame sf − carry (the carry head included).
130
209
  const conditioned = new Set();
131
210
  spans.forEach((span, i) => {
132
211
  if (!Number.isFinite(span.start) || !Number.isFinite(span.end) || span.end <= span.start)
133
212
  return;
134
213
  const carry = i > 0 ? overlaps[i] : 0;
135
- const genStart = span.start - carry;
136
- const won = {};
137
- for (let ci = 0; ci < clips.length; ci++) {
138
- const clip = clips[ci];
139
- if (clip.dur <= 0)
140
- continue;
141
- if (won[clip.cls] !== undefined)
142
- continue;
143
- const lo = Math.max(clip.start, genStart);
144
- const hi = Math.min(clip.start + clip.dur, span.end);
145
- if (hi - lo < 2.4)
146
- continue;
147
- won[clip.cls] = true;
148
- conditioned.add(ci);
214
+ const lanes = chooseLaneClips(clips, span.start, span.end, span.start - carry);
215
+ for (const cls of ['dialogue', 'sfx', 'music']) {
216
+ const ci = lanes[cls];
217
+ if (ci !== undefined)
218
+ conditioned.add(ci);
149
219
  }
150
220
  });
151
221
  // PLACEMENTS: doc frame → film seat through the owner map — the
package/lib/finalize.js CHANGED
@@ -17,9 +17,14 @@ export const H3_T4_STRIP = {
17
17
  'attention_mode', 'blocks_to_swap', 'cache_model', 'offload_device',
18
18
  'swap_io_components'
19
19
  ],
20
+ // decode_tiled is NOT stripped: the SR decode's memory law states
21
+ // it (a 90-frame 1080p decode OOM'd the estate card in one pass),
22
+ // and a strip entry would delete the law on the t4 lane — the very
23
+ // lane the final press derives. The sizes/overlap stay stripped:
24
+ // the node's own declared defaults own them.
20
25
  SeedVR2LoadVAEModel: [
21
26
  'cache_model', 'decode_tile_overlap', 'decode_tile_size',
22
- 'decode_tiled', 'encode_tile_overlap', 'encode_tile_size',
27
+ 'encode_tile_overlap', 'encode_tile_size',
23
28
  'encode_tiled', 'offload_device', 'tile_debug'
24
29
  ],
25
30
  SeedVR2VideoUpscaler: [
package/lib/index.d.ts CHANGED
@@ -5,8 +5,9 @@ export declare const family: Plugin;
5
5
  export { finalizeH3, H3_T4_STRIP } from "./finalize.js";
6
6
  export { renderH3Swap } from "./swap.js";
7
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";
8
+ export { renderH3Edit, EDIT_IDENTITY_BOIL_FLOOR, type EditMaskDial, type EditReferenceDial, } from "./edit.js";
9
+ export { renderH3Extend, LAST_FRAME_BATCH_INDEX } from "./extend.js";
10
+ export { refineArmed, renderH3Refine, renderH3RefineBag, renderH3RefineCarry, renderH3RefineWindow, renderH3RefineWindows, refineWindowCount, refineWindowStarts, tokenExactCarry, nextTokenExact, lawfulCarryStart, REFINE_UPSCALE_MODEL, REFINE_2X_OOM_FRAMES, REFINE_DEFAULT_CLIP_SECONDS, REFINE_DEFAULT_OVERLAP_FRAMES, REFINE_WORKAROUND_WIDE_FRAMES } from "./refine.js";
10
11
  export { refinePlaneSchema, REFINE_PLANE_KEYS } from "./schema.js";
11
12
  export { MAX_COMPOSED_WINDOWS, SEAM_OVERLAP_FRAMES } from "./timelineContract.js";
12
13
  export type { RefineWindowSeat } from "./refine.js";