@miadi/ava8-measure 0.1.0

package/dist/movement.js

@@ -0,0 +1,701 @@
+/**
+ * movement.ts — read an OSC movement capture and say what the body did.
+ *
+ * A port of `atelier_movement.py` (standard library only, numpy never
+ * imported). This one has zero dependencies for the same reason: a movement
+ * take is a few thousand packets, and a module that runs everywhere is worth
+ * more here than one that runs fast. `median`, `mean` and the population
+ * standard deviation are three small functions at the bottom of this file.
+ * Nothing degrades, because there is nothing to degrade to.
+ *
+ * ## THE STREAM
+ *
+ * One JSON object per line — `{"t": <seconds>, "values": [f x 9]}`, OSC on the
+ * address `/wek/inputs`, nine float channels:
+ *
+ * | channels | content |
+ * |---|---|
+ * | 0–2 | linear acceleration |
+ * | 3–5 | gyroscope |
+ * | 6–8 | attitude — channel 8 is a HEADING in radians, and it wraps |
+ *
+ * ## UNITS ARE NOT DECLARED
+ *
+ * The studio's own field ledger says the channel semantic map is **absent**,
+ * and states only what the map *would* read. So every number this module
+ * returns is bare, with no unit, and no function here accepts or emits one.
+ * The music never depended on units — everything the atelier derives from
+ * these channels is a **ratio**: a value over that take's own peak, or one
+ * duration against another. Writing "2.96 m/s²" once, as if the unit were
+ * known, is a mistake already paid for.
+ *
+ * The single exception is {@link Heading.turnDegrees}: a difference of an
+ * *unwrapped* heading is a ratio of angles, not a conversion out of an unknown
+ * unit, so it may honestly be read in degrees.
+ *
+ * ## DEDUPE COMES FIRST, ALWAYS
+ *
+ * A packet whose `values` array equals its predecessor's is a **held value,
+ * not a measurement**. Holding each channel's last value between beats is the
+ * OSC literature's standard mitigation for UDP's non-assured delivery, and the
+ * conductor does it on purpose — but it is the transport speaking, not a body.
+ *
+ * Measured, on the capture of 2026-08-16 17:14:
+ *
+ * ```
+ * 1627 packets over 16.6 s      98 Hz of packets — the requested rate is real
+ * 1232 repeat the previous       76 %
+ *  395 new values               23.8 Hz actual, median gap 41 ms
+ * ```
+ *
+ * Multiplying the requested rate by ten multiplied the information by 2.4. At
+ * 10 Hz the same device produced **zero** repeats.
+ *
+ * Onsets found on the raw stream: **28 attacks spaced 120–133 ms** — regular,
+ * credible, and entirely false. That is the staircase of the held values, the
+ * conductor's repeat interval, and not his body. On the deduped stream:
+ * **15 attacks, spaced 153–1481 ms** — two bursts around a silence, which is a
+ * musical form, and which is his.
+ *
+ * So: {@link dedupe} runs first, every other function operates on the deduped
+ * stream, {@link rates} reports the held ratio prominently, and
+ * {@link onsets} takes `dedupeFirst` defaulting to `true` and says in its
+ * result whether it deduped. Turning it off is a deliberate act.
+ *
+ * @packageDocumentation
+ */
+// ── the nine channels ─────────────────────────────────────────────────────
+/** Linear acceleration. Drives density and dynamics. */
+export const ACCEL = [0, 1, 2];
+/** Gyroscope. Drives density, and — where it stops — the sections. */
+export const ROTATION = [3, 4, 5];
+/** Attitude. Channel 8 is an absolute heading and wraps at 2π. */
+export const ATTITUDE = [6, 7, 8];
+/** The channel that is a compass bearing in radians, not an intensity. */
+export const HEADING_CHANNEL = 8;
+/** One full turn, in radians. */
+export const TWO_PI = 2 * Math.PI;
+/** Nine, by convention — and only by convention. See {@link ParseResult.wrongLength}. */
+export const EXPECTED_CHANNELS = 9;
+// ── reading, and the dedupe that must come first ──────────────────────────
+/**
+ * Read one capture from JSONL **text**. One JSON object per line.
+ *
+ * Text in, never a path: this library never touches the filesystem, so it runs
+ * in a browser, in a worker, or on the capture device itself, and the caller
+ * keeps the decision of where a take comes from.
+ *
+ * Malformed lines are **counted and reported**, never guessed at and never
+ * repaired. A line that is not JSON, or a packet missing `values` or `t`, is
+ * not a packet — its line number comes back in
+ * {@link ParseResult.malformedLines}. Nothing is padded, nothing is
+ * interpolated, and no channel order is assumed that the file does not show.
+ *
+ * Returns the RAW packets. **Nothing downstream should use them directly —
+ * {@link dedupe} first.** They are returned raw so that the held-value ratio
+ * can be stated at all, which is the number that tells a human whether the
+ * requested rate was real.
+ */
+export function parse(text) {
+    const packets = [];
+    const malformedLines = [];
+    const wrongLength = [];
+    let lines = 0;
+    let lineNo = 0;
+    for (const rawLine of text.split("\n")) {
+        lineNo += 1;
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        lines += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            malformedLines.push(lineNo);
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            malformedLines.push(lineNo);
+            continue;
+        }
+        const record = parsed;
+        if (!("values" in record) || !("t" in record)) {
+            malformedLines.push(lineNo);
+            continue;
+        }
+        const values = record["values"];
+        if (!Array.isArray(values) || values.length !== EXPECTED_CHANNELS) {
+            wrongLength.push(lineNo);
+        }
+        packets.push(record);
+    }
+    return {
+        packets,
+        lines,
+        malformed: malformedLines.length,
+        malformedLines,
+        wrongLength,
+    };
+}
+/**
+ * Drop every packet whose `values` equal the previous packet's.
+ *
+ * **MANDATORY BEFORE ANY OTHER MOVEMENT MEASURE.** A held value is the
+ * conductor's UDP mitigation, not a sample of his body; counting it as one
+ * turns the hold interval into a rhythm and hands back a staircase. See the
+ * module header for the 28 ghost onsets this prevents.
+ *
+ * Equality is element-wise over the array, as Python's `!=` on two lists is:
+ * a different length is a different value.
+ */
+export function dedupe(packets) {
+    const out = [];
+    let prev = null;
+    for (const p of packets) {
+        const v = p.values ?? null;
+        if (prev === null || !valuesEqual(v, prev))
+            out.push(p);
+        prev = v;
+    }
+    return out;
+}
+/**
+ * Share of RAW packets that repeated the previous value. Report this first, always.
+ *
+ * 0 means the sensor kept up with the requested rate. 0.76 means it did not,
+ * and that the real resolution is four times coarser than the number on the
+ * box. Both are honest; only one is what was asked for.
+ */
+export function heldRatio(packets) {
+    const n = packets.length;
+    if (n <= 1)
+        return 0;
+    return 1 - dedupe(packets).length / n;
+}
+/**
+ * Declared packet rate against the real rate of NEW values.
+ *
+ * Decides what resolution everything below is entitled to claim. A tempo read
+ * at 23 Hz carries roughly ±7 BPM of instrument error around 140 BPM; calling
+ * 150 and 136 different tempi without saying that would be dishonest.
+ *
+ * Takes the RAW packets — it is the one function that must, because the held
+ * count is its subject.
+ */
+export function rates(packets) {
+    const raw = [...packets];
+    const fresh = dedupe(raw);
+    const span = timeSpan(raw);
+    const gaps = [];
+    for (let i = 1; i < fresh.length; i += 1) {
+        gaps.push(toFloatOrThrow(fresh[i]["t"]) - toFloatOrThrow(fresh[i - 1]["t"]));
+    }
+    const gap = gaps.length > 0 ? median(gaps) : null;
+    return {
+        packets: raw.length,
+        newValues: fresh.length,
+        held: raw.length - fresh.length,
+        heldRatio: raw.length > 0 ? 1 - fresh.length / raw.length : 0,
+        duration: span,
+        packetHz: span > 0 ? raw.length / span : 0,
+        newValueHz: span > 0 ? fresh.length / span : 0,
+        medianGapNew: gap,
+        resolutionMs: gap === null ? null : 1000 * gap,
+    };
+}
+// ── magnitudes ────────────────────────────────────────────────────────────
+/**
+ * `(t, |v|)` per packet for a channel group. Euclidean, because direction is a
+ * separate question answered by {@link unwrapHeading}.
+ *
+ * **Deduped input assumed.** The magnitude of a group is what drives density,
+ * dynamics and onsets; the sign of an individual axis depends on how the phone
+ * sat in his pocket and decides nothing.
+ *
+ * A packet whose array is too short for a requested channel, or whose entries
+ * are not numbers, is skipped — never padded with a zero, which would be a
+ * measurement of a hole. A packet whose `t` cannot be read is skipped for the
+ * same reason; this is the one place the port is gentler than the Python,
+ * which raises there.
+ */
+export function magnitudes(packets, channels = ACCEL) {
+    const out = [];
+    for (const p of packets) {
+        const values = p.values;
+        let sum = 0;
+        let ok = true;
+        for (const c of channels) {
+            const x = toFloat(indexOf(values, c));
+            if (x === null) {
+                ok = false;
+                break;
+            }
+            sum += x * x;
+        }
+        if (!ok)
+            continue;
+        const t = toFloat(p.t);
+        if (t === null)
+            continue;
+        out.push({ t, m: Math.sqrt(sum) });
+    }
+    return out;
+}
+/**
+ * Mean magnitude per whole second, for acceleration (0–2) and rotation (3–5).
+ *
+ * **ONE SECOND OF HIS BODY = ONE BAR.** That is the whole reason this function
+ * exists: it is the bridge from a stream to a score, and it is the shape of
+ * every piece the atelier built from movement. Reading it back is how the form
+ * is checked against him — plateau, peak, dissolution — rather than against a
+ * story about him. It is a choice, and it is undone with a word.
+ *
+ * Pass a bare channel list to measure one group; it comes back under the key
+ * `channels`. Seconds are floored toward zero, as Python's `int()` is, and
+ * each group carries its own second list because a group can lose a packet the
+ * other keeps.
+ */
+export function perSecond(packets, groups) {
+    let named;
+    if (groups === undefined) {
+        named = { acceleration: ACCEL, rotation: ROTATION };
+    }
+    else if (Array.isArray(groups)) {
+        named = { channels: groups };
+    }
+    else {
+        named = groups;
+    }
+    const out = {};
+    for (const [name, chans] of Object.entries(named)) {
+        const buckets = new Map();
+        for (const { t, m } of magnitudes(packets, chans)) {
+            const second = Math.trunc(t);
+            const bucket = buckets.get(second);
+            if (bucket)
+                bucket.push(m);
+            else
+                buckets.set(second, [m]);
+        }
+        const seconds = [...buckets.keys()].sort((a, b) => a - b);
+        out[name] = { seconds, means: seconds.map((s) => mean(buckets.get(s))) };
+    }
+    return out;
+}
+// ── onsets ────────────────────────────────────────────────────────────────
+/**
+ * Local maxima above median + kσ, with a minimum separation. Rhythm from the body.
+ *
+ * Decides where a note is struck when his movement plays the piece. Run on the
+ * raw stream this returns the hold interval — 28 evenly spaced ghosts, spaced
+ * 120–133 ms — so `dedupeFirst` defaults to `true`, the result carries
+ * {@link Onsets.deduped} so a reader can tell which stream a number came from,
+ * and turning it off is a deliberate act.
+ *
+ * `minSepS` exists because a single gesture crosses the threshold on several
+ * consecutive new values; without it one attack is reported as three. The
+ * 0.15 s default is calibrated, not guessed: on the take of 2026-08-16 at
+ * 17:14 it returns 15 attacks in two bursts, which is what the atelier used.
+ *
+ * **Verified against that take, and the disagreement is named rather than
+ * hidden:** the count and the two-burst shape reproduce; **11 of the 15
+ * timestamps land within 30 ms of the session's own published list, and the
+ * remaining four differ, because the session's peak-picking was never written
+ * down.** Re-measure; do not quote its list.
+ */
+export function onsets(packets, options = {}) {
+    const channels = options.channels ?? ACCEL;
+    const k = options.k ?? 1.2;
+    const minSepS = options.minSepS ?? 0.15;
+    const dedupeFirst = options.dedupeFirst ?? true;
+    const pk = dedupeFirst ? dedupe(packets) : [...packets];
+    const mag = magnitudes(pk, channels);
+    if (mag.length < 3) {
+        return {
+            times: [],
+            forces: [],
+            threshold: null,
+            median: null,
+            sigma: null,
+            k,
+            minSepS,
+            n: 0,
+            medianGap: null,
+            gapRange: null,
+            deduped: dedupeFirst,
+        };
+    }
+    const vals = mag.map((x) => x.m);
+    const med = median(vals);
+    const sd = vals.length > 1 ? pstdev(vals) : 0;
+    const thr = med + k * sd;
+    const times = [];
+    const forces = [];
+    for (let i = 1; i < mag.length - 1; i += 1) {
+        const { t, m } = mag[i];
+        if (m < thr)
+            continue;
+        if (!(m >= mag[i - 1].m && m >= mag[i + 1].m))
+            continue;
+        if (times.length > 0 && t - times[times.length - 1] < minSepS) {
+            // One gesture, several new values above the threshold: keep the strongest.
+            if (m > forces[forces.length - 1]) {
+                times[times.length - 1] = t;
+                forces[forces.length - 1] = m;
+            }
+            continue;
+        }
+        times.push(t);
+        forces.push(m);
+    }
+    const gaps = [];
+    for (let i = 1; i < times.length; i += 1)
+        gaps.push(times[i] - times[i - 1]);
+    return {
+        times: times.map(round4),
+        forces: forces.map(round4),
+        threshold: thr,
+        median: med,
+        sigma: sd,
+        k,
+        minSepS,
+        n: times.length,
+        medianGap: gaps.length > 0 ? median(gaps) : null,
+        gapRange: gaps.length > 0 ? [Math.min(...gaps), Math.max(...gaps)] : null,
+        deduped: dedupeFirst,
+    };
+}
+// ── heading ───────────────────────────────────────────────────────────────
+/**
+ * Cumulative heading, and how many 2π wraps were removed to get it.
+ *
+ * Decides the harmony in every piece where the chord follows where he is
+ * facing. Channel 8 never goes below 0 and reaches 6.28: it is a compass
+ * bearing in radians and it wraps at north.
+ *
+ * **Raw use is not a subtle error, it is a catastrophic one.** Used raw, the
+ * music leaps a whole turn every time he passes north — a leap that
+ * corresponds to **no movement of his at all**. One capture wraps thirteen
+ * times, another four.
+ *
+ * Deltas are folded into (−π, π] and accumulated. {@link Heading.wraps} is the
+ * count removed; **if it is 0, either he never crossed north or this channel
+ * is not a heading, and this reading should be doubted before a note is
+ * written on it.**
+ *
+ * Dedupes internally — always — so it is safe to hand this the raw stream.
+ */
+export function unwrapHeading(packets, channel = HEADING_CHANNEL) {
+    const pk = dedupe(packets);
+    const vals = [];
+    const times = [];
+    for (const p of pk) {
+        const v = toFloat(indexOf(p.values, channel));
+        if (v === null)
+            continue;
+        vals.push(v);
+        const t = toFloat(p.t);
+        if (t === null)
+            continue;
+        times.push(t);
+    }
+    if (vals.length === 0) {
+        return {
+            times: [],
+            heading: [],
+            raw: [],
+            wraps: 0,
+            turn: 0,
+            turnDegrees: 0,
+            range: null,
+        };
+    }
+    const u = [vals[0]];
+    let wraps = 0;
+    for (let i = 1; i < vals.length; i += 1) {
+        let d = vals[i] - vals[i - 1];
+        // A jump of very nearly a full turn is north being crossed, not a body.
+        if (Math.abs(Math.abs(d) - TWO_PI) < 0.8)
+            wraps += 1;
+        while (d > Math.PI)
+            d -= TWO_PI;
+        while (d < -Math.PI)
+            d += TWO_PI;
+        u.push(u[u.length - 1] + d);
+    }
+    const turn = u[u.length - 1] - u[0];
+    return {
+        times,
+        heading: u,
+        raw: vals,
+        wraps,
+        turn,
+        turnDegrees: (turn * 180) / Math.PI,
+        range: [Math.min(...u), Math.max(...u)],
+    };
+}
+/**
+ * Which nth of the compass at each moment, and where it changes.
+ *
+ * Six harmonic stations map onto six sixths of the compass: the chord stops
+ * being chosen by a clock or a threshold and starts being chosen by the
+ * direction he is facing. He turns, the harmony turns. **The change points are
+ * the deliverable** — they are where the chord moves, and they do not fall on
+ * bar lines, which is the point.
+ *
+ * Accepts the {@link Heading} from {@link unwrapHeading} or a bare sequence of
+ * unwrapped radians; a bare sequence gets its **indices** as timestamps, which
+ * is the one reason to prefer handing over the whole {@link Heading} — the
+ * change points are wanted in seconds, not in sample numbers.
+ *
+ * **A claim this port measured and had to correct.** The skill this comes from
+ * says "feeding a raw heading here puts a chord change on every pass of
+ * north". It does not: this function takes the heading modulo a turn, so the
+ * wrapped channel and the unwrapped path produce the *identical* sextant
+ * sequence — verified on the take of 2026-08-16 17:14 and on a synthetic turn
+ * through 2π in both directions. The chord choice survives raw input. What
+ * does not survive is everything that reads the heading as a **path**: on that
+ * synthetic turn the raw channel reports +331° where he turned −29°. So
+ * {@link unwrapHeading} stays mandatory — for the turn, the range, and any
+ * pitch — and this function is simply not where the damage lands.
+ *
+ * The sanity bar the atelier used before writing a note: across five usable
+ * takes this produced 6 to 32 changes per take, always touching 2 to 4 of the
+ * six stations. One chord for a whole take, or a change every eighth, is a
+ * mapping to reject at this stage rather than after listening.
+ */
+export function sextants(heading, n = 6) {
+    let series;
+    let times;
+    if (Array.isArray(heading)) {
+        series = [...heading];
+        times = series.map((_, i) => i);
+    }
+    else {
+        const h = heading;
+        series = [...h.heading];
+        times = [...(h.times ?? [])];
+    }
+    const idx = series.map((h) => Math.trunc((pyMod(h, TWO_PI) / TWO_PI) * n) % n);
+    const changes = [];
+    for (let i = 1; i < idx.length; i += 1) {
+        if (idx[i] !== idx[i - 1]) {
+            changes.push({
+                index: i,
+                t: i < times.length ? times[i] : null,
+                from: idx[i - 1],
+                to: idx[i],
+            });
+        }
+    }
+    const counts = new Map();
+    for (const i of idx)
+        counts.set(i, (counts.get(i) ?? 0) + 1);
+    const total = idx.length || 1;
+    const visited = [...counts.keys()].sort((a, b) => a - b);
+    const occupancy = {};
+    for (const key of visited)
+        occupancy[key] = counts.get(key) / total;
+    return { n, sextant: idx, changes, nChanges: changes.length, occupancy, visited };
+}
+// ── stillness ─────────────────────────────────────────────────────────────
+/**
+ * The still spans that cut a piece into sections.
+ *
+ * **Where his body stops, the harmony changes.** Sections come from him and
+ * not from a bar count, and this is the function that says where. Nothing else
+ * in these nine channels segments a take as convincingly, and nothing else
+ * needs so little interpretation — a still body is a still body.
+ *
+ * Read per whole second, on the same grid as {@link perSecond}, so a section
+ * boundary and a bar boundary are the same object.
+ *
+ * `threshold` has **no unit**, because the stream declares none. 0.5 on
+ * rotation is what the atelier used; it is a choice, and it is undone by one
+ * word. The number of stations his body offers is whatever it offers — when
+ * six were wanted and the body gave four, the piece took two passes and said so.
+ *
+ * Dedupes internally — always.
+ */
+export function stillness(packets, options = {}) {
+    const threshold = options.threshold ?? 0.5;
+    const channels = options.channels ?? ROTATION;
+    const minSpanS = options.minSpanS ?? 1;
+    const pk = dedupe(packets);
+    const buckets = new Map();
+    for (const { t, m } of magnitudes(pk, channels)) {
+        const second = Math.trunc(t);
+        const bucket = buckets.get(second);
+        if (bucket)
+            bucket.push(m);
+        else
+            buckets.set(second, [m]);
+    }
+    const seconds = [...buckets.keys()].sort((a, b) => a - b);
+    const series = seconds.map((s) => mean(buckets.get(s)));
+    const still = series.map((v) => v < threshold);
+    const spans = [];
+    const cuts = [];
+    let i = 0;
+    while (i < still.length) {
+        if (still[i]) {
+            let j = i;
+            while (j + 1 < still.length && still[j + 1])
+                j += 1;
+            const duration = seconds[j] - seconds[i] + 1;
+            if (duration >= minSpanS) {
+                spans.push({ startSecond: seconds[i], endSecond: seconds[j], duration });
+                cuts.push(seconds[i]);
+            }
+            i = j + 1;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return {
+        threshold,
+        channels: [...channels],
+        seconds,
+        series,
+        still,
+        spans,
+        cuts,
+        nSections: cuts.length > 0 ? cuts.length : 1,
+        stillShare: still.length > 0 ? still.filter(Boolean).length / still.length : 0,
+    };
+}
+// ── the three small helpers, written rather than depended on ──────────────
+/**
+ * Middle value; the mean of the two middle values when the count is even.
+ *
+ * Preferred over the mean wherever a held-value staircase or a single lurch
+ * would drag an average somewhere no second of the take ever was.
+ */
+export function median(values) {
+    if (values.length === 0)
+        throw new RangeError("median of no values");
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = sorted.length >> 1;
+    if (sorted.length % 2 === 1)
+        return sorted[mid];
+    return (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/**
+ * Arithmetic mean, summed with Neumaier compensation.
+ *
+ * The compensation is not decoration: a 93 s take is thousands of small
+ * magnitudes, and naive summation drifts exactly where the per-second curve is
+ * flattest — which is the part of the take that decides where a section opens.
+ *
+ * Throws on an empty list. An empty mean has no value, and returning 0 would
+ * put a number that was never measured into a score.
+ */
+export function mean(values) {
+    if (values.length === 0)
+        throw new RangeError("mean of no values");
+    return neumaierSum(values) / values.length;
+}
+/**
+ * Population standard deviation — divided by n, not n−1.
+ *
+ * Population, because a take is not a sample of some larger take: it is all of
+ * the body there was. Used by {@link onsets} for the median + kσ threshold.
+ */
+export function pstdev(values) {
+    if (values.length === 0)
+        throw new RangeError("pstdev of no values");
+    if (values.length === 1)
+        return 0;
+    const mu = mean(values);
+    const ss = neumaierSum(values.map((v) => (v - mu) * (v - mu)));
+    return Math.sqrt(ss / values.length);
+}
+// ── internals ─────────────────────────────────────────────────────────────
+/** Kahan–Babuška–Neumaier summation. */
+function neumaierSum(values) {
+    let sum = 0;
+    let c = 0;
+    for (const v of values) {
+        const t = sum + v;
+        if (Math.abs(sum) >= Math.abs(v))
+            c += sum - t + v;
+        else
+            c += v - t + sum;
+        sum = t;
+    }
+    return sum + c;
+}
+/** Element-wise, as Python's `!=` on two lists is. A different length is a different value. */
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1) {
+        const x = a[i];
+        const y = b[i];
+        if (x === y)
+            continue;
+        if (Array.isArray(x) || Array.isArray(y)) {
+            if (!valuesEqual(x, y))
+                return false;
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+/** `seq[i]`, for anything indexable, without pretending a miss is a zero. */
+function indexOf(seq, i) {
+    if (Array.isArray(seq))
+        return i >= 0 && i < seq.length ? seq[i] : undefined;
+    if (typeof seq === "string")
+        return i >= 0 && i < seq.length ? seq[i] : undefined;
+    return undefined;
+}
+/**
+ * Python's `float()`, near enough: numbers, booleans and numeric strings pass;
+ * everything else — including `undefined` from a short `values` array —
+ * returns `null`, and the caller skips the packet.
+ */
+function toFloat(x) {
+    if (typeof x === "number")
+        return Number.isFinite(x) ? x : null;
+    if (typeof x === "boolean")
+        return x ? 1 : 0;
+    if (typeof x === "string") {
+        const s = x.trim();
+        if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s))
+            return null;
+        const n = Number(s);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+function toFloatOrThrow(x) {
+    const n = toFloat(x);
+    if (n === null)
+        throw new TypeError(`not a number: ${JSON.stringify(x) ?? String(x)}`);
+    return n;
+}
+/** Span of the RAW stream, first timestamp to last. */
+function timeSpan(packets) {
+    if (packets.length < 2)
+        return 0;
+    return toFloatOrThrow(packets[packets.length - 1]["t"]) - toFloatOrThrow(packets[0]["t"]);
+}
+/** Python's `%`: the result takes the sign of the divisor, so it is never negative here. */
+function pyMod(a, b) {
+    const r = a % b;
+    return r !== 0 && r < 0 !== b < 0 ? r + b : r;
+}
+/** Python's `round(x, 4)`. No exact tie is representable at four decimals, so these agree. */
+function round4(x) {
+    return Number(x.toFixed(4));
+}
+//# sourceMappingURL=movement.js.map