@nodaro/shared 3.26.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.
Files changed (43) hide show
  1. package/dist/index.cjs +726 -174
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +569 -34
  4. package/dist/index.d.ts +569 -34
  5. package/dist/index.js +667 -175
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/auto-aspect-source.test.ts +372 -0
  9. package/src/__tests__/camera-switch-contract.test.ts +10 -0
  10. package/src/__tests__/collections.test.ts +10 -0
  11. package/src/__tests__/edl.test.ts +319 -4
  12. package/src/__tests__/json-kinds.test.ts +11 -1
  13. package/src/__tests__/llm-models.test.ts +120 -8
  14. package/src/__tests__/pitch-tempo-pricing.test.ts +62 -0
  15. package/src/__tests__/render-nodes.test.ts +84 -5
  16. package/src/__tests__/transcribe-preflight.test.ts +5 -0
  17. package/src/__tests__/video-depth.test.ts +146 -0
  18. package/src/__tests__/video-mask.test.ts +77 -0
  19. package/src/camera-switch-contract.ts +9 -6
  20. package/src/collections.ts +72 -2
  21. package/src/credit-estimators/index.ts +10 -0
  22. package/src/credit-estimators/pitch-tempo.ts +68 -0
  23. package/src/credit-identifiers.ts +87 -19
  24. package/src/edl.ts +143 -23
  25. package/src/fan-out-rows.ts +3 -1
  26. package/src/i18n/camera-format.ko.ts +3 -3
  27. package/src/index.ts +35 -0
  28. package/src/json-kinds.ts +11 -6
  29. package/src/llm-models.ts +87 -2
  30. package/src/mask-composite.ts +108 -0
  31. package/src/model-catalog.ts +146 -4
  32. package/src/model-constants.ts +2 -1
  33. package/src/model-tree.ts +2 -0
  34. package/src/node-mappable-fields.ts +2 -0
  35. package/src/node-runtime-keys.ts +3 -0
  36. package/src/normalize-node-params.ts +47 -4
  37. package/src/pipeline-types.ts +16 -3
  38. package/src/presentation-utils.ts +3 -2
  39. package/src/producer-types.ts +13 -0
  40. package/src/render-nodes.ts +71 -6
  41. package/src/transcribe-preflight.ts +11 -10
  42. package/src/video-depth.ts +151 -0
  43. package/src/video-mask.ts +96 -0
@@ -8,10 +8,16 @@ 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,
14
16
  rendersTranscriptJson,
17
+ RENDER_JSON_HANDLE,
18
+ renderTranscriptOutputOf,
19
+ isRenderDataHandle,
20
+ renderSavedJsonOutputs,
15
21
  } from "../index.js"
16
22
 
17
23
  describe("RENDER_NODE_TYPES — one render-node registry (SV18)", () => {
@@ -31,11 +37,42 @@ describe("RENDER_NODE_TYPES — one render-node registry (SV18)", () => {
31
37
  expect(rendersTranscriptJson("speaker-view")).toBe(false)
32
38
  })
33
39
 
34
- 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)", () => {
35
41
  const d = renderNodeOf("speaker-view")!
36
- expect(d.creditId("proxy")).toBe("speaker-view:proxy")
37
- for (const q of ["final", undefined, null, "", "high", 3]) expect(d.creditId(q)).toBe("speaker-view")
38
- 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)
39
76
  })
40
77
 
