@joewinke/jatui 0.10.0 → 0.12.0

package/dist/video/advisors/smart-speed.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Silence-aware playback speed. Overcast's trick, done off the waveform we
+ * already have. Ported verbatim from extension-library `lib/smart-speed.js`
+ * (mos-5lzns.27) — behaviour identical, including the tuned constants; see
+ * VIDEO-PLAYER-GAP-AUDIT.md ("lift the CONSTANTS AND THE REASONS").
+ *
+ * The problem with a flat 1.5x is that it charges the same tax on everything:
+ * the pauses AND the words. Speech is barely compressible before it turns to
+ * chipmunk, but the gaps between sentences are pure dead time — a lecture is
+ * routinely 15-20% silence, and NONE of that silence carries meaning. So spend
+ * the speed where the meaning isn't: hold 1x through dense speech, and run the
+ * gaps at 2.2x where nobody can hear the difference because there is nothing
+ * to hear.
+ *
+ * Why the waveform and not the transcript: the envelope is already computed for
+ * every video (~600 bins, drawn on the band), it exists before diarization
+ * finishes, and it's honest about pauses WITHIN a transcript segment — segment
+ * boundaries are where the ASR chose to break, not where the speaker actually
+ * stopped. Rejected: analysing the audio live through an AnalyserNode. That
+ * only ever knows the present, so it reacts a beat after each gap opens and a
+ * beat after it closes — exactly the two moments that must be precise.
+ *
+ * This module is a pure ADVISOR (src/lib/video/README.md doctrine). It never
+ * touches a video element and never sets playbackRate; it hands back a
+ * multiplier and the component decides what to do with it (multiplied against
+ * the user's base rate and any per-speaker rate, via the rate composer in
+ * `../rate` — mos-5lzns.32 owns that wiring). Keeping it dumb is what makes it
+ * testable under node with no DOM at all.
+ *
+ * buildSilenceMap(wave, opts) -> { ranges: [[start,end],...], covered, duration }
+ * boostAt(t, map, opts)       -> multiplier (1 outside gaps, boost inside)
+ * estimateSaving(map, opts)   -> seconds saved, for UI copy
+ *
+ * prefers-reduced-motion is deliberately NOT consulted here, and that is a
+ * decision rather than an oversight: reduced motion is about things moving in
+ * the viewport, and rate is neither motion nor decoration — muting it would
+ * silently disable an accessibility-adjacent feature (getting through material
+ * faster) for people who asked for calmer animation. The host owns any visual
+ * indicator of the rate change, and that indicator is where the media query
+ * belongs.
+ */
+/** The waveform envelope the component already holds (`VideoWaveform`). */
+export interface SilenceWave {
+    /** Seconds the peaks span. */
+    duration?: number | null;
+    /** Peak per bin, on any scale — normalised against their own max. */
+    peaks?: ArrayLike<number> | null;
+}
+/** A qualified, padded silent run: `[startSec, endSec)`. */
+export type SilenceRange = [number, number];
+export interface SilenceMap {
+    ranges: SilenceRange[];
+    /** Total seconds inside ranges — the naive figure, before lead-trimming. */
+    covered: number;
+    duration: number;
+}
+export interface SilenceOpts {
+    floor?: number;
+    minGap?: number;
+    mergeGap?: number;
+    pad?: number;
+}
+export interface BoostOpts {
+    boost?: number;
+    lead?: number;
+}
+/**
+ * wave = { duration: seconds, peaks: [0..99] }  (~600 bins, evenly spaced)
+ * opts = { floor, minGap, mergeGap, pad }
+ */
+export declare function buildSilenceMap(wave: SilenceWave | null | undefined, opts?: SilenceOpts | null): SilenceMap;
+/**
+ * Multiplier at time t: 1 outside the gaps, `boost` inside.
+ * opts = { boost, lead }
+ */
+export declare function boostAt(t: unknown, map: unknown, opts?: BoostOpts | null): number;
+/**
+ * Seconds saved across the whole track at this boost — for UI copy
+ * ("about 6 minutes shorter"), not for scheduling.
+ * opts = { boost, lead }
+ */
+export declare function estimateSaving(map: unknown, opts?: BoostOpts | null): number;

