@nodaro/shared 3.11.0 → 3.12.1

package/src/edit-plan-contract.ts

@@ -0,0 +1,96 @@
+/**
+ * The edit-plan node's credit-id scheme and output unwrap — split out of
+ * `edl.ts` (which keeps the EDL shape itself) so that module stays within the
+ * file-size cap. Re-exported from the package index, so importers of
+ * `@nodaro/shared` are unaffected.
+ */
+import { EDL_VERSION } from "./edl.js"
+
+// ─────────────────────────────────────────────────────────────────────────
+//  edit-plan credit-id scheme (STRUCTURE only — the per-mode/tier/bucket credit
+//  VALUES live app-side in backend/ee/billing/credits.ts + migration 432, since
+//  they are probe-set placeholders and the DB row wins at runtime). Lives HERE
+//  so BOTH core payload-builder and ee credits.ts read one id builder — core
+//  may not import ee (check-ee-imports), the same reason buildVideoAnalysisCreditId
+//  is shared. Mirrors the plugin's own (D13-local) pricing.ts scheme.
+// ─────────────────────────────────────────────────────────────────────────
+
+export type EditPlanMode = "tighten" | "clips" | "chapters"
+export type EditPlanTier = "economy" | "standard" | "premium"
+export const EDIT_PLAN_MODES: readonly EditPlanMode[] = ["tighten", "clips", "chapters"]
+export const EDIT_PLAN_TIERS: readonly EditPlanTier[] = ["economy", "standard", "premium"]
+/** The coarse duration ladder (MINUTES) a probed source duration rounds UP to;
+ *  the composite credit id carries the bucket. 3 modes × 3 tiers × 6 buckets =
+ *  54 composites (+ the bare `edit-plan`). */
+export const EDIT_PLAN_BUCKET_MINUTES: readonly number[] = [15, 30, 60, 90, 120, 180]
+/** Hard duration cap (design §7.4). */
+export const EDIT_PLAN_MAX_MINUTES = 180
+/** `clips` mode: how many clips a plan returns when the caller names no count,
+ *  and the most it may be asked for. One source for the credit estimate, the
+ *  orchestrated payload clamp and the request schema. */
+export const EDIT_PLAN_DEFAULT_CLIP_COUNT = 8
+export const EDIT_PLAN_MAX_CLIP_COUNT = 50
+
+/** Clamp a requested clip count into `[1, EDIT_PLAN_MAX_CLIP_COUNT]`; `undefined`
+ *  for anything that is not a positive number (the planner then uses its default). */
+export function clampEditPlanClipCount(count: unknown): number | undefined {
+  if (typeof count !== "number" || !Number.isFinite(count) || count <= 0) return undefined
+  return Math.min(EDIT_PLAN_MAX_CLIP_COUNT, Math.max(1, Math.floor(count)))
+}
+/** The bare estimator / DB-down fallback id. */
+export const EDIT_PLAN_BASE_CREDIT_ID = "edit-plan"
+
+/** Round a source duration (seconds) UP to the smallest covering ladder bucket
+ *  (capped at the max), in minutes. `undefined` / non-finite → the ceiling
+ *  bucket (the safe over-reserve direction). */
+export function editPlanBucketMinutes(durationSec: number | undefined): number {
+  const secs = typeof durationSec === "number" && Number.isFinite(durationSec) ? durationSec : EDIT_PLAN_MAX_MINUTES * 60
+  const mins = Math.max(1, Math.ceil(secs / 60))
+  const capped = Math.min(mins, EDIT_PLAN_MAX_MINUTES)
+  for (const b of EDIT_PLAN_BUCKET_MINUTES) if (capped <= b) return b
+  return EDIT_PLAN_BUCKET_MINUTES[EDIT_PLAN_BUCKET_MINUTES.length - 1]!
+}
+
+/** `edit-plan:<mode>:<tier>:<bucket>m`. `durationSec` undefined → the ceiling
+ *  bucket. Single source of truth for the composite id shape. */
+export function buildEditPlanCreditId(mode: EditPlanMode, tier: EditPlanTier, durationSec?: number): string {
+  return `edit-plan:${mode}:${tier}:${editPlanBucketMinutes(durationSec)}m`
+}
+
+/** Narrow an arbitrary value to a known edit-plan mode, defaulting to "tighten". */
+export function asEditPlanMode(v: unknown): EditPlanMode {
+  return v === "clips" || v === "chapters" ? v : "tighten"
+}
+
+/** Narrow an arbitrary value to a known edit-plan tier, defaulting to "standard". */
+export function asEditPlanTier(v: unknown): EditPlanTier {
+  return v === "economy" || v === "premium" ? v : "standard"
+}
+
+/**
+ * Unwrap an `edit-plan` job's `output_data` into the value stored on the node's
+ * `data.generatedJson`, which every output extractor then reads. This is the ONE
+ * place the three modes are normalized (the same rule on both engines and every
+ * result-application site, so audit-dag parity can't drift):
+ *   - `clips`    → the BARE `Edl[]` (T5: the `list` fan-out reads `Array.isArray`
+ *                  on `generatedJson`; each element becomes one JSON-stringified
+ *                  item a downstream `edl` input `normalizeEdl`-parses).
+ *   - `chapters` → the `{ version, chapters }` object.
+ *   - `tighten`  → the `Edl` object at top level.
+ *
+ * The cloud relay object-spreads `output_data` and adds `viaNodaroCloud: true`;
+ * that key (and any other bookkeeping) is stripped here. The unwrap lives HERE —
+ * NEVER in `output_data` — because a bare array written into `output_data` would
+ * be corrupted into numeric keys by the relay's object-spread (see `EdlClipSet`).
+ */
+export function unwrapEditPlanOutput(outputData: unknown): unknown {
+  if (!outputData || typeof outputData !== "object") return outputData
+  const o = outputData as Record<string, unknown>
+  // clips: EdlClipSet { version, clips: Edl[] } → the bare Edl[].
+  if (Array.isArray(o.clips)) return o.clips
+  // chapters: { version, chapters: [...] } → the object, minus bookkeeping.
+  if (Array.isArray(o.chapters)) return { version: EDL_VERSION, chapters: o.chapters }
+  // tighten: the Edl object at top level → drop the relay's viaNodaroCloud.
+  const { viaNodaroCloud: _viaNodaroCloud, ...rest } = o
+  return rest
+}

