# Needle 3 Audio Formats for Speech Input: WAV, PCM16, and Float32 Support

> Explore Needle 3's supported audio formats for speech input: WAV, PCM16, and Float32. Learn how Needle efficiently processes your audio data for optimal performance.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-09-10

---

**Needle 3 accepts speech input in three specific audio formats—WAV, PCM16, and Float32—which are validated through the internal `_prepare_audio` helper in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py).**

The open-source Needle 3 framework provides native speech processing capabilities through its core agent API. When submitting audio data to methods like `agent.complete()` or `agent.run()`, developers must specify the encoding format via the `audio_format` parameter to ensure correct decoding. According to the cactus-compute/needle source code, format validation occurs in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), where the `_prepare_audio` function maps format strings to numeric constants in `_AUDIO_FORMATS` and raises a `ValueError` for unsupported encodings.

## Supported Audio Formats for Speech Input

Needle 3 recognizes three distinct audio encodings for speech input. Each format serves different use cases, from file-based ingestion to raw byte streams from audio capture hardware.

### WAV Format

The **`wav`** format accepts standard WAV container files. Developers can provide either a file path string or raw bytes from a `.wav` file. When using this format, Needle 3 automatically extracts the sample rate and channel count from the WAV header, making it the simplest option for file-based speech input.

### PCM16 Format

The **`pcm16`** format expects 16-bit signed little-endian PCM audio data. This raw format requires explicit configuration of the **`sample_rate`** and **`channels`** parameters in the API call. Use this encoding when streaming live audio from microphones or processing raw audio buffers without container headers.

### Float32 Format

The **`float32`** format accepts 32-bit floating-point PCM audio. Like PCM16, this raw encoding requires manual specification of **`sample_rate`** and **`channels`**. This format is ideal for applications working with normalized audio data or direct output from digital signal processing pipelines.

## API Implementation Details

As implemented in cactus-compute/needle, the audio preparation logic resides in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). The `_prepare_audio` function validates the `audio_format` argument against the internal `_AUDIO_FORMATS` mapping, which assigns numeric codes to each supported format string. If the supplied format does not match `wav`, `pcm16`, or `float32`, the function raises a `ValueError` before the audio data reaches the inference engine.

## Code Examples

The following examples demonstrate how to use each supported audio format with Needle 3's agent API.

```python

# Example 1 – Using a WAV file from disk

response = agent.complete(
    audio="command.wav",           # path to a WAV file

    audio_format="wav",            # explicit (default) format

    sample_rate=16000,             # optional, ignored for WAV

    channels=1                     # optional, ignored for WAV

)

```

```python

# Example 2 – Feeding raw PCM‑16 bytes

pcm16_bytes = b"\x01\x02..."       # your PCM‑16 audio payload

response = agent.embed(
    audio=pcm16_bytes,
    audio_format="pcm16",
    sample_rate=16000,
    channels=1
)

```

```python

# Example 3 – Using Float32 audio in memory

import numpy as np

float32_bytes = np.random.rand(16000).astype(np.float32).tobytes()
response = agent.run(
    query="What did the speaker say?",
    audio=float32_bytes,
    audio_format="float32",
    sample_rate=16000,
    channels=1
)

```

## Summary

- **Needle 3 supports three audio formats** for speech input: `wav`, `pcm16`, and `float32`, as defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py).
- **The `_prepare_audio` helper validates** all audio format strings against the internal `_AUDIO_FORMATS` mapping and rejects unsupported encodings with a `ValueError`.
- **WAV files auto-detect metadata**, while **PCM16 and Float32 require explicit `sample_rate` and `channels` parameters** in the API call.
- These formats apply to core methods including `agent.complete()`, `agent.embed()`, and `agent.run()`.

## Frequently Asked Questions

### What audio formats does Needle 3 support for speech input?

Needle 3 supports `wav`, `pcm16`, and `float32` audio formats. The `wav` format accepts standard WAV container files, while `pcm16` and `float32` accept raw 16-bit signed integer and 32-bit floating-point PCM data, respectively.

### Do I need to specify sample rate and channels for WAV files in Needle 3?

No. When using the `wav` format, Needle 3 automatically extracts the sample rate and channel count from the WAV file header. However, PCM16 and Float32 formats require explicit `sample_rate` and `channels` parameters since they lack container metadata.

### Where is audio format validation handled in the Needle 3 source code?

Audio format validation occurs in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) within the `_prepare_audio` function. This helper maps format strings to numeric codes stored in `_AUDIO_FORMATS` and raises a `ValueError` if an unsupported format is provided.

### What happens if I provide an unsupported audio format to Needle 3?

If you specify an audio format other than `wav`, `pcm16`, or `float32`, the `_prepare_audio` function raises a `ValueError` during the API call validation phase, preventing the request from reaching the speech processing pipeline.