@joewinke/jatui 0.10.0 → 0.11.0

package/dist/video/advisors/speaker-rate.js

@@ -0,0 +1,322 @@
+/**
+ * Per-speaker playback rate, measured rather than guessed. Ported verbatim
+ * from extension-library `lib/speaker-rate.js` (mos-5lzns.27).
+ *
+ * The manual version of this feature is a speed slider, and a speed slider is
+ * a chore: you nudge it up for the slow host, forget, and then the guest who
+ * talks at 200 wpm arrives sounding auctioned. The premise here is the one
+ * behind loudness matching, one sense over — the app can MEASURE the thing you
+ * were about to compensate for. Words per minute falls straight out of a
+ * diarised transcript (words in a segment, seconds of that segment, attributed
+ * to whoever was talking), so it can propose the rates that put everyone at one
+ * pace and let you keep or discard them. Nobody has to guess "is 1.2 too much
+ * for this one".
+ *
+ * Pure advisor, deliberately (src/lib/video/README.md doctrine): no DOM, no
+ * <video>, no settings reads, no motion (so nothing here for
+ * prefers-reduced-motion to reduce). It answers "how fast is each person
+ * talking, and what would even them out" and stops there — the component
+ * decides whether to apply any of it, and every function returns a safe
+ * neutral value rather than throwing when the data is missing or malformed,
+ * because half this library's videos have no diarisation at all.
+ *
+ *   speakerPace(transcript, speakers)
+ *     -> { bySpeaker: { name: { wpm, words, seconds } }, medianWpm }
+ *   suggestRates(pace, { targetWpm, min, max, step })  -> { name: rate }
+ *   rateAt(t, turns, rates, fallback)                  -> multiplier at time t
+ *   describeRates(pace, rates)                         -> ["Darren 168 wpm → 0.9x", …]
+ *
+ * Input shapes: segments/turns are the same duration-bearing objects the
+ * component already holds (VideoTranscriptSegment / VideoSpeakerTurn read
+ * structurally — `start`/`end` seconds, `text`, `speaker`/`name`, `ad`), so
+ * meeting and scribe data flows straight through. Field names are read with
+ * the extension's spellings (`start`/`end`/`text`/`speaker`/`name`/`ad`);
+ * mos-5lzns.32's wiring maps the component's `Sec`-suffixed props at the call
+ * site if they ever differ.
+ */
+// Under this many words a WPM is an artefact of segment boundaries rather than
+// a speaking style: "Right." alone on a four-second segment reads as 15 wpm,
+// and a three-word interjection inside someone else's sentence reads as 400.
+// Twenty words is roughly eight seconds of continuous speech — the shortest
+// sample that has ever looked like a pace instead of a coincidence.
+const MIN_WORDS = 20;
+// Within ±7% of target, do nothing at all. 1.05 is audible on music and
+// essentially inaudible on speech, so a rate that close buys nothing — and
+// since turns hand off every few seconds, a hair-trigger would have the pitch
+// stepping on every handoff. A rate that flickers 1.0 → 1.05 → 1.0 is worse
+// than no feature; leaving someone alone is a real answer.
+const DEADZONE = 0.07;
+const DEFAULTS = { min: 0.75, max: 1.5, step: 0.05 };
+// finite-or-null: the single gate every external number passes through, so
+// "0.9", undefined, NaN and {} all collapse to one thing callers can test
+function num(v) {
+    const n = typeof v === "number" ? v : parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+}
+function labelOf(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim();
+    return s || null;
+}
+// Whitespace tokens, and nothing cleverer. Stripping punctuation or filtering
+// "um" would make the number prettier and less true — WPM is only useful here
+// as a RATIO between two speakers counted the same way, and both of them say um.
+function countWords(text) {
+    if (typeof text !== "string")
+        return 0;
+    const s = text.trim();
+    return s ? s.split(/\s+/).length : 0;
+}
+function flattenTurns(turns) {
+    const list = [];
+    for (const t of turns) {
+        if (!t || typeof t !== "object")
+            continue;
+        const start = num(t.start);
+        const end = num(t.end);
+        if (start == null || end == null || end <= start)
+            continue;
+        list.push({
+            start,
+            end,
+            name: t.ad ? null : labelOf(t.name),
+        });
+    }
+    if (!list.length)
+        return [];
+    // hosts promise sorted input; sorting anyway costs O(n log n) once per array
+    // and takes the promise out of the contract, which is cheaper than a support
+    // thread about rates being off by one speaker
+    list.sort((a, b) => a.start - b.start);
+    const cuts = [];
+    for (const t of list)
+        cuts.push(t.start, t.end);
+    cuts.sort((a, b) => a - b);
+    const flat = [];
+    let ti = 0;
+    let open = [];
+    for (let i = 0; i < cuts.length - 1; i++) {
+        const a = cuts[i];
+        const b = cuts[i + 1];
+        if (b <= a)
+            continue; // duplicate boundary — zero-width slice, nothing to own
+        while (ti < list.length && list[ti].start <= a)
+            open.push(list[ti++]);
+        open = open.filter((t) => t.end > a); // bounded by overlap depth, not by n
+        if (!open.length)
+            continue;
+        let win = open[0];
+        for (const t of open)
+            if (t.start >= win.start)
+                win = t;
+        const prev = flat[flat.length - 1];
+        // merge across cut points: the interesting boundaries are handoffs, and a
+        // speaker interrupted-then-resumed should read as one stretch, not three
+        if (prev && prev.name === win.name && prev.end === a)
+            prev.end = b;
+        else
+            flat.push({ start: a, end: b, name: win.name });
+    }
+    return flat;
+}
+// rateAt runs on every timeupdate, so the flatten is memoised against the array
+// identity the host handed us. Fingerprinting length + endpoints catches the
+// realistic staleness (a fresh array from setSpeakers, a re-diarise); an
+// in-place edit that preserves both would go unseen, which is why the host
+// replaces this array rather than mutating it.
+const flatCache = new WeakMap();
+function prepared(turns) {
+    if (!Array.isArray(turns) || !turns.length)
+        return [];
+    const mark = turns.length +
+        ":" +
+        turns[0]?.start +
+        ":" +
+        turns[turns.length - 1]?.end;
+    const hit = flatCache.get(turns);
+    if (hit && hit.mark === mark)
+        return hit.flat;
+    const flat = flattenTurns(turns);
+    flatCache.set(turns, { mark, flat });
+    return flat;
+}
+// last slice starting at or before sec, then a coverage check — [start, end),
+// so a time landing exactly on a handoff belongs to the person taking over
+function segAt(flat, sec) {
+    let lo = 0;
+    let hi = flat.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (flat[mid].start <= sec) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    if (found < 0)
+        return null;
+    const seg = flat[found];
+    return sec < seg.end ? seg : null;
+}
+// Weighted by talk time, not a plain median of the speakers. Two speakers with
+// a plain median land on the midpoint and BOTH get resampled — the worst of the
+// three options, since the voice you hear most is the one you're least likely
+// to want altered. Weighted, the dominant speaker sits at the target and stays
+// at 1x, and the occasional guest is the one who moves. An exact tie splits the
+// difference so a two-hander doesn't arbitrarily crown whoever is slower.
+function weightedMedian(rows) {
+    const list = rows.slice().sort((a, b) => a.wpm - b.wpm);
+    const total = list.reduce((s, r) => s + r.seconds, 0);
+    if (!(total > 0))
+        return 0;
+    const half = total / 2;
+    let acc = 0;
+    for (let i = 0; i < list.length; i++) {
+        acc += list[i].seconds;
+        if (acc > half)
+            return list[i].wpm;
+        if (acc === half) {
+            const next = list[i + 1];
+            return next ? (list[i].wpm + next.wpm) / 2 : list[i].wpm;
+        }
+    }
+    return list[list.length - 1].wpm;
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+export function speakerPace(transcript, speakers) {
+    const empty = { bySpeaker: Object.create(null), medianWpm: 0 };
+    if (!Array.isArray(transcript) || !transcript.length)
+        return empty;
+    const flat = prepared(speakers);
+    const acc = new Map();
+    for (const seg of transcript) {
+        if (!seg || typeof seg !== "object")
+            continue;
+        const start = num(seg.start);
+        const end = num(seg.end);
+        if (start == null || end == null || end <= start)
+            continue;
+        const words = countWords(seg.text);
+        if (!words)
+            continue;
+        // Midpoint, not start: a segment straddling a handoff belongs to whoever
+        // did most of the talking in it, and with no per-word timings the midpoint
+        // is the cheapest honest proxy. Turns win over segment.speaker when both
+        // exist — the diarisation pass that produced the turns is the one that
+        // resolved LABEL → display name and marked the ads.
+        const covering = flat.length ? segAt(flat, (start + end) / 2) : null;
+        // covering with a null name is an ad read: known, and deliberately not a
+        // person. Falling through to seg.speaker here would file the sponsor's
+        // words under the host.
+        const name = covering
+            ? covering.name
+            : labelOf(seg.speaker);
+        if (!name)
+            continue;
+        const row = acc.get(name) || { words: 0, seconds: 0 };
+        row.words += words;
+        row.seconds += end - start;
+        acc.set(name, row);
+    }
+    // null-prototype: a speaker literally named "__proto__" (names are
+    // user-editable — the rename menu accepts anything) would otherwise assign
+    // to the object's prototype slot instead of creating a key, leaving
+    // bySpeaker self-inconsistent: readable by name, invisible to Object.keys
+    // (the empty return above is null-prototype for the same reason — both
+    // Object.create(null) sites are deliberate, not style)
+    const bySpeaker = Object.create(null);
+    const rows = [];
+    for (const [name, row] of acc) {
+        if (row.words < MIN_WORDS || !(row.seconds > 0))
+            continue;
+        const wpm = round1((row.words / row.seconds) * 60);
+        bySpeaker[name] = {
+            wpm,
+            words: row.words,
+            seconds: Math.round(row.seconds * 100) / 100,
+        };
+        rows.push({ wpm, seconds: row.seconds });
+    }
+    return {
+        bySpeaker,
+        medianWpm: rows.length ? round1(weightedMedian(rows)) : 0,
+    };
+}
+export function suggestRates(pace, opts) {
+    const out = {};
+    const by = pace && typeof pace === "object" ? pace.bySpeaker : null;
+    if (!by || typeof by !== "object")
+        return out;
+    const o = opts && typeof opts === "object" ? opts : {};
+    const target = num(o.targetWpm) ?? num(pace.medianWpm);
+    if (!(target !== null && target > 0))
+        return out;
+    const a = num(o.min) ?? DEFAULTS.min;
+    const b = num(o.max) ?? DEFAULTS.max;
+    const lo = Math.min(a, b);
+    const hi = Math.max(a, b); // an inverted range is a typo, not an instruction to return nothing
+    const step = num(o.step) ?? DEFAULTS.step;
+    for (const [name, p] of Object.entries(by)) {
+        const wpm = num(p && p.wpm);
+        if (wpm == null || wpm <= 0)
+            continue;
+        const raw = target / wpm;
+        if (Math.abs(raw - 1) <= DEADZONE && raw >= lo && raw <= hi) {
+            // exactly 1, not 0.9999 — the host compares against 1. Gated on the
+            // range: an unmodified 1 is only the right answer if 1 is a rate the
+            // caller actually allows. With min 1.2 it isn't, and returning it anyway
+            // silently broke the one promise this function makes about its output.
+            out[name] = 1;
+            continue;
+        }
+        // snap first, then clamp: snapping a clamped value can walk it back over
+        // the limit, and the limit is the promise the user actually set
+        const snapped = step > 0 ? Math.round(raw / step) * step : raw;
+        const rate = Math.round(Math.min(hi, Math.max(lo, snapped)) * 1000) / 1000;
+        out[name] = Math.abs(rate - 1) < 1e-9 ? 1 : rate;
+    }
+    return out;
+}
+export function rateAt(t, turns, rates, fallback = 1) {
+    const fb = num(fallback) ?? 1;
+    const sec = num(t);
+    if (sec == null)
+        return fb;
+    const flat = prepared(turns);
+    if (!flat.length)
+        return fb;
+    const seg = segAt(flat, sec);
+    // no turn covering t, or an ad read (name === null): nobody to match, so
+    // normal speed. Silence between turns is the one place a rate change would
+    // be inaudible anyway, and holding the last speaker's rate through it makes
+    // the next handoff land late.
+    if (!seg || !seg.name)
+        return fb;
+    const r = rates && typeof rates === "object"
+        ? num(rates[seg.name])
+        : null;
+    return r != null && r > 0 ? r : fb;
+}
+// Sorted by talk time because that's the order you think about the people in:
+// the host first, the guest who said four sentences last. Someone already on
+// pace still gets a line — seeing that they were measured and left alone is
+// the point, and a list that only shows the changed speakers reads like the
+// others were missed.
+export function describeRates(pace, rates) {
+    const by = pace && typeof pace === "object" ? pace.bySpeaker : null;
+    if (!by || typeof by !== "object")
+        return [];
+    const rows = Object.entries(by).filter(([, p]) => p && num(p.wpm) != null);
+    rows.sort((x, y) => (num(y[1].seconds) ?? 0) - (num(x[1].seconds) ?? 0) ||
+        x[0].localeCompare(y[0]));
+    return rows.map(([name, p]) => {
+        const wpm = Math.round(num(p.wpm));
+        const r = rates && typeof rates === "object" ? num(rates[name]) : null;
+        if (r == null || Math.abs(r - 1) < 1e-9)
+            return `${name} ${wpm} wpm · on pace`;
+        return `${name} ${wpm} wpm → ${+r.toFixed(2)}x`;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -76,7 +76,8 @@
     "check:demos": "node scripts/check-demo-coverage.mjs",
     "guard": "node scripts/check-demo-coverage.mjs",
     "test:dist": "svelte-kit sync && vitest run --config vitest.dist.config.ts",
-    "test:unit": "node --import ./tests/unit/register.mjs --test tests/unit/",
+    "test:unit": "node --import ./tests/unit/register.mjs --test tests/unit/*.test.ts",
+    "test:advisors": "svelte-kit sync && vitest run --config vitest.unit.config.ts",
     "prepublishOnly": "node scripts/guard-ci-publish.mjs && npm run package"
   },
   "peerDependencies": {