@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/vehicle/audioReference.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFERENCE_ERROR_FACTOR = exports.REFERENCE_WARN_FACTOR = void 0;
+exports.roughness = roughness;
+exports.timbreMetrics = timbreMetrics;
+exports.compareToReference = compareToReference;
+exports.loadReferenceClip = loadReferenceClip;
+exports.loadReferenceClips = loadReferenceClips;
+/**
+ * Compare a sound with a recording of the real thing: the gate that needs a reference the CLI cannot invent.
+ *
+ * The caller supplies a clip of the real car (an idle recording for the engine, optionally one per slot: horn,
+ * startup, ...). The same three cheap timbre measures are taken from the clip and from the candidate sound with ONE
+ * implementation, so a method difference can never read as a timbre difference:
+ *
+ *   - spectral centroid: the amplitude-weighted mean frequency, 20 Hz - 10 kHz (a bright or dull voice);
+ *   - roughness: the depth of the 8-60 Hz amplitude modulation of the 150 Hz - 2.5 kHz band (firing lumpiness; a
+ *     smoothed or heavily processed recording is lower, one with an exaggerated chug is higher).
+ *
+ * A field recording is not a studio take: mic distance, wind and the recorder's EQ move every one of these by a
+ * factor of 2-4 between two honest recordings of the SAME car (four idle recordings of one car measured 273-1324 Hz
+ * centroid), so the tolerance is a factor, WARN outside 2.5x and ERROR outside 10x, not a percentage. Several reference
+ * clips for one slot are reduced to their median.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const audioSpectral_1 = require("./audioSpectral");
+/** WARN when candidate / reference falls outside [1/WARN, WARN]; ERROR outside [1/ERROR, ERROR]. */
+exports.REFERENCE_WARN_FACTOR = 2.5;
+exports.REFERENCE_ERROR_FACTOR = 10;
+const SECONDS = 6;
+function centred(samples, sr, seconds) {
+    const cap = Math.floor(sr * seconds);
+    if (samples.length <= cap)
+        return samples;
+    const start = Math.floor((samples.length - cap) / 2);
+    return samples.subarray(start, start + cap);
+}
+/** Zero everything outside [lo, hi] Hz in a spectrum of `size` points (both halves). */
+function bandpass(re, im, sr, lo, hi) {
+    const size = re.length;
+    for (let k = 0; k <= size / 2; k += 1) {
+        const hz = (k * sr) / size;
+        if (hz < lo || hz > hi) {
+            re[k] = 0;
+            im[k] = 0;
+            if (k > 0 && k < size / 2) {
+                re[size - k] = 0;
+                im[size - k] = 0;
+            }
+        }
+    }
+}
+function inverse(re, im) {
+    const n = re.length;
+    const r = Float64Array.from(re);
+    const i = new Float64Array(n);
+    for (let k = 0; k < n; k += 1)
+        i[k] = -im[k];
+    (0, audioSpectral_1.fft)(r, i);
+    for (let k = 0; k < n; k += 1) {
+        r[k] /= n;
+        i[k] = -i[k] / n;
+    }
+    return { re: r, im: i };
+}
+/** Depth of the 8-60 Hz amplitude modulation of the 150 Hz - 2.5 kHz band, relative to its mean level. */
+function roughness(samples, sr) {
+    const x = centred(samples, sr, SECONDS);
+    const size = (0, audioSpectral_1.pow2ceil)(x.length);
+    const re = new Float64Array(size);
+    const im = new Float64Array(size);
+    let mean = 0;
+    for (let i = 0; i < x.length; i += 1)
+        mean += x[i];
+    mean /= Math.max(1, x.length);
+    for (let i = 0; i < x.length; i += 1)
+        re[i] = x[i] - mean;
+    (0, audioSpectral_1.fft)(re, im);
+    bandpass(re, im, sr, 150, Math.min(2500, sr * 0.45));
+    // analytic signal: keep the positive half, doubled
+    for (let k = 1; k < size / 2; k += 1) {
+        re[k] *= 2;
+        im[k] *= 2;
+    }
+    for (let k = size / 2 + 1; k < size; k += 1) {
+        re[k] = 0;
+        im[k] = 0;
+    }
+    const an = inverse(re, im);
+    const env = new Float64Array(x.length);
+    let envMean = 0;
+    for (let i = 0; i < x.length; i += 1) {
+        env[i] = Math.hypot(an.re[i], an.im[i]);
+        envMean += env[i];
+    }
+    envMean /= Math.max(1, x.length);
+    if (!(envMean > 1e-9))
+        return 0;
+    const r2 = new Float64Array(size);
+    const i2 = new Float64Array(size);
+    r2.set(env);
+    (0, audioSpectral_1.fft)(r2, i2);
+    bandpass(r2, i2, sr, 8, 60);
+    const m = inverse(r2, i2).re;
+    let ss = 0;
+    for (let i = 0; i < x.length; i += 1)
+        ss += m[i] * m[i];
+    return Math.sqrt(ss / x.length) / envMean;
+}
+function timbreMetrics(samples, sr) {
+    const x = centred(samples, sr, SECONDS);
+    const { f, p } = (0, audioSpectral_1.welchFine)(x, sr);
+    const hi = Math.min(10000, sr * 0.45);
+    let a = 0;
+    let af = 0;
+    for (let i = 0; i < f.length; i += 1) {
+        if (f[i] >= 20 && f[i] <= hi) {
+            const amp = Math.sqrt(p[i]);
+            a += amp;
+            af += amp * f[i];
+        }
+    }
+    return { centroidHz: a > 0 ? af / a : 0, roughness: roughness(samples, sr), seconds: samples.length / sr };
+}
+const median = (v) => {
+    const s = [...v].sort((p, q) => p - q);
+    return s.length === 0 ? 0 : s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2;
+};
+/** Candidate timbre against one or more reference clips of the same sound (median over the references). */
+function compareToReference(candidate, references) {
+    if (references.length === 0)
+        return [];
+    const rows = [
+        ['centroid', 'spectral centroid', candidate.centroidHz, median(references.map((r) => r.centroidHz))],
+        ['roughness', 'roughness (8-60 Hz modulation depth)', candidate.roughness, median(references.map((r) => r.roughness))],
+    ];
+    return rows.map(([metric, label, c, r]) => {
+        const ratio = r > 0 && c > 0 ? c / r : r > 0 ? 0 : 1;
+        const dev = ratio > 0 ? Math.max(ratio, 1 / ratio) : Infinity;
+        return { metric, label, candidate: c, reference: r, ratio, level: dev > exports.REFERENCE_ERROR_FACTOR ? 'error' : dev > exports.REFERENCE_WARN_FACTOR ? 'warn' : 'ok' };
+    });
+}
+/** Decode a reference clip: a WAV directly; any other format (mp3, m4a, ogg, webm) through `ffmpeg` when it is installed. */
+function loadReferenceClip(path) {
+    const file = (0, node_path_1.resolve)(path);
+    if (!(0, node_fs_1.existsSync)(file))
+        throw new Error(`reference clip ${path} does not exist`);
+    let bytes = new Uint8Array((0, node_fs_1.readFileSync)(file));
+    const isWav = bytes.length > 12 && Buffer.from(bytes.subarray(0, 4)).toString('ascii') === 'RIFF' && Buffer.from(bytes.subarray(8, 12)).toString('ascii') === 'WAVE';
+    if (!isWav) {
+        const r = (0, node_child_process_1.spawnSync)('ffmpeg', ['-v', 'error', '-i', file, '-ac', '1', '-ar', '44100', '-c:a', 'pcm_s16le', '-f', 'wav', '-'], { maxBuffer: 512 * 1024 * 1024 });
+        if (r.error || r.status !== 0 || !r.stdout?.length) {
+            throw new Error(`reference clip ${path} is not a WAV and ffmpeg could not convert it (${r.error?.message ?? r.stderr?.toString().trim() ?? 'not installed'}); convert it first: ffmpeg -i ${(0, node_path_1.basename)(path)} -ac 1 -ar 44100 -c:a pcm_s16le reference.wav`);
+        }
+        bytes = new Uint8Array(r.stdout);
+    }
+    const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(bytes, true);
+    return { source: (0, node_path_1.basename)(path), samples, sampleRate };
+}
+/**
+ * `--reference` values: `clip` (the engine at idle) or `slot=clip` (a named slot: `horn=horn.wav`, `startup=start.wav`).
+ * Repeat a slot to give several clips of it; the median is compared.
+ */
+function loadReferenceClips(values) {
+    const bySlot = new Map();
+    for (const value of values) {
+        const m = /^([A-Za-z][A-Za-z0-9]*)=(.+)$/.exec(value);
+        const slot = m && !(0, node_fs_1.existsSync)(value) ? m[1] : 'idle';
+        const path = m && !(0, node_fs_1.existsSync)(value) ? m[2] : value;
+        bySlot.set(slot, [...(bySlot.get(slot) ?? []), loadReferenceClip(path)]);
+    }
+    return { bySlot };
+}
+//# sourceMappingURL=audioReference.js.map

