@storyteller-platform/align 0.1.56 → 0.1.58

package/dist/align/ctc/search.cjs

@@ -0,0 +1,437 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var search_exports = {};
+__export(search_exports, {
+  computeEvidenceRange: () => computeEvidenceRange,
+  findBoundariesInDocument: () => findBoundariesInDocument,
+  findCtcBoundaries: () => findCtcBoundaries
+});
+module.exports = __toCommonJS(search_exports);
+var import_itertools = require("itertools");
+var import_greedyDecode = require("./greedyDecode.cjs");
+const NGRAM_SIZE = 10;
+const RANSAC_ITERATIONS = 500;
+const MIN_INLIERS = 10;
+const MAX_PAIR_SEPARATION_REQUIREMENT = 200;
+const MIN_CONFIDENCE = 0.5;
+const MIN_COVERAGE = 0.3;
+const REFINE_COUNT = 25;
+const ANCHOR_SPACING = 2e3;
+const BOUNDARY_PAD_FRAMES = 500;
+const EVIDENCE_GAP_MULTIPLIER = 3;
+const EVIDENCE_GAP_FLOOR = 500;
+const EVIDENCE_GAP_PERCENTILE = 0.99;
+const MIN_EDGE_CLUSTER_OFFSETS = 10;
+const EDGE_EXTENSION_MAX_GAP = 1e3;
+const EDGE_EXTENSION_WINDOW = 250;
+const EDGE_EXTENSION_PAIR_SEPARATION = 50;
+const ANCHOR_CONTEXT = 40;
+const ANCHOR_AGREEMENT_FRACTION = 0.4;
+const ANCHOR_AGREEMENT_FLOOR = 0.05;
+const ANCHOR_CALIBRATION_MINIMUM = 5;
+const ngramIndexes = /* @__PURE__ */ new WeakMap();
+const decodedEmissions = /* @__PURE__ */ new WeakMap();
+function median(values) {
+  const sorted = Array.from(values).sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+function getNgramIndex(document) {
+  const cached = ngramIndexes.get(document);
+  if (cached) return cached;
+  const { text, positions } = document;
+  const index = /* @__PURE__ */ new Map();
+  for (const i of (0, import_itertools.range)(text.length - NGRAM_SIZE + 1)) {
+    const ngram = text.slice(i, i + NGRAM_SIZE);
+    const position = positions[i];
+    const entries = index.get(ngram);
+    if (entries) {
+      entries.push(position);
+    } else {
+      index.set(ngram, [position]);
+    }
+  }
+  ngramIndexes.set(document, index);
+  return index;
+}
+function collectMatches(query, document, excludedRanges) {
+  const index = getNgramIndex(document);
+  const queryNgramOffsets = /* @__PURE__ */ new Map();
+  const matches = [];
+  for (const i of (0, import_itertools.range)(query.length - NGRAM_SIZE + 1)) {
+    const queryNgram = query.slice(i, i + NGRAM_SIZE);
+    const offsets = queryNgramOffsets.get(queryNgram);
+    if (offsets) offsets.push(i);
+    else queryNgramOffsets.set(queryNgram, [i]);
+    const positions = index.get(queryNgram);
+    if (!positions) continue;
+    for (const position of positions) {
+      if (excludedRanges.some(
+        ([start, end]) => start <= position && position < end
+      )) {
+        continue;
+      }
+      matches.push({ offset: i, position });
+    }
+  }
+  return { matches, queryNgramOffsets };
+}
+function fitLine(matches, pairSeparation, { minSlope, maxSlope, inlierTolerance }) {
+  let seed = 625341585;
+  const random = () => {
+    seed = Math.imul(seed, 1103515245) + 12345 & 2147483647;
+    return seed / 2147483648;
+  };
+  let best = null;
+  for (let i = 0; i < RANSAC_ITERATIONS; i++) {
+    const a = matches[Math.floor(random() * matches.length)];
+    const b = matches[Math.floor(random() * matches.length)];
+    if (Math.abs(b.offset - a.offset) < pairSeparation) continue;
+    const slope2 = (b.position - a.position) / (b.offset - a.offset);
+    if (slope2 < minSlope || slope2 > maxSlope) continue;
+    const intercept2 = a.position - slope2 * a.offset;
+    let count = 0;
+    for (const m of matches) {
+      const predicted = intercept2 + slope2 * m.offset;
+      if (Math.abs(m.position - predicted) <= inlierTolerance) count++;
+    }
+    if (!best || count > best.count) {
+      best = { slope: slope2, intercept: intercept2, count };
+    }
+  }
+  if (!best || best.count < MIN_INLIERS) return null;
+  const inliers = matches.filter((m) => {
+    const predicted = best.intercept + best.slope * m.offset;
+    return Math.abs(m.position - predicted) <= inlierTolerance;
+  });
+  const sorted = inliers.sort((a, b) => a.offset - b.offset);
+  const stride = Math.max(Math.floor(sorted.length / 2), 1);
+  const slopes = [];
+  for (let i = 0; i + stride < sorted.length; i++) {
+    const lo = sorted[i];
+    const hi = sorted[i + stride];
+    if (hi.offset - lo.offset < pairSeparation) continue;
+    slopes.push((hi.position - lo.position) / (hi.offset - lo.offset));
+  }
+  const slope = slopes.length ? median(slopes) : best.slope;
+  const intercept = sorted.length ? median(sorted.map((m) => m.position - slope * m.offset)) : best.intercept;
+  return {
+    slope,
+    intercept,
+    inliers
+  };
+}
+function bigramSimilarity(a, b) {
+  if (a.length < 2 || b.length < 2) return 0;
+  const bigrams = /* @__PURE__ */ new Map();
+  for (const i of (0, import_itertools.range)(a.length - 1)) {
+    const bigram = a.slice(i, i + 2);
+    bigrams.set(bigram, (bigrams.get(bigram) ?? 0) + 1);
+  }
+  let shared = 0;
+  for (const i of (0, import_itertools.range)(b.length - 1)) {
+    const bigram = b.slice(i, i + 2);
+    const remaining = bigrams.get(bigram) ?? 0;
+    if (remaining > 0) {
+      shared++;
+      bigrams.set(bigram, remaining - 1);
+    }
+  }
+  return shared / Math.max(a.length - 1, b.length - 1);
+}
+function positionToDocumentIndex(document, position) {
+  const { positions } = document;
+  let low = 0;
+  let high = positions.length - 1;
+  while (low < high) {
+    const mid = low + high >> 1;
+    if (positions[mid] < position) low = mid + 1;
+    else high = mid;
+  }
+  return low;
+}
+function contextAgreement(match, query, document) {
+  const index = positionToDocumentIndex(document, match.position);
+  const queryLeft = query.slice(
+    Math.max(0, match.offset - ANCHOR_CONTEXT),
+    match.offset
+  );
+  const documentLeft = document.text.slice(
+    Math.max(0, index - ANCHOR_CONTEXT),
+    index
+  );
+  const queryRight = query.slice(
+    match.offset + NGRAM_SIZE,
+    match.offset + NGRAM_SIZE + ANCHOR_CONTEXT
+  );
+  const documentRight = document.text.slice(
+    index + NGRAM_SIZE,
+    index + NGRAM_SIZE + ANCHOR_CONTEXT
+  );
+  return Math.max(
+    bigramSimilarity(queryLeft, documentLeft),
+    bigramSimilarity(queryRight, documentRight)
+  );
+}
+function selectAnchors(query, inliers, queryNgramOffsets, document, slope, intercept) {
+  const documentNgramIndex = getNgramIndex(document);
+  const agreements = /* @__PURE__ */ new Map();
+  const agreement = (match) => {
+    let score = agreements.get(match);
+    if (score === void 0) {
+      score = contextAgreement(match, query, document);
+      agreements.set(match, score);
+    }
+    return score;
+  };
+  const select = (minAgreement) => {
+    const anchors2 = [];
+    for (let i = 0; i < query.length; i += ANCHOR_SPACING) {
+      const windowStart = Math.max(0, i - ANCHOR_SPACING / 2);
+      const windowEnd = Math.min(query.length, i + ANCHOR_SPACING / 2);
+      const candidates = inliers.filter(({ offset }) => windowStart <= offset && offset < windowEnd).sort(
+        ({ offset: a }, { offset: b }) => Math.abs(a - i) - Math.abs(b - i)
+      );
+      for (const c of candidates) {
+        const gram = query.slice(c.offset, c.offset + NGRAM_SIZE);
+        if (documentNgramIndex.get(gram)?.length !== 1) {
+          continue;
+        }
+        if (queryNgramOffsets.get(gram)?.length !== 1) {
+          continue;
+        }
+        if (minAgreement !== null && agreement(c) < minAgreement) {
+          continue;
+        }
+        anchors2.push(c);
+        break;
+      }
+    }
+    return anchors2;
+  };
+  let anchors = select(null);
+  if (anchors.length >= ANCHOR_CALIBRATION_MINIMUM) {
+    const threshold = Math.max(
+      ANCHOR_AGREEMENT_FRACTION * median(anchors.map(agreement)),
+      ANCHOR_AGREEMENT_FLOOR
+    );
+    anchors = select(threshold);
+  }
+  const monotonicAnchors = [];
+  for (const a of anchors) {
+    while (true) {
+      const b = monotonicAnchors.at(-1);
+      if (!b || a.position - b.position >= a.offset - b.offset) {
+        monotonicAnchors.push(a);
+        break;
+      }
+      const aDist = Math.abs(a.position - (intercept + slope * a.offset));
+      const bDist = Math.abs(b.position - (intercept + slope * b.offset));
+      if (aDist > bDist) break;
+      else monotonicAnchors.pop();
+    }
+  }
+  return monotonicAnchors;
+}
+function fitLocalLine(points, fallbackSlope) {
+  const stride = Math.max(Math.floor(points.length / 2), 1);
+  const slopes = [];
+  for (const i of (0, import_itertools.range)(0, points.length - stride, stride)) {
+    const lo = points[i];
+    const hi = points[i + stride];
+    if (hi.offset - lo.offset < EDGE_EXTENSION_PAIR_SEPARATION) continue;
+    slopes.push((hi.position - lo.position) / (hi.offset - lo.offset));
+  }
+  const slope = slopes.length ? median(slopes) : fallbackSlope;
+  const intercept = median(points.map((m) => m.position - slope * m.offset));
+  return { slope, intercept };
+}
+function extendEdge(sortedMatches, sortedInliers, globalSlope, inlierTolerance) {
+  const lastInlier = sortedInliers.at(-1);
+  if (!lastInlier) return [];
+  const window = sortedInliers.slice(-EDGE_EXTENSION_WINDOW);
+  const accepted = [];
+  let lastAcceptedOffset = lastInlier.offset;
+  let local = fitLocalLine(window, globalSlope);
+  for (const match of sortedMatches) {
+    if (match.offset <= lastInlier.offset) continue;
+    if (match.offset - lastAcceptedOffset > EDGE_EXTENSION_MAX_GAP) break;
+    const predicted = local.intercept + local.slope * match.offset;
+    if (Math.abs(match.position - predicted) > inlierTolerance) continue;
+    accepted.push(match);
+    window.push(match);
+    if (window.length > EDGE_EXTENSION_WINDOW) window.shift();
+    lastAcceptedOffset = match.offset;
+    local = fitLocalLine(window, globalSlope);
+  }
+  return accepted;
+}
+function extendInlierEdges(matches, sortedInliers, slope, inlierTolerance) {
+  const byOffset = matches.toSorted((a, b) => a.offset - b.offset);
+  const tail = extendEdge(byOffset, sortedInliers, slope, inlierTolerance);
+  function mirror(m) {
+    return { offset: -m.offset, position: -m.position };
+  }
+  const head = extendEdge(
+    byOffset.map(mirror).reverse(),
+    sortedInliers.map(mirror).reverse(),
+    slope,
+    inlierTolerance
+  ).map(mirror).reverse();
+  return [...head, ...sortedInliers, ...tail];
+}
+function computeEvidenceRange(offsets, queryLength) {
+  if (offsets.length < 2) {
+    return { evidenceRange: [0, queryLength], matchedRange: [0, queryLength] };
+  }
+  const gaps = [];
+  for (let i = 1; i < offsets.length; i++) {
+    gaps.push(offsets[i] - offsets[i - 1]);
+  }
+  const sortedGaps = gaps.toSorted((a, b) => a - b);
+  const p99 = sortedGaps[Math.min(
+    sortedGaps.length - 1,
+    Math.floor(sortedGaps.length * EVIDENCE_GAP_PERCENTILE)
+  )];
+  const threshold = Math.max(EVIDENCE_GAP_MULTIPLIER * p99, EVIDENCE_GAP_FLOOR);
+  const clusters = [];
+  let clusterStart = 0;
+  for (const [i, gap] of (0, import_itertools.enumerate)(gaps, 1)) {
+    if (gap <= threshold) continue;
+    clusters.push([clusterStart, i - 1]);
+    clusterStart = i;
+  }
+  clusters.push([clusterStart, offsets.length - 1]);
+  let firstCluster = 0;
+  let lastCluster = clusters.length - 1;
+  while (firstCluster < lastCluster && clusters[firstCluster][1] - clusters[firstCluster][0] + 1 < MIN_EDGE_CLUSTER_OFFSETS) {
+    firstCluster++;
+  }
+  while (lastCluster > firstCluster && clusters[lastCluster][1] - clusters[lastCluster][0] + 1 < MIN_EDGE_CLUSTER_OFFSETS) {
+    lastCluster--;
+  }
+  const first = offsets[clusters[firstCluster][0]];
+  const last = offsets[clusters[lastCluster][1]] + NGRAM_SIZE;
+  return {
+    matchedRange: [first, last],
+    evidenceRange: [
+      first > threshold ? first - threshold : 0,
+      queryLength - last > threshold ? last + threshold : queryLength
+    ]
+  };
+}
+function findBoundariesInDocument(query, document, options) {
+  const gramCount = Math.max(query.length - NGRAM_SIZE + 1, 0);
+  const pairSeparation = Math.min(
+    Math.max(Math.floor(gramCount / 4), 20),
+    MAX_PAIR_SEPARATION_REQUIREMENT
+  );
+  const { matches, queryNgramOffsets } = collectMatches(
+    query,
+    document,
+    options.excludedRanges
+  );
+  if (matches.length < MIN_INLIERS) return null;
+  const line = fitLine(matches, pairSeparation, options);
+  if (!line) return null;
+  const { slope, intercept, inliers } = line;
+  const byOffset = extendInlierEdges(
+    matches,
+    inliers.sort((a, b) => a.offset - b.offset),
+    slope,
+    options.inlierTolerance
+  );
+  const inlierOffsets = Array.from(
+    new Set(byOffset.map(({ offset }) => offset))
+  );
+  const { evidenceRange, matchedRange } = computeEvidenceRange(
+    inlierOffsets,
+    query.length
+  );
+  const head = byOffset.slice(0, REFINE_COUNT);
+  const tail = byOffset.slice(-REFINE_COUNT);
+  const extrapolatedStart = Math.min(
+    ...head.map((m) => m.position - slope * m.offset)
+  );
+  const extrapolatedEnd = Math.max(
+    ...tail.map((m) => m.position + slope * (query.length - m.offset))
+  );
+  const startPad = Math.max(
+    BOUNDARY_PAD_FRAMES,
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    0.25 * (head[0].position - extrapolatedStart)
+  );
+  const start = extrapolatedStart - startPad;
+  const endPad = Math.max(
+    BOUNDARY_PAD_FRAMES,
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    0.25 * (extrapolatedEnd - tail.at(-1).position)
+  );
+  const end = extrapolatedEnd + endPad;
+  if (end <= start) return null;
+  const matchedGrams = new Set(matches.map((m) => m.offset)).size;
+  const inlierGrams = inlierOffsets.length;
+  const confidence = inlierGrams / matchedGrams;
+  if (confidence < MIN_CONFIDENCE) return null;
+  const first = byOffset[0];
+  const last = byOffset[byOffset.length - 1];
+  const coverage = (last.offset - first.offset + NGRAM_SIZE) / query.length;
+  if (coverage < MIN_COVERAGE) return null;
+  const anchors = selectAnchors(
+    query,
+    inliers,
+    queryNgramOffsets,
+    document,
+    slope,
+    intercept
+  );
+  return {
+    start: Math.round(start),
+    end: Math.round(end),
+    confidence,
+    anchors,
+    evidenceRange,
+    matchedRange
+  };
+}
+async function findCtcBoundaries(query, emissionsReader, excludedRanges) {
+  let document = decodedEmissions.get(emissionsReader);
+  if (!document) {
+    const { text, frames } = await (0, import_greedyDecode.ctcGreedyDecode)(emissionsReader);
+    document = { text, positions: frames };
+    decodedEmissions.set(emissionsReader, document);
+  }
+  const result = findBoundariesInDocument(query, document, {
+    excludedRanges,
+    minSlope: 2,
+    maxSlope: 15,
+    inlierTolerance: 2500
+  });
+  if (!result) return null;
+  return {
+    ...result,
+    start: Math.max(result.start, 0),
+    end: Math.min(result.end, emissionsReader.numFrames - 1)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  computeEvidenceRange,
+  findBoundariesInDocument,
+  findCtcBoundaries
+});

package/dist/align/ctc/search.d.cts

@@ -0,0 +1,46 @@
+import { EmissionsReader } from '../../emit/fs.cjs';
+import '@storyteller-platform/ghost-story';
+import './emissions.cjs';
+
+/**
+ * A searchable document. `text` holds the matchable characters, and
+ * `positions[i]` is the position of `text[i]` in whatever units the caller
+ * wants boundaries expressed in — emission frames for CTC decodings,
+ * original character offsets for transcription text, etc.
+ */
+type PositionedDocument = {
+    text: string;
+    positions: number[];
+};
+interface BoundaryFitOptions {
+    minSlope: number;
+    maxSlope: number;
+    inlierTolerance: number;
+    excludedRanges: [number, number][];
+}
+type Match = {
+    offset: number;
+    position: number;
+};
+declare function computeEvidenceRange(offsets: number[], queryLength: number): {
+    evidenceRange: [number, number];
+    matchedRange: [number, number];
+};
+declare function findBoundariesInDocument(query: string, document: PositionedDocument, options: BoundaryFitOptions): {
+    start: number;
+    end: number;
+    confidence: number;
+    anchors: Match[];
+    evidenceRange: [number, number];
+    matchedRange: [number, number];
+} | null;
+declare function findCtcBoundaries(query: string, emissionsReader: EmissionsReader, excludedRanges: [number, number][]): Promise<{
+    start: number;
+    end: number;
+    confidence: number;
+    anchors: Match[];
+    evidenceRange: [number, number];
+    matchedRange: [number, number];
+} | null>;
+
+export { type BoundaryFitOptions, type Match, type PositionedDocument, computeEvidenceRange, findBoundariesInDocument, findCtcBoundaries };

package/dist/align/ctc/search.d.ts

@@ -0,0 +1,46 @@
+import { EmissionsReader } from '../../emit/fs.js';
+import '@storyteller-platform/ghost-story';
+import './emissions.js';
+
+/**
+ * A searchable document. `text` holds the matchable characters, and
+ * `positions[i]` is the position of `text[i]` in whatever units the caller
+ * wants boundaries expressed in — emission frames for CTC decodings,
+ * original character offsets for transcription text, etc.
+ */
+type PositionedDocument = {
+    text: string;
+    positions: number[];
+};
+interface BoundaryFitOptions {
+    minSlope: number;
+    maxSlope: number;
+    inlierTolerance: number;
+    excludedRanges: [number, number][];
+}
+type Match = {
+    offset: number;
+    position: number;
+};
+declare function computeEvidenceRange(offsets: number[], queryLength: number): {
+    evidenceRange: [number, number];
+    matchedRange: [number, number];
+};
+declare function findBoundariesInDocument(query: string, document: PositionedDocument, options: BoundaryFitOptions): {
+    start: number;
+    end: number;
+    confidence: number;
+    anchors: Match[];
+    evidenceRange: [number, number];
+    matchedRange: [number, number];
+} | null;
+declare function findCtcBoundaries(query: string, emissionsReader: EmissionsReader, excludedRanges: [number, number][]): Promise<{
+    start: number;
+    end: number;
+    confidence: number;
+    anchors: Match[];
+    evidenceRange: [number, number];
+    matchedRange: [number, number];
+} | null>;
+
+export { type BoundaryFitOptions, type Match, type PositionedDocument, computeEvidenceRange, findBoundariesInDocument, findCtcBoundaries };