Low-level C bindings (aic._bindings)

The high-level aic.Model API is recommended for most applications. The low-level bindings mirror the C API and are useful for advanced integrations, benchmarks, or when you need fine-grained control.

Core functions

aic._bindings.model_create(model_type, license_key)

Create a new audio enhancement model instance.

Multiple models can be created to process different audio streams simultaneously or to switch between enhancement algorithms.

Parameters:

• model_type (AICModelType) –

  Selects the enhancement algorithm variant.

• license_key (bytes) –

  Null-terminated license string. Must not be empty.

Returns:

• AICModelPtrT –

  Opaque handle to the created model instance.

Raises:

• RuntimeError –

  If the underlying C call fails. The error message includes the corresponding :class:AICErrorCode name from the SDK.

aic._bindings.model_destroy(model)

Release all resources associated with a model instance.

Safe to call with a null/invalid handle; the operation is idempotent.

Parameters:

• model (AICModelPtrT) –

  Model instance to destroy. Can be None.

Returns:

• None –

aic._bindings.model_initialize(model, sample_rate, num_channels, num_frames, allow_variable_frames=False)

Configure the model for a specific audio format.

Must be called before processing. For the lowest delay use the values returned by :func:get_optimal_sample_rate and :func:get_optimal_num_frames.

Parameters:

• model (AICModelPtrT) –

  Model handle. Must not be None.

• sample_rate (int) –

  Audio sample rate in Hz (8000–192000).

• num_channels (int) –

  Number of audio channels (1 for mono, 2 for stereo, etc.).

• num_frames (int) –

  Number of samples per channel per processing call.

Returns:

• None –

Raises:

• RuntimeError –

  If the configuration is not supported by the model.

Notes

Not real-time safe: do not call from time-critical audio threads.

aic._bindings.model_reset(model)

Clear all internal state and buffers (real-time safe).

Call this when the audio stream is interrupted or when seeking to prevent artifacts from previous audio content. The model remains initialized with the same configuration.

Parameters:

• model (AICModelPtrT) –

  Model instance. Must not be None.

Returns:

• None –

Processing

aic._bindings.process_planar(model, audio_ptr, num_channels, num_frames)

Process audio in-place with separate buffers per channel (planar layout).

Parameters:

• model (AICModelPtrT) –

  Initialized model instance.

• audio_ptr (Any) –

  Array of channel buffer pointers (float* const* on the C side).

• num_channels (int) –

  Number of channels (must match initialization; max 16 channels).

• num_frames (int) –

  Number of samples per channel (must match initialization).

Returns:

• None –

Raises:

• RuntimeError –

  If the model is not initialized, inputs are null, or the channel/frame configuration does not match the initialization.

aic._bindings.process_interleaved(model, audio_ptr, num_channels, num_frames)

Process audio in-place with interleaved channel data.

Parameters:

• model (AICModelPtrT) –

  Initialized model instance.

• audio_ptr (Any) –

  Interleaved audio buffer pointer.

• num_channels (int) –

  Number of channels (must match initialization).

• num_frames (int) –

  Number of frames per channel (must match initialization).

Returns:

• None –

Raises:

• RuntimeError –

  If the model is not initialized, inputs are null, or the channel/frame configuration does not match the initialization.

aic._bindings.process_sequential(model, audio_ptr, num_channels, num_frames)

Process audio in-place with sequential channel data in a single buffer.

Processes audio where all samples for each channel are stored sequentially (channel 0 samples, then channel 1 samples, etc.) rather than interleaved.

Parameters:

• model (AICModelPtrT) –

  Initialized model instance.

• audio_ptr (Any) –

  Sequential audio buffer pointer containing all samples for channel 0, followed by all samples for channel 1, etc.

• num_channels (int) –

  Number of channels (must match initialization).

• num_frames (int) –

  Number of frames per channel (must match initialization).

Returns:

• None –

Raises:

• RuntimeError –

  If the model is not initialized, inputs are null, or the channel/frame configuration does not match the initialization.

Enhancement Parameters

aic._bindings.set_parameter(model, param, value)

Modify a model parameter (thread-safe).

Parameters:

• model (AICModelPtrT) –

  Model instance. Must not be None.

• param (AICEnhancementParameter) –

  Parameter to modify.

• value (float) –

  New parameter value. See parameter docs for valid ranges.

Returns:

• None –

Raises:

• RuntimeError –

  If the value is outside the acceptable range.

aic._bindings.get_parameter(model, param)

Retrieve the current value of a parameter (thread-safe).

Parameters:

• model (AICModelPtrT) –

  Model instance. Must not be None.

• param (AICEnhancementParameter) –

  Parameter to query.

