@nodaro/shared 3.36.0 → 3.38.0

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.
Files changed (144) hide show
  1. package/dist/{chunk-FKQJYMCO.js → chunk-2BHOAYZW.js} +38 -13
  2. package/dist/chunk-2BHOAYZW.js.map +1 -0
  3. package/dist/{chunk-BSQCKTXH.cjs → chunk-33QG2DOW.cjs} +6 -6
  4. package/dist/{chunk-BSQCKTXH.cjs.map → chunk-33QG2DOW.cjs.map} +1 -1
  5. package/dist/{chunk-NYMOHNYV.js → chunk-5OED47LE.js} +3 -3
  6. package/dist/{chunk-NYMOHNYV.js.map → chunk-5OED47LE.js.map} +1 -1
  7. package/dist/{chunk-GZH2SIOF.cjs → chunk-5PCI6M44.cjs} +18 -6
  8. package/dist/chunk-5PCI6M44.cjs.map +1 -0
  9. package/dist/chunk-6Q4BS6AR.js +158 -0
  10. package/dist/chunk-6Q4BS6AR.js.map +1 -0
  11. package/dist/{chunk-AXUW64ZY.js → chunk-7QITUDRT.js} +3 -3
  12. package/dist/{chunk-AXUW64ZY.js.map → chunk-7QITUDRT.js.map} +1 -1
  13. package/dist/{chunk-V3N56Z2S.cjs → chunk-7VDPBFER.cjs} +43 -12
  14. package/dist/chunk-7VDPBFER.cjs.map +1 -0
  15. package/dist/{chunk-LT5IJO4Y.cjs → chunk-AQA6YXY5.cjs} +39 -10
  16. package/dist/chunk-AQA6YXY5.cjs.map +1 -0
  17. package/dist/{chunk-7AB3AE5L.js → chunk-BDSFMY4X.js} +5 -18
  18. package/dist/chunk-BDSFMY4X.js.map +1 -0
  19. package/dist/chunk-BLZBDPZJ.js +16 -0
  20. package/dist/chunk-BLZBDPZJ.js.map +1 -0
  21. package/dist/{chunk-TCBHVIMD.js → chunk-CQJYKSXF.js} +18 -6
  22. package/dist/chunk-CQJYKSXF.js.map +1 -0
  23. package/dist/{chunk-AWWOQH46.cjs → chunk-D33YBZ3B.cjs} +170 -143
  24. package/dist/chunk-D33YBZ3B.cjs.map +1 -0
  25. package/dist/chunk-DBD4BCGH.cjs +169 -0
  26. package/dist/chunk-DBD4BCGH.cjs.map +1 -0
  27. package/dist/{chunk-7VQPHLZ5.cjs → chunk-ENFBA33M.cjs} +21 -21
  28. package/dist/{chunk-7VQPHLZ5.cjs.map → chunk-ENFBA33M.cjs.map} +1 -1
  29. package/dist/{chunk-BBLE4UTG.cjs → chunk-GLON7ANZ.cjs} +48 -15
  30. package/dist/chunk-GLON7ANZ.cjs.map +1 -0
  31. package/dist/{chunk-JSGIEF6Z.cjs → chunk-HSJU5KNR.cjs} +6 -3
  32. package/dist/chunk-HSJU5KNR.cjs.map +1 -0
  33. package/dist/{chunk-YN6AXDN5.cjs → chunk-HZ46RDLD.cjs} +9 -24
  34. package/dist/chunk-HZ46RDLD.cjs.map +1 -0
  35. package/dist/{chunk-NITAUX3A.cjs → chunk-JLKZEKQ3.cjs} +45 -28
  36. package/dist/chunk-JLKZEKQ3.cjs.map +1 -0
  37. package/dist/{chunk-WXNQMJ67.js → chunk-LOWOJN65.js} +100 -6
  38. package/dist/chunk-LOWOJN65.js.map +1 -0
  39. package/dist/chunk-M7G66F6H.js +17 -0
  40. package/dist/chunk-M7G66F6H.js.map +1 -0
  41. package/dist/chunk-PSAWDKO3.cjs +19 -0
  42. package/dist/chunk-PSAWDKO3.cjs.map +1 -0
  43. package/dist/{chunk-2HVFF5SS.js → chunk-QLCSS6DK.js} +165 -141
  44. package/dist/chunk-QLCSS6DK.js.map +1 -0
  45. package/dist/{chunk-ANOQWAMU.js → chunk-R6B2UDFR.js} +35 -5
  46. package/dist/chunk-R6B2UDFR.js.map +1 -0
  47. package/dist/chunk-T3TOSWVH.cjs +20 -0
  48. package/dist/chunk-T3TOSWVH.cjs.map +1 -0
  49. package/dist/{chunk-J65CAOUV.cjs → chunk-TGZJXCLL.cjs} +105 -5
  50. package/dist/chunk-TGZJXCLL.cjs.map +1 -0
  51. package/dist/{chunk-56VQ7V3V.js → chunk-THGNDVVH.js} +29 -4
  52. package/dist/chunk-THGNDVVH.js.map +1 -0
  53. package/dist/{chunk-XNISPHTZ.js → chunk-WPT5ZTA2.js} +6 -3
  54. package/dist/chunk-WPT5ZTA2.js.map +1 -0
  55. package/dist/{chunk-NTHRTRQK.js → chunk-XA53RUSD.js} +22 -6
  56. package/dist/chunk-XA53RUSD.js.map +1 -0
  57. package/dist/entries/apps.cjs +38 -38
  58. package/dist/entries/apps.js +3 -3
  59. package/dist/entries/credits.cjs +135 -134
  60. package/dist/entries/credits.js +3 -2
  61. package/dist/entries/llm-models.cjs +81 -49
  62. package/dist/entries/llm-models.d.cts +82 -14
  63. package/dist/entries/llm-models.d.ts +82 -14
  64. package/dist/entries/llm-models.js +2 -2
  65. package/dist/entries/media.cjs +66 -42
  66. package/dist/entries/media.d.cts +145 -4
  67. package/dist/entries/media.d.ts +145 -4
  68. package/dist/entries/media.js +1 -1
  69. package/dist/entries/models.cjs +84 -27
  70. package/dist/entries/models.d.cts +109 -3
  71. package/dist/entries/models.d.ts +109 -3
  72. package/dist/entries/models.js +3 -2
  73. package/dist/entries/nodes.cjs +204 -199
  74. package/dist/entries/nodes.d.cts +19 -2
  75. package/dist/entries/nodes.d.ts +19 -2
  76. package/dist/entries/nodes.js +5 -4
  77. package/dist/entries/pipeline.d.cts +2 -2
  78. package/dist/entries/pipeline.d.ts +2 -2
  79. package/dist/entries/social.cjs +187 -174
  80. package/dist/entries/social.d.cts +26 -1
  81. package/dist/entries/social.d.ts +26 -1
  82. package/dist/entries/social.js +3 -2
  83. package/dist/entries/workflow.cjs +157 -144
  84. package/dist/entries/workflow.d.cts +49 -1
  85. package/dist/entries/workflow.d.ts +49 -1
  86. package/dist/entries/workflow.js +4 -3
  87. package/dist/index.cjs +942 -800
  88. package/dist/index.d.cts +8 -7
  89. package/dist/index.d.ts +8 -7
  90. package/dist/index.js +14 -12
  91. package/dist/{scene-node-types-Cvbtf-0a.d.ts → model-constants-C43YS07I.d.cts} +1 -497
  92. package/dist/{scene-node-types-Cvbtf-0a.d.cts → model-constants-C43YS07I.d.ts} +1 -497
  93. package/dist/scene-node-types-BSrTKnV7.d.cts +499 -0
  94. package/dist/scene-node-types-BSrTKnV7.d.ts +499 -0
  95. package/package.json +1 -1
  96. package/src/__tests__/cast-swap-limits.test.ts +40 -0
  97. package/src/__tests__/fixtures/root-exports.baseline.json +6 -0
  98. package/src/__tests__/llm-models.test.ts +61 -18
  99. package/src/__tests__/llm-price-key.test.ts +55 -0
  100. package/src/__tests__/node-preset-extract.test.ts +10 -0
  101. package/src/__tests__/node-runtime-keys.test.ts +21 -2
  102. package/src/__tests__/render-output.test.ts +64 -0
  103. package/src/__tests__/schedule-retry.test.ts +35 -0
  104. package/src/__tests__/scrape-analysis-pricing.test.ts +41 -0
  105. package/src/__tests__/suno-separate.test.ts +78 -0
  106. package/src/__tests__/video-mask.test.ts +27 -0
  107. package/src/cast-swap-limits.ts +52 -0
  108. package/src/entries/llm-models.ts +7 -0
  109. package/src/entries/models.ts +26 -1
  110. package/src/entries/social.ts +1 -0
  111. package/src/entries/workflow.ts +6 -0
  112. package/src/generated/unit-contracts.ts +8 -2
  113. package/src/llm-models.ts +111 -23
  114. package/src/mask-composite.ts +80 -3
  115. package/src/node-preset-extract.ts +4 -0
  116. package/src/node-runtime-keys.ts +7 -0
  117. package/src/render-output.ts +36 -1
  118. package/src/schedule-retry.ts +71 -0
  119. package/src/scrape-analysis-pricing.ts +73 -0
  120. package/src/script-model.ts +21 -0
  121. package/src/suno-separate.ts +210 -0
  122. package/src/video-mask.ts +97 -0
  123. package/dist/chunk-2HVFF5SS.js.map +0 -1
  124. package/dist/chunk-56VQ7V3V.js.map +0 -1
  125. package/dist/chunk-7AB3AE5L.js.map +0 -1
  126. package/dist/chunk-ANOQWAMU.js.map +0 -1
  127. package/dist/chunk-AWWOQH46.cjs.map +0 -1
  128. package/dist/chunk-BBLE4UTG.cjs.map +0 -1
  129. package/dist/chunk-FG4E7MTG.cjs +0 -4
  130. package/dist/chunk-FG4E7MTG.cjs.map +0 -1
  131. package/dist/chunk-FKQJYMCO.js.map +0 -1
  132. package/dist/chunk-GZH2SIOF.cjs.map +0 -1
  133. package/dist/chunk-J65CAOUV.cjs.map +0 -1
  134. package/dist/chunk-JSGIEF6Z.cjs.map +0 -1
  135. package/dist/chunk-LT5IJO4Y.cjs.map +0 -1
  136. package/dist/chunk-NITAUX3A.cjs.map +0 -1
  137. package/dist/chunk-NTHRTRQK.js.map +0 -1
  138. package/dist/chunk-TCBHVIMD.js.map +0 -1
  139. package/dist/chunk-TZE673G6.js +0 -3
  140. package/dist/chunk-TZE673G6.js.map +0 -1
  141. package/dist/chunk-V3N56Z2S.cjs.map +0 -1
  142. package/dist/chunk-WXNQMJ67.js.map +0 -1
  143. package/dist/chunk-XNISPHTZ.js.map +0 -1
  144. package/dist/chunk-YN6AXDN5.cjs.map +0 -1
