Node.js VAD API

Version: @ai-coustics/aic-sdk 0.24.0, Core SDK 0.24.0. API index · Node.js quickstart.

`Vad`

Synchronous dedicated voice activity detection (VAD). Use a dedicated VAD model and one instance per stream. Initialize before processing. Input audio is read without mutation. Feed original audio before synchronous enhancement changes that buffer.

`Vad.constructor`

constructor(model: Model, licenseKey: string, otelConfig?: OtelConfig | undefined | null)

model must be a live model handle of the required type. licenseKey is the SDK credential string; see authentication. Construction is synchronous and can throw for an invalid key, a disposed model or a model-type mismatch. Omitted or null otelConfig uses environment settings; otherwise pass an OtelConfig object. There is no automatic initialization.

`Vad.dispose`

dispose(): void

Destroys the native VAD synchronously. Idempotent. Later methods on the VAD object throw Vad has been disposed. Retained contexts remain readable but no new predictions are produced.

`Vad.initialize`

initialize(sampleRate: number, blockSize: number, variableBlockSize?: boolean | undefined | null): void

sampleRate is a whole-number rate in Hz; blockSize is a positive whole-number mono sample count. Query model.getOptimalBlockSize(sampleRate) for the preferred size. Omitted, undefined or null variableBlockSize means false, requiring exactly blockSize samples. Variable mode allows shorter blocks, with possible buffering delay, but rejects larger blocks. Unsupported configurations throw an SDK error. Initialization allocates memory. The streaming SDK accepts supported rates from 8,000 through 192,000 Hz. Call before process.

`Vad.process`

process(audio: Float32Array): void

Reads mono normalized Float32Array samples without modifying the caller’s input. The native VAD copies the samples into its processing buffer. Returns void; read the updated prediction through getContext. Input length must match the initialized block contract. Throws before initialization, for a mismatch, after disposal or when processing is disallowed. Do not concurrently modify a shared input buffer.

`Vad.getContext`

getContext(): VadContext

Returns an independent handle to this VAD’s shared prediction and control state. Throws after disposal of the VAD object.

`Vad.terminateSession`

terminateSession(): void

Requests termination of the associated session. Once termination is handled, further processing is disallowed. This does not release the native object; still call dispose(). Completion may involve asynchronous session handling when another session remains active. Do not use it as a flush operation. Runs synchronously and may block.

`VadAsync`

Dedicated VAD through Node’s shared libuv worker pool. Construction and disposal are synchronous. Await initialization and each processing call in stream order. Concurrent calls on one instance share a lock but have no guaranteed submission order. Use separate instances for independent streams.

`VadAsync.constructor`

constructor(model: Model, licenseKey: string, otelConfig?: OtelConfig | undefined | null)

`VadAsync.dispose`

dispose(): void

Synchronous and idempotent. Can block while a worker holds the native lock. Invalidates both the original object and any withConfig handle. Work that acquires the lock after disposal rejects. Await pending operations before disposing.

`VadAsync.withConfig`

withConfig(sampleRate: number, blockSize: number, variableBlockSize?: boolean | undefined | null): Promise<VadAsync>

sampleRate is a whole-number rate in Hz; blockSize is a positive whole-number mono sample count. Query model.getOptimalBlockSize(sampleRate) for the preferred size. Omitted, undefined or null variableBlockSize means false, requiring exactly blockSize samples. Variable mode allows shorter blocks, with possible buffering delay, but rejects larger blocks. Unsupported configurations reject the promise with an SDK error. Initialization allocates memory. Initializes on a worker and resolves to another handle sharing the same native VAD. Disposing either handle invalidates both. Keep the original object available for cleanup if initialization rejects.

`VadAsync.initialize`

initialize(sampleRate: number, blockSize: number, variableBlockSize?: boolean | undefined | null): Promise<void>