package/dist/video/advisors/smart-speed.js

@@ -0,0 +1,314 @@
+/**
+ * Silence-aware playback speed. Overcast's trick, done off the waveform we
+ * already have. Ported verbatim from extension-library `lib/smart-speed.js`
+ * (mos-5lzns.27) — behaviour identical, including the tuned constants; see
+ * VIDEO-PLAYER-GAP-AUDIT.md ("lift the CONSTANTS AND THE REASONS").
+ *
+ * The problem with a flat 1.5x is that it charges the same tax on everything:
+ * the pauses AND the words. Speech is barely compressible before it turns to
+ * chipmunk, but the gaps between sentences are pure dead time — a lecture is
+ * routinely 15-20% silence, and NONE of that silence carries meaning. So spend
+ * the speed where the meaning isn't: hold 1x through dense speech, and run the
+ * gaps at 2.2x where nobody can hear the difference because there is nothing
+ * to hear.
+ *
+ * Why the waveform and not the transcript: the envelope is already computed for
+ * every video (~600 bins, drawn on the band), it exists before diarization
+ * finishes, and it's honest about pauses WITHIN a transcript segment — segment
+ * boundaries are where the ASR chose to break, not where the speaker actually
+ * stopped. Rejected: analysing the audio live through an AnalyserNode. That
+ * only ever knows the present, so it reacts a beat after each gap opens and a
+ * beat after it closes — exactly the two moments that must be precise.
+ *
+ * This module is a pure ADVISOR (src/lib/video/README.md doctrine). It never
+ * touches a video element and never sets playbackRate; it hands back a
+ * multiplier and the component decides what to do with it (multiplied against
+ * the user's base rate and any per-speaker rate, via the rate composer in
+ * `../rate` — mos-5lzns.32 owns that wiring). Keeping it dumb is what makes it
+ * testable under node with no DOM at all.
+ *
+ * buildSilenceMap(wave, opts) -> { ranges: [[start,end],...], covered, duration }
+ * boostAt(t, map, opts)       -> multiplier (1 outside gaps, boost inside)
+ * estimateSaving(map, opts)   -> seconds saved, for UI copy
+ *
+ * prefers-reduced-motion is deliberately NOT consulted here, and that is a
+ * decision rather than an oversight: reduced motion is about things moving in
+ * the viewport, and rate is neither motion nor decoration — muting it would
+ * silently disable an accessibility-adjacent feature (getting through material
+ * faster) for people who asked for calmer animation. The host owns any visual
+ * indicator of the rate change, and that indicator is where the media query
+ * belongs.
+ */
+const DEFAULTS = {
+    floor: 0.12, // share of the track's OWN peak that still counts as silence
+    // minGap and mergeGap used to be the same number doing two jobs: minGap also
+    // stood in for "how close together do two gaps have to be before they're
+    // treated as one". That meant turning minGap UP — read by anyone as "be more
+    // conservative, speed through fewer gaps" — silently ALSO merged more
+    // aggressively across the loud material between gaps, the opposite of
+    // conservative. Split into two knobs that each move behaviour in the
+    // direction their name promises:
+    minGap: 0.35, // a run shorter than this is natural pacing, not dead air worth speeding through
+    // mergeGap has no default of its OWN — buildSilenceMap defaults it to minGap
+    // when the caller doesn't pass one, so `buildSilenceMap(wave, {})` (the only
+    // way the host calls this) behaves exactly as it always has.
+    pad: 0.08, // trimmed off both ends so an onset is never clipped
+    boost: 2.2,
+    lead: 0.15, // boost starts late / ends early by this much
+};
+// Anything unparseable becomes the fallback rather than propagating NaN through
+// arithmetic — a NaN duration silently produces a map full of NaN ranges, and
+// NaN comparisons are all false, so the bug shows up as "smart speed just does
+// nothing" three files away instead of here.
+function num(v, fallback) {
+    const n = typeof v === "number" ? v : parseFloat(v);
+    return Number.isFinite(n) ? n : fallback;
+}
+function clamp(v, lo, hi) {
+    return v < lo ? lo : v > hi ? hi : v;
+}
+// Accept anything peaks[i]-indexable with a numeric length: a plain Array, but
+// also Float32Array/Uint8Array — the waveform pipeline hands back typed arrays
+// as often as plain ones, and Array.isArray(typedArray) is false, so that check
+// used to reject perfectly good data and fall through to the neutral map with
+// no error and no hint why. Strings are explicitly excluded even though they
+// have a numeric .length and are index-accessible — a string isn't a sequence
+// of numbers, it's text that happens to overlap the shape, and letting it
+// through would mean silently treating every character code as a peak.
+function indexable(v) {
+    // Number.isSafeInteger, not just "is a number": a crafted {length: Infinity}
+    // satisfies every other check here and then hangs the bin loop forever. A
+    // waveform arrives as parsed JSON from a sidecar on disk, so this is defence
+    // against a corrupted file rather than an attacker — but a hang is the one
+    // failure mode this module must never have, since it runs on the UI thread.
+    return (v != null &&
+        typeof v !== "string" &&
+        Number.isSafeInteger(v.length) &&
+        v.length >= 0);
+}
+// ── the map ─────────────────────────────────────────────────────────────────
+/**
+ * wave = { duration: seconds, peaks: [0..99] }  (~600 bins, evenly spaced)
+ * opts = { floor, minGap, mergeGap, pad }
+ */
+export function buildSilenceMap(wave, opts) {
+    const duration = num(wave && wave.duration, 0);
+    const peaks = wave && indexable(wave.peaks) ? wave.peaks : null;
+    // A map with no ranges is a perfectly valid answer — it means "advise 1x
+    // everywhere", which is what every guard below wants to say.
+    const none = {
+        ranges: [],
+        covered: 0,
+        duration: duration > 0 ? duration : 0,
+    };
+    if (!(duration > 0) || !peaks || peaks.length === 0)
+        return none;
+    const floor = clamp(num(opts && opts.floor, DEFAULTS.floor), 0, 1);
+    const minGap = Math.max(0, num(opts && opts.minGap, DEFAULTS.minGap));
+    // mergeGap falls back to minGap, not to DEFAULTS.minGap — so a caller who
+    // customizes minGap and never mentions mergeGap still gets the pre-split
+    // behaviour (one number governing both jobs) rather than a mix of their
+    // minGap and a hardcoded merge distance.
+    const mergeGap = Math.max(0, num(opts && opts.mergeGap, minGap));
+    const pad = Math.max(0, num(opts && opts.pad, DEFAULTS.pad));
+    // Normalize against the track's own maximum, never against the nominal 0..99
+    // scale. A quietly-recorded lecture that peaks at 22 has silence somewhere
+    // around 3, and an absolute 0.12*99 threshold would declare the entire video
+    // silent — the failure mode is speeding through the whole thing at 2.2x,
+    // which is precisely the chipmunk outcome this feature exists to avoid.
+    let max = 0;
+    for (let i = 0; i < peaks.length; i++) {
+        const v = num(peaks[i], NaN);
+        if (Number.isFinite(v) && v > max)
+            max = v;
+    }
+    // No signal at all (all zeros, all garbage): there is nothing to be confident
+    // about, so claim nothing.
+    if (!(max > 0))
+        return { ranges: [], covered: 0, duration };
+    const level = max * floor;
+    const bin = duration / peaks.length;
+    // Pass 1 — raw silent runs, in bin units promoted to seconds. A non-finite
+    // bin counts as LOUD: unreadable data is not evidence of silence, and the
+    // asymmetry matters (a missed gap costs a little time, a wrong gap eats a
+    // word).
+    const runs = [];
+    let open = -1;
+    for (let i = 0; i < peaks.length; i++) {
+        const v = num(peaks[i], NaN);
+        const silent = Number.isFinite(v) && v <= level;
+        if (silent) {
+            if (open < 0)
+                open = i;
+        }
+        else if (open >= 0) {
+            runs.push([open * bin, i * bin]);
+            open = -1;
+        }
+    }
+    if (open >= 0)
+        runs.push([open * bin, peaks.length * bin]);
+    // Pass 2 — coalesce. Two gaps separated by less than mergeGap of speech are
+    // one gap with a blip in it (a breath, a click, a single loud bin of room
+    // tone); treating them separately means the rate drops back to 1x for a
+    // fifth of a second and immediately climbs again, which is audible as a
+    // wobble even though each individual decision was defensible. Deliberately
+    // NOT minGap here (see DEFAULTS) — merging and qualifying are different
+    // questions and default to the same number only because that's today's
+    // behaviour, not because they're actually the same idea.
+    const merged = [];
+    for (const r of runs) {
+        const last = merged[merged.length - 1];
+        if (last && r[0] - last[1] < mergeGap)
+            last[1] = r[1];
+        else
+            merged.push([r[0], r[1]]);
+    }
+    // Pass 3 — qualify by length, THEN pad. Order matters: minGap is a statement
+    // about the pause itself ("is this dead air or is it just how people talk"),
+    // so it has to be judged on the real gap, before pad shaves it. Judging after
+    // padding would silently require minGap + 2*pad of silence and make the two
+    // knobs interfere.
+    const ranges = [];
+    let covered = 0;
+    for (const [a, b] of merged) {
+        if (b - a < minGap)
+            continue;
+        const start = clamp(a + pad, 0, duration);
+        const end = clamp(b - pad, 0, duration);
+        if (end - start <= 0)
+            continue; // padded out of existence
+        ranges.push([start, end]);
+        covered += end - start;
+    }
+    return { ranges, covered, duration };
+}
+// ── lookup ──────────────────────────────────────────────────────────────────
+// boostAt runs on every timeupdate (~4/s per video, and the theater can have a
+// preview element too), so it binary-searches. It also has to survive a map it
+// didn't build — an older cached map, something round-tripped through JSON,
+// ranges a caller assembled by hand — hence one normalize-and-sort pass whose
+// result is cached against the map object. Cost is O(n) once, O(log n) forever
+// after, which is the only way to be both defensive AND cheap in a hot path.
+//
+// Cache key is the map object; the guard is the ranges array's IDENTITY, so a
+// rebuilt map invalidates itself for free. The one thing that fools it is
+// mutating an existing ranges array in place — don't; assign a new one, which
+// is what buildSilenceMap returns anyway.
+const normalized = new WeakMap();
+function rangesOf(map) {
+    if (!map || typeof map !== "object")
+        return null;
+    const raw = map.ranges;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const hit = normalized.get(map);
+    if (hit && hit.src === raw)
+        return hit.out;
+    const clean = [];
+    for (const r of raw) {
+        if (!Array.isArray(r) || r.length < 2)
+            continue;
+        const a = num(r[0], NaN);
+        const b = num(r[1], NaN);
+        if (!Number.isFinite(a) || !Number.isFinite(b) || b <= a)
+            continue;
+        clean.push([a, b]);
+    }
+    clean.sort((x, y) => x[0] - y[0]);
+    // Coalesce overlaps so the array is strictly disjoint and ascending. That is
+    // what makes "rightmost range whose start <= t" a correct containment test
+    // rather than an approximation — with overlaps, a later-starting shorter
+    // range can shadow the one actually containing t.
+    const out = [];
+    for (const r of clean) {
+        const last = out[out.length - 1];
+        if (last && r[0] <= last[1]) {
+            if (r[1] > last[1])
+                last[1] = r[1];
+        }
+        else
+            out.push(r);
+    }
+    // Cache the SAME value we're about to return, not the raw (possibly empty)
+    // `out` array. Caching `out` unconditionally used to mean an all-invalid map
+    // returned null on the first call (out.length is 0) but a truthy empty array
+    // on every call after, from the cache — harmless in practice (boostAt's
+    // binary search over a zero-length array also lands on "no match"), but it's
+    // one value on the first call and a different one on the second for no
+    // reason, which is exactly the kind of thing that stops being harmless the
+    // next time someone adds a `if (!ranges)` check downstream.
+    const result = out.length ? out : null;
+    try {
+        normalized.set(map, { src: raw, out: result });
+    }
+    catch {
+        // a frozen host object can't carry the cache — every call re-normalizes,
+        // which is correct, only slower
+    }
+    return result;
+}
+/**
+ * Multiplier at time t: 1 outside the gaps, `boost` inside.
+ * opts = { boost, lead }
+ */
+export function boostAt(t, map, opts) {
+    const time = num(t, NaN);
+    if (!Number.isFinite(time))
+        return 1;
+    const boost = Math.max(1, num(opts && opts.boost, DEFAULTS.boost));
+    if (boost === 1)
+        return 1;
+    const lead = Math.max(0, num(opts && opts.lead, DEFAULTS.lead));
+    const ranges = rangesOf(map);
+    if (!ranges)
+        return 1;
+    let lo = 0;
+    let hi = ranges.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (ranges[mid][0] <= time) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    if (found < 0)
+        return 1;
+    // lead applied symmetrically: come up to speed only after the speaker has
+    // definitely stopped, and be back at 1x before they start again. The end is
+    // the side that actually matters — arriving at a word already doing 2.2x
+    // clips its onset, and a clipped consonant is the single most noticeable
+    // artifact this whole feature can produce.
+    const [start, end] = ranges[found];
+    return time >= start + lead && time < end - lead ? boost : 1;
+}
+/**
+ * Seconds saved across the whole track at this boost — for UI copy
+ * ("about 6 minutes shorter"), not for scheduling.
+ * opts = { boost, lead }
+ */
+export function estimateSaving(map, opts) {
+    const boost = Math.max(1, num(opts && opts.boost, DEFAULTS.boost));
+    if (boost <= 1)
+        return 0;
+    const lead = Math.max(0, num(opts && opts.lead, DEFAULTS.lead));
+    const ranges = rangesOf(map);
+    if (!ranges)
+        return 0;
+    // Measured off the SAME lead-trimmed windows boostAt actually boosts, so the
+    // number the user is shown is the number they get. Summing map.covered and
+    // multiplying would over-promise by 2*lead per gap — with a lot of short
+    // gaps that is most of the claim.
+    let sped = 0;
+    for (const [a, b] of ranges) {
+        const span = b - a - 2 * lead;
+        if (span > 0)
+            sped += span;
+    }
+    // t seconds of material played at `boost` takes t/boost — the saving is the
+    // remainder, never the naive sped*boost.
+    return sped * (1 - 1 / boost);
+}