package/dist/vehicle/audioReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioReference.js","sourceRoot":"","sources":["../../src/vehicle/audioReference.ts"],"names":[],"mappings":"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"}

package/dist/vehicle/audioSlots.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The HELIX vehicle audio slot vocabulary.
+ *
+ * Source of truth: `VehicleAudioSlot` in helix-web-engine-new
+ * `systems/humanoid-character/src/core/vehicle/package/format.ts` (a TypeScript union, erased at build time, so the
+ * vendored validator cannot export it). `audioSlots.spec.ts` pins this list against that file whenever an engine
+ * checkout is reachable, and against the Python importer's copy (`plugins/beamng-vehicle/bin/sim_audio.py SLOTS`).
+ */
+export declare const VEHICLE_AUDIO_SLOTS: readonly ["engineLadder", "exhaustLadder", "idle", "startup", "shutdown", "shiftUp", "shiftDown", "clutch", "transmissionWhine", "turboSpool", "blowOff", "intake", "revLimiter", "backfire", "suspension", "impactLight", "impactMedium", "impactHeavy", "tyreSqueal", "tyreScrub", "tyreSpin", "tyreRollSlow", "tyreRollFast", "indicatorTick", "skid", "brakeSqueal", "handbrake", "reverseBeep", "horn", "doorOpen", "doorClose"];
+export type VehicleAudioSlotName = typeof VEHICLE_AUDIO_SLOTS[number];
+/**
+ * The only ways a slot may legitimately carry no recording (`consumed: false`, `buffers: []`, plus a `reason`):
+ *   absent: "not-fitted"            the real car physically lacks the component (see NOT_FITTED_SLOTS)
+ *   absent: "combined-with-engine"  exhaustLadder only: the source records engine and exhaust as one set, which plays
+ *                                   on the engine layer (exhaustBlend omitted); requires a sourced engine ladder
+ */
+export declare const ABSENT_NOT_FITTED = "not-fitted";
+export declare const ABSENT_COMBINED_WITH_ENGINE = "combined-with-engine";
+/**
+ * Slots a car can physically lack. Each entry says when, checked against the package's own physics:
+ *   turboSpool / blowOff   no turbocharger (`physics.induction` absent, or its kind is not "turbo")
+ *   reverseBeep            any road car (a reverse warning beeper is fitted equipment, not a given)
+ *   clutch                 a torque-converter automatic or CVT (no clutch to engage)
+ * An electric car additionally lacks every combustion sound.
+ */
+export declare const NOT_FITTED_SLOTS: ReadonlySet<string>;
+export declare const COMBUSTION_ONLY_SLOTS: ReadonlySet<string>;