sampleRate is a whole-number rate in Hz; blockSize is a positive whole-number mono sample count. Query model.getOptimalBlockSize(sampleRate) for the preferred size. Omitted, undefined or null variableBlockSize means false, requiring exactly blockSize samples. Variable mode allows shorter blocks, with possible buffering delay, but rejects larger blocks. Unsupported configurations reject the promise with an SDK error. Initialization allocates memory. Runs on a libuv worker. Await the promise before processing; initialization errors reject it.

`VadAsync.process`

process(audio: Float32Array): Promise<Float32Array<ArrayBuffer>>

Copies audio on the JavaScript thread before queuing work. Resolves to a new Float32Array<ArrayBuffer> containing the original samples, not enhanced audio or VAD probabilities. The original input is unchanged. Read predictions from VadContext after awaiting the call. Format and block constraints match Vad.process; native failures reject.

`VadAsync.getContext`

getContext(): Promise<VadContext>

Resolves to a VadContext after worker access to the instance lock. The returned context’s methods are synchronous. Rejects if the VAD was disposed before the worker acquired it.

`VadAsync.terminateSession`

terminateSession(): Promise<void>

`VadContext`

Read predictions and control a Vad or VadAsync. Obtain it through the corresponding getContext() method; there is no public constructor or dispose(). All methods on this context are synchronous, including a context obtained asynchronously. The handle survives disposal of the VAD, but its prediction stops updating.

`VadContext.setParameter`

setParameter(parameter: VadParameter, value: number): void

Sets parameter to value, converted to a 32-bit float. Throws for an unknown enum value, an out-of-range value or a non-finite value. Timing controls are seconds; see VadParameter below.

`VadContext.getParameter`

getParameter(parameter: VadParameter): number

Returns the current stored 32-bit float value widened to a JavaScript number. The effective detector timing is frame-quantized; do not treat this readback as an observed speech-boundary time. Unknown parameters throw.

`VadContext.isSpeechDetected`

isSpeechDetected(): boolean

Returns the latest boolean decision after sensitivity and speech-timing controls. The result stops changing when no new audio is processed. It lags the corresponding input by getPredictionDelay() samples.

`VadContext.getRawVadProbability`

getRawVadProbability(): number

Returns the latest model speech probability from 0 to 1 before sensitivity thresholding, speech hold and minimum duration. The same prediction delay applies. This is not a guarantee that speech is present.

`VadContext.getPredictionDelay`

getPredictionDelay(): number

Returns prediction delay in samples at the configured input rate, including input buffering and model processing. Convert with delaySamples * 1000 / sampleRate. It is separate from enhancement audio delay: VAD does not delay or modify the caller’s samples.

`VadContext.reset`

reset(): void

Clears the published decision and probability immediately and requests processing-state reset for subsequent audio. Preserves initialization. Reset before unrelated audio or after a discontinuity to prevent stale speech decisions.

`VadContext.updateBearerToken`

updateBearerToken(token: string): void

token replaces a bearer token on a JWT-authenticated session. Both the original credential and replacement must be JWT-form licenses. A synchronous failure preserves the previous token. Return without error confirms local format acceptance, not backend acceptance; subsequent reporting can reject the token and eventually disable work. Obtain a valid replacement to recover. This operation allocates and takes a lock; keep it outside audio callbacks. See authentication.

`VadParameter`

Exported numeric enum used by VadContext. All defaults come from the loaded model; read them with getParameter. Timing values are seconds. The detector operates on model frames, so effective timing is quantized to frame boundaries. The stored parameter is a 32-bit float, not a measurement of the resulting decision delay.

`VadParameter.SpeechHoldDuration`

SpeechHoldDuration = 0

Numeric enum value 0. Duration in seconds, from 0 through 300 times the model window length. Controls how recent speech sustains a positive decision when the current probability is at or below the threshold: speech is reported when at least half of the frames in the lookback window (twice the hold duration) contain speech. When the current probability is above the threshold, the consecutive-frame rule set by MinimumSpeechDuration applies instead. Effective timing is rounded to model frames. Default is model-specific.

`VadParameter.Sensitivity`

Sensitivity = 1

Numeric enum value 1. Probability threshold from 0 to 1. A probability above this value counts as speech; higher values require stronger evidence. Default is model-specific.