package/src/edl-multicam.ts

@@ -0,0 +1,185 @@
+/**
+ * Multicam helpers over the EDL contract (`edl.ts`): folding measured source
+ * offsets into an EDL (D19) and resolving what each on-screen slot of a
+ * segment shows (D20). Pure — no I/O. Type-only imports from `edl.ts` keep the
+ * module graph free of runtime cycles.
+ */
+import type { Edl, EdlRegion, EdlSegment, EdlSource } from "./edl.js"
+
+// ─────────────────────────────────────────────────────────────────────────
+//  D19 — source offsets
+// ─────────────────────────────────────────────────────────────────────────
+
+const hasOwn = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k)
+const isFiniteNumber = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v)
+
+/** audio-sync → EDL source offsets (D19: masterMs = sourceMs + offsetMs).
+ *  `offsets` are measured against ONE common reference (audio-sync's `reference`, which need not be the master).
+ *  ANCHORED SET: anchor = opts.anchor ?? the unique role:"master-audio" source ?? none.
+ *   - The anchor's own offsetMs is NEVER changed (the segments are on its clock).
+ *   - Every other provided source s: offsetMs = round((anchor.offsetMs ?? 0) + offsets[s] − (offsets[anchor] ?? 0)).
+ *   - No anchor: offsetMs = round(offsets[s]) verbatim (offsets already relative to the master clock).
+ *  SET, never ADD (re-running is idempotent). Returns a new Edl; never mutates; never throws.
+ *  `ignored[].reason` is a documented open string: "unknown-source" | "not-finite" | "anchor-unknown" | "anchor-not-finite".
+ *  opts.anchor not in edl.sources → NOTHING applied, ignored = [{ sourceId: anchor, reason: "anchor-unknown" }].
+ *  offsets[anchor] present but non-finite → NOTHING applied, ignored = [{ sourceId: anchor, reason: "anchor-not-finite" }]. */
+export function mergeEdlSourceOffsets(
+  edl: Edl,
+  offsets: Readonly<Record<string, number>>,
+  opts?: { readonly anchor?: string },
+): {
+  readonly edl: Edl
+  /** The source the offsets were anchored to — present whenever one resolved (it exists in `edl.sources`). */
+  readonly anchor?: string
+  /** Source ids whose `offsetMs` was set, in `offsets` key order. */
+  readonly applied: readonly string[]
+  readonly ignored: ReadonlyArray<{ readonly sourceId: string; readonly reason: string }>
+} {
+  const sources: readonly EdlSource[] = Array.isArray(edl?.sources) ? edl.sources : []
+  const rows: Readonly<Record<string, unknown>> = offsets && typeof offsets === "object" ? offsets : {}
+  const byId = new Map<string, EdlSource>()
+  for (const s of sources) if (s && typeof s === "object" && !byId.has(s.id)) byId.set(s.id, s)
+
+  let anchor: string | undefined
+  if (opts?.anchor !== undefined) {
+    if (!byId.has(opts.anchor)) {
+      return { edl: { ...edl }, applied: [], ignored: [{ sourceId: opts.anchor, reason: "anchor-unknown" }] }
+    }
+    anchor = opts.anchor
+  } else {
+    const masters = sources.filter((s) => s && typeof s === "object" && s.role === "master-audio")
+    if (masters.length === 1) anchor = masters[0].id
+  }
+
+  // The anchor's own measurement is the rebase point; an absent one reads as 0.
+  let reference = 0
+  if (anchor !== undefined && hasOwn(rows, anchor)) {
+    const a = rows[anchor]
+    if (!isFiniteNumber(a)) {
+      return { edl: { ...edl }, anchor, applied: [], ignored: [{ sourceId: anchor, reason: "anchor-not-finite" }] }
+    }
+    reference = a
+  }
+  const anchorOffsetMs = anchor !== undefined ? (byId.get(anchor)?.offsetMs ?? 0) : 0
+
+  const next = new Map<string, number>()
+  const applied: string[] = []
+  const ignored: Array<{ sourceId: string; reason: string }> = []
+  for (const sourceId of Object.keys(rows)) {
+    if (sourceId === anchor) continue // never changed: the segments are on its clock
+    if (!byId.has(sourceId)) {
+      ignored.push({ sourceId, reason: "unknown-source" })
+      continue
+    }
+    const measured = rows[sourceId]
+    const offsetMs = isFiniteNumber(measured)
+      ? Math.round(anchor !== undefined ? anchorOffsetMs + measured - reference : measured)
+      : Number.NaN
+    // A non-finite result (the measurement, or a non-finite anchor offsetMs it
+    // is rebased onto) is never written.
+    if (!Number.isFinite(offsetMs)) {
+      ignored.push({ sourceId, reason: "not-finite" })
+      continue
+    }
+    next.set(sourceId, offsetMs)
+    applied.push(sourceId)
+  }
+
+  const merged: Edl = Array.isArray(edl?.sources)
+    ? { ...edl, sources: edl.sources.map((s) => (s && typeof s === "object" && next.has(s.id) ? { ...s, offsetMs: next.get(s.id)! } : s)) }
+    : { ...edl }
+  return { edl: merged, ...(anchor !== undefined ? { anchor } : {}), applied, ignored }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  D20 — slot resolution
+// ─────────────────────────────────────────────────────────────────────────
+
+export const EDL_FULL_FRAME: EdlRegion = Object.freeze({ x: 0, y: 0, w: 1, h: 1 })
+
+export interface EdlResolvedSlot {
+  readonly source: string
+  readonly region: EdlRegion
+  /** "resolver" = the caller's `regionFor` (v3 per-segment tracks). */
+  readonly regionFrom: "slot" | "segment" | "resolver" | "speaker" | "source" | "full"
+  readonly speaker?: string
+  readonly weight?: number
+}
+
+export interface ResolveEdlSlotsOptions {
+  /** speaker-view's per-speaker framing table (a node SETTING, not an EDL field), keyed by (source, speaker) so a
+   *  wide-shot region never lands on a close-up camera framing the same person. */
+  readonly speakerRegions?: ReadonlyArray<{ readonly source: string; readonly speaker: string; readonly region: EdlRegion }>
+  /** v3 hook: a per-(segment, slot) region, e.g. from a face track. Undefined = no opinion. */
+  readonly regionFor?: (q: { readonly segment: EdlSegment; readonly source: string; readonly speaker?: string }) => EdlRegion | undefined
+}
+
+/** A valid in-frame box: finite, 0..1, w/h > 0, x+w ≤ 1, y+h ≤ 1 — with the
+ *  same edge tolerance `validateEdl` accepts, so the two never disagree. */
+function isInFrameRegion(r: unknown): r is EdlRegion {
+  if (!r || typeof r !== "object") return false
+  const { x, y, w, h } = r as Record<string, unknown>
+  for (const v of [x, y, w, h]) if (!isFiniteNumber(v) || v < 0 || v > 1) return false
+  const box = r as EdlRegion
+  return box.w > 0 && box.h > 0 && box.x + box.w <= 1 + 1e-9 && box.y + box.h <= 1 + 1e-9
+}
+
+type Rung = EdlResolvedSlot["regionFrom"]
+
+/** D20 — the ONE region-precedence implementation:
+ *  slot.region ▷ segment.region (single-slot only) ▷ regionFor ▷ speakerRegions[(source, speaker)] ▷ source.region ▷ full frame.
+ *  Slots = layout.slots when non-empty, else ONE implicit slot from segment.video (no video → []).
+ *  A slot's speaker = slot.speaker ?? (single slot ? segment.speaker : undefined); no speaker → the speaker rung is skipped.
+ *  A rung whose region is not a valid in-frame box (finite, 0..1, w/h > 0, x+w ≤ 1, y+h ≤ 1) falls through to the next.
+ *  Unknown source id → the source rung is skipped. Pure; never throws on its own. */
+export function resolveEdlSegmentSlots(edl: Edl, segment: EdlSegment, opts?: ResolveEdlSlotsOptions): readonly EdlResolvedSlot[] {
+  if (!segment || typeof segment !== "object") return []
+  const sources: readonly EdlSource[] = Array.isArray(edl?.sources) ? edl.sources : []
+  const layoutSlots = Array.isArray(segment.layout?.slots) ? segment.layout!.slots! : []
+  const slots: NonNullable<NonNullable<EdlSegment["layout"]>["slots"]> =
+    layoutSlots.length > 0
+      ? layoutSlots
+      : typeof segment.video === "string" && segment.video
+        ? [{ source: segment.video }]
+        : []
+  const single = slots.length === 1
+
+  const out: EdlResolvedSlot[] = []
+  for (const slot of slots) {
+    if (!slot || typeof slot !== "object") continue
+    const source = slot.source
+    const speaker = slot.speaker ?? (single ? segment.speaker : undefined)
+
+    // Each rung is evaluated lazily, top-down; the first valid box wins.
+    const rungs: ReadonlyArray<readonly [Rung, () => unknown]> = [
+      ["slot", () => slot.region],
+      ["segment", () => (single ? segment.region : undefined)],
+      ["resolver", () => opts?.regionFor?.({ segment, source, ...(speaker !== undefined ? { speaker } : {}) })],
+      ["speaker", () =>
+        speaker === undefined
+          ? undefined
+          : Array.isArray(opts?.speakerRegions)
+            ? opts.speakerRegions.find((row) => row && row.source === source && row.speaker === speaker)?.region
+            : undefined],
+      ["source", () => sources.find((s) => s && typeof s === "object" && s.id === source)?.region],
+    ]
+    let region: EdlRegion = EDL_FULL_FRAME
+    let regionFrom: Rung = "full"
+    for (const [from, read] of rungs) {
+      const candidate = read()
+      if (isInFrameRegion(candidate)) {
+        region = candidate
+        regionFrom = from
+        break
+      }
+    }
+    out.push({
+      source,
+      region,
+      regionFrom,
+      ...(speaker !== undefined ? { speaker } : {}),
+      ...(slot.weight !== undefined ? { weight: slot.weight } : {}),
+    })
+  }
+  return out
+}