@ai-coustics/aic-sdk 0.12.0 → 0.13.0

package/README.md

@@ -1,10 +1,11 @@
-# ai-coustics Speech Enhancement SDK for Node.js
+# aic-sdk - Node.js Bindings for ai-coustics SDK
 
-Node.js bindings for the ai-coustics Speech Enhancement SDK.
+Node.js wrapper for the ai-coustics Speech Enhancement SDK.
 
-## Prerequisites
+For comprehensive documentation, visit [docs.ai-coustics.com](https://docs.ai-coustics.com).
 
-- SDK license key from [ai-coustics Developer Portal](https://developers.ai-coustics.io)
+> [!NOTE]
+> This SDK requires a license key. Generate your key at [developers.ai-coustics.io](https://developers.ai-coustics.io).
 
 ## Installation
 
@@ -12,63 +13,162 @@ Node.js bindings for the ai-coustics Speech Enhancement SDK.
 npm install @ai-coustics/aic-sdk
 ```
 
-### Supported Platforms
+## Quick Start
 
-- Linux: x64, ARM64 (GNU libc)
-- macOS: x64, ARM64
-- Windows: x64, ARM64 (MSVC)
+```javascript
+const { Model, Processor } = require("@ai-coustics/aic-sdk");
+
+// Get your license key from the environment variable
+const licenseKey = process.env.AIC_SDK_LICENSE;
+
+// Download and load a model (or download manually at https://artifacts.ai-coustics.io/)
+const modelPath = Model.download("sparrow-xxs-48khz", "./models");
+const model = Model.fromFile(modelPath);
+
+// Get optimal configuration
+const sampleRate = model.getOptimalSampleRate();
+const numFrames = model.getOptimalNumFrames(sampleRate);
+const numChannels = 2;
+
+// Create and initialize processor
+const processor = new Processor(model, licenseKey);
+processor.initialize(sampleRate, numChannels, numFrames, false);
+
+// Process audio (Float32Array, interleaved: [L0, R0, L1, R1, ...])
+const audioBuffer = new Float32Array(numChannels * numFrames);
+processor.processInterleaved(audioBuffer);
+```
+
+## Usage
+
+### SDK Information
+
+```javascript
+const { getVersion, getCompatibleModelVersion } = require("@ai-coustics/aic-sdk");
+
+// Get SDK version
+console.log(`SDK version: ${getVersion()}`);
 
-## Example
+// Get compatible model version
+console.log(`Compatible model version: ${getCompatibleModelVersion()}`);
+```
+
+### Loading Models
+
+Download models and find available IDs at [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io/).
+
+#### From File
+```javascript
+const model = Model.fromFile("path/to/model.aicmodel");
+```
 
+#### Download from CDN
 ```javascript
-const { Model, ModelType, EnhancementParameter } = require('@ai-coustics/aic-sdk');
+const modelPath = Model.download("sparrow-xxs-48khz", "./models");
+const model = Model.fromFile(modelPath);
+```
+
+### Model Information
+
+```javascript
+// Get model ID
+const modelId = model.getId();
 
-const model = new Model(ModelType.QuailS48, process.env.AIC_SDK_LICENSE);
+// Get optimal sample rate for the model
+const optimalRate = model.getOptimalSampleRate();
 
-// Get optimal settings
-const sampleRate = model.optimalSampleRate();
-const numFrames = model.optimalNumFrames(sampleRate);
+// Get optimal frame count for a specific sample rate
+const optimalFrames = model.getOptimalNumFrames(48000);
+```
 
-// Initialize for stereo audio
-model.initialize(sampleRate, 2, numFrames, false);
+### Configuring the Processor
+
+```javascript
+// Create processor
+const processor = new Processor(model, licenseKey);
+
+// Initialize with audio settings
+processor.initialize(
+  sampleRate,           // Sample rate in Hz (8000 - 192000)
+  numChannels,          // Number of audio channels
+  numFrames,            // Samples per channel per processing call
+  allowVariableFrames   // Allow variable frame sizes (default: false)
+);
+```
+
+### Processing Audio
+
+```javascript
+// Interleaved audio: [L0, R0, L1, R1, ...]
+const buffer = new Float32Array(numChannels * numFrames);
+processor.processInterleaved(buffer);
+
+// Sequential audio: [L0, L1, ..., R0, R1, ...]
+processor.processSequential(buffer);
+
+// Planar audio: separate buffer per channel
+const left = new Float32Array(numFrames);
+const right = new Float32Array(numFrames);
+processor.processPlanar([left, right]);
+```
+
+### Processor Context
+
+```javascript
+const { ProcessorParameter } = require("@ai-coustics/aic-sdk");
+
+// Get processor context
+const procCtx = processor.getProcessorContext();
+
+// Get output delay in samples
+const delay = procCtx.getOutputDelay();
+
+// Reset processor state (clears internal buffers)
+procCtx.reset();
 
 // Set enhancement parameters
-model.setParameter(EnhancementParameter.EnhancementLevel, 0.7);
-model.setParameter(EnhancementParameter.VoiceGain, 1.5);
-
-// Process interleaved audio
-const interleavedBuffer = new Float32Array(2 * numFrames);
-model.processInterleaved(interleavedBuffer, 2, numFrames);
-
-// Or process planar audio
-const planarBuffers = [
-  new Float32Array(numFrames), // Left channel
-  new Float32Array(numFrames), // Right channel
-];
-model.processPlanar(planarBuffers);
+procCtx.setParameter(ProcessorParameter.EnhancementLevel, 0.8);
+procCtx.setParameter(ProcessorParameter.VoiceGain, 1.5);
+procCtx.setParameter(ProcessorParameter.Bypass, 0.0);
+
+// Get parameter values
+const level = procCtx.getParameter(ProcessorParameter.EnhancementLevel);
+console.log(`Enhancement level: ${level}`);
+```
+
+### Voice Activity Detection (VAD)
+
+```javascript
+const { VadParameter } = require("@ai-coustics/aic-sdk");
+
+// Get VAD context from processor
+const vadCtx = processor.getVadContext();
+
+// Configure VAD parameters
+vadCtx.setParameter(VadParameter.Sensitivity, 6.0);
+vadCtx.setParameter(VadParameter.SpeechHoldDuration, 0.05);
+vadCtx.setParameter(VadParameter.MinimumSpeechDuration, 0.0);
+
+// Get parameter values
+const sensitivity = vadCtx.getParameter(VadParameter.Sensitivity);
+console.log(`VAD sensitivity: ${sensitivity}`);
+
+// Check for speech (after processing audio through the processor)
+if (vadCtx.isSpeechDetected()) {
+  console.log("Speech detected!");
+}
 ```
 
-## Links
+## Examples
 
-- [Example Usage](examples/basic.js)
-- [API Reference](index.js)
-- [C SDK Reference](https://github.com/ai-coustics/aic-sdk-c/blob/HEAD/sdk-reference.md)
-- [Documentation](https://docs.ai-coustics.com/)
-- [Issues](https://github.com/ai-coustics/aic-sdk-node/issues)
+See the [`basic.js`](examples/basic.js) file for a complete working example.
 
-### Other SDKs
+## Documentation
 
-| Platform | Repository |
-|----------|------------|
-| **C** | [aic-sdk-c](https://github.com/ai-coustics/aic-sdk-c) |
-| **C++** | [aic-sdk-cpp](https://github.com/ai-coustics/aic-sdk-cpp) |
-| **Python** | [aic-sdk-py](https://github.com/ai-coustics/aic-sdk-py) |
-| **Rust** | [aic-sdk-rs](https://github.com/ai-coustics/aic-sdk-rs) |
-| **Web (WASM)** | [aic-sdk-wasm](https://github.com/ai-coustics/aic-sdk-wasm) |
-| **Demo Plugin** | [aic-sdk-plugin](https://github.com/ai-coustics/aic-sdk-plugin) |
+- **Full Documentation**: [docs.ai-coustics.com](https://docs.ai-coustics.com)
+- **Node.js API Reference**: See the [index.js](index.js) for detailed JSDoc documentation
+- **Available Models**: [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io)
 
 ## License
 
-Dual-licensed:
-- Node.js wrapper code: Apache License 2.0
-- AIC SDK binaries: Proprietary AIC-SDK Binary License Agreement
+This Node.js wrapper is distributed under the Apache 2.0 license. The core C SDK is distributed under the proprietary AIC-SDK license.

package/index.js

@@ -1,7 +1,6 @@
 // Platform-specific binary loader
 let native;
 try {
-  // Try to load platform-specific binary from optional dependencies
   const platform = process.platform;
   const arch = process.arch;
 
@@ -21,11 +20,9 @@ try {
     try {
       native = require(platformPackage);
     } catch (e) {
-      // Fall back to local binary
       native = require("./index.node");
     }
   } else {
-    // Fall back to local binary
     native = require("./index.node");
   }
 } catch (e) {
@@ -37,204 +34,566 @@ try {
 }
 
 /**
- * Model types available in the SDK
+ * Configurable parameters for audio enhancement.
+ * @enum {number}
  */
-const ModelType = {
-  QuailL48: "QuailL48",
-  QuailL16: "QuailL16",
-  QuailL8: "QuailL8",
-  QuailS48: "QuailS48",
-  QuailS16: "QuailS16",
-  QuailS8: "QuailS8",
-  QuailXs: "QuailXs",
-  QuailXxs: "QuailXxs",
-  QuailSttL16: "QuailSttL16",
-  QuailSttL8: "QuailSttL8",
-  QuailSttS16: "QuailSttS16",
-  QuailSttS8: "QuailSttS8",
-  QuailVfSttL16: "QuailVfSttL16",
-};
+const ProcessorParameter = {
+  /**
+   * Controls whether audio processing is bypassed while preserving algorithmic delay.
+   *
+   * When enabled, the input audio passes through unmodified, but the output is still
+   * delayed by the same amount as during normal processing. This ensures seamless
+   * transitions when toggling enhancement on/off without audible clicks or timing shifts.
+   *
+   * Range: 0.0 to 1.0
+   *   - 0.0: Enhancement active (normal processing)
+   *   - 1.0: Bypass enabled (latency-compensated passthrough)
+   *
+   * Default: 0.0
+   */
+  Bypass: native.PROCESSOR_PARAM_BYPASS,
 
-/**
- * Enhancement parameters
- */
-const EnhancementParameter = {
-  Bypass: native.ENHANCEMENT_PARAM_BYPASS,
-  EnhancementLevel: native.ENHANCEMENT_PARAM_ENHANCEMENT_LEVEL,
-  VoiceGain: native.ENHANCEMENT_PARAM_VOICE_GAIN,
+  /**
+   * Controls the intensity of speech enhancement processing.
+   *
+   * Range: 0.0 to 1.0
+   *   - 0.0: Bypass mode - original signal passes through unchanged
+   *   - 1.0: Full enhancement - maximum noise reduction but also more audible artifacts
+   *
+   * Default: 1.0
+   */
+  EnhancementLevel: native.PROCESSOR_PARAM_ENHANCEMENT_LEVEL,
+
+  /**
+   * Compensates for perceived volume reduction after noise removal.
+   *
+   * Range: 0.1 to 4.0 (linear amplitude multiplier)
+   *   - 0.1: Significant volume reduction (-20 dB)
+   *   - 1.0: No gain change (0 dB, default)
+   *   - 2.0: Double amplitude (+6 dB)
+   *   - 4.0: Maximum boost (+12 dB)
+   *
+   * Formula: Gain (dB) = 20 × log₁₀(value)
+   *
+   * Default: 1.0
+   */
+  VoiceGain: native.PROCESSOR_PARAM_VOICE_GAIN,
 };
 
 /**
- * VAD (Voice Activity Detection) parameters
+ * Configurable parameters for Voice Activity Detection.
+ * @enum {number}
  */
 const VadParameter = {
+  /**
+   * Controls for how long the VAD continues to detect speech after the audio signal
+   * no longer contains speech.
+   *
+   * The VAD reports speech detected if the audio signal contained speech in at least 50%
+   * of the frames processed in the last speech_hold_duration seconds.
+   *
+   * This affects the stability of speech detected -> not detected transitions.
+   *
+   * Note: The VAD returns a value per processed buffer, so this duration is rounded
+   * to the closest model window length.
+   *
+   * Range: 0.0 to 20x model window length (value in seconds)
+   * Default: 0.05 (50 ms)
+   */
   SpeechHoldDuration: native.VAD_PARAM_SPEECH_HOLD_DURATION,
+
+  /**
+   * Controls the sensitivity (energy threshold) of the VAD.
+   *
+   * This value is used by the VAD as the threshold a speech audio signal's energy
+   * has to exceed in order to be considered speech.
+   *
+   * Range: 1.0 to 15.0
+   * Formula: Energy threshold = 10 ^ (-sensitivity)
+   * Default: 6.0
+   */
   Sensitivity: native.VAD_PARAM_SENSITIVITY,
+
+  /**
+   * Controls for how long speech needs to be present in the audio signal before
+   * the VAD considers it speech.
+   *
+   * This affects the stability of speech not detected -> detected transitions.
+   *
+   * Note: The VAD returns a value per processed buffer, so this duration is rounded
+   * to the closest model window length.
+   *
+   * Range: 0.0 to 1.0 (value in seconds)
+   * Default: 0.0
+   */
   MinimumSpeechDuration: native.VAD_PARAM_MINIMUM_SPEECH_DURATION,
 };
 
 /**
- * Voice Activity Detector
+ * Context for managing processor state and parameters.
+ * Created via Processor.getProcessorContext().
+ */
+class ProcessorContext {
+  constructor(nativeContext) {
+    this._context = nativeContext;
+  }
+
+  /**
+   * Clears all internal state and buffers.
+   *
+   * Call this when the audio stream is interrupted or when seeking
+   * to prevent artifacts from previous audio content.
+   *
+   * The processor stays initialized to the configured settings.
+   *
+   * Thread Safety: Real-time safe. Can be called from audio processing threads.
+   */
+  reset() {
+    native.processorContextReset(this._context);
+  }
+
+  /**
+   * Modifies a processor parameter.
+   *
+   * All parameters can be changed during audio processing.
+   * This function can be called from any thread.
+   *
+   * @param {ProcessorParameter} parameter - Parameter to modify
+   * @param {number} value - New parameter value. See parameter documentation for ranges
+   * @throws {Error} If the parameter value is out of range.
+   *
+   * @example
+   * processorContext.setParameter(ProcessorParameter.EnhancementLevel, 0.8);
+   */
+  setParameter(parameter, value) {
+    native.processorContextSetParameter(this._context, parameter, value);
+  }
+
+  /**
+   * Retrieves the current value of a parameter.
+   *
+   * This function can be called from any thread.
+   *
+   * @param {ProcessorParameter} parameter - Parameter to query
+   * @returns {number} The current parameter value.
+   *
+   * @example
+   * const level = processorContext.getParameter(ProcessorParameter.EnhancementLevel);
+   */
+  getParameter(parameter) {
+    return native.processorContextGetParameter(this._context, parameter);
+  }
+
+  /**
+   * Returns the total output delay in samples for the current audio configuration.
+   *
+   * This function provides the complete end-to-end latency introduced by the model,
+   * which includes both algorithmic processing delay and any buffering overhead.
+   * Use this value to synchronize enhanced audio with other streams or to implement
+   * delay compensation in your application.
+   *
+   * Delay behavior:
+   *   - Before initialization: Returns the base processing delay using the model's
+   *     optimal frame size at its native sample rate
+   *   - After initialization: Returns the actual delay for your specific configuration,
+   *     including any additional buffering introduced by non-optimal frame sizes
+   *
+   * Important: The delay value is always expressed in samples at the sample rate
+   * you configured during initialize(). To convert to time units:
+   * delay_ms = (delay_samples * 1000) / sample_rate
+   *
+   * Note: Using frame sizes different from the optimal value returned by
+   * Model.getOptimalNumFrames() will increase the delay beyond the model's base latency.
+   *
+   * @returns {number} The delay in samples.
+   *
+   * @example
+   * const delay = processorContext.getOutputDelay();
+   * console.log(`Output delay: ${delay} samples`);
+   */
+  getOutputDelay() {
+    return native.processorContextGetOutputDelay(this._context);
+  }
+}
+
+/**
+ * Voice Activity Detector backed by an ai-coustics speech enhancement model.
+ *
+ * The VAD works automatically using the enhanced audio output of the model
+ * that created the VAD.
+ *
+ * Important:
+ *   - The latency of the VAD prediction is equal to the backing model's processing latency.
+ *   - If the backing model stops being processed, the VAD will not update its speech detection prediction.
+ *
+ * Created via Processor.getVadContext().
+ *
+ * @example
+ * const vad = processor.getVadContext();
+ * vad.setParameter(VadParameter.Sensitivity, 5.0);
+ * if (vad.isSpeechDetected()) {
+ *   console.log("Speech detected!");
+ * }
  */
-class Vad {
-  constructor(nativeVad) {
-    this._vad = nativeVad;
+class VadContext {
+  constructor(nativeContext) {
+    this._context = nativeContext;
   }
 
   /**
-   * Check if speech is detected
-   * @returns {boolean}
+   * Returns the VAD's prediction.
+   *
+   * Important:
+   *   - The latency of the VAD prediction is equal to the backing model's processing latency.
+   *   - If the backing model stops being processed, the VAD will not update its speech detection prediction.
+   *
+   * @returns {boolean} True if speech is detected, False otherwise.
    */
   isSpeechDetected() {
-    return native.vadIsSpeechDetected(this._vad);
+    return native.vadContextIsSpeechDetected(this._context);
   }
 
   /**
-   * Set a VAD parameter
-   * @param {number} parameter - Parameter constant from VadParameter
-   * @param {number} value - Parameter value
-   * @throws {Error} If parameter setting fails (invalid parameter, out of range, etc.)
+   * Modifies a VAD parameter.
+   *
+   * @param {VadParameter} parameter - Parameter to modify
+   * @param {number} value - New parameter value. See parameter documentation for ranges
+   * @throws {Error} If the parameter value is out of range.
+   *
+   * @example
+   * vad.setParameter(VadParameter.SpeechHoldDuration, 0.08);
+   * vad.setParameter(VadParameter.Sensitivity, 5.0);
    */
   setParameter(parameter, value) {
-    native.vadSetParameter(this._vad, parameter, value);
+    native.vadContextSetParameter(this._context, parameter, value);
   }
 
   /**
-   * Get a VAD parameter value
-   * @param {number} parameter - Parameter constant from VadParameter
-   * @returns {number}
+   * Retrieves the current value of a VAD parameter.
+   *
+   * @param {VadParameter} parameter - Parameter to query
+   * @returns {number} The current parameter value.
+   *
+   * @example
+   * const sensitivity = vad.getParameter(VadParameter.Sensitivity);
+   * console.log(`Current sensitivity: ${sensitivity}`);
    */
   getParameter(parameter) {
-    return native.vadGetParameter(this._vad, parameter);
+    return native.vadContextGetParameter(this._context, parameter);
   }
 }
 
 /**
- * AI-Coustics audio enhancement model
+ * High-level wrapper for the ai-coustics audio enhancement model.
+ *
+ * This class provides a safe, JavaScript-friendly interface to the underlying native library.
+ * It handles memory management automatically.
+ *
+ * @example
+ * const model = Model.fromFile("/path/to/model.aicmodel");
+ * const processor = new Processor(model, licenseKey);
+ * processor.initialize(model.getOptimalSampleRate(), 2, model.getOptimalNumFrames(sampleRate), false);
  */
 class Model {
+  constructor(nativeModel) {
+    this._model = nativeModel;
+  }
+
   /**
-   * Create a new model instance
-   * @param {string} modelType - Model type from ModelType enum
-   * @param {string} licenseKey - SDK license key
-   * @throws {Error} If model creation fails (invalid license, unsupported model type, etc.)
+   * Creates a new audio enhancement model instance from a file.
+   *
+   * Multiple models can be created to process different audio streams simultaneously
+   * or to switch between different enhancement algorithms during runtime.
+   *
+   * @param {string} path - Path to the model file (.aicmodel). You can download models manually
+   *   from https://artifacts.ai-coustics.io or use Model.download() to fetch them programmatically.
+   * @returns {Model} A new Model instance.
+   * @throws {Error} If model creation fails.
+   *
+   * @see https://artifacts.ai-coustics.io for available model IDs and downloads.
+   *
+   * @example
+   * const model = Model.fromFile("/path/to/model.aicmodel");
    */
-  constructor(modelType, licenseKey) {
-    this._model = native.modelNew(modelType, licenseKey);
+  static fromFile(path) {
+    const nativeModel = native.modelFromFile(path);
+    return new Model(nativeModel);
   }
 
   /**
-   * Get the optimal sample rate for this model
-   * @returns {number} Sample rate in Hz
+   * Downloads a model file from the ai-coustics artifact CDN.
+   *
+   * This method fetches the model manifest, checks whether the requested model
+   * exists in a version compatible with this library, and downloads the model
+   * file into the provided directory.
+   *
+   * Note: This is a blocking operation.
+   *
+   * @param {string} modelId - The model identifier as listed in the manifest (e.g. "sparrow-l-16khz").
+   *   Find available model IDs at https://artifacts.ai-coustics.io
+   * @param {string} downloadDir - Directory where the downloaded model file should be stored
+   * @returns {string} The full path to the downloaded model file.
+   * @throws {Error} If the download operation fails.
+   *
+   * @see https://artifacts.ai-coustics.io for available model IDs.
+   *
+   * @example
+   * const path = Model.download("sparrow-l-16khz", "/tmp/models");
+   * const model = Model.fromFile(path);
    */
-  optimalSampleRate() {
-    return native.modelOptimalSampleRate(this._model);
+  static download(modelId, downloadDir) {
+    return native.modelDownload(modelId, downloadDir);
   }
 
   /**
-   * Get the optimal number of frames for a given sample rate
-   * @param {number} sampleRate - Sample rate in Hz
-   * @returns {number} Number of frames
+   * Returns the model identifier string.
+   *
+   * @returns {string} The model ID string.
    */
-  optimalNumFrames(sampleRate) {
-    return native.modelOptimalNumFrames(this._model, sampleRate);
+  getId() {
+    return native.modelId(this._model);
   }
 
   /**
-   * Initialize the model with audio configuration
-   * @param {number} sampleRate - Sample rate in Hz
-   * @param {number} numChannels - Number of audio channels
-   * @param {number} numFrames - Number of frames per process call
-   * @param {boolean} allowVariableFrames - Allow variable frame counts
-   * @throws {Error} If initialization fails (invalid parameters)
+   * Retrieves the native sample rate of the model.
+   *
+   * Each model is optimized for a specific sample rate, which determines the frequency
+   * range of the enhanced audio output. While you can process audio at any sample rate,
+   * understanding the model's native rate helps predict the enhancement quality.
+   *
+   * How sample rate affects enhancement:
+   *   - Models trained at lower sample rates (e.g., 8 kHz) can only enhance frequencies
+   *     up to their Nyquist limit (4 kHz for 8 kHz models)
+   *   - When processing higher sample rate input (e.g., 48 kHz) with a lower-rate model,
+   *     only the lower frequency components will be enhanced
+   *
+   * Recommendation: For maximum enhancement quality across the full frequency spectrum,
+   * match your input sample rate to the model's native rate when possible.
+   *
+   * @returns {number} The model's native sample rate in Hz.
+   *
+   * @example
+   * const optimalRate = model.getOptimalSampleRate();
+   * console.log(`Optimal sample rate: ${optimalRate} Hz`);
    */
-  initialize(sampleRate, numChannels, numFrames, allowVariableFrames = false) {
-    native.modelInitialize(
-      this._model,
-      sampleRate,
-      numChannels,
-      numFrames,
-      allowVariableFrames,
-    );
+  getOptimalSampleRate() {
+    return native.modelGetOptimalSampleRate(this._model);
   }
 
   /**
-   * Get the output delay in samples
-   * @returns {number} Delay in samples
+   * Retrieves the optimal number of frames for the model at a given sample rate.
+   *
+   * Using the optimal number of frames minimizes latency by avoiding internal buffering.
+   *
+   * When you use a different frame count than the optimal value, the model will
+   * introduce additional buffering latency on top of its base processing delay.
+   *
+   * The optimal frame count varies based on the sample rate. Each model operates on a
+   * fixed time window duration, so the required number of frames changes with sample rate.
+   * For example, a model designed for 10 ms processing windows requires 480 frames at
+   * 48 kHz, but only 160 frames at 16 kHz to capture the same duration of audio.
+   *
+   * Call this function with your intended sample rate before calling
+   * Processor.initialize() to determine the best frame count for minimal latency.
+   *
+   * @param {number} sampleRate - The sample rate in Hz for which to calculate the optimal frame count
+   * @returns {number} The optimal frame count for the given sample rate.
+   *
+   * @example
+   * const sampleRate = model.getOptimalSampleRate();
+   * const optimalFrames = model.getOptimalNumFrames(sampleRate);
+   * console.log(`Optimal frame count: ${optimalFrames}`);
    */
-  outputDelay() {
-    return native.modelOutputDelay(this._model);
+  getOptimalNumFrames(sampleRate) {
+    return native.modelGetOptimalNumFrames(this._model, sampleRate);
   }
+}
 
+/**
+ * High-level wrapper for the ai-coustics audio enhancement processor.
+ *
+ * This class provides a safe, JavaScript-friendly interface to the underlying native library.
+ * It handles memory management automatically.
+ *
+ * @example
+ * const model = Model.fromFile("/path/to/model.aicmodel");
+ * const processor = new Processor(model, licenseKey);
+ * const sampleRate = model.getOptimalSampleRate();
+ * const numFrames = model.getOptimalNumFrames(sampleRate);
+ * processor.initialize(sampleRate, 2, numFrames, false);
+ * const audio = new Float32Array(2 * numFrames);
+ * processor.processInterleaved(audio);
+ */
+class Processor {
   /**
-   * Reset the model's internal state
+   * Creates a new audio enhancement processor instance.
+   *
+   * Multiple processors can be created to process different audio streams simultaneously
+   * or to switch between different enhancement algorithms during runtime.
+   *
+   * @param {Model} model - The loaded model instance
+   * @param {string} licenseKey - License key for the ai-coustics SDK
+   *   (generate your key at https://developers.ai-coustics.com/)
+   * @throws {Error} If processor creation fails.
+   *
+   * @example
+   * const model = Model.fromFile("/path/to/model.aicmodel");
+   * const processor = new Processor(model, licenseKey);
+   * processor.initialize(sampleRate, numChannels, numFrames, false);
    */
-  reset() {
-    native.modelReset(this._model);
+  constructor(model, licenseKey) {
+    this._processor = native.processorNew(model._model, licenseKey);
   }
 
   /**
-   * Set an enhancement parameter
-   * @param {number} parameter - Parameter constant from EnhancementParameter
-   * @param {number} value - Parameter value
-   * @throws {Error} If parameter setting fails (invalid parameter, out of range, etc)
+   * Configures the processor for specific audio settings.
+   *
+   * This function must be called before processing any audio.
+   * For the lowest delay use the sample rate and frame size returned by
+   * Model.getOptimalSampleRate() and Model.getOptimalNumFrames().
+   *
+   * Warning: Do not call from audio processing threads as this allocates memory.
+   *
+   * Note: All channels are mixed to mono for processing. To process channels
+   * independently, create separate Processor instances.
+   *
+   * @param {number} sampleRate - Sample rate in Hz (8000 - 192000)
+   * @param {number} numChannels - Number of audio channels
+   * @param {number} numFrames - Samples per channel provided to each processing call
+   * @param {boolean} [allowVariableFrames=false] - Allow variable frame sizes (adds latency)
+   * @throws {Error} If the audio configuration is unsupported.
+   *
+   * @example
+   * const sampleRate = model.getOptimalSampleRate();
+   * const numFrames = model.getOptimalNumFrames(sampleRate);
+   * processor.initialize(sampleRate, 2, numFrames, false);
    */
-  setParameter(parameter, value) {
-    native.modelSetParameter(this._model, parameter, value);
+  initialize(sampleRate, numChannels, numFrames, allowVariableFrames = false) {
+    native.processorInitialize(
+      this._processor,
+      sampleRate,
+      numChannels,
+      numFrames,
+      allowVariableFrames,
+    );
   }
 
   /**
-   * Get an enhancement parameter value
-   * @param {number} parameter - Parameter constant from EnhancementParameter
-   * @returns {number}
+   * Processes interleaved audio (all channels mixed in one buffer).
+   *
+   * Enhances speech in the provided audio buffer. The buffer is modified in-place.
+   *
+   * @param {Float32Array} buffer - Interleaved audio buffer (channel samples alternating)
+   * @throws {Error} If processing fails (processor not initialized, invalid buffer size, etc.)
+   *
+   * @example
+   * // For stereo: [L0, R0, L1, R1, L2, R2, ...]
+   * const buffer = new Float32Array(numChannels * numFrames);
+   * processor.processInterleaved(buffer);
    */
-  getParameter(parameter) {
-    return native.modelGetParameter(this._model, parameter);
+  processInterleaved(buffer) {
+    native.processorProcessInterleaved(this._processor, buffer);
   }
 
   /**
-   * Process interleaved audio (all channels mixed in one buffer)
-   * @param {Float32Array} buffer - Interleaved audio buffer
-   * @param {number} numChannels - Number of channels
-   * @param {number} numFrames - Number of frames
-   * @throws {Error} If processing fails (model not initialized, invalid buffer size, etc.)
+   * Processes sequential/channel-contiguous audio.
+   *
+   * Enhances speech in the provided audio buffer. The buffer is modified in-place.
+   * All samples for each channel are stored contiguously.
+   *
+   * @param {Float32Array} buffer - Sequential audio buffer (all channel 0 samples, then all channel 1 samples, etc.)
+   * @throws {Error} If processing fails (processor not initialized, invalid buffer size, etc.)
+   *
+   * @example
+   * // For stereo: [L0, L1, L2, ..., R0, R1, R2, ...]
+   * const buffer = new Float32Array(numChannels * numFrames);
+   * processor.processSequential(buffer);
    */
-  processInterleaved(buffer, numChannels, numFrames) {
-    native.modelProcessInterleaved(this._model, buffer, numChannels, numFrames);
+  processSequential(buffer) {
+    native.processorProcessSequential(this._processor, buffer);
   }
 
   /**
-   * Process planar audio (separate buffer for each channel)
+   * Processes planar audio (separate buffer for each channel).
+   *
+   * Enhances speech in the provided audio buffers. The buffers are modified in-place.
+   *
    * @param {Float32Array[]} buffers - Array of audio buffers, one per channel (max 16 channels)
-   * @throws {Error} If processing fails (model not initialized, too many channels, invalid buffer size, etc.)
+   * @throws {Error} If processing fails (processor not initialized, too many channels, invalid buffer size, etc.)
+   *
+   * @example
+   * const left = new Float32Array(numFrames);
+   * const right = new Float32Array(numFrames);
+   * processor.processPlanar([left, right]);
    */
   processPlanar(buffers) {
-    native.modelProcessPlanar(this._model, buffers);
+    native.processorProcessPlanar(this._processor, buffers);
+  }
+
+  /**
+   * Creates a ProcessorContext instance.
+   *
+   * This can be used to control all parameters and other settings of the processor.
+   *
+   * @returns {ProcessorContext} A new ProcessorContext instance.
+   *
+   * @example
+   * const processorContext = processor.getProcessorContext();
+   * processorContext.setParameter(ProcessorParameter.EnhancementLevel, 0.8);
+   */
+  getProcessorContext() {
+    const nativeContext = native.processorGetProcessorContext(this._processor);
+    return new ProcessorContext(nativeContext);
   }
 
   /**
-   * Create a Voice Activity Detector for this model
-   * @returns {Vad}
+   * Creates a Voice Activity Detector Context instance.
+   *
+   * @returns {VadContext} A new VadContext instance.
+   *
+   * @example
+   * const vad = processor.getVadContext();
+   * if (vad.isSpeechDetected()) {
+   *   console.log("Speech detected!");
+   * }
    */
-  createVad() {
-    const nativeVad = native.modelCreateVad(this._model);
-    return new Vad(nativeVad);
+  getVadContext() {
+    const nativeContext = native.processorGetVadContext(this._processor);
+    return new VadContext(nativeContext);
   }
 }
 
 /**
- * Get the SDK version
- * @returns {string}
+ * Returns the version of the ai-coustics core SDK library used by this package.
+ *
+ * Note: This is not necessarily the same as this package's version.
+ *
+ * @returns {string} The library version as a string.
+ *
+ * @example
+ * const version = getVersion();
+ * console.log(`ai-coustics SDK version: ${version}`);
  */
 function getVersion() {
   return native.getVersion();
 }
 
+/**
+ * Returns the model version number compatible with this SDK build.
+ *
+ * @returns {number} The compatible model version number.
+ */
+function getCompatibleModelVersion() {
+  return native.getCompatibleModelVersion();
+}
+
 module.exports = {
   Model,
-  Vad,
-  ModelType,
-  EnhancementParameter,
+  Processor,
+  ProcessorContext,
+  VadContext,
+  ProcessorParameter,
   VadParameter,
   getVersion,
+  getCompatibleModelVersion,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-coustics/aic-sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Node.js package of ai-coustics SDK",
   "main": "index.js",
   "scripts": {
@@ -34,14 +34,15 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ai-coustics/aic-sdk-darwin-arm64": "0.12.0",
-    "@ai-coustics/aic-sdk-darwin-x64": "0.12.0",
-    "@ai-coustics/aic-sdk-linux-arm64-gnu": "0.12.0",
-    "@ai-coustics/aic-sdk-linux-x64-gnu": "0.12.0",
-    "@ai-coustics/aic-sdk-win32-arm64-msvc": "0.12.0",
-    "@ai-coustics/aic-sdk-win32-x64-msvc": "0.12.0"
+    "@ai-coustics/aic-sdk-darwin-arm64": "0.13.0",
+    "@ai-coustics/aic-sdk-darwin-x64": "0.13.0",
+    "@ai-coustics/aic-sdk-linux-arm64-gnu": "0.13.0",
+    "@ai-coustics/aic-sdk-linux-x64-gnu": "0.13.0",
+    "@ai-coustics/aic-sdk-win32-arm64-msvc": "0.13.0",
+    "@ai-coustics/aic-sdk-win32-x64-msvc": "0.13.0"
   },
   "devDependencies": {
-    "@neon-rs/cli": "0.1.82"
+    "@neon-rs/cli": "0.1.82",
+    "wavefile": "^11.0.0"
   }
 }