@@ -0,0 +1,210 @@
1
+ /**
2
+ * Suno Separate — the public contract of the separation node and its API.
3
+ *
4
+ * The three separation modes, the stem names "one instrument" mode accepts,
5
+ * the result fields a run writes, the credit id each mode is priced from, and
6
+ * the rule that turns a run's output into the URL behind each handle. One
7
+ * module so the route, the worker, both engines' output extractors and the
8
+ * editor read the same answers (they used to keep their own copies and price
9
+ * or route a mode in one place but not another). Structural vocabulary only.
10
+ */
11
+
12
+ /** Separation modes, in the provider's wire spelling. */
13
+ export const SUNO_SEPARATE_TYPES = ["separate_vocal", "split_stem", "split_stem_advanced"] as const
14
+ export type SunoSeparateType = (typeof SUNO_SEPARATE_TYPES)[number]
15
+
16
+ /**
17
+ * Every `stem_name` the provider accepts for `split_stem_advanced` ("one
18
+ * instrument"), verbatim and in the provider's order.
19
+ */
20
+ export const SUNO_STEM_NAMES = [
21
+ "Lead Vocal",
22
+ "Drum Kit",
23
+ "Kick",
24
+ "Snare",
25
+ "Risers",
26
+ "Bass",
27
+ "Backing Vocals",
28
+ "Piano",
29
+ "Electric Guitar",
30
+ "Percussion",
31
+ "String Section",
32
+ "Synth",
33
+ "Acoustic Guitar",
34
+ "Sound Effects",
35
+ "Synth Pad",
36
+ "Synth Bass",
37
+ "Guitar",
38
+ "Brass Section",
39
+ "Organ",
40
+ "Electronic Drum Kit",
41
+ "Lead Electric Guitar",
42
+ "Synth Keys",
43
+ "Rhythm Electric Guitar",
44
+ "Electric Piano",
45
+ "Upright Bass",
46
+ "Keyboards",
47
+ "Distorted Electric Guitar",
48
+ "Synth Strings",
49
+ "Synth Lead",
50
+ "Woodwinds",
51
+ "Rhythm Acoustic Guitar",
52
+ "Flute",
53
+ "Harp",
54
+ "Tambourine",
55
+ "Trumpet",
56
+ "Arpeggiator",
57
+ "Accordion",
58
+ "Fiddle",
59
+ "Pedal Steel Guitar",
60
+ "Synth Voice",
61
+ "Violin",
62
+ "Digital Piano",
63
+ "Synth Brass",
64
+ "Mandolin",
65
+ "Choir",
66
+ "Banjo",
67
+ "Bells",
68
+ "Clarinet",
69
+ "Tenor Saxophone",
70
+ "Trombone",
71
+ "Shaker",
72
+ "French Horn",
73
+ "Glockenspiel",
74
+ "Electric Bass",
75
+ "Cello",
76
+ "Timpani",
77
+ "Harmonica",
78
+ "Marimba",
79
+ "Vibraphone",
80
+ "Lap Steel Guitar",
81
+ "Saxophone",
82
+ "Orchestra",
83
+ "Horns",
84
+ "Cymbals",
85
+ "Hand Clap",
86
+ "Oboe",
87
+ "Celesta",
88
+ "Congas",
89
+ "Drone",
90
+ "Alto Saxophone",
91
+ "Double Bass",
92
+ "Ukulele",
93
+ "Harpsichord",
94
+ "Baritone Saxophone",
95
+ "Xylophone",
96
+ "Tuba",
97
+ "Bass Guitar",
98
+ "Whistle",
99
+ "Lead Guitar",
100
+ "Rhodes",
101
+ "808",
102
+ "Bongos",
103
+ "Bassoon",
104
+ "Cowbell",
105
+ "Viola",
106
+ "Sitar",
107
+ "Steel Drums",
108
+ "Piccolo",
109
+ "Theremin",
110
+ "Bagpipes",
111
+ "Hi-Hat",
112
+ "Music Box",
113
+ "Melodica",
114
+ "Tabla",
115
+ "Koto",
116
+ "Djembe",
117
+ "Taiko",
118
+ "Didgeridoo",
119
+ ] as const
120
+ export type SunoStemName = (typeof SUNO_STEM_NAMES)[number]
121
+
122
+ export const DEFAULT_SUNO_STEM_NAME: SunoStemName = "Lead Vocal"
123
+
124
+ /**
125
+ * Credit id a mode is priced from. Anything that is not a full-stems or
126
+ * one-instrument run prices as the two-stem (vocals + instrumental) split.
127
+ */
128
+ export function sunoSeparateCreditId(
129
+ type: unknown,
130
+ ): "suno-separate" | "suno-separate-stem" | "suno-separate-single" {
131
+ if (type === "split_stem") return "suno-separate-stem"
132
+ if (type === "split_stem_advanced") return "suno-separate-single"
133
+ return "suno-separate"
134
+ }
135
+
136
+ /**
137
+ * Flat per-stem URL fields of a run's output. `otherUrl` carries the Demucs
138
+ * `other` stem of a full-stems fallback run.
139
+ */
140
+ export const SUNO_SEPARATE_STEM_FIELDS = [
141
+ "vocalUrl", "instrumentalUrl", "backingVocalsUrl", "drumsUrl",
142
+ "bassUrl", "guitarUrl", "pianoUrl", "keyboardUrl",
143
+ "percussionUrl", "stringsUrl", "synthUrl", "fxUrl",
144
+ "brassUrl", "woodwindsUrl", "otherUrl",
145
+ ] as const
146
+ export type SunoSeparateStemField = (typeof SUNO_SEPARATE_STEM_FIELDS)[number]
147
+
148
+ /**
149
+ * One-instrument mode's two takes: the named instrument alone (`isolated`) and
150
+ * the song without it (`without`). Take 1 drives the `isolated` / `without`
151
+ * handles; take 2 is kept with the result but is not wireable.
152
+ */
153
+ export const SUNO_SEPARATE_TAKE_FIELDS = ["isolatedUrl", "withoutUrl", "isolated2Url", "without2Url"] as const
154
+
155
+ /** Every URL field a run's output can carry. */
156
+ export const SUNO_SEPARATE_RESULT_FIELDS = [...SUNO_SEPARATE_STEM_FIELDS, ...SUNO_SEPARATE_TAKE_FIELDS] as const
157
+ export type SunoSeparateResultField = (typeof SUNO_SEPARATE_RESULT_FIELDS)[number]
158
+
159
+ /** Non-URL fields a run's output records about how it ran. */
160
+ export const SUNO_SEPARATE_META_FIELDS = ["separateType", "stemName", "engineUsed", "sunoRefused", "fallbackReason"] as const
161
+
162
+ function str(v: unknown): string | undefined {
163
+ return typeof v === "string" && v !== "" ? v : undefined
164
+ }
165
+
166
+ // An output written before the per-field URLs existed: only `audioUrl`.
167
+ function isLegacyShape(output: Readonly<Record<string, unknown>>): boolean {
168
+ return !SUNO_SEPARATE_RESULT_FIELDS.some((field) => str(output[field]) !== undefined)
169
+ }
170
+
171
+ /**
172
+ * The URL a run's output puts behind one handle. A stem that did not come back
173
+ * is empty — never filled with the main audio; only an output of the legacy
174
+ * shape routes `audioUrl` to `vocals` / `instrumental`. Accepts the old handle
175
+ * spellings (`vocal`, `vocal-out`, `instrumental-out`). Any other handle, or
176
+ * none, gets the primary URL.
177
+ */
178
+ export function sunoSeparateHandleUrl(
179
+ output: Readonly<Record<string, unknown>>,
180
+ handle: string | null | undefined,
181
+ ): string | undefined {
182
+ switch (handle) {
183
+ case "vocals":
184
+ case "vocal":
185
+ case "vocal-out":
186
+ return str(output.vocalUrl) ?? (isLegacyShape(output) ? str(output.audioUrl) : undefined)
187
+ case "instrumental":
188
+ case "instrumental-out":
189
+ return str(output.instrumentalUrl) ?? (isLegacyShape(output) ? str(output.audioUrl) : undefined)
190
+ case "isolated":
191
+ return str(output.isolatedUrl)
192
+ case "without":
193
+ return str(output.withoutUrl)
194
+ default:
195
+ return sunoSeparatePrimaryUrl(output) ?? str(output.audioUrl)
196
+ }
197
+ }
198
+
199
+ /**
200
+ * A run's main URL: vocals, else instrumental, else the isolated instrument,
201
+ * else the first stem that came back.
202
+ */
203
+ export function sunoSeparatePrimaryUrl(output: Readonly<Record<string, unknown>>): string | undefined {
204
+ return (
205
+ str(output.vocalUrl) ??
206
+ str(output.instrumentalUrl) ??
207
+ str(output.isolatedUrl) ??
208
+ SUNO_SEPARATE_STEM_FIELDS.map((field) => str(output[field])).find((url) => url !== undefined)
209
+ )
210
+ }
package/src/video-mask.ts CHANGED
@@ -23,10 +23,39 @@ export const VIDEO_MASK_PROVIDERS = ["sam-3.1", "sam-3"] as const
23
23
  export type VideoMaskProvider = (typeof VIDEO_MASK_PROVIDERS)[number]
