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

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.

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

# 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

)

# 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
)

# 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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}