package/dist/vehicle/audioSlots.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMBUSTION_ONLY_SLOTS = exports.NOT_FITTED_SLOTS = exports.ABSENT_COMBINED_WITH_ENGINE = exports.ABSENT_NOT_FITTED = exports.VEHICLE_AUDIO_SLOTS = void 0;
+/**
+ * The HELIX vehicle audio slot vocabulary.
+ *
+ * Source of truth: `VehicleAudioSlot` in helix-web-engine-new
+ * `systems/humanoid-character/src/core/vehicle/package/format.ts` (a TypeScript union, erased at build time, so the
+ * vendored validator cannot export it). `audioSlots.spec.ts` pins this list against that file whenever an engine
+ * checkout is reachable, and against the Python importer's copy (`plugins/beamng-vehicle/bin/sim_audio.py SLOTS`).
+ */
+exports.VEHICLE_AUDIO_SLOTS = [
+    'engineLadder', 'exhaustLadder',
+    'idle', 'startup', 'shutdown',
+    'shiftUp', 'shiftDown', 'clutch',
+    'transmissionWhine',
+    'turboSpool', 'blowOff', 'intake',
+    'revLimiter', 'backfire',
+    'suspension', 'impactLight', 'impactMedium', 'impactHeavy',
+    'tyreSqueal', 'tyreScrub', 'tyreSpin', 'tyreRollSlow', 'tyreRollFast',
+    'indicatorTick', 'skid', 'brakeSqueal', 'handbrake',
+    'reverseBeep', 'horn', 'doorOpen', 'doorClose',
+];
+/**
+ * The only ways a slot may legitimately carry no recording (`consumed: false`, `buffers: []`, plus a `reason`):
+ *   absent: "not-fitted"            the real car physically lacks the component (see NOT_FITTED_SLOTS)
+ *   absent: "combined-with-engine"  exhaustLadder only: the source records engine and exhaust as one set, which plays
+ *                                   on the engine layer (exhaustBlend omitted); requires a sourced engine ladder
+ */
+exports.ABSENT_NOT_FITTED = 'not-fitted';
+exports.ABSENT_COMBINED_WITH_ENGINE = 'combined-with-engine';
+/**
+ * Slots a car can physically lack. Each entry says when, checked against the package's own physics:
+ *   turboSpool / blowOff   no turbocharger (`physics.induction` absent, or its kind is not "turbo")
+ *   reverseBeep            any road car (a reverse warning beeper is fitted equipment, not a given)
+ *   clutch                 a torque-converter automatic or CVT (no clutch to engage)
+ * An electric car additionally lacks every combustion sound.
+ */
+exports.NOT_FITTED_SLOTS = new Set(['turboSpool', 'blowOff', 'reverseBeep', 'clutch']);
+exports.COMBUSTION_ONLY_SLOTS = new Set([
+    'exhaustLadder', 'idle', 'startup', 'shutdown', 'clutch', 'turboSpool', 'blowOff', 'intake', 'revLimiter', 'backfire',
+]);
+//# sourceMappingURL=audioSlots.js.map

