> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/labs-voice-agent/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/labs-voice-agent/_mcp/server.

# nemo_voice_agent.utils.audio

## Module Contents

### Classes

| Name                                                                                 | Description                                                                                                    |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| [`AudioStream`](#nemo_voice_agent-utils-audio-AudioStream)                           | A class that simulates a realtime audio stream. It caches the input audio chunks                               |
| [`NoiseConfig`](#nemo_voice_agent-utils-audio-NoiseConfig)                           | A class that configures the noise for the audio stream.                                                        |
| [`NoiseGenerator`](#nemo_voice_agent-utils-audio-NoiseGenerator)                     | A class that generates noise audio by reading provided noise audio files.                                      |
| [`SOXRAudioResampler`](#nemo_voice_agent-utils-audio-SOXRAudioResampler)             | An audio resampler that uses the SoX resampler library. It's stateless and will return the result immediately. |
| [`SOXRAudioStreamResampler`](#nemo_voice_agent-utils-audio-SOXRAudioStreamResampler) | A class that resamples an audio stream using the SoX resampler library.                                        |

### Functions

| Name                                                                             | Description                                                                |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`audio_bytes_to_float32`](#nemo_voice_agent-utils-audio-audio_bytes_to_float32) | Convert PCM-16 audio bytes to float32 numpy array, clamped to -1.0 to 1.0. |
| [`audio_float32_to_bytes`](#nemo_voice_agent-utils-audio-audio_float32_to_bytes) | Convert float32 numpy array to PCM-16 audio bytes.                         |

### Data

[`STREAM_TIMEOUT_SECS`](#nemo_voice_agent-utils-audio-STREAM_TIMEOUT_SECS)

### API

```python
class nemo_voice_agent.utils.audio.AudioStream(
    chunk_size_in_seconds: float,
    input_sample_rate: int,
    output_sample_rate: int,
    stream_resampler: bool = True,
    tag: str = '',
    min_buffer_chunks: int = 5,
    drain_threshold: int = 5,
    min_sustain_chunks: int = 1,
    noise_config: typing.Optional[nemo_voice_agent.utils.audio.NoiseConfig] = None
)
```

A class that simulates a realtime audio stream. It caches the input audio chunks
and resamples them to the output sample rate. Each time its get() function is called,
it returns the next chunk of audio at the output sample rate. If the audio cache doesn't
have enough audio to fill the output chunk, it will append silence to the output chunk.

The class will be used in an asyncio context, where one thread is putting audio chunks
into the cache and another thread is getting audio chunks from the cache.

**`_buffer_empty_count`**

---

**`_next_send_time`**

---

**`_prev_noise_scale`**

---

**`audio_cache`**

---

**`current_buffer_size`**

Get the current size of the buffer.

---

**`gain_db`**

---

**`noise_generator`**

---

**`output_buffer`**

---

**`output_chunk_bytes`**

---

**`resampler`**

---

```python
nemo_voice_agent.utils.audio.AudioStream._augment_with_noise(
    audio_chunk: bytes,
    noise_chunk: typing.Optional[bytes] = None
) -> bytes
```

Augment audio with noise based on random SNR sampling.

This method mixes audio with noise according to a gain\_db.

**Parameters:**

**`audio_chunk`**

Original audio bytes (16-bit signed integers)

---

**`noise_chunk`**

Noise audio bytes (16-bit signed integers)

---

**Returns:** `bytes`

Mixed audio with noise as bytes

```python
nemo_voice_agent.utils.audio.AudioStream._is_buffer_full() -> bool
```

Check if the buffer is full.

```python
nemo_voice_agent.utils.audio.AudioStream._send_audio_sleep()
```

async

Simulate audio device timing by sleeping between audio chunks.

```python
nemo_voice_agent.utils.audio.AudioStream.get_nowait() -> typing.Tuple[bytes, bool]
```

async

Get the next output chunk of audio, immediately padding with silence if no audio is available.

```python
nemo_voice_agent.utils.audio.AudioStream.get_output_chunk(
    audio_chunk: bytes,
    noise_chunk: typing.Optional[bytes] = None
) -> bytes
```

Pad audio chunk with silence/noise if shorter than expected output chunk size.

If noise\_chunk is provided and noise\_generator is available, the audio will be
augmented with noise based on SNR. Otherwise, it pads with silence (zeros).

**Parameters:**

**`audio_chunk`**

Audio bytes (16-bit signed integers)

---

**`noise_chunk`**

Optional noise bytes for augmentation

---

**Returns:** `bytes`

Audio chunk padded to output\_chunk\_bytes

```python
nemo_voice_agent.utils.audio.AudioStream.get_wait(
    timeout: float = None,
    no_wait: bool = False
) -> typing.Tuple[bytes, bool]
```

async

Get the next output chunk of audio, WAITING for audio to be available.

Unlike get(), this method will block and wait for audio to arrive rather than
immediately padding with silence. This prevents gaps in audio when packets
arrive in bursts (common in WebSocket/network scenarios).

Use this for continuous audio streaming where you want smooth audio without
artificial gaps.

Returns:
Tuple\[audio\_chunk, has\_speech]: Tuple containing the audio chunk bytes and a
boolean indicating if there's speech in the chunk

**Parameters:**

**`timeout`**

Maximum time to wait in seconds (None = no wait)

---

**`no_wait`**

If True, only tries to read the audio cache once, and returns silence
immediately if no audio is available.

---

```python
nemo_voice_agent.utils.audio.AudioStream.put(
    audio_chunk: bytes
)
```

async

Put an audio chunk into the audio cache after resampling.

**Parameters:**

**`audio_chunk`**

Input audio chunk at input\_sample\_rate

---

```python
nemo_voice_agent.utils.audio.AudioStream.resample(
    audio_chunk: bytes
) -> bytes
```

Resample an audio chunk from input sample rate to output sample rate.

**Parameters:**

**`audio_chunk`**

Raw audio bytes (16-bit signed integers)

---

**Returns:** `bytes`

Resampled audio bytes (16-bit signed integers)

```python
class nemo_voice_agent.utils.audio.NoiseConfig(
    noise_files: typing.Optional[typing.Union[typing.List[str], str]] = None,
    gain_db: float = 0.0,
    max_noise_duration: typing.Optional[float] = 600.0,
    random_offset: bool = True,
    random_white_noise: bool = False,
    white_noise_db: typing.Optional[float] = -90.0
)
```

Dataclass

A class that configures the noise for the audio stream.

**`gain_db`**

---

**`max_noise_duration`**

---

**`noise_files`**

---

**`random_offset`**

---

**`random_white_noise`**

---

**`white_noise_db`**

---

```python
nemo_voice_agent.utils.audio.NoiseConfig.to_dict() -> dict
```

Convert the noise configuration to a dictionary.

```python
class nemo_voice_agent.utils.audio.NoiseGenerator(
    noise_audio_files: typing.Union[typing.List[str], str],
    sample_rate: int,
    max_duration: typing.Optional[float] = None,
    random_offset: bool = True,
    random_white_noise: bool = False,
    white_noise_db: typing.Optional[float] = None
)
```

A class that generates noise audio by reading provided noise audio files.

**`current_position`**

---

**`noise_audio_data`**

---

```python
nemo_voice_agent.utils.audio.NoiseGenerator.generate_random_white_noise() -> numpy.ndarray
```

Generate random white noise with the given duration and sample rate.

**Returns:** `np.ndarray`

np.ndarray: Float32 white noise in \[-1.0, 1.0], length max\_duration \* sample\_rate.
Scaled by white\_noise\_db when set (amplitude = 10^(white\_noise\_db/20)).

```python
nemo_voice_agent.utils.audio.NoiseGenerator.get_noise_chunk(
    chunk_size_in_seconds: float
) -> numpy.ndarray
```

Get the next noise audio segment of chunk size chunk\_size\_in\_seconds, and return the chunk.
If the noise audio data is less than the chunk size, restart from the beginning.

**Parameters:**

**`chunk_size_in_seconds`**

Duration of the noise chunk to return in seconds.

---

**Returns:** `np.ndarray`

np.ndarray: Noise audio chunk of the requested duration.

```python
nemo_voice_agent.utils.audio.NoiseGenerator.get_noise_chunk_bytes(
    chunk_size_in_seconds: float
) -> bytes
```

Get the next noise audio segment of chunk size chunk\_size\_in\_seconds, and return the chunk as Int16 bytes.

```python
nemo_voice_agent.utils.audio.NoiseGenerator.load_audio_files() -> numpy.ndarray
```

Load the noise audio files.

```python
class nemo_voice_agent.utils.audio.SOXRAudioResampler(
    in_sample_rate: int,
    out_sample_rate: int,
    quality: str = 'VHQ',
    args = (),
    kwargs = {}
)
```

An audio resampler that uses the SoX resampler library. It's stateless and will return the result immediately.

```python
nemo_voice_agent.utils.audio.SOXRAudioResampler.resample(
    audio: bytes
) -> bytes
```

Resample audio data using SoX resampler library.

**Parameters:**

**`audio`**

Input audio data as raw bytes (16-bit signed integers).

---

**Returns:** `bytes`

Resampled audio data as raw bytes (16-bit signed integers).

```python
class nemo_voice_agent.utils.audio.SOXRAudioStreamResampler(
    in_sample_rate: int,
    out_sample_rate: int,
    quality: str = 'VHQ',
    args = (),
    kwargs = {}
)
```

A class that resamples an audio stream using the SoX resampler library.

**`resampler`**

---

```python
nemo_voice_agent.utils.audio.SOXRAudioStreamResampler._should_flush()
```

Check if the resampler should be flushed.

```python
nemo_voice_agent.utils.audio.SOXRAudioStreamResampler.resample(
    audio: bytes
)
```

Resample an audio chunk using the SoX resampler library.
Args:
audio: The audio chunk to resample.
Returns:
The resampled audio chunk.

```python
nemo_voice_agent.utils.audio.SOXRAudioStreamResampler.reset()
```

Reset the resampler.

```python
nemo_voice_agent.utils.audio.audio_bytes_to_float32(
    audio_bytes: bytes
) -> numpy.ndarray
```

Convert PCM-16 audio bytes to float32 numpy array, clamped to -1.0 to 1.0.

```python
nemo_voice_agent.utils.audio.audio_float32_to_bytes(
    audio_float32: numpy.ndarray
) -> bytes
```

Convert float32 numpy array to PCM-16 audio bytes.

```python
nemo_voice_agent.utils.audio.STREAM_TIMEOUT_SECS = 0.2
```