package/dist/video/advisors/speaker-rate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+/** A diarized turn: seconds, a resolved name, and the ad flag. */
+export interface RateTurn {
+    start?: unknown;
+    end?: unknown;
+    /** Resolved display name (raw SPEAKER_NN labels are the caller's problem). */
+    name?: string | null;
+    /** Ad read — never attributed to a person, never a landing point. */
+    ad?: boolean;
+}
+/** A transcript segment: seconds, text, and a fallback speaker label. */
+export interface RateSegment {
+    start?: unknown;
+    end?: unknown;
+    text?: unknown;
+    speaker?: string | null;
+}
+export interface SpeakerPaceRow {
+    wpm: number;
+    words: number;
+    seconds: number;
+}
+export interface SpeakerPace {
+    /** Null-prototype map — a speaker literally named "__proto__" stays a key. */
+    bySpeaker: Record<string, SpeakerPaceRow>;
+    medianWpm: number;
+}
+export interface SuggestOpts {
+    targetWpm?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/** name → rate multiplier. */
+export type RateMap = Record<string, number>;
+export declare function speakerPace(transcript: unknown, speakers: unknown): SpeakerPace;
+export declare function suggestRates(pace: unknown, opts?: SuggestOpts | null): RateMap;
+export declare function rateAt(t: unknown, turns: unknown, rates: unknown, fallback?: unknown): number;
+export declare function describeRates(pace: unknown, rates: unknown): string[];