@nodaro/shared 3.20.0 → 3.23.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 (86) hide show
  1. package/dist/index.cjs +2287 -195
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +1938 -82
  4. package/dist/index.d.ts +1938 -82
  5. package/dist/index.js +2119 -196
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/add-captions-plan.test.ts +33 -0
  9. package/src/__tests__/caption-plan-parse.test.ts +23 -0
  10. package/src/__tests__/caption-segment-schema.test.ts +30 -0
  11. package/src/__tests__/collections.test.ts +253 -0
  12. package/src/__tests__/default-tts-provider.test.ts +46 -0
  13. package/src/__tests__/dialogue-capabilities.test.ts +157 -0
  14. package/src/__tests__/edit-plan-review.test.ts +70 -0
  15. package/src/__tests__/edl-clocks.test.ts +97 -0
  16. package/src/__tests__/edl.test.ts +34 -0
  17. package/src/__tests__/execution-outcome.test.ts +44 -0
  18. package/src/__tests__/fan-out-meta.test.ts +23 -0
  19. package/src/__tests__/fan-out-rows.test.ts +36 -0
  20. package/src/__tests__/fan-out-url-item.test.ts +44 -0
  21. package/src/__tests__/fixtures/speaker-tracks.fixtures.json +622 -0
  22. package/src/__tests__/input-field-extra-keys.test.ts +34 -0
  23. package/src/__tests__/list-consumers-fan-in.test.ts +40 -0
  24. package/src/__tests__/model-tree.test.ts +7 -0
  25. package/src/__tests__/node-pass-through.test.ts +23 -0
  26. package/src/__tests__/node-runtime-keys.test.ts +1 -0
  27. package/src/__tests__/picker-restrictions.test.ts +36 -0
  28. package/src/__tests__/preview-gate.test.ts +305 -0
  29. package/src/__tests__/render-basis.test.ts +176 -0
  30. package/src/__tests__/render-nodes.test.ts +73 -0
  31. package/src/__tests__/render-output.test.ts +392 -0
  32. package/src/__tests__/run-continuation.test.ts +32 -0
  33. package/src/__tests__/speaker-tracks.test.ts +474 -0
  34. package/src/__tests__/speech-pricing.test.ts +69 -0
  35. package/src/__tests__/telegram-channel.test.ts +91 -0
  36. package/src/__tests__/tts-capabilities.test.ts +83 -5
  37. package/src/__tests__/tts-neighbour-text.test.ts +19 -0
  38. package/src/__tests__/ugc-call-body.test.ts +38 -0
  39. package/src/__tests__/ugc-run-state.test.ts +68 -0
  40. package/src/__tests__/video-character-refs.test.ts +213 -0
  41. package/src/__tests__/video-overlay-layer-plan.test.ts +94 -0
  42. package/src/add-captions-plan.ts +50 -0
  43. package/src/caption-plan.ts +45 -0
  44. package/src/caption-segment-schema.ts +82 -0
  45. package/src/collections.ts +462 -0
  46. package/src/competitors.ts +77 -0
  47. package/src/credit-estimators/index.ts +9 -0
  48. package/src/credit-estimators/speech.ts +51 -0
  49. package/src/dialogue-capabilities.ts +48 -0
  50. package/src/edit-plan-contract.ts +20 -9
  51. package/src/edit-plan-review.ts +40 -1
  52. package/src/edl.ts +27 -1
  53. package/src/execution-outcome.ts +41 -0
  54. package/src/fan-out-meta.ts +23 -0
  55. package/src/fan-out-rows.ts +74 -5
  56. package/src/gemini-omni-voices.ts +59 -0
  57. package/src/handle-aliases.ts +295 -0
  58. package/src/i18n/camera-motions.pt-BR.ts +14 -14
  59. package/src/i18n/transitions.pt-BR.ts +13 -13
  60. package/src/index.ts +180 -1
  61. package/src/model-catalog.ts +125 -15
  62. package/src/model-constants.ts +37 -4
  63. package/src/model-tree.ts +5 -1
  64. package/src/node-execution-state.ts +13 -0
  65. package/src/node-mappable-fields.ts +7 -1
  66. package/src/node-pass-through.ts +37 -0
  67. package/src/node-runtime-keys.ts +14 -0
  68. package/src/picker-restrictions.ts +49 -0
  69. package/src/presentation-types.ts +26 -2
  70. package/src/presentation-utils.ts +25 -7
  71. package/src/preview-gate.ts +279 -0
  72. package/src/producer-types.ts +58 -0
  73. package/src/render-final.ts +20 -0
  74. package/src/render-nodes.ts +92 -0
  75. package/src/render-output.ts +565 -0
  76. package/src/run-continuation.ts +39 -0
  77. package/src/speaker-tracks.ts +638 -0
  78. package/src/telegram-channel.ts +140 -0
  79. package/src/transcribe-preflight.ts +8 -4
  80. package/src/tts-capabilities.ts +19 -5
  81. package/src/tts-neighbour-text.ts +46 -0
  82. package/src/ugc-call-body.ts +86 -0
  83. package/src/ugc-run-state.ts +64 -0
  84. package/src/video-character-refs.ts +233 -0
  85. package/src/video-overlay.ts +78 -21
  86. package/src/voices.ts +11 -7