24
24
  export const DEFAULT_VIDEO_MASK_PROVIDER: VideoMaskProvider = "sam-3.1"
25
25
 
26
+ /**
27
+ * `zone`: keep only the subjects whose bounding-box CENTRE lies inside an
28
+ * inner rectangle, given as margins in % of the frame (each
29
+ * `VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MIN`–`ZONE_MARGIN_PCT_MAX`). All zero, or
30
+ * no zone, = off.
31
+ */
32
+ export interface VideoMaskZone {
33
+ readonly leftPct: number
34
+ readonly rightPct: number
35
+ readonly topPct: number
36
+ readonly bottomPct: number
37
+ }
38
+
26
39
  /** A new Video Mask node's settings — spread into its node definition. */
27
40
  export const VIDEO_MASK_DEFAULTS = {
28
41
  threshold: 0.5,
29
42
  provider: "sam-3.1" as VideoMaskProvider,
43
+ /** Off: the mask is the model's, frame for frame (see `HOLD_EMPTY_BELOW_FRACTION`). */
44
+ holdLastMask: false,
45
+ /** 0 = off: every region the model finds is kept (see `MIN_SUBJECT_HEIGHT_PCT_*`). */
46
+ minSubjectHeightPct: 0,
47
+ /** 0 = off: no ceiling on a region's height (see `MAX_SUBJECT_HEIGHT_PCT_*`). */
48
+ maxSubjectHeightPct: 0,
49
+ /** Off: subjects anywhere in the frame are kept (see `ZONE_MARGIN_PCT_*`). */
50
+ zone: null as VideoMaskZone | null,
51
+ /**
52
+ * Off: one pass over the whole clip. On: the clip's scene cuts are found
53
+ * first and each shot is segmented on its own — the model starts afresh
54
+ * after every cut (finding the new shot's subjects), and `holdLastMask`
55
+ * never carries a mask across a cut. A clip with no cut (a flash is not
56
+ * one) is one shot: the same mask, fitted to the clip's exact frame count.
57
+ */
58
+ perShot: false,
30
59
  } as const
