voice-amd 1.0.0

package/src/AnsweringMachineDetector.js

@@ -0,0 +1,302 @@
+"use strict";
+
+const { EventEmitter } = require("events");
+const {
+  DEFAULT_CONFIG,
+  AMD_DECISIONS,
+  AUDIO_FORMATS,
+} = require("./constants/defaults");
+const PcmUtils = require("./audio/pcmUtils");
+const VoiceActivityDetector = require("./audio/vad");
+const GoertzelDetector = require("./dsp/goertzel");
+const AnsweringMachineStateMachine = require("./classifier/stateMachine");
+const TextPatternClassifier = require("./classifier/textPatterns");
+
+class AnsweringMachineDetector extends EventEmitter {
+  /**
+   * @param {Object} options Configuration overrides
+   */
+  constructor(options = {}) {
+    super();
+
+    this.options = Object.assign({}, DEFAULT_CONFIG, options);
+
+    // Audio format & native sample rate resolution
+    this.audioFormat = this.options.audioFormat || DEFAULT_CONFIG.audioFormat;
+
+    if (options.sampleRate) {
+      this.sampleRate = options.sampleRate;
+    } else if (
+      this.audioFormat === AUDIO_FORMATS.ULAW_8K ||
+      this.audioFormat === AUDIO_FORMATS.ALAW_8K ||
+      this.audioFormat === AUDIO_FORMATS.PCM_8K
+    ) {
+      this.sampleRate = 8000;
+    } else if (this.audioFormat === AUDIO_FORMATS.PCM_24K) {
+      this.sampleRate = 24000;
+    } else if (this.audioFormat === AUDIO_FORMATS.PCM_32K) {
+      this.sampleRate = 32000;
+    } else if (this.audioFormat === AUDIO_FORMATS.PCM_44K) {
+      this.sampleRate = 44100;
+    } else if (this.audioFormat === AUDIO_FORMATS.PCM_48K) {
+      this.sampleRate = 48000;
+    } else {
+      this.sampleRate = 16000;
+    }
+
+    this.frameSizeMs = this.options.frameSizeMs || 20;
+
+    // Native frame calculations (Zero Resampling!)
+    // 16-bit linear PCM has 2 bytes per sample
+    this.bytesPerMs = (this.sampleRate * 2) / 1000;
+    this.bytesPerFrame = this.bytesPerMs * this.frameSizeMs;
+
+    // Submodules (configured for native sample rate)
+    const subOptions = Object.assign({}, this.options, {
+      sampleRate: this.sampleRate,
+    });
+    this.vad = new VoiceActivityDetector(subOptions);
+    this.stateMachine = new AnsweringMachineStateMachine(subOptions);
+
+    if (this.options.enableBeepDetection) {
+      this.beepDetector = new GoertzelDetector(subOptions);
+    } else {
+      this.beepDetector = null;
+    }
+
+    // Residual audio buffer for frame alignment
+    this.audioBuffer = Buffer.alloc(0);
+
+    // Activity flags
+    this.wasSpeaking = false;
+    this.currentSpeechDurationMs = 0;
+    this.hasDecided = false;
+    this.lastDecision = null;
+  }
+
+  /**
+   * Process a single incoming chunk of audio (Buffer or base64 string)
+   * Natively processes at the audio's original sample rate with zero resampling.
+   *
+   * @param {Buffer|string} chunk
+   * @returns {Object} Current decision status
+   */
+  processChunk(chunk) {
+    if (this.hasDecided) {
+      return this.stateMachine.getResult();
+    }
+
+    if (!chunk) return this.stateMachine.getResult();
+
+    // 1. Decode non-linear codecs to 16-bit PCM at native sample rate (Zero Resampling)
+    const nativePcm16 = PcmUtils.decodeToNativePcm16(chunk, {
+      audioFormat: this.audioFormat,
+      channels: this.options.channels,
+      endianness: this.options.endianness,
+    });
+
+    // 2. Append to accumulator buffer
+    this.audioBuffer = Buffer.concat([this.audioBuffer, nativePcm16]);
+
+    // 3. Process complete fixed-size native frames (e.g. 20ms at native rate)
+    while (this.audioBuffer.length >= this.bytesPerFrame && !this.hasDecided) {
+      const frame = this.audioBuffer.subarray(0, this.bytesPerFrame);
+      this.audioBuffer = this.audioBuffer.subarray(this.bytesPerFrame);
+
+      this._processFrame(frame);
+    }
+
+    return this.stateMachine.getResult();
+  }
+
+  /**
+   * Process a single aligned native audio frame
+   * @private
+   * @param {Buffer} frame - Native 20ms 16-bit linear PCM frame
+   */
+  _processFrame(frame) {
+    const frameMs = this.frameSizeMs;
+
+    // 1. Run Tone / Beep Detector at native sample rate
+    if (this.beepDetector) {
+      const beepResult = this.beepDetector.process(frame, frameMs);
+      if (beepResult.isBeep) {
+        const result = this.stateMachine.forceDecision(
+          AMD_DECISIONS.BEEP,
+          `Voicemail beep tone detected (${beepResult.detectedFrequency}Hz)`,
+          0.99,
+        );
+        this._finalizeDecision(result, {
+          frequency: beepResult.detectedFrequency,
+        });
+        return;
+      }
+    }
+
+    // 2. Run Voice Activity Detector at native sample rate
+    const vadResult = this.vad.analyze(frame);
+
+    // 3. Emit granular speech transition events
+    if (vadResult.isSpeaking && !this.wasSpeaking) {
+      this.wasSpeaking = true;
+      this.currentSpeechDurationMs = 0;
+      this.emit("speech_start", {
+        rms: vadResult.rms,
+        snr: vadResult.snr,
+        zcrFrequencyHz: vadResult.zcrFrequencyHz,
+        timestamp: Date.now(),
+      });
+    } else if (!vadResult.isSpeaking && this.wasSpeaking) {
+      this.wasSpeaking = false;
+      this.emit("speech_end", {
+        durationMs: this.currentSpeechDurationMs,
+        timestamp: Date.now(),
+      });
+    }
+
+    if (vadResult.isSpeaking) {
+      this.currentSpeechDurationMs += frameMs;
+    }
+
+    // 4. Update State Machine
+    const smResult = this.stateMachine.update(vadResult.isSpeaking, frameMs);
+
+    if (smResult.isFinal) {
+      this._finalizeDecision(smResult);
+    }
+  }
+
+  /**
+   * Process an optional text transcript snippet (e.g. from an ASR/STT provider)
+   * to immediately detect carrier IVR phrases.
+   * @param {string} text
+   * @returns {Object|null}
+   */
+  processTranscript(text) {
+    if (this.hasDecided || !text) return this.stateMachine.getResult();
+
+    const classification = TextPatternClassifier.classify(text);
+    if (classification.isVoicemail) {
+      const result = this.stateMachine.forceDecision(
+        AMD_DECISIONS.VOICEMAIL,
+        `Carrier IVR phrase detected: "${classification.matchedPattern}" (${classification.label})`,
+        classification.confidence,
+      );
+      this._finalizeDecision(result, {
+        transcriptMatch: classification.matchedPattern,
+        label: classification.label,
+      });
+      return result;
+    }
+
+    return null;
+  }
+
+  /**
+   * Finalize the decision, emit events, and freeze processing
+   * @private
+   * @param {Object} result
+   * @param {Object} extraDetails
+   */
+  _finalizeDecision(result, extraDetails = {}) {
+    if (this.hasDecided) return;
+
+    this.hasDecided = true;
+    this.lastDecision = Object.assign({}, result, { extra: extraDetails });
+
+    // Emit generic decision event
+    this.emit("decision", {
+      type: result.decision,
+      confidence: result.confidence,
+      reason: result.reason,
+      details: result.details,
+      extra: extraDetails,
+    });
+
+    // Emit specific convenience events
+    switch (result.decision) {
+      case AMD_DECISIONS.HUMAN:
+        this.emit("human", {
+          confidence: result.confidence,
+          reason: result.reason,
+          details: result.details,
+        });
+        break;
+
+      case AMD_DECISIONS.VOICEMAIL:
+        this.emit("voicemail", {
+          confidence: result.confidence,
+          reason: result.reason,
+          details: result.details,
+          extra: extraDetails,
+        });
+        break;
+
+      case AMD_DECISIONS.BEEP:
+        this.emit("beep", {
+          confidence: result.confidence,
+          frequency: extraDetails.frequency,
+          reason: result.reason,
+          details: result.details,
+        });
+        break;
+
+      case AMD_DECISIONS.SILENCE:
+        this.emit("silence", {
+          confidence: result.confidence,
+          reason: result.reason,
+          details: result.details,
+        });
+        break;
+    }
+  }
+
+  /**
+   * Node.js Stream / Transform write alias
+   * @param {Buffer|string} chunk
+   */
+  write(chunk) {
+    this.processChunk(chunk);
+    return true;
+  }
+
+  /**
+   * Node.js Stream end alias
+   */
+  end() {
+    if (!this.hasDecided) {
+      const result = this.stateMachine.update(
+        false,
+        this.options.maxAnalysisWindowMs,
+      );
+      if (result.isFinal) {
+        this._finalizeDecision(result);
+      }
+    }
+    this.emit("finish");
+  }
+
+  /**
+   * Retrieve current decision state
+   * @returns {Object}
+   */
+  getDecision() {
+    return this.stateMachine.getResult();
+  }
+
+  /**
+   * Reset detector for a new call
+   */
+  reset() {
+    this.audioBuffer = Buffer.alloc(0);
+    this.wasSpeaking = false;
+    this.currentSpeechDurationMs = 0;
+    this.hasDecided = false;
+    this.lastDecision = null;
+    this.vad.reset();
+    this.stateMachine.reset();
+    if (this.beepDetector) this.beepDetector.reset();
+  }
+}
+
+module.exports = AnsweringMachineDetector;

