@entros/pulse-sdk 2.0.0 → 3.0.0

package/dist/index.mjs

@@ -47,6 +47,25 @@ function sdkWarn(...args) {
 
 // src/sensor/audio.ts
 var TARGET_SAMPLE_RATE = 16e3;
+var TARGET_CAPTURE_RMS = 0.05;
+var MIN_RMS_FOR_NORMALIZATION = 1e-4;
+var MAX_NORMALIZATION_GAIN = 50;
+function normalizeCaptureRMS(samples) {
+  if (samples.length === 0) return samples;
+  let sumSq = 0;
+  for (let i = 0; i < samples.length; i++) {
+    const s = samples[i];
+    sumSq += s * s;
+  }
+  const rms = Math.sqrt(sumSq / samples.length);
+  if (rms < MIN_RMS_FOR_NORMALIZATION) return samples;
+  const gain = Math.min(TARGET_CAPTURE_RMS / rms, MAX_NORMALIZATION_GAIN);
+  const out = new Float32Array(samples.length);
+  for (let i = 0; i < samples.length; i++) {
+    out[i] = Math.max(-1, Math.min(1, samples[i] * gain));
+  }
+  return out;
+}
 async function captureAudio(options = {}) {
   const {
     signal,
@@ -134,8 +153,9 @@ async function captureAudio(options = {}) {
         samples.set(chunk, offset);
         offset += chunk.length;
       }
+      const normalized = normalizeCaptureRMS(samples);
       resolve({
-        samples,
+        samples: normalized,
         sampleRate: capturedSampleRate,
         duration: totalLength / capturedSampleRate
       });
@@ -310,6 +330,9 @@ function variance(values, mu) {
   for (const v of values) sum += (v - m) ** 2;
   return sum / (values.length - 1);
 }
+var SKEWNESS_BOUND = 20;
+var KURTOSIS_LOWER = 0;
+var KURTOSIS_UPPER = 50;
 function skewness(values) {
   if (values.length < 3) return 0;
   const n = values.length;
@@ -318,7 +341,8 @@ function skewness(values) {
   if (s === 0) return 0;
   let sum = 0;
   for (const v of values) sum += ((v - m) / s) ** 3;
-  return n / ((n - 1) * (n - 2)) * sum;
+  const raw = n / ((n - 1) * (n - 2)) * sum;
+  return Math.max(-SKEWNESS_BOUND, Math.min(SKEWNESS_BOUND, raw));
 }
 function kurtosis(values) {
   if (values.length < 4) return 0;
@@ -329,7 +353,7 @@ function kurtosis(values) {
   let sum = 0;
   for (const v of values) sum += (v - m) ** 4 / s2 ** 2;
   const k = n * (n + 1) / ((n - 1) * (n - 2) * (n - 3)) * sum - 3 * (n - 1) ** 2 / ((n - 2) * (n - 3));
-  return k;
+  return Math.max(KURTOSIS_LOWER, Math.min(KURTOSIS_UPPER, k));
 }
 function condense(values) {
   const m = mean(values);
@@ -590,9 +614,20 @@ function extractLpcAnalysis(samples, sampleRate, frameSize, hopSize, lpcOrder =
 
 // src/extraction/mfcc.ts
 var NUM_MFCC_COEFFICIENTS = 13;
+var MFCC_DROP_LEADING = 1;
+var NUM_USED_MFCC = NUM_MFCC_COEFFICIENTS - MFCC_DROP_LEADING;
 var DELTA_REGRESSION_HALF_WIDTH = 2;
-var MFCC_FEATURE_COUNT = NUM_MFCC_COEFFICIENTS * 4 + // mean, var, skew, kurt per coefficient
-NUM_MFCC_COEFFICIENTS * 2;
+var MFCC_FEATURE_COUNT = NUM_USED_MFCC * 4 + // mean, var, skew, kurt per coefficient
+NUM_USED_MFCC * 2;
+function applyPreEmphasis(samples) {
+  const out = new Float32Array(samples.length);
+  if (samples.length === 0) return out;
+  out[0] = samples[0];
+  for (let i = 1; i < samples.length; i++) {
+    out[i] = samples[i] - 0.97 * samples[i - 1];
+  }
+  return out;
+}
 function computeDelta(series, halfWidth) {
   const n = series.length;
   const out = new Array(n);
@@ -642,15 +677,16 @@ async function extractMfccFeatures(samples, sampleRate, frameSize, hopSize) {
     return new Array(MFCC_FEATURE_COUNT).fill(0);
   }
   const mfccTracks = Array.from(
-    { length: NUM_MFCC_COEFFICIENTS },
+    { length: NUM_USED_MFCC },
     () => []
   );
   const frame = new Float32Array(frameSize);
   Meyda.bufferSize = frameSize;
   Meyda.sampleRate = sampleRate;
+  const emphasized = applyPreEmphasis(samples);
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
-    frame.set(samples.subarray(start, start + frameSize), 0);
+    frame.set(emphasized.subarray(start, start + frameSize), 0);
     const result = Meyda.extract("mfcc", frame);
     if (!Array.isArray(result) || result.length !== NUM_MFCC_COEFFICIENTS) {
       continue;
@@ -663,21 +699,21 @@ async function extractMfccFeatures(samples, sampleRate, frameSize, hopSize) {
       }
     }
     if (!allFinite) continue;
-    for (let c = 0; c < NUM_MFCC_COEFFICIENTS; c++) {
-      mfccTracks[c].push(result[c]);
+    for (let c = 0; c < NUM_USED_MFCC; c++) {
+      mfccTracks[c].push(result[c + MFCC_DROP_LEADING]);
     }
   }
   const out = [];
   out.length = MFCC_FEATURE_COUNT;
   let writeIdx = 0;
-  for (let c = 0; c < NUM_MFCC_COEFFICIENTS; c++) {
+  for (let c = 0; c < NUM_USED_MFCC; c++) {
     const stats = condense(mfccTracks[c]);
     out[writeIdx++] = stats.mean;
     out[writeIdx++] = stats.variance;
     out[writeIdx++] = stats.skewness;
     out[writeIdx++] = stats.kurtosis;
   }
-  for (let c = 0; c < NUM_MFCC_COEFFICIENTS; c++) {
+  for (let c = 0; c < NUM_USED_MFCC; c++) {
     const delta = computeDelta(mfccTracks[c], DELTA_REGRESSION_HALF_WIDTH);
     const muDelta = mean(delta);
     out[writeIdx++] = muDelta;
@@ -1196,9 +1232,9 @@ async function extractSpeakerFeaturesDetailed(audio) {
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
     let sum = 0;
-    const end = Math.min(start + frameSize, samples.length);
+    const end = Math.min(start + frameSize, normalizedSamples.length);
     for (let j = start; j < end; j++) {
-      sum += (samples[j] ?? 0) * (samples[j] ?? 0);
+      sum += (normalizedSamples[j] ?? 0) * (normalizedSamples[j] ?? 0);
     }
     amplitudes.push(Math.sqrt(sum / (end - start)));
   }
@@ -1307,15 +1343,15 @@ async function extractSpeakerFeaturesDetailed(audio) {
     ...ampFeatures,
     // 5     [39..44]  AMPLITUDE
     ...mfccFeatures,
-    // 78    [44..122] MFCC + delta-MFCC
+    // 72    [44..116] MFCC + delta-MFCC (MFCC[0] dropped)
     ...lpcStats,
-    // 24    [122..146] LPC coefficient stats
+    // 24    [116..140] LPC coefficient stats
     ...formantTrajectoryFeatures,
-    // 16    [146..162] Formant absolutes + dynamics + bandwidths
+    // 16    [140..156] Formant absolutes + dynamics + bandwidths
     ...voiceQualityFeatures,
-    // 9     [162..171] Voice quality
+    // 9     [156..165] Voice quality
     ...pitchShapeFeatures
-    // 5     [171..176] Pitch contour shape DCT
+    // 5     [165..170] Pitch contour shape DCT
   ];
   return { features, f0Contour: f0 };
 }
@@ -1841,8 +1877,61 @@ function extractMouseDynamics(samples) {
     angleAutoCorr[2] ?? 0,
     normalizedPathLength
   ];
-  const padding = MOUSE_DYNAMICS_FEATURE_COUNT - legacyMouseDynamics.length;
-  return padding > 0 ? [...legacyMouseDynamics, ...new Array(padding).fill(0)] : legacyMouseDynamics;
+  const v2 = computeMouseV2(samples, vx, vy, accX, accY, speed, acc, jerk, directions);
+  return [...legacyMouseDynamics, ...v2];
+}
+function computeMouseV2(samples, vx, vy, accX, accY, speed, acc, jerk, directions) {
+  const out = [];
+  const covPairs = [
+    [vx, vy],
+    [vx, accX],
+    [vx, accY],
+    [vy, accX],
+    [vy, accY],
+    [accX, accY]
+  ];
+  for (const [a, b] of covPairs) out.push(covariance(a, b));
+  const sampleRate = sampleRateFromTimestamps(samples.map((s) => s.timestamp));
+  const fftSize = nextPow2(Math.max(64, speed.length));
+  const bands = [
+    [0, 2],
+    [2, 6],
+    [6, 12],
+    [12, 30]
+  ];
+  const speedSpectrum = realFFT(meanCenter(speed), fftSize);
+  const accSpectrum = realFFT(meanCenter(acc), fftSize);
+  const jerkSpectrum = realFFT(meanCenter(jerk), fftSize);
+  for (const spectrum of [speedSpectrum, accSpectrum, jerkSpectrum]) {
+    for (const [lo, hi] of bands) {
+      out.push(bandEnergy(spectrum.real, spectrum.imag, sampleRate, lo, hi));
+    }
+  }
+  const tremor = peakInBand(
+    speedSpectrum.real,
+    speedSpectrum.imag,
+    sampleRate,
+    4,
+    12
+  );
+  out.push(tremor.freq, tremor.amplitude);
+  const duration = captureDurationSec(samples);
+  const reversalRates = [vx, vy, speed].map(
+    (channel) => duration > 0 ? signChangeCount(derivative2(channel)) / duration : 0
+  );
+  out.push(mean(reversalRates), variance(reversalRates));
+  let dirAccum = 0;
+  for (let i = 1; i < directions.length; i++) {
+    let diff = directions[i] - directions[i - 1];
+    while (diff > Math.PI) diff -= 2 * Math.PI;
+    while (diff < -Math.PI) diff += 2 * Math.PI;
+    dirAccum += Math.abs(diff);
+  }
+  out.push(directions.length > 1 ? dirAccum / (directions.length - 1) : 0);
+  for (const lag of [1, 5, 10, 25]) {
+    out.push(autocorrelation(speed, lag));
+  }
+  return out.map((v) => Number.isFinite(v) ? v : 0);
 }
 
 // src/hashing/simhash.ts