41
78
  it("describes Apply EDL exactly as its hard-coded sites behaved", () => {
@@ -52,6 +89,7 @@ describe("RENDER_NODE_TYPES — one render-node registry (SV18)", () => {
52
89
  for (const quality of ["proxy", "final", undefined, null, "", "high", 3]) {
53
90
  for (const output of ["video", "audio", undefined]) {
54
91
  expect(d.creditId(quality, output)).toBe(applyEdlCreditId(quality))
92
+ expect(d.creditId(quality, output, "complex")).toBe(applyEdlCreditId(quality))
55
93
  }
56
94
  }
57
95
  })
@@ -85,8 +123,49 @@ describe("RENDER_NODE_TYPES — one render-node registry (SV18)", () => {
85
123
  expect(rendersTranscriptJson("transcribe")).toBe(false)
86
124
  })
87
125
 
126
+ describe("the transcript output: where a render's wired transcript, remapped through its cut, comes out (decided 2026-10-08)", () => {
127
+ it("Apply EDL's rides its `json` pip and `generatedJson`; Speaker View's its own `transcript` pip and `generatedTranscript`", () => {
128
+ expect(RENDER_JSON_HANDLE).toBe("json")
129
+ expect(renderTranscriptOutputOf("apply-edl")).toEqual({ handle: "json", dataField: "generatedJson" })
130
+ expect(renderTranscriptOutputOf("speaker-view")).toEqual({ handle: "transcript", dataField: "generatedTranscript" })
131
+ for (const t of ["camera-switch", "transcribe", "constructor", undefined, null]) expect(renderTranscriptOutputOf(t)).toBeUndefined()
132
+ })
133
+
134
+ it("a render's json is its transcript exactly when its transcript output IS the json pip — the two descriptions never disagree", () => {
135
+ for (const [t, d] of Object.entries(RENDER_NODE_TYPES)) {
136
+ const onJson = d.transcriptOutput.handle === RENDER_JSON_HANDLE
137
+ expect(d.jsonKind === "transcript", t).toBe(onJson)
138
+ expect(d.transcriptOutput.dataField === "generatedJson", t).toBe(onJson)
139
+ }
140
+ })
141
+
142
+ it("tells a render's data pips (json, transcript) from its media pip", () => {
143
+ expect(isRenderDataHandle("apply-edl", "json")).toBe(true)
144
+ expect(isRenderDataHandle("apply-edl", "media")).toBe(false)
145
+ expect(isRenderDataHandle("apply-edl", "transcript")).toBe(false)
146
+ expect(isRenderDataHandle("apply-edl", undefined)).toBe(false)
147
+ expect(isRenderDataHandle("speaker-view", "json")).toBe(true)
148
+ expect(isRenderDataHandle("speaker-view", "transcript")).toBe(true)
149
+ expect(isRenderDataHandle("speaker-view", "video")).toBe(false)
150
+ expect(isRenderDataHandle("speaker-view", null)).toBe(false)
151
+ expect(isRenderDataHandle("camera-switch", "transcript")).toBe(false)
152
+ })
153
+
154
+ it("lists the json outputs a render lands on its node, json first, each once", () => {
155
+ expect(renderSavedJsonOutputs("apply-edl")).toEqual([{ outputKey: "json", dataField: "generatedJson" }])
156
+ expect(renderSavedJsonOutputs("speaker-view")).toEqual([
157
+ { outputKey: "json", dataField: "generatedJson" },
158
+ { outputKey: "transcript", dataField: "generatedTranscript" },
159
+ ])
160
+ expect(renderSavedJsonOutputs("camera-switch")).toEqual([])
161
+ })
162
+ })
163
+
88
164
  it("is frozen: no consumer can register a render at run time", () => {
89
165
  expect(Object.isFrozen(RENDER_NODE_TYPES)).toBe(true)
90
- for (const d of Object.values(RENDER_NODE_TYPES)) expect(Object.isFrozen(d)).toBe(true)
166
+ for (const d of Object.values(RENDER_NODE_TYPES)) {
167
+ expect(Object.isFrozen(d)).toBe(true)
168
+ expect(Object.isFrozen(d.transcriptOutput)).toBe(true)
169
+ }
91
170
  })
92
171
  })
@@ -37,6 +37,11 @@ describe("findWordlessTranscriptFeeds", () => {
37
37
  )
38
38
  expect(hits.map((h) => h.consumerNodeId)).toEqual(["c"])
39
39
  })
40
+ it("follows the transcript THROUGH speaker-view (transcript in → its own transcript out, decided 2026-10-08), never its EDL json", () => {
41
+ const nodes = [n("t", "transcribe", { provider: "whisper" }), n("sv", "speaker-view"), n("c", "add-captions")]
42
+ expect(findWordlessTranscriptFeeds(nodes, [e("t", "json", "sv", "transcript"), e("sv", "transcript", "c", "transcript")]).map((h) => h.consumerNodeId)).toEqual(["c"])
43
+ expect(findWordlessTranscriptFeeds(nodes, [e("t", "json", "sv", "transcript"), e("sv", "json", "c", "transcript")])).toEqual([])
44
+ })
40
45
  it("does NOT flag a word-capable lane, the text handle, or a non-caption consumer", () => {
41
46
  const nodes = [n("ok", "transcribe", { provider: "elevenlabs-stt" }), n("w", "transcribe", { provider: "whisper" }), n("c", "add-captions"), n("p", "edit-plan")]
42
47
  expect(findWordlessTranscriptFeeds(nodes, [e("ok", "json", "c", "transcript")])).toEqual([])
@@ -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
+ })
@@ -4,6 +4,7 @@
4
4
  * screen is decided by the Cloud plugin; these only read the inputs it needs
5
5
  * and pre-fill the speaker table. Pure, no I/O.
6
6
  */
7
+ import { normalizeTranscript } from "./edl.js"
7
8
 
8
9
  /** The settings and their decided defaults (the plugin holds its own copy, D13). */