package/src/audio/pcmUtils.js

@@ -0,0 +1,198 @@
+"use strict";
+
+const { AUDIO_FORMATS } = require("../constants/defaults");
+
+// Precomputed µ-law expansion table for 16-bit linear PCM (G.711u)
+const ULAW_TO_PCM16_TABLE = new Int16Array(256);
+for (let i = 0; i < 256; i++) {
+  let u = ~i;
+  let sign = u & 0x80;
+  let exponent = (u >> 4) & 0x07;
+  let mantissa = u & 0x0f;
+  let sample = ((mantissa << 3) + 0x84) << exponent;
+  sample -= 0x84;
+  ULAW_TO_PCM16_TABLE[i] = sign ? -sample : sample;
+}
+
+// Precomputed A-law expansion table for 16-bit linear PCM (G.711a)
+const ALAW_TO_PCM16_TABLE = new Int16Array(256);
+for (let i = 0; i < 256; i++) {
+  let a = i ^ 0x55;
+  let sign = a & 0x80;
+  let exponent = (a >> 4) & 0x07;
+  let mantissa = a & 0x0f;
+  let sample = 0;
+  if (exponent === 0) {
+    sample = (mantissa << 4) + 8;
+  } else {
+    sample = ((mantissa << 4) + 0x108) << (exponent - 1);
+  }
+  ALAW_TO_PCM16_TABLE[i] = sign ? -sample : sample;
+}
+
+class PcmUtils {
+  /**
+   * Ensure input is a Node.js Buffer
+   * @param {Buffer|string} input
+   * @returns {Buffer}
+   */
+  static toBuffer(input) {
+    if (Buffer.isBuffer(input)) return input;
+    if (typeof input === "string") return Buffer.from(input, "base64");
+    throw new TypeError("Audio input must be a Buffer or base64 string");
+  }
+
+  /**
+   * Convert 8kHz µ-law (G.711u) buffer to 16-bit linear PCM (keeps native 8kHz)
+   * @param {Buffer} ulawBuf
+   * @returns {Buffer}
+   */
+  static ulawToPcm16(ulawBuf) {
+    const pcmBuf = Buffer.alloc(ulawBuf.length * 2);
+    for (let i = 0; i < ulawBuf.length; i++) {
+      const sample = ULAW_TO_PCM16_TABLE[ulawBuf[i]];
+      pcmBuf.writeInt16LE(sample, i * 2);
+    }
+    return pcmBuf;
+  }
+
+  /**
+   * Convert 8kHz A-law (G.711a) buffer to 16-bit linear PCM (keeps native 8kHz)
+   * @param {Buffer} alawBuf
+   * @returns {Buffer}
+   */
+  static alawToPcm16(alawBuf) {
+    const pcmBuf = Buffer.alloc(alawBuf.length * 2);
+    for (let i = 0; i < alawBuf.length; i++) {
+      const sample = ALAW_TO_PCM16_TABLE[alawBuf[i]];
+      pcmBuf.writeInt16LE(sample, i * 2);
+    }
+    return pcmBuf;
+  }
+
+  /**
+   * Convert 32-bit Float PCM (-1.0 to 1.0) to 16-bit linear PCM (keeps native sample rate)
+   * @param {Buffer} floatBuf
+   * @param {string} endianness - "LE" | "BE"
+   * @returns {Buffer}
+   */
+  static float32ToPcm16(floatBuf, endianness = "LE") {
+    const numSamples = Math.floor(floatBuf.length / 4);
+    const pcmBuf = Buffer.alloc(numSamples * 2);
+
+    for (let i = 0; i < numSamples; i++) {
+      const floatVal =
+        endianness === "BE"
+          ? floatBuf.readFloatBE(i * 4)
+          : floatBuf.readFloatLE(i * 4);
+
+      const clamped = Math.max(-1.0, Math.min(1.0, floatVal));
+      const int16 =
+        clamped < 0 ? Math.round(clamped * 32768) : Math.round(clamped * 32767);
+
+      pcmBuf.writeInt16LE(int16, i * 2);
+    }
+
+    return pcmBuf;
+  }
+
+  /**
+   * Convert 8-bit unsigned PCM (0-255) to 16-bit linear PCM (keeps native sample rate)
+   * @param {Buffer} pcm8Buf
+   * @returns {Buffer}
+   */
+  static pcm8bitToPcm16(pcm8Buf) {
+    const pcmBuf = Buffer.alloc(pcm8Buf.length * 2);
+    for (let i = 0; i < pcm8Buf.length; i++) {
+      const sample = (pcm8Buf[i] - 128) << 8;
+      pcmBuf.writeInt16LE(sample, i * 2);
+    }
+    return pcmBuf;
+  }
+
+  /**
+   * Downmix 2-channel Stereo 16-bit PCM to Mono (keeps native sample rate)
+   * @param {Buffer} stereoBuf
+   * @returns {Buffer}
+   */
+  static downmixStereoToMono(stereoBuf) {
+    const numFrames = Math.floor(stereoBuf.length / 4);
+    const monoBuf = Buffer.alloc(numFrames * 2);
+
+    for (let i = 0; i < numFrames; i++) {
+      const left = stereoBuf.readInt16LE(i * 4);
+      const right = stereoBuf.readInt16LE(i * 4 + 2);
+      const mixed = Math.round((left + right) / 2);
+      monoBuf.writeInt16LE(mixed, i * 2);
+    }
+
+    return monoBuf;
+  }
+
+  /**
+   * Convert any audio format to 16-bit linear PCM at its NATIVE sample rate (Zero-Resampling)
+   * @param {Buffer|string} input - Audio data
+   * @param {Object|string} options - Format string or options { audioFormat, channels, endianness }
+   * @returns {Buffer} 16-bit linear PCM at native sample rate
+   */
+  static decodeToNativePcm16(input, options = {}) {
+    let buf = this.toBuffer(input);
+
+    let format = AUDIO_FORMATS.PCM_16K;
+    let channels = 1;
+    let endianness = "LE";
+
+    if (typeof options === "string") {
+      format = options;
+    } else if (typeof options === "object") {
+      format = options.audioFormat || format;
+      channels = options.channels || channels;
+      endianness = options.endianness || endianness;
+    }
+
+    let pcm16;
+    switch (format) {
+      case AUDIO_FORMATS.ULAW_8K:
+        pcm16 = this.ulawToPcm16(buf);
+        break;
+
+      case AUDIO_FORMATS.ALAW_8K:
+        pcm16 = this.alawToPcm16(buf);
+        break;
+
+      case AUDIO_FORMATS.FLOAT_32:
+        pcm16 = this.float32ToPcm16(buf, endianness);
+        break;
+
+      case AUDIO_FORMATS.PCM_8BIT:
+        pcm16 = this.pcm8bitToPcm16(buf);
+        break;
+
+      default:
+        pcm16 = buf;
+        break;
+    }
+
+    if (channels === 2) {
+      pcm16 = this.downmixStereoToMono(pcm16);
+    }
+
+    return pcm16;
+  }
+
+  /**
+   * Extract Int16Array of samples from a 16-bit PCM Buffer
+   * @param {Buffer} pcmBuf
+   * @returns {Int16Array}
+   */
+  static pcmToInt16Array(pcmBuf) {
+    const sampleCount = Math.floor(pcmBuf.length / 2);
+    const samples = new Int16Array(sampleCount);
+    for (let i = 0; i < sampleCount; i++) {
+      samples[i] = pcmBuf.readInt16LE(i * 2);
+    }
+    return samples;
+  }
+}
+
+module.exports = PcmUtils;

