Migrate Python SDK 2.5 to 3.0

Python SDK 3.0 tracks core SDK 0.22.0. It contains two breaking changes that affect every integration, plus a set of renames.

Audio is mono only

process() and buffer() take a 1D array. The internal mixdown is gone.

VAD is its own object

Vad runs a dedicated VAD model. Energy-based VAD is removed.

This page is the Python-specific reference. The two guides above explain the reasoning and the audio-handling changes in more detail.

Your license key and your enhancement models keep working. No key regeneration is needed for this upgrade.

Quick migration checklist

Downmix to mono

Pass a 1D float32 array to process(), process_async(), and buffer(). A 2D array now raises AudioConfigMismatchError.

Rename the config fields

num_frames is block_size, allow_variable_frames is variable_block_size, and num_channels is gone.

Rename get_processor_context

It is now get_context() on both Processor and ProcessorAsync.

Replace the processor-owned VAD

Create a Vad or VadAsync from a dedicated VAD model. get_vad_context() no longer exists.

Update the three renamed error classes

NotInitializedError, ProcessingNotAllowedError, and FilePathInvalidError.

Keep model types in the right objects

Processor takes enhancement and bypass models only. Vad takes VAD models only.

Renames

`ProcessorConfig`

ProcessorConfig is shared by Processor, Vad, and Collector.

2.5	3.0
`ProcessorConfig(sample_rate, num_channels, num_frames, allow_variable_frames)`	`ProcessorConfig(sample_rate, block_size, variable_block_size)`
`config.num_frames`	`config.block_size`
`config.allow_variable_frames`	`config.variable_block_size`
`config.num_channels`	Removed
`ProcessorConfig.optimal(model, num_channels=2)`	`ProcessorConfig.optimal(model)`

config = aic.ProcessorConfig(
    sample_rate=48000,
    num_channels=2,
    num_frames=480,
    allow_variable_frames=False,
)

config = aic.ProcessorConfig(
    sample_rate=48000,
    block_size=480,
    variable_block_size=False,
)

`Model`

2.5	3.0
`model.get_optimal_num_frames(sample_rate)`	`model.get_optimal_block_size(sample_rate)`

`Processor` and `ProcessorAsync`

2.5	3.0
`processor.get_processor_context()`	`processor.get_context()`
`processor.get_vad_context()`	Removed, create a `Vad` instead
`processor.process(audio)` with a 2D array	`processor.process(audio)` with a 1D mono array
(not available)	`processor.terminate_session()`

`ProcessorContext`

2.5	3.0
`proc_ctx.get_output_delay()`	`proc_ctx.get_audio_delay()`

The rename says what the value delays. get_audio_delay() reports how far the enhanced samples lag their input. It no longer covers VAD timing, because the VAD has its own get_prediction_delay(). ProcessorContext.reset() now affects enhancement state only. Reset a VAD through its own VadContext.

Errors

2.5	3.0
`ModelNotInitializedError`	`NotInitializedError`
`EnhancementNotAllowedError`	`ProcessingNotAllowedError`
`ModelFilePathInvalidError`	`FilePathInvalidError`

Migrate enhancement

import aic_sdk as aic
import numpy as np

model = aic.Model.from_file(model_path)
config = aic.ProcessorConfig.optimal(model, num_channels=2)
processor = aic.Processor(model, license_key, config)

proc_ctx = processor.get_processor_context()
print(f"Delay: {proc_ctx.get_output_delay()} samples")

# Stereo in, stereo out. The SDK mixed both channels down internally.
audio = np.zeros((config.num_channels, config.num_frames), dtype=np.float32)
enhanced = processor.process(audio)

import aic_sdk as aic
import numpy as np

model = aic.Model.from_file(model_path)
config = aic.ProcessorConfig.optimal(model)
processor = aic.Processor(model, license_key, config)

proc_ctx = processor.get_context()
print(f"Delay: {proc_ctx.get_audio_delay()} samples")

# Mono in, mono out. Downmix in your application first.
audio = np.zeros(config.block_size, dtype=np.float32)
enhanced = processor.process(audio)

To downmix a file loaded with soundfile:

import numpy as np
import soundfile as sf

audio, sample_rate = sf.read(path, dtype="float32")

# audio is (frames,) for mono or (frames, channels) for multi-channel.
if audio.ndim > 1:
    audio = audio.mean(axis=1)

audio = np.ascontiguousarray(audio, dtype=np.float32)

mean(axis=1) widens to float64 for many input dtypes, so cast back to float32. process() also needs a contiguous array, which is why slices of a larger buffer may need np.ascontiguousarray.

To keep channels separate, create one Processor per channel. Each one holds the state for exactly one stream.

