voice-amd 1.0.0

package/src/classifier/stateMachine.js

@@ -0,0 +1,177 @@
+"use strict";
+
+const { AMD_DECISIONS, DEFAULT_CONFIG } = require("../constants/defaults");
+
+class AnsweringMachineStateMachine {
+  /**
+   * @param {Object} options
+   */
+  constructor(options = {}) {
+    this.humanMaxGreetingDurationMs =
+      options.humanMaxGreetingDurationMs ||
+      DEFAULT_CONFIG.humanMaxGreetingDurationMs;
+    this.humanSilenceConfirmationMs =
+      options.humanSilenceConfirmationMs ||
+      DEFAULT_CONFIG.humanSilenceConfirmationMs;
+    this.voicemailContinuousDurationMs =
+      options.voicemailContinuousDurationMs ||
+      DEFAULT_CONFIG.voicemailContinuousDurationMs;
+    this.maxAnalysisWindowMs =
+      options.maxAnalysisWindowMs || DEFAULT_CONFIG.maxAnalysisWindowMs;
+    this.minSpeechDurationMs =
+      options.minSpeechDurationMs || DEFAULT_CONFIG.minSpeechDurationMs;
+
+    this.reset();
+  }
+
+  reset() {
+    this.totalAnalyzedMs = 0;
+    this.consecutiveSpeechMs = 0;
+    this.consecutiveSilenceMs = 0;
+    this.totalSpeechMs = 0;
+    this.speechBursts = 0;
+    this.lastSpeechBurstDurationMs = 0;
+    this.maxSpeechBurstDurationMs = 0;
+    this.decision = AMD_DECISIONS.UNKNOWN;
+    this.decisionReason = null;
+    this.confidence = 0;
+    this.isFinal = false;
+  }
+
+  /**
+   * Step the state machine with the latest VAD observation
+   * @param {boolean} isSpeaking
+   * @param {number} frameDurationMs
+   * @returns {Object} { decision, isFinal, confidence, reason, details }
+   */
+  update(isSpeaking, frameDurationMs = 20) {
+    if (this.isFinal) {
+      return this.getResult();
+    }
+
+    this.totalAnalyzedMs += frameDurationMs;
+
+    if (isSpeaking) {
+      this.totalSpeechMs += frameDurationMs;
+      this.consecutiveSpeechMs += frameDurationMs;
+      this.consecutiveSilenceMs = 0;
+
+      // Start of a new speech burst
+      if (this.consecutiveSpeechMs === frameDurationMs) {
+        this.speechBursts++;
+      }
+      this.lastSpeechBurstDurationMs = this.consecutiveSpeechMs;
+      if (this.consecutiveSpeechMs > this.maxSpeechBurstDurationMs) {
+        this.maxSpeechBurstDurationMs = this.consecutiveSpeechMs;
+      }
+    } else {
+      this.consecutiveSilenceMs += frameDurationMs;
+
+      // Reset consecutive speech if silence is long enough to count as a natural inter-word gap
+      if (this.consecutiveSilenceMs >= 200) {
+        this.consecutiveSpeechMs = 0;
+      }
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // Rule 1: Continuous Unbroken Speech / Voicemail Monologue
+    // ─────────────────────────────────────────────────────────────
+    const isHighDensityMonologue =
+      this.totalSpeechMs >= this.voicemailContinuousDurationMs &&
+      this.consecutiveSilenceMs < this.humanSilenceConfirmationMs;
+
+    if (this.consecutiveSpeechMs >= this.voicemailContinuousDurationMs || isHighDensityMonologue) {
+      this.decision = AMD_DECISIONS.VOICEMAIL;
+      this.isFinal = true;
+      this.confidence = Math.min(
+        0.98,
+        0.88 + (this.totalSpeechMs - this.voicemailContinuousDurationMs) / 2000,
+      );
+      this.decisionReason = `Unbroken/continuous speech detected for ${this.totalSpeechMs}ms without conversational pause`;
+      return this.getResult();
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // Rule 2: Human Greeting ("Hello?" -> Silence)
+    // ─────────────────────────────────────────────────────────────
+    const peakBurst = Math.max(
+      this.lastSpeechBurstDurationMs,
+      this.maxSpeechBurstDurationMs,
+    );
+    const hasValidGreeting =
+      peakBurst >= this.minSpeechDurationMs &&
+      this.totalSpeechMs <= this.humanMaxGreetingDurationMs;
+
+    const hasSilenceConfirmation =
+      this.consecutiveSilenceMs >= this.humanSilenceConfirmationMs;
+
+    if (hasValidGreeting && hasSilenceConfirmation) {
+      this.decision = AMD_DECISIONS.HUMAN;
+      this.isFinal = true;
+      this.confidence = 0.95;
+      this.decisionReason = `Human greeting detected (${this.totalSpeechMs}ms speech followed by ${this.consecutiveSilenceMs}ms pause)`;
+      return this.getResult();
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // Rule 3: Analysis Window Expired
+    // ─────────────────────────────────────────────────────────────
+    if (this.totalAnalyzedMs >= this.maxAnalysisWindowMs) {
+      this.isFinal = true;
+
+      if (this.totalSpeechMs < this.minSpeechDurationMs) {
+        this.decision = AMD_DECISIONS.SILENCE;
+        this.confidence = 0.92;
+        this.decisionReason = `No speech detected during ${this.totalAnalyzedMs}ms analysis window`;
+      } else if (this.totalSpeechMs > 2000) {
+        this.decision = AMD_DECISIONS.VOICEMAIL;
+        this.confidence = 0.88;
+        this.decisionReason = `High total speech activity (${this.totalSpeechMs}ms) across analysis window`;
+      } else {
+        this.decision = AMD_DECISIONS.HUMAN;
+        this.confidence = 0.78;
+        this.decisionReason = `Moderate intermittent speech activity (${this.totalSpeechMs}ms) consistent with human`;
+      }
+
+      return this.getResult();
+    }
+
+    return this.getResult();
+  }
+
+  /**
+   * Manually force a decision (e.g. from Beep detector or Text pattern)
+   * @param {string} decision - "BEEP" | "VOICEMAIL" | "HUMAN"
+   * @param {string} reason
+   * @param {number} confidence
+   */
+  forceDecision(decision, reason, confidence = 1.0) {
+    this.decision = decision;
+    this.decisionReason = reason;
+    this.confidence = confidence;
+    this.isFinal = true;
+    return this.getResult();
+  }
+
+  /**
+   * Retrieve current state snapshot
+   * @returns {Object}
+   */
+  getResult() {
+    return {
+      decision: this.decision,
+      isFinal: this.isFinal,
+      confidence: this.confidence,
+      reason: this.decisionReason,
+      details: {
+        totalAnalyzedMs: this.totalAnalyzedMs,
+        totalSpeechMs: this.totalSpeechMs,
+        consecutiveSpeechMs: this.consecutiveSpeechMs,
+        consecutiveSilenceMs: this.consecutiveSilenceMs,
+        speechBursts: this.speechBursts,
+      },
+    };
+  }
+}
+
+module.exports = AnsweringMachineStateMachine;

package/src/classifier/textPatterns.js

@@ -0,0 +1,145 @@
+"use strict";
+
+const GLOBAL_CARRIER_PATTERNS = [
+  // ── Indian Telecom IVR (Hindi / Hinglish) ──
+  {
+    regex:
+      /(jis\s*vyakti|kripya\s*kuch\s*samay|doosri\s*call|vyast\s*hai|switched\s*off|network\s*kshetra|se\s*bahar|pahunch\s*se\s*door|uttar\s*nahi\s*de|kripya\s*pratiksha|call\s*(forward|forwarded|divert|diverted|kiya\s*ja\s*raha)|line\s*par\s*bane\s*rahein|dhyan\s*de|aashvast\s*karein)/i,
+    label: "INDIAN_CARRIER_HINDI",
+    confidence: 0.95,
+  },
+  // ── Indian Telecom IVR (English) ──
+  {
+    regex:
+      /(subscriber\s*is\s*(currently\s*)?(busy|switched\s*off|not\s*reachable|out\s*of\s*coverage)|(number\s*you\s*(have\s*)?(dialled|called)|dialled\s*number)\s*is\s*(busy|switched\s*off|not\s*answering|out\s*of\s*coverage)|please\s*try\s*later|call\s*has\s*been\s*(forwarded|diverted)|currently\s*speaking\s*to\s*someone\s*else|please\s*hold\s*the\s*line)/i,
+    label: "INDIAN_CARRIER_ENGLISH",
+    confidence: 0.95,
+  },
+  // ── Indian Regional Languages ──
+  // Marathi
+  {
+    regex: /(व्यस्त\s*आहे|कॉल\s*करा|कवरेज\s*क्षेत्राच्या\s*बाहेर|उत्तर\s*देत\s*नाहीत|vyasta\s*aahe|uttar\s*det\s*naahit)/i,
+    label: "INDIAN_CARRIER_MARATHI",
+    confidence: 0.95,
+  },
+  // Tamil
+  {
+    regex: /(தொடர்பு\s*எல்லைக்கு\s*வெளியே|வேறொரு\s*அழைப்பில்|busy-aga\s*irukkirar|thodarbu\s*kollavum)/i,
+    label: "INDIAN_CARRIER_TAMIL",
+    confidence: 0.95,
+  },
+  // Telugu
+  {
+    regex: /(బిజీ|స్విచ్\s*ఆఫ్|పరిధిలో\s*లేరు|మరొక\s*కాల్|busy\s*ga|switch\s*off\s*chesaru)/i,
+    label: "INDIAN_CARRIER_TELUGU",
+    confidence: 0.95,
+  },
+  // Bengali
+  {
+    regex: /(ব্যস্ত\s*আছেন|সুইচ\s*অফ|নেটওয়ার্কের\s*বাইরে|byasto\s*aachen)/i,
+    label: "INDIAN_CARRIER_BENGALI",
+    confidence: 0.95,
+  },
+  // ── Global English Voicemail & Answering Machines ──
+  {
+    regex:
+      /(leave\s*a\s*message|after\s*the\s*(tone|beep)|at\s*the\s*tone|please\s*record\s*your\s*message|voicemail\s*(box|system)|mailbox\s*is\s*full|not\s*available\s*to\s*take\s*your\s*call|record\s*your\s*name)/i,
+    label: "GLOBAL_VOICEMAIL_ENGLISH",
+    confidence: 0.98,
+  },
+  // ── Spanish (Español) ──
+  {
+    regex:
+      /(deje\s*su\s*mensaje|despu[eé]s\s*del\s*tono|buz[oó]n\s*de\s*voz|no\s*est[aá]\s*disponible|intente\s*m[aá]s\s*tarde|el\s*n[uú]mero\s*que\s*(usted\s*)?marca\s*(se\s*encuentra\s*)?est[aá]\s*ocupado|se\s*encuentra\s*ocupado)/i,
+    label: "GLOBAL_CARRIER_SPANISH",
+    confidence: 0.96,
+  },
+  // ── French (Français) ──
+  {
+    regex:
+      /(laissez\s*un\s*message|apr[eè]s\s*le\s*bip|messagerie\s*vocale|votre\s*correspondant\s*n'est\s*pas\s*joignable|veuillez\s*rappeler\s*ult[eé]rieurement)/i,
+    label: "GLOBAL_CARRIER_FRENCH",
+    confidence: 0.96,
+  },
+  // ── German (Deutsch) ──
+  {
+    regex:
+      /(hinterlassen\s*sie\s*eine\s*nachricht|nach\s*dem\s*signalton|mailbox|der\s*teilnehmer\s*ist\s*vor[uü]bergehend\s*nicht\s*erreichbar|bitte\s*versuchen\s*sie\s*es\s*sp[aä]ter)/i,
+    label: "GLOBAL_CARRIER_GERMAN",
+    confidence: 0.96,
+  },
+  // ── Portuguese (Português) ──
+  {
+    regex:
+      /(deixe\s*seu\s*recado|ap[oó]s\s*o\s*sinal|caixa\s*postal|o\s*n[uú]mero\s*est[aá]\s*ocupado|fora\s*da\s*área\s*de\s*cobertura)/i,
+    label: "GLOBAL_CARRIER_PORTUGUESE",
+    confidence: 0.96,
+  },
+  // ── Arabic (العربية) ──
+  {
+    regex:
+      /(البريد\s*الصوتي|اترك\s*رسالة|بعد\s*سماع\s*النغمة|المشترك\s*الذي\s*تطلبه\s*غير\s*متاح|مغلق\s*حاليا)/i,
+    label: "GLOBAL_CARRIER_ARABIC",
+    confidence: 0.96,
+  },
+  // ── Automated IVR Menus ──
+  {
+    regex:
+      /(press\s*(1|2|3|one|two|three|nine|zero)|for\s*english\s*press|hindi\s*ke\s*liye|main\s*menu|to\s*speak\s*to\s*our\s*executive|para\s*español\s*oprima)/i,
+    label: "IVR_MENU",
+    confidence: 0.92,
+  },
+];
+
+class TextPatternClassifier {
+  constructor() {
+    this.customPatterns = [];
+  }
+
+  /**
+   * Register custom regex patterns
+   * @param {Array<{ regex: RegExp, label: string, confidence?: number }>} patterns
+   */
+  static registerCustomPatterns(patterns) {
+    if (Array.isArray(patterns)) {
+      GLOBAL_CARRIER_PATTERNS.unshift(...patterns);
+    }
+  }
+
+  /**
+   * Check if a transcript snippet contains known answering machine / IVR phrases in any language
+   * @param {string} text
+   * @returns {Object} { isVoicemail: boolean, matchedPattern: string|null, label: string|null, confidence: number }
+   */
+  static classify(text) {
+    if (!text || typeof text !== "string") {
+      return { isVoicemail: false, matchedPattern: null, label: null, confidence: 0 };
+    }
+
+    const cleanText = text.trim();
+    if (cleanText.length === 0) {
+      return { isVoicemail: false, matchedPattern: null, label: null, confidence: 0 };
+    }
+
+    for (const item of GLOBAL_CARRIER_PATTERNS) {
+      const match = cleanText.match(item.regex);
+      if (match) {
+        return {
+          isVoicemail: true,
+          matchedPattern: match[0],
+          label: item.label,
+          confidence: item.confidence || 0.95,
+        };
+      }
+    }
+
+    return {
+      isVoicemail: false,
+      matchedPattern: null,
+      label: null,
+      confidence: 0,
+    };
+  }
+}
+
+module.exports = TextPatternClassifier;

package/src/constants/defaults.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const AMD_DECISIONS = {
+  UNKNOWN: "UNKNOWN",
+  HUMAN: "HUMAN",
+  VOICEMAIL: "VOICEMAIL",
+  BEEP: "BEEP",
+  SILENCE: "SILENCE",
+};
+
+const AUDIO_FORMATS = {
+  PCM_16K: "16kpcm",
+  PCM_8K: "8kpcm",
+  PCM_24K: "24kpcm",
+  PCM_32K: "32kpcm",
+  PCM_44K: "44.1kpcm",
+  PCM_48K: "48kpcm",
+  FLOAT_32: "float32",
+  ULAW_8K: "8kulaw",
+  ALAW_8K: "8kalaw",
+  PCM_8BIT: "8bitpcm",
+};
+
+const DEFAULT_CONFIG = {
+  // Audio format & rate
+  audioFormat: AUDIO_FORMATS.PCM_16K, // Default: 16kHz 16-bit mono linear PCM
+  sampleRate: 16000,                  // Default sample rate in Hz
+  channels: 1,                        // 1 = Mono, 2 = Stereo (auto-downmixed)
+  endianness: "LE",                   // "LE" (Little Endian) or "BE" (Big Endian)
+  frameSizeMs: 20,                    // 20ms audio frame processing
+
+  // Voice Activity Detection (VAD) thresholds
+  speechThresholdRMS: 400,            // RMS energy threshold to trigger standard speech
+  silenceThresholdRMS: 80,            // Energy below which is considered true silence
+  adaptiveNoiseFloor: true,           // Dynamically adjust noise floor for cellular PSTN noise
+  minSpeechDurationMs: 60,            // Minimum speech burst (60ms = 3 frames for brisk "Yes"/"No"/"Hi")
+
+  // Timing & Decision thresholds
+  humanMaxGreetingDurationMs: 1800,   // Human "Hello" / greeting is typically 300ms - 1800ms
+  humanSilenceConfirmationMs: 400,    // Pause after human greeting confirming listening state
+  voicemailContinuousDurationMs: 2000, // Voicemail / IVR speaks continuously for >= 2.0s without natural pause
+  maxAnalysisWindowMs: 5000,          // Total maximum time to listen before making fallback decision
+
+  // Tone / Voicemail Beep Detection (Goertzel Algorithm)
+  enableBeepDetection: true,          // Detect voicemail recording beep tones
+  beepTargetFrequencies: [1000, 950, 850, 700, 440], // Global carrier, PBX, and telecom beep frequencies (700Hz Asterisk, 950Hz US, 1000Hz standard, 440Hz UK)
+  beepMinDurationMs: 100,             // Minimum sustained tone duration
+  beepEnergyRatioThreshold: 0.80,     // Ratio of target frequency power to total frame power (sinusoid vs multi-harmonic voice)
+};
+
+module.exports = {
+  AMD_DECISIONS,
+  AUDIO_FORMATS,
+  DEFAULT_CONFIG,
+};

package/src/dsp/goertzel.js

@@ -0,0 +1,125 @@
+"use strict";
+
+const { DEFAULT_CONFIG } = require("../constants/defaults");
+const PcmUtils = require("../audio/pcmUtils");
+
+class GoertzelDetector {
+  /**
+   * @param {Object} options
+   */
+  constructor(options = {}) {
+    this.sampleRate = options.sampleRate || DEFAULT_CONFIG.sampleRate;
+    this.targetFrequencies =
+      options.beepTargetFrequencies || DEFAULT_CONFIG.beepTargetFrequencies;
+    this.energyRatioThreshold =
+      options.beepEnergyRatioThreshold ||
+      DEFAULT_CONFIG.beepEnergyRatioThreshold;
+    this.minDurationMs =
+      options.beepMinDurationMs || DEFAULT_CONFIG.beepMinDurationMs;
+
+    this.sustainedToneMs = 0;
+    this.detectedFrequency = null;
+
+    // Precalculate Goertzel coefficients for target frequencies
+    this.coefficients = {};
+    for (const freq of this.targetFrequencies) {
+      const normalizedFreq = freq / this.sampleRate;
+      this.coefficients[freq] = 2.0 * Math.cos(2.0 * Math.PI * normalizedFreq);
+    }
+  }
+
+  /**
+   * Process a 16kHz PCM audio chunk and test for single-tone beep
+   * @param {Buffer|Int16Array} chunk
+   * @param {number} chunkDurationMs
+   * @returns {Object} { isBeep, detectedFrequency, peakPowerRatio, sustainedDurationMs }
+   */
+  process(chunk, chunkDurationMs = 20) {
+    const samples = Buffer.isBuffer(chunk)
+      ? PcmUtils.pcmToInt16Array(chunk)
+      : chunk;
+
+    const N = samples.length;
+    if (N === 0) {
+      return {
+        isBeep: false,
+        detectedFrequency: null,
+        peakPowerRatio: 0,
+        sustainedDurationMs: this.sustainedToneMs,
+      };
+    }
+
+    // Calculate total energy of the chunk
+    let totalEnergy = 0;
+    for (let i = 0; i < N; i++) {
+      totalEnergy += samples[i] * samples[i];
+    }
+
+    if (totalEnergy < 1e6) {
+      // Audio chunk is too quiet to contain an audible beep tone
+      this.sustainedToneMs = 0;
+      this.detectedFrequency = null;
+      return {
+        isBeep: false,
+        detectedFrequency: null,
+        peakPowerRatio: 0,
+        sustainedDurationMs: 0,
+      };
+    }
+
+    let maxPower = 0;
+    let strongestFreq = null;
+
+    // Run Goertzel filter for each target frequency
+    for (const freq of this.targetFrequencies) {
+      const coeff = this.coefficients[freq];
+      let s_prev = 0;
+      let s_prev2 = 0;
+
+      for (let i = 0; i < N; i++) {
+        const s = samples[i] + coeff * s_prev - s_prev2;
+        s_prev2 = s_prev;
+        s_prev = s;
+      }
+
+      // Compute power at target frequency
+      const power = s_prev * s_prev + s_prev2 * s_prev2 - coeff * s_prev * s_prev2;
+
+      if (power > maxPower) {
+        maxPower = power;
+        strongestFreq = freq;
+      }
+    }
+
+    // Ratio of peak frequency power to total frame energy
+    const powerRatio = maxPower / (totalEnergy * (N / 2) + 1e-5);
+    const hasSharpTone = powerRatio >= this.energyRatioThreshold;
+
+    if (hasSharpTone) {
+      this.sustainedToneMs += chunkDurationMs;
+      this.detectedFrequency = strongestFreq;
+    } else {
+      this.sustainedToneMs = 0;
+      this.detectedFrequency = null;
+    }
+
+    const isBeep = this.sustainedToneMs >= this.minDurationMs;
+
+    return {
+      isBeep,
+      detectedFrequency: this.detectedFrequency,
+      peakPowerRatio: parseFloat(powerRatio.toFixed(3)),
+      sustainedDurationMs: this.sustainedToneMs,
+    };
+  }
+
+  /**
+   * Reset detector state
+   */
+  reset() {
+    this.sustainedToneMs = 0;
+    this.detectedFrequency = null;
+  }
+}
+
+module.exports = GoertzelDetector;