Returns:

• float –

  The current value of the parameter.

Information helpers

aic._bindings.get_processing_latency(model)

Return total output delay in samples for the current configuration.

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 the configured sample rate and frame size, including any additional buffering when using non-optimal frame sizes.

Parameters:

• model (AICModelPtrT) –

  Model instance. Must not be None.

Returns:

• int –

  Delay in samples (at the current sample rate). Convert to milliseconds via delay_ms = delay_samples * 1000 / sample_rate.

aic._bindings.get_output_delay(model)

Alias of :func:get_processing_latency.

Parameters:

• model (AICModelPtrT) –

  Model instance.

Returns:

• int –

  Delay in samples.

aic._bindings.get_optimal_sample_rate(model)

Return the model's native sample rate in Hz.

Each model is optimized for a specific sample rate. While processing at other rates is supported, enhancement quality for high frequencies is bounded by the model's native Nyquist frequency.

Parameters:

• model (AICModelPtrT) –

  Model instance.

Returns:

• int –

  Native/optimal sample rate in Hz.

aic._bindings.get_optimal_num_frames(model, sample_rate)

Return the optimal number of frames for minimal latency at a sample rate.

Using the optimal frame size avoids internal buffering and thus minimizes end-to-end delay. The optimal value depends on sample rate and updates when the model is initialized with a different rate. Before initialization this returns the optimal size for the provided sample rate.

Parameters:

• model (AICModelPtrT) –

  Model instance.

• sample_rate (int) –

  Sample rate in Hz for which to query the optimal frame count.

Returns:

• int –

  Optimal frame count for the current/native sample rate.

aic._bindings.get_library_version()

Return the SDK version string.

The returned value originates from a static C string and is safe to use for the lifetime of the program.

Returns:

• str –

  Semantic version string, for example "1.2.3".

Voice Activity Detection (VAD)

aic._bindings.vad_create(model)

Create a Voice Activity Detector bound to a model.

aic._bindings.vad_destroy(vad)

Destroy a VAD instance (idempotent).

aic._bindings.vad_is_speech_detected(vad)

Return the current VAD prediction.

aic._bindings.vad_set_parameter(vad, param, value)

Set a VAD parameter.

aic._bindings.vad_get_parameter(vad, param)

Get a VAD parameter.

Enums

aic._bindings.AICErrorCode

Error codes returned by the C API.

These mirror the values from the underlying SDK and are raised as RuntimeError by the thin wrappers in this module when a call does not succeed.

AUDIO_CONFIG_MISMATCH = 5 class-attribute instance-attribute

Process was called with a different audio buffer configuration than initialized.

AUDIO_CONFIG_UNSUPPORTED = 4 class-attribute instance-attribute

Audio configuration is not supported by the model.

ENHANCEMENT_NOT_ALLOWED = 6 class-attribute instance-attribute

SDK key not authorized or usage reporting failed (check internet connection).

INTERNAL_ERROR = 7 class-attribute instance-attribute

Internal error occurred. Contact support.

LICENSE_EXPIRED = 52 class-attribute instance-attribute

License key has expired.

LICENSE_FORMAT_INVALID = 50 class-attribute instance-attribute

License key format is invalid or corrupted.

LICENSE_VERSION_UNSUPPORTED = 51 class-attribute instance-attribute

License version is not compatible with this SDK version.

MODEL_NOT_INITIALIZED = 3 class-attribute instance-attribute

Model must be initialized before this operation.

NULL_POINTER = 1 class-attribute instance-attribute

Required pointer argument was NULL.

PARAMETER_FIXED = 8 class-attribute instance-attribute

The requested parameter is read-only for this model type and cannot be modified.

PARAMETER_OUT_OF_RANGE = 2 class-attribute instance-attribute

Parameter value is outside acceptable range.

SUCCESS = 0 class-attribute instance-attribute

Operation completed successfully.

aic._bindings.AICModelType

Available model types for audio enhancement.

Each model is optimized for a native sample rate and frame size and has a characteristic processing latency.

QUAIL_L16 = 1 class-attribute instance-attribute

Specifications:

• Native sample rate: 16 kHz
• Native num frames: 160
• Processing latency: 30 ms

QUAIL_L48 = 0 class-attribute instance-attribute

Specifications:

• Native sample rate: 48 kHz
• Native num frames: 480
• Processing latency: 30 ms

QUAIL_L8 = 2 class-attribute instance-attribute

Specifications:

• Native sample rate: 8 kHz
• Native num frames: 80
• Processing latency: 30 ms

QUAIL_S16 = 4 class-attribute instance-attribute

Specifications:

• Native sample rate: 16 kHz
• Native num frames: 160
• Processing latency: 30 ms