9
10
  export const CAMERA_SWITCH_DEFAULTS = Object.freeze({
@@ -28,14 +29,16 @@ const parseMaybe = (raw: unknown): unknown => {
28
29
  }
29
30
 
30
31
  /** Distinct speaker labels of a transcript (an object or its JSON string), in
31
- * order of first appearance. Empty → camera-switch refuses before charging. */
32
+ * order of first appearance in time. Read through `normalizeTranscript`
33
+ * (decided 2026-10-08) — the Cloud plugin's reading — so a broken word (no
34
+ * usable time) names no speaker here either; a zero-width word is a point
35
+ * and does. Empty → camera-switch refuses before charging. */
32
36
  export function transcriptSpeakerLabels(transcript: unknown): string[] {
33
- const words = (parseMaybe(transcript) as { words?: unknown } | null | undefined)?.words
34
- if (!Array.isArray(words)) return []
37
+ const parsed = parseMaybe(transcript)
38
+ if (!parsed || typeof parsed !== "object") return []
35
39
  const seen = new Set<string>()
36
- for (const w of words) {
37
- const s = (w as { speaker?: unknown } | null)?.speaker
38
- if (typeof s === "string" && s && !seen.has(s)) seen.add(s)
40
+ for (const w of normalizeTranscript(parsed).words) {
41
+ if (w.speaker && !seen.has(w.speaker)) seen.add(w.speaker)
39
42
  }
40
43
  return [...seen]
41
44
  }
@@ -14,6 +14,8 @@
14
14
  * read node, MCP and the CLI render records with.
15
15
  */
16
16
 
17
+ import { loneMediaUrlKind } from "./lone-media-url.js"
18
+
17
19
  export const COLLECTION_NAME_MAX = 80
18
20
  export const COLLECTION_DESCRIPTION_MAX = 500
19
21
  export const COLLECTION_RECORD_TITLE_MAX = 500
@@ -77,21 +79,32 @@ export interface Collection {
77
79
  readonly name: string
78
80
  readonly description: string
79
81
  readonly recordCount: number
82
+ /** How many of its records have been used (`usedAt` set) and are not in the Trash. On the one-collection read; a server before the usage migration leaves it out. */
83
+ readonly usedCount?: number
84
+ /** How many of its records are in the Trash. On the one-collection read; a server before the usage migration leaves it out. `recordCount` counts them too (they still count toward the cap). */
85
+ readonly trashCount?: number
80
86
  readonly createdAt: string
81
87
  readonly updatedAt: string
82
88
  }
83
89
 
84
- /** Where a record came from — a node in a run, or a direct write. */
90
+ /** Where a record came from — a node in a run, or a direct write. The same shape says who USED it. */
85
91
  export interface CollectionRecordSource {
86
92
  readonly via?: "api" | "mcp" | "node" | "ui"
87
93
  readonly nodeType?: string
88
94
  readonly workflowId?: string
89
95
  readonly executionId?: string
90
96
  readonly nodeId?: string
97
+ /** Read-side enrichment: the workflow's name and project, looked up when the records are listed. Ignored on a write. */
98
+ readonly workflowName?: string
99
+ readonly projectId?: string
91
100
  }
92
101
 
93
102
  export type CollectionFieldValue = string | number | boolean
94
103
 
104
+ /** Which records a list or a read returns: every record, the ones not used yet, or the ones used. */
105
+ export const COLLECTION_USAGES = ["all", "unused", "used"] as const
106
+ export type CollectionUsage = (typeof COLLECTION_USAGES)[number]
107
+
95
108
  export interface CollectionRecord {
96
109
  readonly id: string
97
110
  readonly collectionId: string
@@ -104,6 +117,35 @@ export interface CollectionRecord {
104
117
  readonly dedupeKey: string | null
105
118
  readonly source: CollectionRecordSource
106
119
  readonly createdAt: string
120
+ /** When the record was used (a Save to Collection node with "mark the item as used", the API, the page) — null until then. A server before the usage migration leaves it out. */
121
+ readonly usedAt?: string | null
122
+ /** Who used it, in the shape of `source`; empty until then. */
123
+ readonly usedBy?: CollectionRecordSource
124
+ /** When the record was moved to the Trash (a delete on the page, the API or the CLI); null while it is live. A server before the usage migration leaves it out. */
125
+ readonly deletedAt?: string | null
126
+ }
127
+
128
+ /** Which records a list returns: the live ones (`active`, the default) or the ones in the Trash. Nodes, exports and MCP read the live ones only. */
129
+ export const COLLECTION_RECORD_STATUSES = ["active", "trash"] as const
130
+ export type CollectionRecordStatus = (typeof COLLECTION_RECORD_STATUSES)[number]
131
+
132
+ /** The most records one bulk call (`POST /v1/collections/:id/records/bulk`) touches. */
133
+ export const COLLECTION_BULK_MAX = 100
134
+ /** The actions of a bulk call: move the records to the Trash, bring them back, or delete records already in the Trash for good. */
135
+ export const COLLECTION_BULK_ACTIONS = ["trash", "restore", "delete"] as const
136
+ export type CollectionBulkAction = (typeof COLLECTION_BULK_ACTIONS)[number]
137
+ /** The most records a numbered page may skip (`offset`) — past any page a person turns to, within the largest cap. */
138
+ export const COLLECTION_RECORDS_OFFSET_MAX = 1_000_000
139
+
140
+ /** The body of `POST /v1/collections/:id/records/bulk`. */
141
+ export type BulkCollectionRecordsInput = {
142
+ readonly ids: readonly string[]
143
+ readonly action: CollectionBulkAction
144
+ }
145
+
146
+ export interface BulkCollectionRecordsResult {
147
+ /** How many of the ids were the caller's records in that collection and changed (a record already in the asked state is not counted). */
148
+ readonly updated: number
107
149
  }
108
150
 
109
151
  /** The caller's limits as the API quotes them: `null` is "no limit" (a
@@ -139,15 +181,34 @@ export type ListCollectionRecordsParams = {
139
181
  readonly q?: string
140
182
  /** Only records saved at or after this ISO timestamp (date and time). */
141
183
  readonly since?: string
142
- /** The `nextCursor` of the previous page. */
184
+ /** Only records saved before this ISO timestamp (date and time). */
185
+ readonly until?: string
186
+ /** `all` (default), `unused` (not used yet) or `used`. */
187
+ readonly usage?: CollectionUsage
188
+ /** `newest` (default) or `oldest` first. */
189
+ readonly order?: "newest" | "oldest"
190
+ /** `active` (default: the live records) or `trash`. */
191
+ readonly status?: CollectionRecordStatus
192
+ /** The `nextCursor` of the previous page. Not together with `offset`. */
143
193
  readonly cursor?: string
194
+ /** Skip this many records first (0–`COLLECTION_RECORDS_OFFSET_MAX`; a numbered page is `offset = (page - 1) × limit`). Not together with `cursor`; the result then carries `total`. */
195
+ readonly offset?: number
144
196
  /** 1–100, default 50. */
145
197
  readonly limit?: number
146
198
  }
147
199
 
200
+ /** The body of `PATCH /v1/collections/:id/records/:recordId`: mark a record used (or not used again). */
201
+ export type SetCollectionRecordUsedInput = {
202
+ readonly used: boolean
203
+ /** Who is marking it; the API fills `via` when absent. */
204
+ readonly source?: CollectionRecordSource
205
+ }
206
+
148
207
  export interface ListCollectionRecordsResult {
149
208
  readonly data: readonly CollectionRecord[]
150
209
  readonly nextCursor: string | null
210
+ /** How many records match the filters in all (a numbered page is `ceil(total / limit)` pages). Only on a page asked for by `offset`, and left out when the server could not count. */
211
+ readonly total?: number
151
212
  }
152
213
 
153
214
  /** The body of `POST /v1/collections/:id/records`. An explicit field wins over
@@ -437,9 +498,18 @@ function mediaFromItem(item: Record<string, unknown>): CollectionMedia[] {
437
498
  for (const key of IMAGE_KEYS) if (isHttpUrl(item[key]) && !push({ type: "image", url: item[key] as string })) break
438
499
  for (const key of VIDEO_KEYS) if (isHttpUrl(item[key]) && !push({ type: "video", url: item[key] as string })) break
439
500
  for (const key of AUDIO_KEYS) if (isHttpUrl(item[key]) && !push({ type: "audio", url: item[key] as string })) break
501
+ // A `mediaUrl` whose kind sits beside it (`mediaKind`: image / photo / video / audio), else read off the
502
+ // file's ending, else a plain link. Both keys stay fields as well: a workflow may read them there.
503
+ if (isHttpUrl(item.mediaUrl)) push({ type: mediaKindOf(item.mediaKind, item.mediaUrl), url: item.mediaUrl })
440
504
  return out
441
505
  }
442
506
 
507
+ function mediaKindOf(kind: unknown, url: string): CollectionMediaType {
508
+ if (kind === "photo" || kind === "image") return "image"
509
+ if (kind === "video" || kind === "audio") return kind
510
+ return loneMediaUrlKind(url) ?? "link"
511
+ }
512
+
443
513
  /**
444
514
  * A record read out of any JSON item — a Telegram post, a Social Search
445
515
  * result, an LLM's object, a plain string. Title ← title / headline / name;
@@ -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
+ }