@nodaro/shared 3.27.0 → 3.30.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodaro/shared",
3
- "version": "3.27.0",
3
+ "version": "3.30.0",
4
4
  "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -0,0 +1,62 @@
1
+ import { describe, expect, it } from "vitest"
2
+ import {
3
+ PITCH_TEMPO_PRICING,
4
+ parsePitchTempoCreditId,
5
+ pitchTempoBaseCredits,
6
+ pitchTempoCreditId,
7
+ pitchTempoStartedMinutes,
8
+ semitonesToPitchRatio,
9
+ } from "../credit-estimators/pitch-tempo.js"
10
+
11
+ const RATE = PITCH_TEMPO_PRICING.CREDITS_PER_MINUTE_DEFAULT
12
+
13
+ describe("pitch-tempo pricing", () => {
14
+ // The worked examples in docs/nodes/processing-audio/pitch-tempo.md.
15
+ it.each([
16
+ [45, 20],
17
+ [60, 20],
18
+ [61, 40],
19
+ [190, 80],
20
+ [1800, 600],
21
+ ])("%ss of input costs %s credits at the default rate", (sec, credits) => {
22
+ expect(pitchTempoBaseCredits(RATE, pitchTempoStartedMinutes(sec))).toBe(credits)
23
+ })
24
+
25
+ it("prices an unknown or non-positive length as one minute", () => {
26
+ expect(pitchTempoStartedMinutes(undefined)).toBe(1)
27
+ expect(pitchTempoStartedMinutes(null)).toBe(1)
28
+ expect(pitchTempoStartedMinutes(0)).toBe(1)
29
+ expect(pitchTempoStartedMinutes(Number.NaN)).toBe(1)
30
+ })
31
+
32
+ it("clamps the minutes at the 30-minute cap (the route refuses longer input)", () => {
33
+ expect(pitchTempoStartedMinutes(1800.4)).toBe(30)
34
+ expect(pitchTempoStartedMinutes(5000)).toBe(30)
35
+ })
36
+
37
+ it("builds and parses the per-minute id", () => {
38
+ expect(pitchTempoCreditId(190)).toBe("pitch-tempo:4m")
39
+ expect(pitchTempoCreditId(undefined)).toBe("pitch-tempo:1m")
40
+ expect(parsePitchTempoCreditId("pitch-tempo:4m")).toEqual({ minutes: 4 })
41
+ expect(parsePitchTempoCreditId(pitchTempoCreditId(1800))).toEqual({ minutes: 30 })
42
+ })
43
+
44
+ it.each(["pitch-tempo", "pitch-tempo:0m", "pitch-tempo:31m", "pitch-tempo:2.5m", "edit-plan:tighten:economy:3m"])(
45
+ "does not read %s as a per-minute id",
46
+ (id) => {
47
+ expect(parsePitchTempoCreditId(id)).toBeUndefined()
48
+ },
49
+ )
50
+
51
+ it("never charges less than one credit and rounds up", () => {
52
+ expect(pitchTempoBaseCredits(0, 3)).toBe(1)
53
+ expect(pitchTempoBaseCredits(2.5, 3)).toBe(8)
54
+ })
55
+
56
+ it("converts semitones to a frequency ratio", () => {
57
+ expect(semitonesToPitchRatio(0)).toBe(1)
58
+ expect(semitonesToPitchRatio(12)).toBeCloseTo(2, 10)
59
+ expect(semitonesToPitchRatio(-12)).toBeCloseTo(0.5, 10)
60
+ expect(semitonesToPitchRatio(3)).toBeCloseTo(1.189207, 6)
61
+ })
62
+ })
@@ -8,6 +8,8 @@ import {
8
8
  PREVIEW_RENDER_NODE_TYPES,
9
9
  applyEdlCreditId,
10
10
  speakerViewCreditId,
11
+ SPEAKER_VIEW_CREDIT_IDS,
12
+ SPEAKER_VIEW_PRICE_TIERS,
11
13
  isRenderNodeType,
12
14
  renderNodeOf,
13
15
  rendersLatestBatch,
@@ -35,11 +37,42 @@ describe("RENDER_NODE_TYPES — one render-node registry (SV18)", () => {
35
37
  expect(rendersTranscriptJson("speaker-view")).toBe(false)
36
38
  })
37
39
 
38
- it("prices a Preview on its own row and everything else on the final's", () => {
40
+ it("prices a Preview on its own row and everything else on the final's, per price tier (C4)", () => {
39
41
  const d = renderNodeOf("speaker-view")!
40
- expect(d.creditId("proxy")).toBe("speaker-view:proxy")
41
- for (const q of ["final", undefined, null, "", "high", 3]) expect(d.creditId(q)).toBe("speaker-view")
42
- expect(speakerViewCreditId("proxy")).toBe("speaker-view:proxy")
42
+ expect(d.creditId("proxy", undefined, "standard")).toBe("speaker-view:proxy")
43
+ expect(d.creditId("proxy", undefined, "complex")).toBe("speaker-view:complex:proxy")
44
+ for (const q of ["final", undefined, null, "", "high", 3]) {
45
+ expect(d.creditId(q, undefined, "standard")).toBe("speaker-view")
46
+ expect(d.creditId(q, undefined, "complex")).toBe("speaker-view:complex")
47
+ }
48
+ expect(speakerViewCreditId("proxy", "standard")).toBe("speaker-view:proxy")
49
+ })
50
+
51
+ it("an unknown price tier names the dearer row: an order that cannot say leans high (C4)", () => {
52
+ const d = renderNodeOf("speaker-view")!
53
+ for (const tier of [undefined, null, "", "STANDARD", "wide", 2]) {
54
+ expect(d.creditId("proxy", undefined, tier)).toBe("speaker-view:complex:proxy")
55
+ expect(d.creditId("final", undefined, tier)).toBe("speaker-view:complex")
56
+ expect(speakerViewCreditId("final", tier)).toBe("speaker-view:complex")
57
+ }
58
+ expect(speakerViewCreditId("proxy")).toBe("speaker-view:complex:proxy")
59
+ })
60
+
61
+ it("lists every id each render can name, and names only listed ids", () => {
62
+ expect([...SPEAKER_VIEW_CREDIT_IDS].sort()).toEqual(["speaker-view", "speaker-view:complex", "speaker-view:complex:proxy", "speaker-view:proxy"])
63
+ expect([...SPEAKER_VIEW_PRICE_TIERS]).toEqual(["standard", "complex"])
64
+ for (const type of RENDER_NODE_TYPE_IDS) {
65
+ const d = renderNodeOf(type)!
66
+ const named = new Set<string>()
67
+ for (const quality of ["proxy", "final", undefined]) {
68
+ for (const output of ["video", "audio", undefined]) {
69
+ for (const priceTier of [...SPEAKER_VIEW_PRICE_TIERS, undefined]) named.add(d.creditId(quality, output, priceTier))
70
+ }
71
+ }
72
+ expect([...named].sort(), type).toEqual([...d.creditIds].sort())
73
+ }
74
+ expect(renderNodeOf("apply-edl")!.creditIds).toEqual(["apply-edl", "apply-edl:proxy"])
75
+ expect(renderNodeOf("speaker-view")!.creditIds).toEqual(SPEAKER_VIEW_CREDIT_IDS)
43
76
  })
44
77
 
45
78
  it("describes Apply EDL exactly as its hard-coded sites behaved", () => {
@@ -56,6 +89,7 @@ describe("RENDER_NODE_TYPES — one render-node registry (SV18)", () => {
56
89
  for (const quality of ["proxy", "final", undefined, null, "", "high", 3]) {
57
90
  for (const output of ["video", "audio", undefined]) {
58
91
  expect(d.creditId(quality, output)).toBe(applyEdlCreditId(quality))
92
+ expect(d.creditId(quality, output, "complex")).toBe(applyEdlCreditId(quality))
59
93
  }
60
94
  }
61
95
  })
@@ -0,0 +1,146 @@
1
+ // packages/shared/src/__tests__/video-depth.test.ts
2
+ import { describe, expect, it } from "vitest"
3
+ import {
4
+ VIDEO_DEPTH_PROVIDERS,
5
+ FAL_VIDEO_DEPTH_PROVIDERS,
6
+ REPLICATE_VIDEO_DEPTH_PROVIDERS,
7
+ videoDepthLevers,
8
+ checkVideoDepthLength,
9
+ videoDepthCreditId,
10
+ videoDepthColormaps,
11
+ resolveVideoDepthColormap,
12
+ videoDepthNeedsGrayscalePass,
13
+ VIDEO_DEPTH_COLORMAPS,
14
+ VIDEO_DEPTH_LIMITS,
15
+ VIDEO_DEPTH_BUCKETS,
16
+ resolveVideoDepthProvider,
17
+ resolveVideoDepthModelSize,
18
+ } from "../video-depth.js"
19
+
20
+ describe("video-depth providers", () => {
21
+ it("partitions every provider into exactly one serving lane", () => {
22
+ for (const p of VIDEO_DEPTH_PROVIDERS) {
23
+ const lanes = [FAL_VIDEO_DEPTH_PROVIDERS.has(p), REPLICATE_VIDEO_DEPTH_PROVIDERS.has(p)].filter(Boolean)
24
+ expect(lanes).toHaveLength(1)
25
+ }
26
+ })
27
+ it("fal has all three levers, Replicate only colormap, unknown none", () => {
28
+ expect([...videoDepthLevers("video-depth-anything")].sort()).toEqual(["colormap", "resolution", "sideBySide"])
29
+ expect([...videoDepthLevers("depth-anything-frames")]).toEqual(["colormap"])
30
+ expect(videoDepthLevers("nope").size).toBe(0)
31
+ })
32
+ })
33
+
34
+ describe("videoDepthColormaps", () => {
35
+ it("fal offers all five in order, Replicate grayscale + inferno, unknown none", () => {
36
+ expect(videoDepthColormaps("video-depth-anything")).toEqual([...VIDEO_DEPTH_COLORMAPS])
37
+ expect(videoDepthColormaps("depth-anything-frames")).toEqual(["grayscale", "inferno"])
38
+ expect(videoDepthColormaps("nope")).toEqual([])
39
+ })
40
+ })
41
+
42
+ describe("resolveVideoDepthColormap", () => {
43
+ it("keeps a colormap the provider offers", () => {
44
+ expect(resolveVideoDepthColormap("video-depth-anything", "turbo")).toBe("turbo")
45
+ expect(resolveVideoDepthColormap("depth-anything-frames", "inferno")).toBe("inferno")
46
+ })
47
+ it("coerces an unsupported, missing or garbage value to grayscale", () => {
48
+ expect(resolveVideoDepthColormap("depth-anything-frames", "turbo")).toBe("grayscale")
49
+ expect(resolveVideoDepthColormap("depth-anything-frames", undefined)).toBe("grayscale")
50
+ expect(resolveVideoDepthColormap("video-depth-anything", 42)).toBe("grayscale")
51
+ })
52
+ it("returns undefined for a provider with no colormap lever", () => {
53
+ expect(resolveVideoDepthColormap("nope", "turbo")).toBeUndefined()
54
+ })
55
+ })
56
+
57
+ describe("videoDepthNeedsGrayscalePass", () => {
58
+ it("Replicate needs the pass unless inferno is chosen", () => {
59
+ expect(videoDepthNeedsGrayscalePass("depth-anything-frames", undefined)).toBe(true)
60
+ expect(videoDepthNeedsGrayscalePass("depth-anything-frames", "grayscale")).toBe(true)
61
+ expect(videoDepthNeedsGrayscalePass("depth-anything-frames", "inferno")).toBe(false)
62
+ })
63
+ it("fal never needs the pass", () => {
64
+ expect(videoDepthNeedsGrayscalePass("video-depth-anything", "grayscale")).toBe(false)
65
+ })
66
+ })
67
+
68
+ describe("checkVideoDepthLength", () => {
69
+ it("fal: exactly 2400 frames passes, 2401 rejects", () => {
70
+ expect(checkVideoDepthLength("video-depth-anything", { durationSec: 100, fps: 24 })).toEqual({ ok: true })
71
+ const r = checkVideoDepthLength("video-depth-anything", { durationSec: 100.01, fps: 24 })
72
+ expect(r.ok).toBe(false)
73
+ if (!r.ok) expect(r.message).toMatch(/2,401 frames.*2,400.*100 s at 24 fps/)
74
+ })
75
+ it("fal: unknown fps assumes 30 (80 s cap)", () => {
76
+ expect(checkVideoDepthLength("video-depth-anything", { durationSec: 80 })).toEqual({ ok: true })
77
+ const r = checkVideoDepthLength("video-depth-anything", { durationSec: 80.1 })
78
+ expect(r.ok).toBe(false)
79
+ if (!r.ok) expect(r.message).toMatch(/assumed 30 fps/)
80
+ })
81
+ it("fal: also capped at 300 s (the top price bucket), whatever the frame count", () => {
82
+ expect(VIDEO_DEPTH_LIMITS.FAL_MAX_SECONDS).toBe(300)
83
+ // 5 fps × 480 s = 2,400 frames: within the frame limit, over the seconds cap.
84
+ const long = checkVideoDepthLength("video-depth-anything", { durationSec: 480, fps: 5 })
85
+ expect(long.ok).toBe(false)
86
+ if (!long.ok) expect(long.message).toBe("Video is 480 s. This provider accepts at most 300 s. Trim the clip and run again.")
87
+ // 8 fps × 300 s = 2,400 frames: both limits met exactly.
88
+ expect(checkVideoDepthLength("video-depth-anything", { durationSec: 300, fps: 8 })).toEqual({ ok: true })
89
+ const over = checkVideoDepthLength("video-depth-anything", { durationSec: 300.5, fps: 1 })
90
+ expect(over.ok).toBe(false)
91
+ if (!over.ok) expect(over.message).toMatch(/^Video is 301 s\. This provider accepts at most 300 s\./)
92
+ })
93
+ it("replicate: seconds cap", () => {
94
+ expect(checkVideoDepthLength("depth-anything-frames", { durationSec: VIDEO_DEPTH_LIMITS.REPLICATE_MAX_SECONDS })).toEqual({ ok: true })
95
+ expect(checkVideoDepthLength("depth-anything-frames", { durationSec: 80.5 }).ok).toBe(false)
96
+ })
97
+ })
98
+
99
+ describe("videoDepthCreditId", () => {
100
+ it("buckets by duration, boundaries inclusive", () => {
101
+ expect(videoDepthCreditId("video-depth-anything", 5)).toBe("video-depth-anything:15s")
102
+ expect(videoDepthCreditId("video-depth-anything", 15)).toBe("video-depth-anything:15s")
103
+ expect(videoDepthCreditId("video-depth-anything", 15.01)).toBe("video-depth-anything:30s")
104
+ expect(videoDepthCreditId("depth-anything-frames", 61)).toBe("depth-anything-frames:120s")
105
+ expect(videoDepthCreditId("video-depth-anything", 299)).toBe("video-depth-anything:300s")
106
+ })
107
+ it("unknown, non-positive or over-cap duration prices the provider's highest REACHABLE bucket", () => {
108
+ // fal: capped at 300 s → the 300 s row.
109
+ expect(videoDepthCreditId("video-depth-anything", undefined)).toBe("video-depth-anything:300s")
110
+ expect(videoDepthCreditId("video-depth-anything", 0)).toBe("video-depth-anything:300s")
111
+ expect(videoDepthCreditId("video-depth-anything", 900)).toBe("video-depth-anything:300s")
112
+ // Replicate: capped at 80 s → the 120 s row; a longer clip is refused, so the 300 s row is unreachable.
113
+ expect(videoDepthCreditId("depth-anything-frames", undefined)).toBe("depth-anything-frames:120s")
114
+ expect(videoDepthCreditId("depth-anything-frames", -1)).toBe("depth-anything-frames:120s")
115
+ expect(videoDepthCreditId("depth-anything-frames", Number.NaN)).toBe("depth-anything-frames:120s")
116
+ expect(videoDepthCreditId("depth-anything-frames", 200)).toBe("depth-anything-frames:120s")
117
+ expect(videoDepthCreditId("depth-anything-frames", 80)).toBe("depth-anything-frames:120s")
118
+ })
119
+ it("derives each reachable ceiling from the limits: the smallest bucket at or above the provider's longest clip", () => {
120
+ const ceilingFor = (maxSec: number) => VIDEO_DEPTH_BUCKETS.find((b) => b >= maxSec)
121
+ expect(videoDepthCreditId("depth-anything-frames", undefined)).toBe(`depth-anything-frames:${ceilingFor(VIDEO_DEPTH_LIMITS.REPLICATE_MAX_SECONDS)}s`)
122
+ expect(videoDepthCreditId("video-depth-anything", undefined)).toBe(`video-depth-anything:${ceilingFor(VIDEO_DEPTH_LIMITS.FAL_MAX_SECONDS)}s`)
123
+ })
124
+ })
125
+
126
+ // Raw workflow JSON can carry any value; every layer that dispatches, denies or
127
+ // prices a run reads the SAME resolved provider, so none of them can drift.
128
+ describe("resolveVideoDepthProvider", () => {
129
+ it("keeps a known provider, resolves missing/unknown/non-string to the default", () => {
130
+ expect(resolveVideoDepthProvider("depth-anything-frames")).toBe("depth-anything-frames")
131
+ expect(resolveVideoDepthProvider("video-depth-anything")).toBe("video-depth-anything")
132
+ for (const raw of [undefined, null, "", "nope", "constructor", 42]) {
133
+ expect(resolveVideoDepthProvider(raw), String(raw)).toBe("video-depth-anything")
134
+ }
135
+ })
136
+ })
137
+
138
+ describe("resolveVideoDepthModelSize", () => {
139
+ it("keeps a known size, resolves anything else to large", () => {
140
+ expect(resolveVideoDepthModelSize("small")).toBe("small")
141
+ expect(resolveVideoDepthModelSize("base")).toBe("base")
142
+ for (const raw of [undefined, "huge", "constructor", 1]) {
143
+ expect(resolveVideoDepthModelSize(raw), String(raw)).toBe("large")
144
+ }
145
+ })
146
+ })
@@ -0,0 +1,77 @@
1
+ import { describe, it, expect } from "vitest"
2
+ import { readFileSync } from "node:fs"
3
+ import { resolve } from "node:path"
4
+ import {
5
+ VIDEO_MASK_LIMITS,
6
+ VIDEO_MASK_PROVIDERS,
7
+ resolveVideoMaskProvider,
8
+ videoMaskBilledSeconds,
9
+ videoMaskCreditId,
10
+ videoMaskCreditIds,
11
+ } from "../video-mask.js"
12
+ import { maskCompositeUnits } from "../mask-composite.js"
13
+
14
+ /** The priced length a run uses: billed seconds rounded up (lib/video-mask-length.ts). */
15
+ const rowFor = (sec: number, fps?: number) => videoMaskCreditId(Math.ceil(videoMaskBilledSeconds(sec, fps)))
16
+
17
+ describe("Video Mask pricing", () => {
18
+ // Repeated verbatim in docs/nodes/ai-video/video-mask.md → Worked examples.
19
+ it.each([
20
+ [4, 30, "sam-3.1-video:5s"],
21
+ [12, 24, "sam-3.1-video:15s"],
22
+ [10, 60, "sam-3.1-video:30s"],
23
+ [45, 30, "sam-3.1-video:60s"],
24
+ [100, 30, "sam-3.1-video:120s"],
25
+ ])("%s s at %s fps → %s", (sec, fps, row) => {
26
+ expect(rowFor(sec, fps)).toBe(row)
27
+ })
28
+
29
+ it("prices SAM 3 on its own rows (4 min at 30 fps → sam-3-video:240s)", () => {
30
+ expect(videoMaskCreditId(240, "sam-3")).toBe("sam-3-video:240s")
31
+ })
32
+
33
+ it("prices a clip at or under 30 fps at its own length, a faster one proportionally longer", () => {
34
+ expect(videoMaskBilledSeconds(10, 24)).toBe(10)
35
+ expect(videoMaskBilledSeconds(10, 30)).toBe(10)
36
+ expect(videoMaskBilledSeconds(10, 60)).toBe(20)
37
+ expect(videoMaskBilledSeconds(10, undefined)).toBe(10)
38
+ })
39
+
40
+ it("quotes an unknown length at the longest row and clamps past the cap", () => {
41
+ expect(videoMaskCreditId(undefined)).toBe("sam-3.1-video:300s")
42
+ expect(videoMaskCreditId(0)).toBe("sam-3.1-video:300s")
43
+ expect(videoMaskCreditId(500)).toBe("sam-3.1-video:300s")
44
+ expect(videoMaskCreditId(5)).toBe("sam-3.1-video:5s")
45
+ expect(videoMaskCreditId(5.01)).toBe("sam-3.1-video:10s")
46
+ expect(videoMaskCreditId(61)).toBe("sam-3.1-video:90s")
47
+ })
48
+
49
+ it("the last row covers exactly the longest clip a run accepts", () => {
50
+ for (const provider of VIDEO_MASK_PROVIDERS) {
51
+ expect(videoMaskCreditIds(provider).at(-1)).toBe(`${provider}-video:${VIDEO_MASK_LIMITS.MAX_BILLED_SEC}s`)
52
+ }
53
+ })
54
+
55
+ it("the doc's price table names every row", () => {
56
+ const doc = readFileSync(resolve(__dirname, "../../../../docs/nodes/ai-video/video-mask.md"), "utf8")
57
+ for (const provider of VIDEO_MASK_PROVIDERS) for (const id of videoMaskCreditIds(provider)) expect(doc).toContain(`\`${id}\``)
58
+ })
59
+
60
+ it("narrows unknown providers to the default", () => {
61
+ expect(resolveVideoMaskProvider("sam-3")).toBe("sam-3")
62
+ expect(resolveVideoMaskProvider("sam-3.1")).toBe("sam-3.1")
63
+ expect(resolveVideoMaskProvider("sam-9")).toBe("sam-3.1")
64
+ expect(resolveVideoMaskProvider(undefined)).toBe("sam-3.1")
65
+ })
66
+ })
67
+
68
+ describe("Mask Composite units", () => {
69
+ // Repeated in docs/nodes/processing-video/mask-composite.md (at the 10-credit row).
70
+ it.each([[3, 1], [5, 1], [10, 2], [10.0000001, 2], [61, 13], [300, 60]])("%s s → %s unit(s)", (sec, units) => {
71
+ expect(maskCompositeUnits(sec)).toBe(units)
72
+ })
73
+ it("an unknown length counts the 300 s cap (an upper bound); past the cap clamps", () => {
74
+ expect(maskCompositeUnits(undefined)).toBe(60)
75
+ expect(maskCompositeUnits(900)).toBe(60)
76
+ })
77
+ })
@@ -50,3 +50,13 @@ export {
50
50
  speechPriceUnits,
51
51
  speechCredits,
52
52
  } from "./speech.js"
53
+
54
+ export {
55
+ PITCH_TEMPO_PRICING,
56
+ PITCH_TEMPO_LIMITS,
57
+ pitchTempoStartedMinutes,
58
+ pitchTempoCreditId,
59
+ parsePitchTempoCreditId,
60
+ pitchTempoBaseCredits,
61
+ semitonesToPitchRatio,
62
+ } from "./pitch-tempo.js"
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Pitch & Tempo pricing — per STARTED minute of the input media (decided
3
+ * 2026-10-12), at least one minute, at most 30.
4
+ *
5
+ * One `model_pricing` row, `pitch-tempo`, holds the credits per minute; a run
6
+ * reserves `pitch-tempo:<N>m` (N = started minutes), which billing prices as
7
+ * that row × N — never a row of its own, so a retune of the rate row moves the
8
+ * route, the workflow run, the node's Run button and every estimate together.
9
+ * The same id is built by the route (from the probed length), the workflow run
10
+ * (the same probe) and the editor (the upstream length it knows).
11
+ *
12
+ * Worked examples at the row's listed rate of 20 (repeated in
13
+ * docs/nodes/processing-audio/pitch-tempo.md):
14
+ * 0:45 → 20, 1:00 → 20, 1:01 → 40, 3:10 → 80, 30:00 → 600.
15
+ */
16
+
17
+ export const PITCH_TEMPO_PRICING = {
18
+ /** The rate row: credits per started minute. Never reserved by itself. */
19
+ RATE_CREDIT_ID: "pitch-tempo",
20
+ /** The longest input a run accepts, in seconds (the route refuses longer). */
21
+ MAX_DURATION_SEC: 1800,
22
+ /** The most minutes a `pitch-tempo:<N>m` id can carry. */
23
+ MAX_MINUTES: 30,
24
+ /** The rate row's launch value (admin-retunable in /admin/models). */
25
+ CREDITS_PER_MINUTE_DEFAULT: 20,
26
+ } as const
27
+
28
+ /** The control ranges every surface validates against. */
29
+ export const PITCH_TEMPO_LIMITS = {
30
+ SEMITONES_MIN: -12,
31
+ SEMITONES_MAX: 12,
32
+ TEMPO_MIN: 0.5,
33
+ TEMPO_MAX: 2,
34
+ } as const
35
+
36
+ /**
37
+ * Started minutes of an input of `durationSec` seconds: ceil(sec / 60), at
38
+ * least 1, at most 30. An unknown or non-positive length counts as one minute
39
+ * (what the editor quotes before it knows the length; a run always measures).
40
+ */
41
+ export function pitchTempoStartedMinutes(durationSec: number | null | undefined): number {
42
+ if (typeof durationSec !== "number" || !Number.isFinite(durationSec) || durationSec <= 0) return 1
43
+ return Math.min(PITCH_TEMPO_PRICING.MAX_MINUTES, Math.max(1, Math.ceil(durationSec / 60)))
44
+ }
45
+
46
+ /** `pitch-tempo:<N>m` — the id a run on an input of `durationSec` seconds reserves. */
47
+ export function pitchTempoCreditId(durationSec: number | null | undefined): string {
48
+ return `pitch-tempo:${pitchTempoStartedMinutes(durationSec)}m`
49
+ }
50
+
51
+ /** The minutes of a `pitch-tempo:<N>m` id (1 ≤ N ≤ 30), or `undefined` for any other id. */
52
+ export function parsePitchTempoCreditId(id: string): { minutes: number } | undefined {
53
+ const m = /^pitch-tempo:(\d+)m$/.exec(id)
54
+ if (!m) return undefined
55
+ const minutes = Number(m[1])
56
+ if (!Number.isInteger(minutes) || minutes < 1 || minutes > PITCH_TEMPO_PRICING.MAX_MINUTES) return undefined
57
+ return { minutes }
58
+ }
59
+
60
+ /** rate × minutes, rounded up, at least 1 credit — what a `pitch-tempo:<N>m` id costs. */
61
+ export function pitchTempoBaseCredits(ratePerMinute: number, minutes: number): number {
62
+ return Math.max(1, Math.ceil(ratePerMinute * minutes))
63
+ }
64
+
65
+ /** The frequency ratio for a shift of `semitones` (12 = one octave up = ×2). */
66
+ export function semitonesToPitchRatio(semitones: number): number {
67
+ return 2 ** (semitones / 12)
68
+ }
@@ -718,14 +718,39 @@ export function applyEdlCreditId(quality: unknown): "apply-edl" | "apply-edl:pro
718
718
  }
719
719
 
720
720
  /**
721
- * The credit id of a Speaker View render (decided 2026-09-23, F4): a Preview
722
- * (`quality` "proxy") reserves on `speaker-view:proxy`, anything else on
723
- * `speaker-view`. The job is always named `speaker-view`; only its credit id
724
- * follows the quality, as Apply EDL's does. Ids only — no price is published
725
- * here, and none is set yet.
721
+ * Speaker View's price tiers (decided 2026-10-10, C4): a render is priced by
722
+ * how many speakers it composites at once. `standard` — at most two tiles on
723
+ * any segment and no zoom; `complex` — three to six tiles, or any zoom. Which
724
+ * tier a render is in is the render rule's to say (the app's
725
+ * `@nodaro/render-rules`), never this vocabulary's.
726
726
  */
727
- export function speakerViewCreditId(quality: unknown): "speaker-view" | "speaker-view:proxy" {
728
- return quality === "proxy" ? "speaker-view:proxy" : "speaker-view"
727
+ export const SPEAKER_VIEW_PRICE_TIERS = ["standard", "complex"] as const
728
+ export type SpeakerViewPriceTier = (typeof SPEAKER_VIEW_PRICE_TIERS)[number]
729
+
730
+ export type SpeakerViewCreditId = "speaker-view" | "speaker-view:proxy" | "speaker-view:complex" | "speaker-view:complex:proxy"
731
+
732
+ /** Every id `speakerViewCreditId` can name. */
733
+ export const SPEAKER_VIEW_CREDIT_IDS: readonly SpeakerViewCreditId[] = Object.freeze([
734
+ "speaker-view",
735
+ "speaker-view:proxy",
736
+ "speaker-view:complex",
737
+ "speaker-view:complex:proxy",
738
+ ] as const)
739
+
740
+ /**
741
+ * The credit id of a Speaker View render (F4, decided 2026-09-23; tiers
742
+ * decided 2026-10-10): a Preview (`quality` "proxy") reserves on its own row,
743
+ * anything else on the final's, and each in its price tier — `standard` on
744
+ * `speaker-view` / `speaker-view:proxy`, `complex` on `speaker-view:complex` /
745
+ * `speaker-view:complex:proxy`. A tier that is not exactly `standard` (absent
746
+ * included) names the `complex` row: a caller that cannot tell quotes high,
747
+ * never low. The job is always named `speaker-view`; only its credit id
748
+ * follows the quality and the tier.
749
+ */
750
+ export function speakerViewCreditId(quality: unknown, tier?: unknown): SpeakerViewCreditId {
751
+ const proxy = quality === "proxy"
752
+ if (tier === "standard") return proxy ? "speaker-view:proxy" : "speaker-view"
753
+ return proxy ? "speaker-view:complex:proxy" : "speaker-view:complex"
729
754
  }
730
755
 
731
756
  /**
@@ -43,6 +43,8 @@ export const NON_PROMPT_TEXT_LANES: Readonly<Record<string, "*" | readonly strin
43
43
  script: ["ai-avatar"],
44
44
  transcript: ["add-captions", "apply-edl", "edit-plan", "camera-switch", "speaker-view", "speaker-frames"],
45
45
  edl: ["apply-edl", "camera-switch", "speaker-view"],
46
+ // Speaker View's face tracks (Speaker Frames' descriptor): framing data, never a prompt.
47
+ tracks: ["speaker-view"],
46
48
  silence: ["edit-plan"],
47
49
  offsets: ["edit-plan"],
48
50
  qrText: ["image-overlay"],
package/src/index.ts CHANGED
@@ -304,6 +304,10 @@ export {
304
304
  speedRampCreditId,
305
305
  applyEdlCreditId,
306
306
  speakerViewCreditId,
307
+ SPEAKER_VIEW_CREDIT_IDS,
308
+ SPEAKER_VIEW_PRICE_TIERS,
309
+ type SpeakerViewPriceTier,
310
+ type SpeakerViewCreditId,
307
311
  sunoCreditType,
308
312
  SUNO_VERSION_CREDIT_KEYS,
309
313
  SUNO_VERSION_PRICED_OPERATIONS,
@@ -550,6 +554,7 @@ export {
550
554
  buildLipSyncCreditId,
551
555
  } from "./lip-sync-pricing.js"
552
556
  export type { LipSyncDurationBucket } from "./lip-sync-pricing.js"
557
+ export * from "./video-depth.js"
553
558
 
554
559
  export { isFlux2Model, FLUX2_RES_MP } from "./flux2-pricing.js"
555
560
  export type { Flux2Model } from "./flux2-pricing.js"
@@ -1703,6 +1708,8 @@ export * from "./audio-fx-presets.js"
1703
1708
  export * from "./supported-fonts.js"
1704
1709
  export * from "./image-overlay-layers.js"
1705
1710
  export * from "./video-overlay.js"
1711
+ export * from "./video-mask.js"
1712
+ export * from "./mask-composite.js"
1706
1713
  export * from "./image-overlay-shapes.js"
1707
1714
  export * from "./image-overlay-platforms.js"
1708
1715
  // --- Shot-sequence visual elements (text/shape/image; shared with backend Zod validation) ---
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Mask Composite — place a foreground video over a background video through a
3
+ * mask video (white = keep the foreground, black = show the background). The
4
+ * wire contract of the `mask-composite` node, `POST /v1/mask-composite`, the
5
+ * `mask_composite` MCP verb, `client.media.maskComposite` and
6
+ * `nodaro media mask-composite`, defined ONCE. Pair it with Video Mask, whose
7
+ * output is exactly such a mask.
8
+ *
9
+ * The render follows the FOREGROUND: its size, frame rate and length. The
10
+ * background is fitted to that frame (`backgroundFit`) and loops when shorter;
11
+ * the mask is stretched to the frame and holds its last frame when shorter.
12
+ *
13
+ * Priced per started 5 seconds of the result (the foreground's length), like
14
+ * Trim / Loop / Combine Videos: the node's own `model_pricing` row is ONE unit
15
+ * (`maskCompositeUnits` counts them). Worked examples (repeated in
16
+ * docs/nodes/processing-video/mask-composite.md, at the 10-credit row):
17
+ * 3 s → 1 unit (10), 10 s → 2 units (20), 61 s → 13 units (130), 5 min → 60 units (600).
18
+ *
19
+ * Wire contract only — no I/O.
20
+ */
21
+
22
+ /** How the background is fitted to the foreground's frame. */
23
+ export const MASK_COMPOSITE_BACKGROUND_FITS = ["cover", "contain", "stretch"] as const
24
+ export type MaskCompositeBackgroundFit = (typeof MASK_COMPOSITE_BACKGROUND_FITS)[number]
25
+
26
+ /** Which sound the result carries. `mix` blends both tracks at equal level. */
27
+ export const MASK_COMPOSITE_AUDIO_SOURCES = ["foreground", "background", "mix", "none"] as const
28
+ export type MaskCompositeAudioSource = (typeof MASK_COMPOSITE_AUDIO_SOURCES)[number]
29
+
30
+ export const MASK_COMPOSITE_BOUNDS = {
31
+ /** Edge softening, pixels of blur radius on the mask (0 = hard edge). */
32
+ FEATHER_MIN: 0,
33
+ FEATHER_MAX: 20,
34
+ /** Grow (+) or shrink (−) the white region, pixels. */
35
+ GROW_MIN: -10,
36
+ GROW_MAX: 10,
37
+ /** The longest foreground a run accepts, seconds. */
38
+ MAX_DURATION_SEC: 300,
39
+ } as const
40
+
41
+ /** Seconds of result one pricing unit covers. */
42
+ export const MASK_COMPOSITE_UNIT_SEC = 5
43
+
44
+ /**
45
+ * Pricing units for a result `durationSec` long: one per started 5 seconds,
46
+ * at least one. An unknown length counts the longest result a run accepts
47
+ * (an upper bound — the pre-run quote for a clip whose length is not known
48
+ * yet; every run measures its foreground).
49
+ */
50
+ export function maskCompositeUnits(durationSec: number | null | undefined): number {
51
+ const sec =
52
+ typeof durationSec === "number" && Number.isFinite(durationSec) && durationSec > 0
53
+ ? Math.min(durationSec, MASK_COMPOSITE_BOUNDS.MAX_DURATION_SEC)
54
+ : MASK_COMPOSITE_BOUNDS.MAX_DURATION_SEC
55
+ // The epsilon absorbs float noise (a 10.0000001 s probe is 2 units, not 3).
56
+ return Math.max(1, Math.ceil(sec / MASK_COMPOSITE_UNIT_SEC - 1e-6))
57
+ }
58
+
59
+ export const MASK_COMPOSITE_DEFAULTS = {
60
+ invertMask: false,
61
+ feather: 2,
62
+ grow: 0,
63
+ backgroundFit: "cover" as MaskCompositeBackgroundFit,
64
+ audioSource: "foreground" as MaskCompositeAudioSource,
65
+ } as const
66
+
67
+ export interface MaskCompositeSettings {
68
+ readonly invertMask: boolean
69
+ readonly feather: number
70
+ readonly grow: number
71
+ readonly backgroundFit: MaskCompositeBackgroundFit
72
+ readonly audioSource: MaskCompositeAudioSource
73
+ }
74
+
75
+ const clampInt = (v: unknown, min: number, max: number, fallback: number): number =>
76
+ typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, Math.round(v))) : fallback
77
+
78
+ /**
79
+ * Node data (or any loose object) → settings every engine renders with.
80
+ * Unknown enum values fall back to the default and numbers are clamped, so a
81
+ * node written straight into workflow JSON renders the same as one set in the
82
+ * panel. The ONE normaliser both workflow engines and the worker call.
83
+ */
84
+ export function resolveMaskCompositeSettings(data: Readonly<Record<string, unknown>>): MaskCompositeSettings {
85
+ const d = MASK_COMPOSITE_DEFAULTS
86
+ const b = MASK_COMPOSITE_BOUNDS
87
+ return {
88
+ invertMask: typeof data.invertMask === "boolean" ? data.invertMask : d.invertMask,
89
+ feather: clampInt(data.feather, b.FEATHER_MIN, b.FEATHER_MAX, d.feather),
90
+ grow: clampInt(data.grow, b.GROW_MIN, b.GROW_MAX, d.grow),
91
+ backgroundFit: (MASK_COMPOSITE_BACKGROUND_FITS as readonly string[]).includes(data.backgroundFit as string)
92
+ ? (data.backgroundFit as MaskCompositeBackgroundFit)
93
+ : d.backgroundFit,
94
+ audioSource: (MASK_COMPOSITE_AUDIO_SOURCES as readonly string[]).includes(data.audioSource as string)
95
+ ? (data.audioSource as MaskCompositeAudioSource)
96
+ : d.audioSource,
97
+ }
98
+ }
99
+
100
+ /** `POST /v1/mask-composite` request body. */
101
+ export interface MaskCompositeRequest extends Partial<MaskCompositeSettings> {
102
+ /** The video whose white-masked region is kept (its size, rate and length lead). */
103
+ readonly foregroundUrl: string
104
+ /** The video shown where the mask is black. */
105
+ readonly backgroundUrl: string
106
+ /** The mask video — white = foreground (Video Mask's output). */
107
+ readonly maskUrl: string
108
+ }