package/dist/vehicle/audioSlots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioSlots.js","sourceRoot":"","sources":["../../src/vehicle/audioSlots.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACU,QAAA,mBAAmB,GAAG;IACjC,cAAc,EAAE,eAAe;IAC/B,MAAM,EAAE,SAAS,EAAE,UAAU;IAC7B,SAAS,EAAE,WAAW,EAAE,QAAQ;IAChC,mBAAmB;IACnB,YAAY,EAAE,SAAS,EAAE,QAAQ;IACjC,YAAY,EAAE,UAAU;IACxB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa;IAC1D,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc;IACrE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW;IACnD,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW;CACtC,CAAC;AAGX;;;;;GAKG;AACU,QAAA,iBAAiB,GAAG,YAAY,CAAC;AACjC,QAAA,2BAA2B,GAAG,sBAAsB,CAAC;AAElE;;;;;;GAMG;AACU,QAAA,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;AACpG,QAAA,qBAAqB,GAAwB,IAAI,GAAG,CAAC;IAChE,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU;CACtH,CAAC,CAAC"}

package/dist/vehicle/audioSpectral.d.ts

@@ -0,0 +1,71 @@
+/** In-place forward FFT. `re`/`im` must be length 2^k. */
+export declare function fft(re: Float64Array, im: Float64Array): void;
+export declare const pow2ceil: (n: number) => number;
+export declare const pow2floor: (n: number) => number;
+/** Decode a PCM/float WAV into a mono Float64Array (channels averaged). Throws on anything not a RIFF/WAVE. */
+export declare function decodeWavMono(bytes: Uint8Array, lenient?: boolean): {
+    samples: Float64Array;
+    sampleRate: number;
+};
+/** Max normalised autocorrelation beyond the first zero crossing (lag 2 ms .. half the window). ~1 for a pure loop. */
+export declare function autocorrMax(samples: Float64Array, sr: number): number;
+export declare const db: (v: number) => number;
+/** Naive sliding median (odd kernel), edges mirrored. */
+export declare function medianFilter(v: Float64Array, kernel: number): Float64Array;
+export interface SpectralRichness {
+    sampleRate: number;
+    durationS: number;
+    /** Max normalised autocorrelation beyond the first zero crossing. */
+    autocorrMax: number;
+    /** Spectral flatness (geometric / arithmetic mean) over 50 Hz .. min(0.45·sr, 16 kHz). */
+    flatness: number;
+    /** Number of spectral lines at least 20 dB above their local floor. */
+    nLines20: number;
+    /** dB of the energy OUTSIDE the strong lines, relative to the whole spectrum. Very negative = pure tone. */
+    lineResidualDb: number;
+    /** Spectral centroid, Hz. */
+    centroidHz: number;
+    isNearPureTone: boolean;
+    why: string | null;
+}
+export declare const largestOddAtMost: (n: number) => number;
+export declare const smallestOddAtLeast: (n: number) => number;
+/** Spectral richness + the near-pure-tone verdict for one decoded WAV. */
+export declare function spectralRichness(samples: Float64Array, sr: number): SpectralRichness;
+/** Convenience: read + decode + analyse a WAV file path. */
+export declare function spectralRichnessFile(path: string): SpectralRichness;
+/**
+ * The engine's firing fundamental for one rpm label: the frequency the ladder rung's pitch must sit at.
+ *
+ * A 4-stroke engine fires each cylinder once per 2 crank revolutions, so there are `C/2` firing events per rev and
+ * an even-firing engine's dominant is `C·rpm/120` (a flat-plane V8: `rpm/15`). A cross-plane V8 groups those firings
+ * unevenly, so its dominant is the crank-order "burble" at `rpm/60` — two octaves below the flat-plane value.
+ */
+export declare function firingFundamental(rpm: number, cylinderCount: number, strokes: number, crankLayout?: string): number;
+/**
+ * A fine Welch spectrum for fundamental estimation: Hann windows, nps = min(32768, 2^k) with a 2048 floor — the
+ * resolution the harness's `fine_spectrum` uses, so low fundamentals (e.g. a 33 Hz firing at 1000 rpm) resolve their
+ * harmonics as distinct peaks.
+ */
+export declare function welchFine(samples: Float64Array, sr: number): {
+    f: Float64Array;
+    p: Float64Array;
+};
+/** A chance-corrected comb-salience fundamental estimate, ported from the harness's `audio_analyze.py estimate_f0`. */
+export declare function estimateFundamental(samples: Float64Array, sr: number, opts?: {
+    fLo?: number;
+    fHi?: number;
+}): {
+    f0: number;
+    score: number;
+    nPeaks: number;
+} | null;
+/**
+ * Firing-comb cross-check (the f40-r8 owner-proxy's `firing_xcheck.py`): summed spectral peak magnitude on the labelled
+ * firing comb, k × f (k = 1..6), over the half-order comb between it, (k − ½) × f. A rung recorded at its label puts its
+ * energy on the comb (real F40 sim-mod ladders measure 8-30); a rung an octave or two low puts as much or more between
+ * the teeth (an octave-down copy of a real ladder measures ~1.5, a two-octaves-low synthetic one under 1). Unlike a
+ * periodicity tracker it does not lock onto the engine-cycle sub-harmonic that real recordings and exactly periodic
+ * loops both carry. Uses up to 2 s from the middle of the take.
+ */
+export declare function firingCombRatio(samples: Float64Array, sr: number, firingHz: number): number | null;