Migrate VAD

# The VAD came from the enhancement processor.
processor = aic.Processor(model, license_key, config)
vad_ctx = processor.get_vad_context()
vad_ctx.set_parameter(aic.VadParameter.Sensitivity, 5.0)  # energy threshold

enhanced = processor.process(audio)  # also advanced the VAD

if vad_ctx.is_speech_detected():
    print("Speech detected")

# The VAD is its own object, backed by a dedicated VAD model.
vad_model = aic.Model.from_file(
    aic.Model.download("vad-2.1-xxs-16khz", "./models")
)
vad = aic.Vad(vad_model, license_key, aic.ProcessorConfig.optimal(vad_model))
vad_ctx = vad.get_context()
vad_ctx.set_parameter(aic.VadParameter.Sensitivity, 0.8)  # probability

vad.process(audio)  # returns None, does not modify the audio

if vad_ctx.is_speech_detected():
    print("Speech detected")

VadParameter.Sensitivity is now a probability threshold from 0.0 to 1.0, and the direction is inverted: higher values require more confidence and therefore fire less often. Old energy-threshold values above 1.0 raise ParameterOutOfRangeError. Retune against real audio and start from the model default. See Retune sensitivity.

Running both together, on the same original input block:

vad.process(audio)                 # reads the block
enhanced = processor.process(audio) # returns the enhanced block

Feed the VAD the original input rather than the enhanced output. Enhancement changes the signal the VAD model was trained on, and it adds the processor’s delay on top of the VAD’s own.

Async VAD

VadAsync mirrors ProcessorAsync:

vad = aic.VadAsync(vad_model, license_key)
await vad.initialize_async(config)
await vad.process_async(audio)

print(vad.get_context().is_speech_detected())
await vad.terminate_session_async()

`VadContext`

VadContext gained the methods the processor context already had:

Method	Notes
`is_speech_detected()`	Unchanged
`raw_vad_probability()`	Unchanged. The model’s probability before thresholding, useful for picking a sensitivity value
`get_prediction_delay()`	New on the VAD. How far the published prediction lags its input, independent of the processor’s audio delay
`reset()`	New. Clears VAD state and immediately clears the published decision and probability
`update_bearer_token(token)`	New. Same JWT rules as the processor context

These names match the C API’s aic_processor_context_get_audio_delay and aic_vad_context_get_prediction_delay.

Model types are enforced

Object	Accepts
`Processor`, `ProcessorAsync`	Enhancement and bypass models
`Vad`, `VadAsync`	Dedicated VAD models
`Analyzer`, `FileAnalyzer`	Analysis models

A mismatch raises ModelTypeUnsupportedError at creation time.

Session termination

Processor, Vad, and Analyzer can now close their telemetry session explicitly, instead of waiting for garbage collection:

processor.terminate_session()
vad.terminate_session()

# Async variants
await processor.terminate_session_async()
await vad.terminate_session_async()

The object cannot process more audio afterwards. The session is still terminated automatically on destruction, so this is only needed where deallocation may be delayed.

Validation

Confirm every process(), process_async(), and buffer() call receives a contiguous 1D float32 array.
Confirm no code still reads config.num_frames, config.num_channels, or config.allow_variable_frames.
Search for get_processor_context and get_vad_context.
Search for the three renamed error classes, including in except clauses.
Compare speech detection against representative audio after retuning sensitivity.
Compare enhancement output level against representative recordings if you previously relied on the internal mixdown and mixback.

Need help?

See the GitHub repository and the type stubs file.
Browse available models at artifacts.ai-coustics.io.
Check the compatibility matrix for binding, core, and model file versions.

SDK Reference

Concepts

Deprecated

Migrate Python SDK 2.5 to 3.0

Audio is mono only

VAD is its own object

Quick migration checklist

Renames

`ProcessorConfig`

`Model`

`Processor` and `ProcessorAsync`

`ProcessorContext`

Errors

Migrate enhancement

Migrate VAD

Async VAD

`VadContext`

Model types are enforced

Session termination

Validation

Need help?

Audio is mono only

VAD is its own object

​Quick migration checklist

​Renames

​ProcessorConfig

​Model

​Processor and ProcessorAsync

​ProcessorContext

​Errors

​Migrate enhancement

​Migrate VAD

​Async VAD

​VadContext

​Model types are enforced

​Session termination

​Validation

​Need help?

Quick migration checklist

Renames

`ProcessorConfig`

`Model`

`Processor` and `ProcessorAsync`

`ProcessorContext`

Errors

Migrate enhancement

Migrate VAD

Async VAD

`VadContext`

Model types are enforced

Session termination

Validation

Need help?