@@ -0,0 +1,39 @@
1
+ /**
2
+ * A run CONTINUED from an earlier execution (`continueFromExecutionId` on
3
+ * `POST /v1/workflows/:id/run`): the nodes it does not run hand on what that
4
+ * execution produced, never the workflow's saved results. Render final after a
5
+ * run that stopped at a preview is one, and an app's Render final runs as one,
6
+ * outside the app run.
7
+ *
8
+ * The stable codes a continuation is refused with. A client branches on the
9
+ * code, never on the text.
10
+ */
11
+
12
+ /** The execution does not exist, or the caller did not start it. */
13
+ export const CONTINUATION_NOT_FOUND = "continuation_not_found"
14
+
15
+ /** The execution ran another workflow. */
16
+ export const CONTINUATION_WORKFLOW_MISMATCH = "continuation_workflow_mismatch"
17
+
18
+ /** The execution ran another version of the graph: a published app version
19
+ * where this run uses the live workflow, or the reverse, or another version. */
20
+ export const CONTINUATION_VERSION_MISMATCH = "continuation_version_mismatch"
21
+
22
+ /** The execution has not ended `completed` (it is still running, or it
23
+ * failed or was cancelled). */
24
+ export const CONTINUATION_NOT_COMPLETED = "continuation_not_completed"
25
+
26
+ /** A continuation names the nodes it runs (`nodeIds`); every other node hands
27
+ * on the execution's output. */
28
+ export const CONTINUATION_SUBSET_REQUIRED = "continuation_subset_required"
29
+
30
+ /** Every continuation refusal code. */
31
+ export const RUN_CONTINUATION_CODES = [
32
+ CONTINUATION_NOT_FOUND,
33
+ CONTINUATION_WORKFLOW_MISMATCH,
34
+ CONTINUATION_VERSION_MISMATCH,
35
+ CONTINUATION_NOT_COMPLETED,
36
+ CONTINUATION_SUBSET_REQUIRED,
37
+ ] as const
38
+
39
+ export type RunContinuationCode = (typeof RUN_CONTINUATION_CODES)[number]
@@ -0,0 +1,638 @@
1
+ import type { Edl, EdlSource, EdlValidation } from "./edl.js"
2
+
3
+ /**
4
+ * Speaker tracks — where each speaker's face is, over time, per camera.
5
+ *
6
+ * WHY THIS EXISTS
7
+ * A face-tracking analysis node samples each camera an edit shows, finds the
8
+ * faces, links them into tracks and labels each track with a speaker. Its
9
+ * result feeds the framing rung `resolveEdlSegmentSlots` reserves for a
10
+ * per-segment resolver (D20, edl-multicam.ts). This module is the wire shape
11
+ * of that result plus the pure functions that read it: structural vocabulary
12
+ * only — no detector, no linking or attribution rule, no framing or follow
13
+ * math, no thresholds. That is why it lives in the Apache-licensed
14
+ * `@nodaro/shared` (the public contract: the API response, the SDK type and
15
+ * the MCP output). Every published version is an irrevocable grant, so every
16
+ * later field is optional and additive.
17
+ *
18
+ * TWO SHAPES, ONE PROJECTION
19
+ * - `SpeakerTrackSet` — the full set, boxes included. At a long multi-camera
20
+ * edit it is megabytes of JSON, so it is stored as a JSON artifact (the
21
+ * versioned box body), never inline in a job row or a node's data.
22
+ * - `SpeakerTrackSetDescriptor` — what the node outputs: the same set with
23
+ * every box removed (a `boxCount` per track instead) plus the artifact's
24
+ * `url`, `sha256` and `bytes`. Consumers fetch the body by URL, check the
25
+ * hash, run `normalizeSpeakerTracks` + `validateSpeakerTracks` on it, and
26
+ * can confirm it is the body the descriptor names with
27
+ * `describeSpeakerTracks(body, artifact)` deep-equal to the descriptor.
28
+ *
29
+ * CLOCK (D19)
30
+ * Boxes are per SOURCE and on that source's own clock (`clock: "source"`), in
31
+ * integer ms. A consumer maps to the master clock through the EDL source's
32
+ * offset: `masterMs = ms + offsetMs` (`remapMsThroughEdl(edl, ms, sourceId)`).
33
+ * Nothing here applies the offset, and nothing ever rescales a time (no
34
+ * seconds→ms guessing — an implausible value is a validation error).
35
+ *
36
+ * GEOMETRY
37
+ * Box coordinates are fractions 0..1 of `frame`: the display-oriented frame
38
+ * (after rotation, square pixels) the producer sampled.
39
+ *
40
+ * SAMPLING
41
+ * `sampledSpans` say what was looked at. No box for a track outside them means
42
+ * "not sampled"; inside them it means "no face there". Spans are half-open
43
+ * `[startMs, endMs)`, like EDL segments.
44
+ */
45
+
46
+ export const SPEAKER_TRACKS_VERSION = 1 as const
47
+
48
+ /** How a track got its speaker. Open: a newer producer may add a method, which
49
+ * an older validator reports as a WARNING, never an issue. */
50
+ export const SPEAKER_TRACK_ATTRIBUTION_METHODS = ["source-map", "region", "mouth-motion", "manual"] as const
51
+ export type SpeakerTrackAttributionMethod = (typeof SPEAKER_TRACK_ATTRIBUTION_METHODS)[number]
52
+ const KNOWN_METHODS: ReadonlySet<string> = new Set(SPEAKER_TRACK_ATTRIBUTION_METHODS)
53
+
54
+ /** Default hard cap on boxes per source. The longest edit the platform plans
55
+ * for (180 minutes) sampled at 2 per second is 21,600 samples per source; the
56
+ * cap leaves room for several faces in every sample. Override per call with
57
+ * `maxBoxesPerSource`. */
58
+ export const SPEAKER_TRACKS_MAX_BOXES_PER_SOURCE = 100_000
59
+ /** Default hard cap on the serialized size of a track set (UTF-8 bytes of its
60
+ * JSON), so no consumer ever loads an unbounded body. Override per call with
61
+ * `maxBytes`. */
62
+ export const SPEAKER_TRACKS_MAX_BYTES = 64 * 1024 * 1024
63
+
64
+ /** One detection. `ms` on the source clock; x/y/w/h fractions 0..1 of the frame. */
65
+ export interface SpeakerTrackBox {
66
+ readonly ms: number
67
+ readonly x: number
68
+ readonly y: number
69
+ readonly w: number
70
+ readonly h: number
71
+ /** Detector confidence 0..1, when the detector reports one. */
72
+ readonly score?: number
73
+ }
74
+
75
+ export interface SpeakerTrackAttribution {
76
+ /** Known: `SPEAKER_TRACK_ATTRIBUTION_METHODS`. */
77
+ readonly method: SpeakerTrackAttributionMethod | (string & {})
78
+ /** 0..1. */
79
+ readonly confidence: number
80
+ /** The transcript's own label for this speaker, kept beside the display name
81
+ * in `speaker` so a later rename re-maps instead of orphaning the track. */
82
+ readonly rawSpeaker?: string
83
+ }
84
+
85
+ /** What a track says about itself, without its boxes. */
86
+ export interface SpeakerTrackHeader {
87
+ /** Unique in the whole set, e.g. "wide/t3". */
88
+ readonly id: string
89
+ /** A label in the edit's speaker space. Absent = unattributed. */
90
+ readonly speaker?: string
91
+ readonly attribution?: SpeakerTrackAttribution
92
+ }
93
+
94
+ export interface SpeakerTrack extends SpeakerTrackHeader {
95
+ /** Strictly increasing `ms`, each inside one of the source's `sampledSpans`. */
96
+ readonly boxes: readonly SpeakerTrackBox[]
97
+ }
98
+
99
+ export interface SpeakerTrackSummary extends SpeakerTrackHeader {
100
+ readonly boxCount: number
101
+ }
102
+
103
+ export interface SpeakerTrackSpan {
104
+ readonly startMs: number
105
+ /** Exclusive, > startMs. */
106
+ readonly endMs: number
107
+ }
108
+
109
+ interface SpeakerTrackSourceFields {
110
+ /** `EdlSource.id` of a video source. */
111
+ readonly sourceId: string
112
+ /** Boxes, spans and cuts are ms on this SOURCE's own clock (D19). */
113
+ readonly clock: "source"
114
+ /** The display-oriented frame (after rotation, square pixels), in pixels, that box fractions refer to. */
115
+ readonly frame: { readonly w: number; readonly h: number }
116
+ /** What was sampled: sorted, non-overlapping, half-open. */
117
+ readonly sampledSpans: readonly SpeakerTrackSpan[]
118
+ /** Source-clock ms of detected scene changes, ascending. No track spans one. */
119
+ readonly cuts?: readonly number[]
120
+ }
121
+
122
+ export interface SpeakerTrackSource extends SpeakerTrackSourceFields {
123
+ readonly tracks: readonly SpeakerTrack[]
124
+ }
125
+
126
+ export interface SpeakerTrackSourceSummary extends SpeakerTrackSourceFields {
127
+ readonly tracks: readonly SpeakerTrackSummary[]
128
+ }
129
+
130
+ interface SpeakerTrackSetFields {
131
+ readonly version: 1
132
+ /** Samples per second the producer looked at. */
133
+ readonly sampleFps: number
134
+ /** Informational: which detector produced the boxes, e.g. "example:face-detector". */
135
+ readonly detector: { readonly id: string; readonly version?: string }
136
+ }
137
+
138
+ /** The full set — the versioned box body, stored as a JSON artifact. */
139
+ export interface SpeakerTrackSet extends SpeakerTrackSetFields {
140
+ readonly sources: readonly SpeakerTrackSource[]
141
+ }
142
+
143
+ /** What the analysis node outputs: the set without its boxes, plus where the body is. */
144
+ export interface SpeakerTrackSetDescriptor extends SpeakerTrackSetFields {
145
+ readonly sources: readonly SpeakerTrackSourceSummary[]
146
+ /** Where the `SpeakerTrackSet` body is stored. */
147
+ readonly url: string
148
+ /** SHA-256 of the stored body's bytes, 64 lowercase hex characters. */
149
+ readonly sha256: string
150
+ /** Size of the stored body in bytes. */
151
+ readonly bytes: number
152
+ }
153
+
154
+ // ─────────────────────────────────────────────────────────────────────────
155
+ // Normalization (coerce, never reject — and never reinterpret)
156
+ // ─────────────────────────────────────────────────────────────────────────
157
+
158
+ const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v)
159
+ const isNum = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v)
160
+ const num = (v: unknown, fallback = 0): number => (isNum(v) ? v : fallback)
161
+ const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined)
162
+ const clamp01 = (v: number): number => Math.min(1, Math.max(0, v))
163
+ /** A readonly array field of a value that may have skipped normalization. */
164
+ const arr = <T,>(v: readonly T[] | undefined): readonly T[] => (Array.isArray(v) ? v : [])
165
+ /** Integer ms; never -0 (JSON cannot carry it, so a round trip would differ). */
166
+ const int = (v: number): number => {
167
+ const r = Math.round(v)
168
+ return r === 0 ? 0 : r
169
+ }
170
+
171
+ /** One axis of a detection, cropped to the frame: the visible part of
172
+ * `[p, p+s]` within `[0, 1]`, or undefined when none of it is visible. An
173
+ * in-frame axis is returned untouched (so a second pass cannot drift by a
174
+ * float ulp); an overhanging one becomes the intersection, whichever edge it
175
+ * crosses, so its centre only ever moves toward the visible part. */
176
+ function cropAxis(p: number, s: number): readonly [number, number] | undefined {
177
+ if (!(s > 0)) return undefined
178
+ if (p >= 0 && p + s <= 1) return [p, s]
179
+ const lo = clamp01(p)
180
+ const hi = clamp01(p + s)
181
+ return hi > lo ? [lo, hi - lo] : undefined
182
+ }
183
+
184
+ function normalizeBox(raw: unknown): SpeakerTrackBox | undefined {
185
+ if (!isObj(raw)) return undefined
186
+ if (![raw.ms, raw.x, raw.y, raw.w, raw.h].every(isNum)) return undefined
187
+ // A detection is cropped to the frame, never moved: a face at the frame edge
188
+ // keeps only its visible part, and one entirely off-frame is dropped. This is
189
+ // deliberately NOT `normalizeRegion`'s clamp-then-shrink (edl.ts), which is
190
+ // fine for a region a user draws but would shift a left/top overhang and turn
191
+ // an off-frame detection into an in-frame face.
192
+ const xs = cropAxis(raw.x as number, raw.w as number)
193
+ const ys = cropAxis(raw.y as number, raw.h as number)
194
+ if (!xs || !ys) return undefined
195
+ const [x, w] = xs
196
+ const [y, h] = ys
197
+ return { ms: int(raw.ms as number), x, y, w, h, ...(isNum(raw.score) ? { score: clamp01(raw.score) } : {}) }
198
+ }
199
+
200
+ function normalizeSpans(raw: unknown): SpeakerTrackSpan[] {
201
+ if (!Array.isArray(raw)) return []
202
+ const spans = raw
203
+ .filter(isObj)
204
+ .filter((s) => isNum(s.startMs) && isNum(s.endMs))
205
+ .map((s) => ({ startMs: int(s.startMs as number), endMs: int(s.endMs as number) }))
206
+ .filter((s) => s.endMs > s.startMs)
207
+ .sort((a, b) => a.startMs - b.startMs || a.endMs - b.endMs)
208
+ const merged: SpeakerTrackSpan[] = []
209
+ for (const s of spans) {
210
+ const last = merged[merged.length - 1]
211
+ if (last && s.startMs <= last.endMs) merged[merged.length - 1] = { startMs: last.startMs, endMs: Math.max(last.endMs, s.endMs) }
212
+ else merged.push(s)
213
+ }
214
+ return merged
215
+ }
216
+
217
+ function normalizeCuts(raw: unknown): number[] {
218
+ if (!Array.isArray(raw)) return []
219
+ const sorted = raw.filter(isNum).map(int).sort((a, b) => a - b)
220
+ return sorted.filter((c, i) => i === 0 || c !== sorted[i - 1])
221
+ }
222
+
223
+ function normalizeAttribution(raw: unknown): SpeakerTrackAttribution | undefined {
224
+ if (!isObj(raw)) return undefined
225
+ const method = str(raw.method)
226
+ if (!method) return undefined
227
+ const rawSpeaker = str(raw.rawSpeaker)
228
+ return { method, confidence: clamp01(num(raw.confidence)), ...(rawSpeaker ? { rawSpeaker } : {}) }
229
+ }
230
+
231
+ function normalizeHeader(raw: Record<string, unknown>, fallbackId: string): SpeakerTrackHeader {
232
+ const speaker = str(raw.speaker)
233
+ const attribution = normalizeAttribution(raw.attribution)
234
+ return {
235
+ id: str(raw.id) || fallbackId,
236
+ ...(speaker ? { speaker } : {}),
237
+ ...(attribution ? { attribution } : {}),
238
+ }
239
+ }
240
+
241
+ function normalizeSetFields(o: Record<string, unknown>): SpeakerTrackSetFields {
242
+ const detector = isObj(o.detector) ? o.detector : {}
243
+ const detectorVersion = str(detector.version)
244
+ return {
245
+ // Only an ABSENT version defaults to 1. Any present value — another
246
+ // number, "2", null — is kept as is so validate refuses it rather than
247
+ // reading a newer (or broken) body as this one.
248
+ version: (o.version === undefined ? SPEAKER_TRACKS_VERSION : o.version) as 1,
249
+ sampleFps: num(o.sampleFps),
250
+ detector: { id: str(detector.id) ?? "", ...(detectorVersion ? { version: detectorVersion } : {}) },
251
+ }
252
+ }
253
+
254
+ function normalizeSources<T>(
255
+ raw: unknown,
256
+ track: (t: Record<string, unknown>, fallbackId: string) => T,
257
+ ): Array<SpeakerTrackSourceFields & { readonly tracks: readonly T[] }> {
258
+ if (!Array.isArray(raw)) return []
259
+ return raw.map((r) => {
260
+ const s = isObj(r) ? r : {}
261
+ const sourceId = str(s.sourceId) ?? ""
262
+ const frame = isObj(s.frame) ? s.frame : {}
263
+ const cuts = normalizeCuts(s.cuts)
264
+ const tracks = Array.isArray(s.tracks) ? s.tracks.map((t, k) => track(isObj(t) ? t : {}, `${sourceId}/t${k + 1}`)) : []
265
+ return {
266
+ sourceId,
267
+ // A clock other than "source" cannot be repaired: boxes on another clock
268
+ // would land offsetMs away from their frame. Keep it for validate to refuse.
269
+ clock: (typeof s.clock === "string" ? s.clock : "source") as "source",
270
+ frame: { w: int(num(frame.w)), h: int(num(frame.h)) },
271
+ sampledSpans: normalizeSpans(s.sampledSpans),
272
+ tracks,
273
+ ...(cuts.length > 0 ? { cuts } : {}),
274
+ }
275
+ })
276
+ }
277
+
278
+ /**
279
+ * Coerce an unknown value into a well-formed `SpeakerTrackSet` (the box body):
280
+ * drop unknown keys and malformed boxes, crop every box to the frame (an
281
+ * entirely off-frame box is dropped, an overhang keeps its visible part), clamp
282
+ * scores and confidences to 0..1, round every time to integer ms, sort each
283
+ * track's boxes by time (box order IS time, unlike EDL segment order), sort and
284
+ * merge sampled spans, sort and de-duplicate cuts.
285
+ *
286
+ * It never repairs what would change meaning: a box outside every sampled
287
+ * span, two boxes at one instant, a track across a cut, another version or
288
+ * another clock all survive for `validateSpeakerTracks` to report.
289
+ */
290
+ export function normalizeSpeakerTracks(input: unknown): SpeakerTrackSet {
291
+ const o = isObj(input) ? input : {}
292
+ return {
293
+ ...normalizeSetFields(o),
294
+ sources: normalizeSources(o.sources, (t, fallbackId) => {
295
+ const boxes = Array.isArray(t.boxes) ? t.boxes.map(normalizeBox).filter((b): b is SpeakerTrackBox => b !== undefined) : []
296
+ return { ...normalizeHeader(t, fallbackId), boxes: [...boxes].sort((a, b) => a.ms - b.ms) }
297
+ }),
298
+ }
299
+ }
300
+
301
+ /** Coerce an unknown value into a `SpeakerTrackSetDescriptor`, by the same rules
302
+ * as `normalizeSpeakerTracks`; a missing or broken `boxCount` becomes 0. */
303
+ export function normalizeSpeakerTrackSetDescriptor(input: unknown): SpeakerTrackSetDescriptor {
304
+ const o = isObj(input) ? input : {}
305
+ return {
306
+ ...normalizeSetFields(o),
307
+ sources: normalizeSources(o.sources, (t, fallbackId) => ({
308
+ ...normalizeHeader(t, fallbackId),
309
+ boxCount: Math.max(0, int(num(t.boxCount))),
310
+ })),
311
+ url: str(o.url) ?? "",
312
+ sha256: str(o.sha256) ?? "",
313
+ bytes: int(num(o.bytes)),
314
+ }
315
+ }
316
+
317
+ /** The descriptor of a (normalized) set stored at `artifact.url`: every box
318
+ * removed, a `boxCount` per track. Pure; the caller hashes and stores the body. */
319
+ export function describeSpeakerTracks(
320
+ set: SpeakerTrackSet,
321
+ artifact: { readonly url: string; readonly sha256: string; readonly bytes: number },
322
+ ): SpeakerTrackSetDescriptor {
323
+ return {
324
+ version: set.version,
325
+ sampleFps: set.sampleFps,
326
+ detector: { ...set.detector },
327
+ sources: set.sources.map((s) => ({
328
+ sourceId: s.sourceId,
329
+ clock: s.clock,
330
+ frame: { ...s.frame },
331
+ sampledSpans: s.sampledSpans.map((sp) => ({ ...sp })),
332
+ tracks: s.tracks.map((t) => ({
333
+ id: t.id,
334
+ ...(t.speaker !== undefined ? { speaker: t.speaker } : {}),
335
+ ...(t.attribution ? { attribution: { ...t.attribution } } : {}),
336
+ boxCount: t.boxes.length,
337
+ })),
338
+ ...(s.cuts && s.cuts.length > 0 ? { cuts: [...s.cuts] } : {}),
339
+ })),
340
+ url: artifact.url,
341
+ sha256: artifact.sha256,
342
+ bytes: artifact.bytes,
343
+ }
344
+ }
345
+
346
+ // ─────────────────────────────────────────────────────────────────────────
347
+ // The edit's speaker space
348
+ // ─────────────────────────────────────────────────────────────────────────
349
+
350
+ /** The speaker labels an edit uses: the union of `sources[].speakers`,
351
+ * `segments[].speaker` and `segments[].layout.slots[].speaker`, over every EDL
352
+ * given (a clip pack), sorted by code unit. Tracks must be labelled in this
353
+ * space, or no track ever matches a segment's speaker. */
354
+ export function edlSpeakerSpace(edl: Edl | readonly Edl[]): string[] {
355
+ const out = new Set<string>()
356
+ const add = (v: unknown) => {
357
+ if (typeof v === "string" && v) out.add(v)
358
+ }
359
+ for (const e of edlList(edl)) {
360
+ for (const s of Array.isArray(e.sources) ? e.sources : []) {
361
+ for (const sp of Array.isArray(s?.speakers) ? s.speakers : []) add(sp)
362
+ }
363
+ for (const seg of Array.isArray(e.segments) ? e.segments : []) {
364
+ add(seg?.speaker)
365
+ for (const slot of Array.isArray(seg?.layout?.slots) ? seg.layout!.slots! : []) add(slot?.speaker)
366
+ }
367
+ }
368
+ return [...out].sort()
369
+ }
370
+
371
+ function edlList(edl: Edl | readonly Edl[] | undefined): readonly Edl[] {
372
+ if (!edl) return []
373
+ const all: readonly unknown[] = Array.isArray(edl) ? edl : [edl]
374
+ return all.filter((e): e is Edl => isObj(e))
375
+ }
376
+
377
+ // ─────────────────────────────────────────────────────────────────────────
378
+ // Validation
379
+ // ─────────────────────────────────────────────────────────────────────────
380
+
381
+ export interface SpeakerTracksValidateOptions {
382
+ /** The edit the tracks are for — one EDL, or every clip of a pack. When given,
383
+ * every source must resolve to one of its video sources, and attributed
384
+ * speakers must be in its speaker space (`edlSpeakerSpace`). */
385
+ readonly edl?: Edl | readonly Edl[]
386
+ /** Default `SPEAKER_TRACKS_MAX_BOXES_PER_SOURCE`. */
387
+ readonly maxBoxesPerSource?: number
388
+ /** Default `SPEAKER_TRACKS_MAX_BYTES`. */
389
+ readonly maxBytes?: number
390
+ /** `validateSpeakerTracks` only: the body's known size in bytes (e.g. the
391
+ * fetched length), so a large body is not serialized again to measure it. */
392
+ readonly serializedBytes?: number
393
+ }
394
+
395
+ const SHA256_HEX = /^[0-9a-f]{64}$/
396
+
397
+ type Findings = { issues: string[]; warnings: string[] }
398
+
399
+ /** The rules shared by the body and the descriptor. `perTrack` adds the body's
400
+ * box rules and returns the track's box count. */
401
+ function validateCommon<T extends SpeakerTrackHeader>(
402
+ set: SpeakerTrackSetFields & { readonly sources: ReadonlyArray<SpeakerTrackSourceFields & { readonly tracks: readonly T[] }> },
403
+ opts: SpeakerTracksValidateOptions,
404
+ perTrack: (track: T, source: SpeakerTrackSourceFields, f: Findings) => number,
405
+ ): Findings {
406
+ const f: Findings = { issues: [], warnings: [] }
407
+ const { issues, warnings } = f
408
+ const sources = arr(set.sources)
409
+ const maxBoxes = opts.maxBoxesPerSource ?? SPEAKER_TRACKS_MAX_BOXES_PER_SOURCE
410
+
411
+ if (set.version !== SPEAKER_TRACKS_VERSION) issues.push(`version must be ${SPEAKER_TRACKS_VERSION}`)
412
+ if (!(isNum(set.sampleFps) && set.sampleFps > 0)) issues.push("sampleFps must be a finite number > 0")
413
+
414
+ const edls = edlList(opts.edl)
415
+ const edlSources = new Map<string, EdlSource>()
416
+ for (const e of edls) {
417
+ for (const s of Array.isArray(e.sources) ? e.sources : []) {
418
+ if (s && typeof s.id === "string" && !edlSources.has(s.id)) edlSources.set(s.id, s)
419
+ }
420
+ }
421
+
422
+ const sourceIds = new Set<string>()
423
+ const trackIds = new Set<string>()
424
+ sources.forEach((s, i) => {
425
+ const sid = s.sourceId
426
+ const at = `source "${sid}"`
427
+ if (!sid) issues.push(`source[${i}]: sourceId is empty`)
428
+ else if (sourceIds.has(sid)) issues.push(`duplicate source id "${sid}"`)
429
+ sourceIds.add(sid)
430
+ if (sid && edls.length > 0) {
431
+ const es = edlSources.get(sid)
432
+ if (!es) issues.push(`${at}: not a source of the EDL`)
433
+ else if (es.kind !== "video") issues.push(`${at}: the EDL source is kind:"${es.kind}", tracks need a video source`)
434
+ }
435
+ if (s.clock !== "source") issues.push(`${at}: clock must be "source"`)
436
+ if (!(isObj(s.frame) && isNum(s.frame.w) && isNum(s.frame.h) && s.frame.w > 0 && s.frame.h > 0)) {
437
+ issues.push(`${at}: frame w/h must be positive`)
438
+ }
439
+
440
+ const spans = arr<SpeakerTrackSpan>(s.sampledSpans)
441
+ spans.forEach((sp, j) => {
442
+ const startMs: unknown = sp?.startMs
443
+ const endMs: unknown = sp?.endMs
444
+ if (!(isNum(startMs) && isNum(endMs) && endMs > startMs)) {
445
+ issues.push(`${at}: sampledSpans[${j}] [${startMs},${endMs}) is not positive`)
446
+ return
447
+ }
448
+ if (!(Number.isInteger(startMs) && Number.isInteger(endMs))) issues.push(`${at}: sampledSpans[${j}] [${startMs},${endMs}) is not integer ms`)
449
+ if (startMs < 0) issues.push(`${at}: sampledSpans[${j}] starts before 0`)
450
+ const prevEnd: unknown = spans[j - 1]?.endMs
451
+ if (j > 0 && isNum(prevEnd) && startMs < prevEnd) {
452
+ issues.push(`${at}: sampledSpans must be sorted and non-overlapping (span ${j})`)
453
+ }
454
+ })
455
+
456
+ const cuts = s.cuts
457
+ if (cuts !== undefined) {
458
+ const okCuts = Array.isArray(cuts) && cuts.every((c, k) => Number.isInteger(c) && c >= 0 && (k === 0 || c > cuts[k - 1]))
459
+ if (!okCuts) issues.push(`${at}: cuts must be ascending non-negative ms`)
460
+ }
461
+
462
+ let boxes = 0
463
+ const tracks = arr<T>(s.tracks)
464
+ tracks.forEach((t, k) => {
465
+ if (!t?.id) issues.push(`${at} track[${k}]: id is empty`)
466
+ else if (trackIds.has(t.id)) issues.push(`duplicate track id "${t.id}"`)
467
+ if (t?.id) trackIds.add(t.id)
468
+ const a = t?.attribution
469
+ if (a) {
470
+ if (!(isNum(a.confidence) && a.confidence >= 0 && a.confidence <= 1)) {
471
+ issues.push(`track "${t.id}": attribution.confidence=${a.confidence} out of 0..1`)
472
+ }
473
+ if (!KNOWN_METHODS.has(a.method)) {
474
+ warnings.push(`track "${t.id}": unknown attribution method "${a.method}" (known: ${SPEAKER_TRACK_ATTRIBUTION_METHODS.join(", ")})`)
475
+ }
476
+ }
477
+ boxes += perTrack(t, s, f)
478
+ })
479
+ if (boxes > maxBoxes) issues.push(`${at}: ${boxes} boxes is over the cap of ${maxBoxes}`)
480
+ })
481
+
482
+ // The speaker name space: labels from the raw transcript against an edit
483
+ // that uses display names (or the reverse) match nothing, and every slot
484
+ // would silently fall back to static framing.
485
+ if (edls.length > 0) {
486
+ const space = edlSpeakerSpace(edls)
487
+ const attributed = sources.flatMap((s) => (Array.isArray(s.tracks) ? s.tracks : [])).filter((t) => !!t?.speaker)
488
+ if (space.length > 0 && attributed.length > 0) {
489
+ const inSpace = new Set(space)
490
+ const matches = (t: T) => inSpace.has(t.speaker!) || (!!t.attribution?.rawSpeaker && inSpace.has(t.attribution.rawSpeaker))
491
+ if (!attributed.some(matches)) {
492
+ const labels = [...new Set(attributed.map((t) => t.speaker!))].sort()
493
+ issues.push(
494
+ `no tracked speaker is in the edit's speaker set: the tracks are labelled ${labels.map((l) => `"${l}"`).join(", ")}` +
495
+ ` and the edit uses ${space.map((l) => `"${l}"`).join(", ")} — wire Speaker Frames to the same transcript as Camera Switch`,
496
+ )
497
+ } else {
498
+ for (const t of attributed) {
499
+ if (!matches(t)) warnings.push(`track "${t.id}": speaker "${t.speaker}" is not in the edit's speaker set`)
500
+ }
501
+ }
502
+ }
503
+ }
504
+ return f
505
+ }
506
+
507
+ /** Per-box findings listed per track and rule before the rest are summarized
508
+ * in one line, and the most issues a validation lists before one truncation
509
+ * line. A systematic producer bug (a clock off by `offsetMs`, say) puts EVERY
510
+ * box out of span; the refusal must stay readable wherever it is shown. */
511
+ const BOX_FINDINGS_PER_RULE = 5
512
+ const MAX_LISTED_FINDINGS = 100
513
+
514
+ /** A per-box finding: the rule (what the per-track summary line counts, as
515
+ * "N more boxes <rule>") and the message for one box. */
516
+ type BoxFinding = readonly [rule: string, message: string]
517
+
518
+ function boxIssues(b: SpeakerTrackBox, at: string): BoxFinding[] {
519
+ const out: BoxFinding[] = []
520
+ for (const k of ["x", "y", "w", "h"] as const) {
521
+ const v = b?.[k]
522
+ if (!isNum(v) || v < 0 || v > 1) out.push([`with ${k} out of 0..1`, `${at}: ${k}=${v} out of 0..1`])
523
+ }
524
+ if (out.length > 0) return out
525
+ // The same edge tolerance as validateEdl's regions, so the two never disagree.
526
+ if (b.w <= 0 || b.h <= 0) out.push(["with a non-positive w/h", `${at}: non-positive w/h`])
527
+ if (b.x + b.w > 1 + 1e-9) out.push(["extending past the right edge", `${at}: extends past the right edge (x+w>1)`])
528
+ if (b.y + b.h > 1 + 1e-9) out.push(["extending past the bottom edge", `${at}: extends past the bottom edge (y+h>1)`])
529
+ if (b.score !== undefined && !(isNum(b.score) && b.score >= 0 && b.score <= 1)) out.push(["with a score out of 0..1", `${at}: score=${b.score} out of 0..1`])
530
+ return out
531
+ }
532
+
533
+ /** Cap a findings list at `MAX_LISTED_FINDINGS`, ending in one line that counts
534
+ * the rest. Never empties a non-empty list, so `ok` is unchanged. */
535
+ function capListed(list: readonly string[], noun: "issues" | "warnings"): string[] {
536
+ if (list.length <= MAX_LISTED_FINDINGS) return [...list]
537
+ return [...list.slice(0, MAX_LISTED_FINDINGS), `${list.length - MAX_LISTED_FINDINGS} more ${noun} not listed`]
538
+ }
539
+
540
+ /** Is `ms` inside one of `spans` (sorted, half-open)? Binary search. */
541
+ function inSpans(spans: readonly SpeakerTrackSpan[], ms: number): boolean {
542
+ let lo = 0
543
+ let hi = spans.length - 1
544
+ while (lo <= hi) {
545
+ const mid = (lo + hi) >> 1
546
+ const sp = spans[mid]
547
+ if (ms < sp.startMs) hi = mid - 1
548
+ else if (ms >= sp.endMs) lo = mid + 1
549
+ else return true
550
+ }
551
+ return false
552
+ }
553
+
554
+ /**
555
+ * Structural validation of a track set (the box body). Normalization is
556
+ * `normalizeSpeakerTracks`'s job; this reports what is still wrong after it.
557
+ * Issues are facts intrinsic to the set (or to the set against the EDL);
558
+ * warnings are judgements an older validator must not turn into a refusal
559
+ * (an unknown attribution method, one stray speaker label).
560
+ *
561
+ * Rules: version; a positive sample rate; unique source ids that resolve to
562
+ * the EDL's video sources; the source clock; a positive frame; sorted,
563
+ * non-overlapping, positive, integer-ms spans; ascending integer cuts; unique
564
+ * track ids; every box in-frame, at an integer ms, strictly after the previous
565
+ * one and inside a sampled span; no track across a cut; the speaker name
566
+ * space; the box and byte caps.
567
+ *
568
+ * The listing is bounded: per track, the first few boxes breaking each rule
569
+ * are listed and the rest counted in one line; past a fixed total, one line
570
+ * counts the issues (or warnings) not listed. `ok` counts every finding.
571
+ */
572
+ export function validateSpeakerTracks(set: SpeakerTrackSet, opts: SpeakerTracksValidateOptions = {}): EdlValidation {
573
+ const safe = isObj(set) ? set : ({} as SpeakerTrackSet)
574
+ const f = validateCommon(safe, opts, (t, source, { issues }) => {
575
+ const boxes = Array.isArray(t?.boxes) ? t.boxes : []
576
+ const spans = Array.isArray(source.sampledSpans) ? source.sampledSpans : []
577
+ let first = Infinity
578
+ let last = -Infinity
579
+ // The first few findings of each rule are listed; the rest are counted.
580
+ const seen = new Map<string, number>()
581
+ const report = ([rule, message]: BoxFinding) => {
582
+ const n = (seen.get(rule) ?? 0) + 1
583
+ seen.set(rule, n)
584
+ if (n <= BOX_FINDINGS_PER_RULE) issues.push(message)
585
+ }
586
+ const outside = `outside every sampled span of source "${source.sourceId}"`
587
+ boxes.forEach((b, j) => {
588
+ const at = `track "${t.id}" box[${j}]`
589
+ boxIssues(b, at).forEach(report)
590
+ if (!isNum(b?.ms)) {
591
+ report(["whose ms is not a number", `${at}: ms is not a number`])
592
+ return
593
+ }
594
+ if (!Number.isInteger(b.ms)) report(["whose ms is not an integer", `${at}: ms ${b.ms} is not an integer`])
595
+ const prev = boxes[j - 1]?.ms
596
+ if (j > 0 && isNum(prev) && !(b.ms > prev)) report(["not after the previous box", `${at}: ms ${b.ms} is not after the previous box (${prev})`])
597
+ if (!inSpans(spans, b.ms)) report([outside, `${at}: ms ${b.ms} is ${outside}`])
598
+ first = Math.min(first, b.ms)
599
+ last = Math.max(last, b.ms)
600
+ })
601
+ for (const [rule, n] of seen) {
602
+ if (n > BOX_FINDINGS_PER_RULE) issues.push(`track "${t.id}": ${n - BOX_FINDINGS_PER_RULE} more boxes ${rule}`)
603
+ }
604
+ const cut = (Array.isArray(source.cuts) ? source.cuts : []).find((c) => first < c && c <= last)
605
+ if (cut !== undefined) issues.push(`track "${t.id}": spans the cut at ${cut} ms (boxes ${first}..${last})`)
606
+ return boxes.length
607
+ })
608
+ const maxBytes = opts.maxBytes ?? SPEAKER_TRACKS_MAX_BYTES
609
+ const bytes = opts.serializedBytes ?? new TextEncoder().encode(JSON.stringify(safe)).length
610
+ if (bytes > maxBytes) f.issues.push(`the track set is ${bytes} bytes, over the cap of ${maxBytes}`)
611
+ return { ok: f.issues.length === 0, issues: capListed(f.issues, "issues"), warnings: capListed(f.warnings, "warnings") }
612
+ }
613
+
614
+ /**
615
+ * Structural validation of a descriptor (the node's output): the same rules as
616
+ * `validateSpeakerTracks` minus the per-box ones (it has no boxes; `boxCount`
617
+ * feeds the per-source cap), plus a non-empty `url`, a well-formed `sha256`
618
+ * and a positive `bytes` within the byte cap.
619
+ */
620
+ export function validateSpeakerTrackSetDescriptor(
621
+ d: SpeakerTrackSetDescriptor,
622
+ opts: Omit<SpeakerTracksValidateOptions, "serializedBytes"> = {},
623
+ ): EdlValidation {
624
+ const safe = isObj(d) ? d : ({} as SpeakerTrackSetDescriptor)
625
+ const f = validateCommon(safe, opts, (t, _source, { issues }) => {
626
+ if (!(Number.isInteger(t?.boxCount) && t.boxCount >= 0)) {
627
+ issues.push(`track "${t?.id}": boxCount must be a non-negative integer`)
628
+ return 0
629
+ }
630
+ return t.boxCount
631
+ })
632
+ if (!(typeof safe.url === "string" && safe.url.trim())) f.issues.push("url is empty")
633
+ if (!(typeof safe.sha256 === "string" && SHA256_HEX.test(safe.sha256))) f.issues.push("sha256 must be 64 lowercase hex characters")
634
+ const maxBytes = opts.maxBytes ?? SPEAKER_TRACKS_MAX_BYTES
635
+ if (!(Number.isInteger(safe.bytes) && safe.bytes > 0)) f.issues.push("bytes must be a positive integer")
636
+ else if (safe.bytes > maxBytes) f.issues.push(`the track set is ${safe.bytes} bytes, over the cap of ${maxBytes}`)
637
+ return { ok: f.issues.length === 0, issues: capListed(f.issues, "issues"), warnings: capListed(f.warnings, "warnings") }
638
+ }