> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python audio analysis

> Python reference for analyzer_pair, Collector, Analyzer, FileAnalyzer and AnalysisResult in aic-sdk 3.2.0.

**Package:** `aic-sdk==3.2.0`. **Core SDK:** `0.24.0`. Source: [Python wrapper 3.2.0](https://github.com/ai-coustics/aic-sdk-py/tree/cca6f30d448c8e97bf7cfb13d6528a63de8f2c39).

The fragments below use these imports. Supply `license_key` from your approved secret source and use the loaded model and initialized objects described in each section. For complete examples, follow [batch call analysis](/models/audio-insight/batch-call-analysis) with `FileAnalyzer` or [real-time analysis](/models/audio-insight/real-time-analysis) with `analyzer_pair`.

```python theme={null}
import numpy as np
import numpy.typing as npt
import aic_sdk as aic
from aic_sdk import Model, ProcessorConfig, Collector, Analyzer, FileAnalyzer, AnalysisResult
```

`audio` denotes a one-dimensional NumPy `float32` array. Async fragments run inside an async function.

<a id="analyzer_pair" />

<a id="aic_sdk-analyzer_pair" />

## analyzer\_pair()

<p><Badge>function</Badge></p>

```python theme={null}
def analyzer_pair(model: Model, license_key: str) -> tuple[Collector, Analyzer]
```

For a complete collector/worker example, follow [real-time analysis with Tyto](/models/audio-insight/real-time-analysis).

Creates a [`Collector`](/reference/sdk/api/python/analysis#collector)/[`Analyzer`](/reference/sdk/api/python/analysis#analyzer) pair for non-real-time analysis.

Buffer audio in the capture path and run analysis on a separate thread. The analyzer safely reads the collector across threads. Native buffering releases the GIL, but interpreter calls and strided-array copies do not guarantee hard real-time execution.

The collector retains a span of audio determined by the analysis model. As more samples get collected, old audio is discarded.

**Parameters**

<ResponseField name="model" type="Model" required>
  The loaded model instance. See [`Model`](/reference/sdk/api/python/models-and-config#model).
</ResponseField>

<ResponseField name="license_key" type="str" required>
  SDK key or JWT for the ai-coustics SDK (generate your key at [developers.ai-coustics.com](https://developers.ai-coustics.com/)).
</ResponseField>

**Returns**

* `tuple[Collector, Analyzer]`: A tuple of ([`Collector`](/reference/sdk/api/python/analysis#collector), [`Analyzer`](/reference/sdk/api/python/analysis#analyzer)).

**Raises**

* [`LicenseFormatInvalidError`](/reference/sdk/api/python/errors#licenseformatinvaliderror): If the license key string contains null bytes.
* [SDK exceptions](/reference/sdk/api/python/errors): Invalid credentials, an unsupported model type or native creation failures.

**Example**

```python theme={null}
collector, analyzer = aic.analyzer_pair(model, license_key)
config = aic.ProcessorConfig.optimal(model)
collector.initialize(config)
```

<a id="collector" />

<a id="aic_sdk-Collector" />

## Collector

<p><Badge>class</Badge></p>

Buffers audio for later analysis.

The collector is designed to be placed in the audio thread, buffering audio chunks for the [`Analyzer`](/reference/sdk/api/python/analysis#analyzer) to analyze later.

Created via [`analyzer_pair()`](/reference/sdk/api/python/analysis#analyzer_pair).

<a id="collector-initialize" />

<a id="aic_sdk-Collector-initialize" />

### Collector.initialize()

```python theme={null}
def initialize(self, config: ProcessorConfig) -> None
```

Configures the collector for specific audio settings.

This function must be called before buffering any audio. Using the sample rate and block size returned by [`Model.get_optimal_sample_rate()`](/reference/sdk/api/python/models-and-config#model-get_optimal_sample_rate) and [`Model.get_optimal_block_size()`](/reference/sdk/api/python/models-and-config#model-get_optimal_block_size) avoids internal resampling and rebuffering.

**Parameters**

<ResponseField name="config" type="ProcessorConfig" required>
  Audio buffering configuration. See [`ProcessorConfig`](/reference/sdk/api/python/models-and-config#processorconfig).
</ResponseField>

**Raises**

* [`AudioConfigUnsupportedError`](/reference/sdk/api/python/errors#audioconfigunsupportederror): If the audio configuration is unsupported.

<Warning>
  Do not call from audio processing threads as this allocates memory.
</Warning>

**Example**

```python theme={null}
config = aic.ProcessorConfig.optimal(model)
collector.initialize(config)
```

<a id="collector-buffer" />

<a id="aic_sdk-Collector-buffer" />

### Collector.buffer()

```python theme={null}
def buffer(self, buffer: npt.NDArray[np.float32]) -> None
```

Buffers a one-dimensional NumPy `float32` array of mono samples without changing it. Contiguous arrays are read directly and strided arrays are copied. Do not mutate input concurrently. Native work releases the GIL. Supply the configured fixed length or a length up to `block_size` when variable blocks are enabled. Wrong dtype or dimensionality raises `TypeError`.

**Parameters**

<ResponseField name="buffer" type="npt.NDArray[np.float32]" required>
  1D NumPy array of mono float32 samples to be buffered.
</ResponseField>

**Raises**

* [`NotInitializedError`](/reference/sdk/api/python/errors#notinitializederror): If the collector has not been initialized.
* [`AudioConfigMismatchError`](/reference/sdk/api/python/errors#audioconfigmismatcherror): If the buffer shape doesn't match the configured audio settings.

**Example**

```python theme={null}
audio = np.zeros(config.block_size, dtype=np.float32)
collector.buffer(audio)
```

<a id="analyzer" />

<a id="aic_sdk-Analyzer" />

## Analyzer

<p><Badge>class</Badge></p>

Runs an analysis model over the audio buffered by a [`Collector`](/reference/sdk/api/python/analysis#collector).

Run analysis outside the audio thread. The analyzer safely reads audio from a collector on another thread.

Created via [`analyzer_pair()`](/reference/sdk/api/python/analysis#analyzer_pair).

<a id="analyzer-reset" />

<a id="aic_sdk-Analyzer-reset" />

### Analyzer.reset()

```python theme={null}
def reset(self) -> None
```

Requests a reset of analyzer and collector state and buffers. The collector applies it on the next collection pass. Until then, analysis reads a zero-filled snapshot instead of the previously published audio.

Call this when the audio stream is interrupted or when seeking to prevent mispredictions from previous audio content. This operates on both the analyzer and its collector. The collector stays initialized to the configured settings.

<Note>
  **Concurrency.** Reset requests clear shared analyzer and collector state. Serialize reset with your application's stream boundaries; Python calls are not a hard real-time guarantee.
</Note>

**Example**

```python theme={null}
analyzer.reset()
```

<a id="analyzer-analyze_buffered" />

<a id="aic_sdk-Analyzer-analyze_buffered" />

### Analyzer.analyze\_buffered()

```python theme={null}
def analyze_buffered(self) -> AnalysisResult
```

Analyzes the buffered signal, releasing the GIL during native work. Calls on the same analyzer must be serialized. `ProcessingNotAllowedError` means no `AnalysisResult` is returned; other native failures use the [SDK exception mapping](/reference/sdk/api/python/errors).

Analyzes a fixed-length window determined by the model. If the collector has buffered less audio, the input tail is padded with silence.

**Returns**

* [`AnalysisResult`](/reference/sdk/api/python/analysis#analysisresult): An AnalysisResult.

<Note>
  This function is not real-time safe. Avoid calling it from audio threads.
</Note>

**Example**

```python theme={null}
result = analyzer.analyze_buffered()
print(result.risk_score)
```

<a id="analyzer-terminate_session" />

<a id="aic_sdk-Analyzer-terminate_session" />

### Analyzer.terminate\_session()

```python theme={null}
def terminate_session(self) -> None
```

Terminates the analyzer's telemetry session.

Stop submitting audio and treat this session as closed once you request termination. Processing becomes disallowed when the native lifecycle task handles the signal. The call can return before that handling completes when other sessions remain alive; it is not proof of remote usage acknowledgment. The session is also stopped when the object is destroyed.

<Warning>
  This method may block and is not real-time safe.
</Warning>

<a id="analyzer-update_bearer_token" />

<a id="aic_sdk-Analyzer-update_bearer_token" />

### Analyzer.update\_bearer\_token()

```python theme={null}
def update_bearer_token(self, token: str) -> None
```

Replaces the bearer token on the analyzer.

Use this when your license key is a JWT and needs to be refreshed before it expires. The replacement is used for subsequent authentication. A successful update does not prove backend acceptance or uninterrupted processing; continue handling processing errors. Both the original key and the new token must be JWTs; otherwise a [`TokenUnsupportedError`](/reference/sdk/api/python/errors#tokenunsupportederror) is raised and the existing token stays in use.

**Parameters**

<ResponseField name="token" type="str" required>
  The new JWT to install.
</ResponseField>

**Raises**

* [`TokenUnsupportedError`](/reference/sdk/api/python/errors#tokenunsupportederror): If either the original or new token is not a JWT.
* [`LicenseFormatInvalidError`](/reference/sdk/api/python/errors#licenseformatinvaliderror): If the token string contains null bytes.

**Example**

```python theme={null}
analyzer.update_bearer_token(renewed_jwt)
```

<a id="fileanalyzer" />

<a id="aic_sdk-FileAnalyzer" />

## FileAnalyzer

<p><Badge>class</Badge></p>

Analyzes complete mono audio buffers.

FileAnalyzer is a convenience wrapper around a [`Collector`](/reference/sdk/api/python/analysis#collector) and [`Analyzer`](/reference/sdk/api/python/analysis#analyzer) pair for non-real-time analysis of audio that is already loaded in memory.

Each call to [`analyze()`](/reference/sdk/api/python/analysis#fileanalyzer-analyze) configures the collector for mono input with the model's optimal block size. It analyzes independent five-second windows, advancing the start of each window by `step_samples`.

For a complete file-analysis example, follow [batch call analysis with Tyto](/models/audio-insight/batch-call-analysis). For streaming analysis, use [`analyzer_pair()`](/reference/sdk/api/python/analysis#analyzer_pair) directly.

**Example**

```python theme={null}
analyzer = aic.FileAnalyzer(model, license_key)
results = analyzer.analyze(audio, 16000)
print(results[0].risk_score)
```

<a id="fileanalyzer-constructor" />

<a id="aic_sdk-FileAnalyzer-constructor" />

### FileAnalyzer() constructor

```python theme={null}
FileAnalyzer(model: Model, license_key: str) -> FileAnalyzer
```

Creates a new file analyzer for a Tyto analysis model. The wrapper retains a strong reference to `model`. There is no file-path argument: decode the file into mono `float32` samples before calling `analyze()`. Native resources are released when the object is released. This class has no public token-update or session-termination method; use the streaming `Analyzer` when those controls are needed.

The collector is not initialized until [`analyze()`](/reference/sdk/api/python/analysis#fileanalyzer-analyze) is called. This lets the same FileAnalyzer instance analyze mono buffers with different sample rates or step sizes.

**Parameters**

<ResponseField name="model" type="Model" required>
  The loaded model instance. See [`Model`](/reference/sdk/api/python/models-and-config#model).
</ResponseField>

<ResponseField name="license_key" type="str" required>
  SDK key or JWT for the ai-coustics SDK (generate your key at [developers.ai-coustics.com](https://developers.ai-coustics.com/)).
</ResponseField>

**Raises**

* [`LicenseFormatInvalidError`](/reference/sdk/api/python/errors#licenseformatinvaliderror): If the license key string contains null bytes.
* [SDK exceptions](/reference/sdk/api/python/errors): Invalid credentials, an unsupported model type or native creation failures.

**Example**

```python theme={null}
analyzer = aic.FileAnalyzer(model, license_key)
```

<a id="fileanalyzer-analyze" />

<a id="aic_sdk-FileAnalyzer-analyze" />

### FileAnalyzer.analyze()

```python theme={null}
def analyze(
    self,
    audio: npt.NDArray[np.float32],
    sample_rate: int,
    step_samples: int | None = None,
) -> list[AnalysisResult]
```

Analyzes a complete mono audio buffer.

The input must be a one-dimensional NumPy `float32` array of mono samples at the actual `sample_rate`. There is no channel mixing. Native collection handles supported non-native input rates. The wrapper reads contiguous input directly and copies strided input; native analysis releases the GIL. Do not mutate the input concurrently. Wrong dtype or dimensionality raises `TypeError`.

The analyzer evaluates five-second windows. FileAnalyzer buffers a window starting at sample 0, runs the analyzer once, resets, then repeats with a window starting `step_samples` later. If audio is empty, shorter than or equal to five seconds, it is padded with silence and a single result is returned. For longer signals, only complete five-second windows are analyzed after the first window.

**Parameters**

<ResponseField name="audio" type="npt.NDArray[np.float32]" required>
  1D NumPy array of mono float32 samples to analyze.
</ResponseField>

<ResponseField name="sample_rate" type="int" required>
  Sample rate of audio in Hz.
</ResponseField>

<ResponseField name="step_samples" type="int | None" default="None">
  Number of samples to advance between analysis results. Defaults to `5 * sample_rate` samples with no overlap. Must be greater than zero. Smaller values overlap windows; larger values leave gaps.
</ResponseField>

**Returns**

* `list[AnalysisResult]`: A list of [`AnalysisResult`](/reference/sdk/api/python/analysis#analysisresult) values, one per analysis window.

**Raises**

* [`AudioConfigUnsupportedError`](/reference/sdk/api/python/errors#audioconfigunsupportederror): If the sample rate or step size is unsupported.

**Example**

```python theme={null}
results = analyzer.analyze(audio, 16000)
print(results[0].risk_score)
```

<a id="analysisresult" />

<a id="aic_sdk-AnalysisResult" />

## AnalysisResult

<p><Badge>class</Badge></p>

The result of analyzing an audio signal with an [`Analyzer`](/reference/sdk/api/python/analysis#analyzer).

Returned results expose read-only properties; there is no public `AnalysisResult()` constructor. Scores are model outputs in the range 0.0–1.0, not calibrated probabilities or guarantees about a specific downstream system. For all fields except `speaker_loudness`, lower values indicate less problematic audio.

<a id="analysisresult-risk_score" />

<a id="aic_sdk-AnalysisResult-risk_score" />

#### AnalysisResult.risk\_score

<ResponseField name="risk_score" type="float" post={["read-only"]}>
  Headline audio score.

  Predicts likelihood of failure of downstream models including speech-to-text, voice activity detection or turn-taking or speech-to-speech models. Lower indicates less problematic audio.

  **Range:** 0.0–1.0
</ResponseField>

<a id="analysisresult-speaker_reverb" />

<a id="aic_sdk-AnalysisResult-speaker_reverb" />

#### AnalysisResult.speaker\_reverb

<ResponseField name="speaker_reverb" type="float" post={["read-only"]}>
  Measure of speaker distance and reverberance. Lower indicates less problematic audio.

  **Range:** 0.0–1.0
</ResponseField>

<a id="analysisresult-speaker_loudness" />

<a id="aic_sdk-AnalysisResult-speaker_loudness" />

#### AnalysisResult.speaker\_loudness

<ResponseField name="speaker_loudness" type="float" post={["read-only"]}>
  Measure of speaker loudness.

  **Range:** 0.0–1.0
</ResponseField>

<a id="analysisresult-interfering_speech" />

<a id="aic_sdk-AnalysisResult-interfering_speech" />

#### AnalysisResult.interfering\_speech

<ResponseField name="interfering_speech" type="float" post={["read-only"]}>
  Measure of interference from additional speakers present in audio. Lower indicates less problematic audio.

  **Range:** 0.0–1.0
</ResponseField>

<a id="analysisresult-noise" />

<a id="aic_sdk-AnalysisResult-noise" />

#### AnalysisResult.noise

<ResponseField name="noise" type="float" post={["read-only"]}>
  Measure of ambient or environmental noise. Lower indicates less problematic audio.

  **Range:** 0.0–1.0
</ResponseField>

<a id="analysisresult-codec_degradation" />

<a id="aic_sdk-AnalysisResult-codec_degradation" />

#### AnalysisResult.codec\_degradation

<ResponseField name="codec_degradation" type="float" post={["read-only"]}>
  Measure of artifacts introduced by lossy speech codecs, e.g. from a low bitrate or a narrowband codec. Lower indicates less problematic audio.

  **Range:** 0.0–1.0

  Added in Python package 3.1.0.
</ResponseField>

<a id="analysisresult-packet_loss" />

<a id="aic_sdk-AnalysisResult-packet_loss" />

#### AnalysisResult.packet\_loss

<ResponseField name="packet_loss" type="float" post={["read-only"]}>
  Measure of audio dropouts or discontinuities in the stream, e.g. from packet loss, frame erasure, jitter or CPU overload. Lower indicates less problematic audio.

  **Range:** 0.0–1.0
</ResponseField>

See the [Python API index](/reference/sdk/api/python/index), [batch call analysis](/models/audio-insight/batch-call-analysis), [real-time analysis](/models/audio-insight/real-time-analysis) and [troubleshooting](/production/troubleshooting).

<a id="analysisresult-__repr__" />

<a id="aic_sdk-AnalysisResult-__repr__" />

### AnalysisResult.**repr**()

```python theme={null}
def __repr__(self) -> str
```

Returns a diagnostic string containing the object's current fields. It is not a serialization format.