31
60
 
32
61
  export const VIDEO_MASK_LIMITS = {
@@ -42,6 +71,41 @@ export const VIDEO_MASK_LIMITS = {
42
71
  THRESHOLD_STEP: 0.05,
43
72
  /** Default detection confidence. Lower finds more (and less precise) regions. */
44
73
  THRESHOLD_DEFAULT: VIDEO_MASK_DEFAULTS.threshold,
74
+ /**
75
+ * `holdLastMask`: a frame whose mask covers less than this fraction of the
76
+ * picture (0.002 % — about 41 px at 1080p: a stray speck, never a subject) counts as empty — the subject lost (hidden behind a
77
+ * hand, turned away) — and shows the most recent non-empty frame's mask
78
+ * instead. Frames before the first detection stay as they are.
79
+ */
80
+ HOLD_EMPTY_BELOW_FRACTION: 0.00002,
81
+ /**
82
+ * `minSubjectHeightPct`: drop every connected white region (8-connected)
83
+ * whose bounding box is shorter than this % of the frame height — extras'
84
+ * small faces behind the main subject. 0 = off. Applied before
85
+ * `holdLastMask`, so a frame left with only small regions counts as empty
86
+ * and is held from the last frame with a big subject.
87
+ */
88
+ MIN_SUBJECT_HEIGHT_PCT_MIN: 0,
89
+ MIN_SUBJECT_HEIGHT_PCT_MAX: 100,
90
+ /**
91
+ * `maxSubjectHeightPct`, the mirror: drop every region whose bounding box is
92
+ * TALLER than this % of the frame height (keep only the small subjects — a
93
+ * paste-back mask of the background faces). 0 = off. With both set, a
94
+ * region is kept when min ≤ height ≤ max (min > max is refused). Same pass,
95
+ * same order (before `holdLastMask`).
96
+ */
97
+ MAX_SUBJECT_HEIGHT_PCT_MIN: 0,
98
+ MAX_SUBJECT_HEIGHT_PCT_MAX: 100,
99
+ /**
100
+ * `zone` margins (left / right / top / bottom, % of the frame width or
101
+ * height): drop every connected region whose bounding-box centre lies
102
+ * outside `[w·left/100, w·(1−right/100)] × [h·top/100, h·(1−bottom/100)]`
103
+ * — the faces at the edges of the picture. At most 49 % a side, so the
104
+ * inner rectangle is never empty. Applied after the size cut and before
105
+ * `holdLastMask`, so a frame left with nothing inside counts as empty.
106
+ */
107
+ ZONE_MARGIN_PCT_MIN: 0,
108
+ ZONE_MARGIN_PCT_MAX: 49,
45
109
  } as const
46
110
 
47
111
  const VIDEO_MASK_BUCKETS_SEC = [5, 10, 15, 30, 60, 90, 120, 180, 240, 300] as const
@@ -84,6 +148,23 @@ export function resolveVideoMaskProvider(value: unknown): VideoMaskProvider {
84
148
  : DEFAULT_VIDEO_MASK_PROVIDER
85
149
  }
86
150
 
151
+ /**
152
+ * A zone as the region filter reads it: each margin a finite number clamped
153
+ * to `ZONE_MARGIN_PCT_MIN`–`ZONE_MARGIN_PCT_MAX` (anything else is 0), and
154
+ * null when there is no zone or every margin is 0 (off). The one reading
155
+ * shared by the worker, a workflow run's payload and the node's own run.
156
+ */
157
+ export function resolveVideoMaskZone(value: unknown): VideoMaskZone | null {
158
+ if (!value || typeof value !== "object") return null
159
+ const v = value as Record<string, unknown>
160
+ const margin = (x: unknown) =>
161
+ typeof x === "number" && Number.isFinite(x)
162
+ ? Math.min(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MAX, Math.max(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MIN, x))
163
+ : 0
164
+ const zone = { leftPct: margin(v.leftPct), rightPct: margin(v.rightPct), topPct: margin(v.topPct), bottomPct: margin(v.bottomPct) }
165
+ return zone.leftPct > 0 || zone.rightPct > 0 || zone.topPct > 0 || zone.bottomPct > 0 ? zone : null
166
+ }
167
+
87
168
  /** `POST /v1/video-mask` request body. */
88
169
  export interface VideoMaskRequest {
89
170
  /** The clip to segment. */
@@ -93,4 +174,20 @@ export interface VideoMaskRequest {
93
174
  /** Detection confidence, `VIDEO_MASK_LIMITS.THRESHOLD_MIN`–`THRESHOLD_MAX` (default 0.5). */
94
175
  readonly threshold?: number
95
176
  readonly provider?: VideoMaskProvider
177
+ /** Hold the last mask where the subject is lost (default false): an empty frame
178
+ * after the first detection repeats the most recent non-empty one. */
179
+ readonly holdLastMask?: boolean
180
+ /** Ignore subjects smaller than this % of the frame height, 0–100 (default 0 = off):
181
+ * connected regions whose bounding box is shorter are dropped from every frame. */
182
+ readonly minSubjectHeightPct?: number
183
+ /** Ignore subjects larger than this % of the frame height, 0–100 (default 0 = off):
184
+ * connected regions whose bounding box is taller are dropped from every frame. */
185
+ readonly maxSubjectHeightPct?: number
186
+ /** Keep only the subjects whose bounding-box centre is inside these margins, each
187
+ * 0–49 % of the frame (a margin left out is 0). null / omitted / all 0 = off. */
188
+ readonly zone?: Partial<VideoMaskZone> | null
189
+ /** Segment each shot on its own (default false): the clip's scene cuts are found
190
+ * first and the subjects are detected again in every shot; `holdLastMask` never
191
+ * carries a mask across a cut. The output then carries `shots`. */
192
+ readonly perShot?: boolean
96
193
  }