QUAIL_S48 = 3 class-attribute instance-attribute

Specifications:

• Native sample rate: 48 kHz
• Native num frames: 480
• Processing latency: 30 ms

QUAIL_S8 = 5 class-attribute instance-attribute

Specifications:

• Native sample rate: 8 kHz
• Native num frames: 80
• Processing latency: 30 ms

QUAIL_STT_L16 = 8 class-attribute instance-attribute

Special model optimized for human-to-machine interaction (e.g., voice agents, speech-to-text) designed specifically to improve STT accuracy across unpredictable, diverse and challenging environments.

Specifications:

• Window length: 10 ms
• Native sample rate: 16 kHz
• Native num frames: 160
• Processing latency: 30 ms

QUAIL_STT_L8 = 9 class-attribute instance-attribute

Special model optimized for human-to-machine interaction (e.g., voice agents, speech-to-text) designed specifically to improve STT accuracy across unpredictable, diverse and challenging environments.

Specifications:

• Window length: 10 ms
• Native sample rate: 8 kHz
• Native num frames: 80
• Processing latency: 30 ms

QUAIL_STT_S16 = 10 class-attribute instance-attribute

Special model optimized for human-to-machine interaction (e.g., voice agents, speech-to-text) designed specifically to improve STT accuracy across unpredictable, diverse and challenging environments.

Specifications:

• Window length: 10 ms
• Native sample rate: 16 kHz
• Native num frames: 160
• Processing latency: 30 ms

QUAIL_STT_S8 = 11 class-attribute instance-attribute

Special model optimized for human-to-machine interaction (e.g., voice agents, speech-to-text) designed specifically to improve STT accuracy across unpredictable, diverse and challenging environments.

Specifications:

• Window length: 10 ms
• Native sample rate: 8 kHz
• Native num frames: 80
• Processing latency: 30 ms

QUAIL_VF_STT_L16 = 12 class-attribute instance-attribute

Special model optimized for human-to-machine interaction (e.g., voice agents, speech-to-text) purpose-built to isolate and elevate the foreground speaker while suppressing both interfering speech and background noise.

Specifications:

• Window length: 10 ms
• Native sample rate: 16 kHz
• Native num frames: 160
• Processing latency: 30 ms

QUAIL_XS = 6 class-attribute instance-attribute

Specifications:

• Native sample rate: 48 kHz
• Native num frames: 480
• Processing latency: 10 ms

QUAIL_XXS = 7 class-attribute instance-attribute

Specifications:

• Native sample rate: 48 kHz
• Native num frames: 480
• Processing latency: 10 ms

aic._bindings.AICEnhancementParameter

Configurable parameters for audio enhancement.

BYPASS = 0 class-attribute instance-attribute

Bypass audio processing while preserving algorithmic delay.

Range: 0.0 … 1.0

• 0.0: Enhancement active (normal processing)
• 1.0: Bypass enabled (latency-compensated passthrough)

Default: 0.0

ENHANCEMENT_LEVEL = 1 class-attribute instance-attribute

Controls the intensity of speech enhancement processing.

Range: 0.0 … 1.0

• 0.0: No enhancement
• 1.0: Full enhancement (maximum noise reduction, potentially more artifacts)

Default: 1.0

NOISE_GATE_ENABLE = 3 class-attribute instance-attribute

Enable or disable a noise gate as a post-processing step.

Valid values: 0.0 or 1.0

• 0.0: Noise gate disabled
• 1.0: Noise gate enabled

Default: 0.0

VOICE_GAIN = 2 class-attribute instance-attribute

Compensates for perceived volume reduction after noise removal.

Range: 0.1 … 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 * log10(value) Default: 1.0

aic._bindings.AICParameter = AICEnhancementParameter module-attribute

aic._bindings.AICVadParameter

Configurable parameters for Voice Activity Detection (VAD).

MINIMUM_SPEECH_DURATION = 2 class-attribute instance-attribute

Controls for how long speech needs to be present 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 buffer. For example, if the model is initialized to process audio in chunks of 10 ms, the VAD will round up/down to the closest multiple of 10 ms. Because of this, this parameter may return a different value than the one it was last set to.

Range: 0.0 … 1.0 (value in seconds) Default: 0.0

SENSITIVITY = 1 class-attribute instance-attribute

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

SPEECH_HOLD_DURATION = 0 class-attribute instance-attribute

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. For example, if the model has a processing window length of 10 ms, the VAD will round up/down to the closest multiple of 10 ms. Because of this, this parameter may return a different value than the one it was last set to.

Range: 0.0 to 20x model window length (value in seconds)

Default: 0.05