`VadParameter.MinimumSpeechDuration`

MinimumSpeechDuration = 2

Numeric enum value 2. Duration in seconds from 0 to 1. Controls the speech duration required before a positive decision. Effective timing is rounded to model frames. Default is model-specific.

Example

With the pinned package installed, set AIC_SDK_LICENSE and run node detect-block.cjs path/to/vad.aicmodel. The object printed contains a decision, probability, prediction delay and model sensitivity. One silent block does not measure detection quality. Feed representative speech and pauses in sequence to evaluate decisions.

detect-block.cjs

const { Model, Vad, VadParameter } = require('@ai-coustics/aic-sdk');

const key = process.env.AIC_SDK_LICENSE;
const modelPath = process.argv[2];
if (!key || !modelPath) throw new Error('Set AIC_SDK_LICENSE and pass a dedicated VAD model path');
const model = Model.fromFile(modelPath);
let vad;
try {
  vad = new Vad(model, key);
  const rate = model.getOptimalSampleRate();
  const size = model.getOptimalBlockSize(rate);
  vad.initialize(rate, size);
  const context = vad.getContext();
  const input = new Float32Array(size);
  vad.process(input);
  console.log({
    speech: context.isSpeechDetected(),
    probability: context.getRawVadProbability(),
    delaySamples: context.getPredictionDelay(),
    sensitivity: context.getParameter(VadParameter.Sensitivity),
  });
} finally {
  if (vad) vad.dispose();
  model.dispose();
}

Node.js API index · Errors and recovery · Stream lifecycle.

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

`Vad`

`Vad.constructor`

`Vad.dispose`

`Vad.initialize`

`Vad.process`

`Vad.getContext`

`Vad.terminateSession`

`VadAsync`

`VadAsync.constructor`

`VadAsync.dispose`

`VadAsync.withConfig`

`VadAsync.initialize`

`VadAsync.process`

`VadAsync.getContext`

`VadAsync.terminateSession`

`VadContext`

`VadContext.setParameter`

`VadContext.getParameter`

`VadContext.isSpeechDetected`

`VadContext.getRawVadProbability`

`VadContext.getPredictionDelay`

`VadContext.reset`

`VadContext.updateBearerToken`

`VadParameter`

`VadParameter.SpeechHoldDuration`

`VadParameter.Sensitivity`

`VadParameter.MinimumSpeechDuration`

Example

​Vad

​Vad.constructor

​Vad.dispose

​Vad.initialize

​Vad.process

​Vad.getContext

​Vad.terminateSession

​VadAsync

​VadAsync.constructor

​VadAsync.dispose

​VadAsync.withConfig

​VadAsync.initialize

​VadAsync.process

​VadAsync.getContext

​VadAsync.terminateSession

​VadContext

​VadContext.setParameter

​VadContext.getParameter

​VadContext.isSpeechDetected

​VadContext.getRawVadProbability

​VadContext.getPredictionDelay

​VadContext.reset

​VadContext.updateBearerToken

​VadParameter

​VadParameter.SpeechHoldDuration

​VadParameter.Sensitivity

​VadParameter.MinimumSpeechDuration

​Example

​Related

`Vad`

`Vad.constructor`

`Vad.dispose`

`Vad.initialize`

`Vad.process`

`Vad.getContext`

`Vad.terminateSession`

`VadAsync`

`VadAsync.constructor`

`VadAsync.dispose`

`VadAsync.withConfig`

`VadAsync.initialize`

`VadAsync.process`

`VadAsync.getContext`

`VadAsync.terminateSession`

`VadContext`

`VadContext.setParameter`

`VadContext.getParameter`

`VadContext.isSpeechDetected`

`VadContext.getRawVadProbability`

`VadContext.getPredictionDelay`

`VadContext.reset`

`VadContext.updateBearerToken`

`VadParameter`

`VadParameter.SpeechHoldDuration`

`VadParameter.Sensitivity`

`VadParameter.MinimumSpeechDuration`

Example

Related