package/src/audio/vad.js

@@ -0,0 +1,138 @@
+"use strict";
+
+const { DEFAULT_CONFIG } = require("../constants/defaults");
+const PcmUtils = require("./pcmUtils");
+
+class VoiceActivityDetector {
+  /**
+   * @param {Object} options
+   */
+  constructor(options = {}) {
+    this.sampleRate = options.sampleRate || DEFAULT_CONFIG.sampleRate;
+    this.speechThresholdRMS =
+      options.speechThresholdRMS || DEFAULT_CONFIG.speechThresholdRMS;
+    this.silenceThresholdRMS =
+      options.silenceThresholdRMS || DEFAULT_CONFIG.silenceThresholdRMS;
+    this.adaptiveNoiseFloor =
+      options.adaptiveNoiseFloor !== undefined
+        ? options.adaptiveNoiseFloor
+        : DEFAULT_CONFIG.adaptiveNoiseFloor;
+
+    // Noise floor initialized to a clean baseline (80)
+    this.noiseFloor = this.silenceThresholdRMS;
+    this.noiseAlpha = 0.08;
+
+    // Hangover smoothing to bridge consonant-vowel transitions (40ms)
+    this.hangoverFrames = 0;
+    this.maxHangoverFrames = 2;
+  }
+
+  /**
+   * Analyze a 16-bit linear PCM audio chunk at its native sample rate
+   * @param {Buffer|Int16Array} chunk - 16-bit linear PCM chunk
+   * @returns {Object} { isSpeaking, rms, zcr, zcrFrequencyHz, snr, noiseFloor }
+   */
+  analyze(chunk) {
+    const samples = Buffer.isBuffer(chunk)
+      ? PcmUtils.pcmToInt16Array(chunk)
+      : chunk;
+
+    const N = samples.length;
+    if (N === 0) {
+      return {
+        isSpeaking: false,
+        rms: 0,
+        zcr: 0,
+        zcrFrequencyHz: 0,
+        snr: 0,
+        noiseFloor: this.noiseFloor,
+      };
+    }
+
+    // 1. Calculate DC Bias / Mean of the Frame
+    let sum = 0;
+    for (let i = 0; i < N; i++) {
+      sum += samples[i];
+    }
+    const mean = sum / N;
+
+    // 2. AC-Coupled RMS Energy and Zero-Crossing Rate (removes hardware DC bias)
+    let sumSquares = 0;
+    let zeroCrossings = 0;
+    let prevSample = 0;
+
+    for (let i = 0; i < N; i++) {
+      const acSample = samples[i] - mean;
+      sumSquares += acSample * acSample;
+
+      if (i > 0) {
+        if (
+          (acSample >= 0 && prevSample < 0) ||
+          (acSample < 0 && prevSample >= 0)
+        ) {
+          zeroCrossings++;
+        }
+      }
+      prevSample = acSample;
+    }
+
+    const rms = Math.sqrt(sumSquares / N);
+    const zcr = parseFloat((zeroCrossings / N).toFixed(4));
+    // Physical zero-crossing frequency in Hz
+    const zcrFrequencyHz = Math.round(
+      (zeroCrossings * this.sampleRate) / (2 * N),
+    );
+
+    // 3. Adaptive Noise Floor Tracking
+    if (this.adaptiveNoiseFloor) {
+      if (rms < this.speechThresholdRMS * 0.7) {
+        this.noiseFloor =
+          this.noiseFloor * (1 - this.noiseAlpha) + rms * this.noiseAlpha;
+      }
+    }
+
+    // Signal-to-Noise Ratio (SNR) in dB
+    const snr =
+      this.noiseFloor > 0
+        ? 20 * Math.log10((rms + 1e-5) / Math.max(1, this.noiseFloor))
+        : 0;
+
+    // 4. Multi-Feature Speech Decision
+    const isHumanSpectralRange =
+      zcrFrequencyHz >= 50 && zcrFrequencyHz <= 6000;
+
+    // High energy speech (vowels)
+    const isHighEnergy = rms >= this.speechThresholdRMS && isHumanSpectralRange;
+    // Distinct voice with solid SNR above ambient noise floor
+    const isDistinctVoice = rms >= 140 && snr >= 4.0 && isHumanSpectralRange;
+
+    let isRawSpeaking = isHighEnergy || isDistinctVoice;
+
+    // 5. Hangover smoothing for natural speech continuation
+    if (isRawSpeaking) {
+      this.hangoverFrames = this.maxHangoverFrames;
+    } else if (this.hangoverFrames > 0) {
+      this.hangoverFrames--;
+      isRawSpeaking = true;
+    }
+
+    return {
+      isSpeaking: isRawSpeaking,
+      rms: Math.round(rms),
+      zcr,
+      zcrFrequencyHz,
+      snr: parseFloat(snr.toFixed(2)),
+      noiseFloor: Math.round(this.noiseFloor),
+    };
+  }
+
+  /**
+   * Reset noise floor tracking and hangover
+   */
+  reset() {
+    this.noiseFloor = this.silenceThresholdRMS;
+    this.hangoverFrames = 0;
+  }
+}
+
+module.exports = VoiceActivityDetector;