Skip to main content
ai-coustics Node.js bindings provide native processing with TypeScript declarations. The tutorial below uses @ai-coustics/aic-sdk 0.24.0. Use the Node.js API reference for classes, functions, properties and errors. The released TypeScript declarations and examples provide source context.

Installation

Use Node.js 22 for this example. The package declares Node.js 18 or later; see the compatibility matrix for native platform support. Create an isolated project and install the pinned SDK and WAV reader:

Quickstart

Prepare the key and input

Generate an SDK key on the developer platform. Set it in the terminal where you will run the example, replacing YOUR_SDK_KEY with your key. Keep it out of source control and shared terminal logs.
Download the noisy speech fixture and save it as input.wav in aic-node-quickstart. It contains 56,080 mono PCM16 samples at 16 kHz (3.505 seconds). The fixture guide includes attribution, checksums and the aligned clean reference. For your own recording, export a short sentence with background noise as mono, 16 kHz, signed 16-bit PCM WAV. Renaming a file does not convert it. The example downloads quail-vf-2.2-l-16khz into ./models. Quail Voice Focus isolates the primary speaker for speech-to-text (STT) input. The first run needs network access for the model download and SDK key authorization. See authentication for deployment options.

Save and run

Save this complete program as quickstart.cjs. The .cjs extension makes its CommonJS module format explicit, including in projects that use "type": "module".
quickstart.cjs
Run it from aic-node-quickstart:

Check the result

The program prints the native SDK version, resolved model ID and processed sample count. It writes enhanced.wav beside input.wav at 16 kHz with the same sample count, compensating for processing delay. With the supplied fixture, the processed sample count is 56080. Verify the file headers:
Listen to both recordings and compare them with the same STT settings to evaluate quality.

Recover from an error

Adapt this example

Use one processor per independent stream and await each operation before submitting the next block. Use separate processors for simultaneous streams; Promise.all over blocks from one stream can reorder processing. Downmix stereo input or give each channel its own processor. See audio format, streams and state and the Node.js binding guide. This example reads the full file into memory and uses synchronous file I/O. For live audio or long files, process bounded blocks and keep file I/O and model downloads outside the audio path. For human listening, evaluate Rook Multi Speaker.

Integration behavior

The package includes TypeScript declarations and is distributed as CommonJS. The .cjs tutorial runs independently of your project’s type setting. Keep the generated lockfile and install dependencies on the deployment platform so npm selects the matching native package. terminateSession() requests session termination but does not replace dispose() for deterministic native cleanup. Once termination is handled, processing is no longer allowed. Disposal is idempotent; other methods fail after disposal. Context handles are independent objects, but a retained context no longer controls a live processor after that processor is disposed. For voice activity detection (VAD), use Vad or VadAsync with a dedicated VAD model. Feed original input to VAD before synchronous enhancement modifies it. See the VAD example. For Tyto analysis, use Analyzer, which buffers input separately from enhancement.

Handle SDK errors

Synchronous operations throw JavaScript errors; asynchronous operations reject promises. Catch failures around model loading, initialization and processing. The error message distinguishes causes such as invalid credentials, unsupported models and an audio configuration mismatch. Never treat a rejected processing promise as enhanced output. Correct the cause before retrying: use the exact model ID with Model.download, keep input blocks consistent with initialization and check authentication when processing is not allowed. SDK construction and dispose() are synchronous even when you use ProcessorAsync; keep lifecycle work outside the audio callback.