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.

Parameters

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

Modify a model parameter (thread-safe).

Parameters:

• model (AICModelPtrT) –

  Model instance. Must not be None.

• param (AICParameter) –

  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 (AICParameter) –

  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".

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_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_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.AICParameter

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