rust-portaudio

To install rust-portaudio, use cargo build at the root of the repository.

By default, the build process attempts to detect an existing PortAudio installation on your system. If no installation is found, or if the PORTAUDIO_ONLY_STATIC environment variable is set during the build process, the crate will attempt to download and build PortAudio statically.

Platform Specifics:

• macOS: You may need to manually install portaudio and pkg-config using Homebrew:

  brew install portaudio
  brew install pkg-config

If the automatic build fails, you can manually download and install PortAudio from the official PortAudio website.

You can use standard Cargo commands to interact with the project:

• To build and run tests: cargo test
• To build and run examples: cargo test (Note: examples are typically included in the test suite or run via cargo run --example <name>)
• To generate documentation: cargo doc

To open an audio stream, you must define PaStreamParameters for input and/or output.

Key fields include:

• device: A PaDeviceIndex (0 to Pa_GetDeviceCount()-1).
• channelCount: Number of audio channels.
• sampleFormat: The PaSampleFormat used for the buffer.
• suggestedLatency: Desired latency in seconds (PaTime).
• hostApiSpecificStreamInfo: An optional pointer for API-specific configuration.

let params = PaStreamParameters {
    device: 0, // Use first device
    channelCount: 2,
    sampleFormat: /* e.g. paFloat32 */, 
    suggestedLatency: 0.05,
    hostApiSpecificStreamInfo: std::ptr::null_mut(),
};

The library uses a Sample trait to constrain stream types. The following primitive types are supported as audio samples:

• f32 (32-bit float)
• i32 (32-bit integer)
• i16 (16-bit integer)
• i8 (8-bit integer)
• u8 (8-bit unsigned integer)

To specify an audio device for a stream, use DeviceIndex or DeviceKind.

• DeviceIndex(u32): A direct index to a device, typically ranging from 0 to PortAudio::device_count - 1.
• DeviceKind::Index(DeviceIndex): Wraps a specific device index.
• DeviceKind::UseHostApiSpecificDeviceSpecification: A special variant used to indicate that device details are provided via host-API-specific stream information structures rather than a simple index.

use portaudio::{DeviceIndex, DeviceKind};

let my_device = DeviceKind::Index(DeviceIndex(0));
let host_specific = DeviceKind::UseHostApiSpecificDeviceSpecification;

The Flow of a Stream defines the direction of audio data movement:

• Input (Input<I>): Receives audio data from an input device's ADC (Analog-to-Digital Converter).
• Output (Output<O>): Sends audio data to an output device's DAC (Digital-to-Analog Converter).
• Duplex (Duplex<I, O>): A bi-directional stream that receives and sends data on two devices synchronously.

Each flow type has associated Settings used to open the stream and specific CallbackArgs used when operating in NonBlocking mode.

A PortAudio Stream can operate in two distinct modes, which determine how you interact with audio data:

1. Blocking (Blocking<B>): The stream runs on the caller's thread. You manually manage audio data by reading from Input or Duplex streams and writing to Output or Duplex streams using methods like read, read_available, write, and write_available.

2. Non-Blocking (NonBlocking): The stream runs on a separate thread managed by PortAudio. You interact with the audio data via a callback function. The specific arguments provided to your callback depend on the stream's Flow (Input, Output, or Duplex).

Choose Blocking for simpler, synchronous logic where you control the timing of audio processing, and Non-Blocking for low-latency, high-performance applications where audio processing should not interrupt the main application logic.

Add portaudio to your Cargo.toml dependencies. The build script will attempt to automatically download and install the PortAudio C library if it is not already present on your system. If automatic installation fails, you may need to install PortAudio manually from the official website.

[dependencies]
portaudio = "*"

Before using most PortAudio API functions, you must call Pa_Initialize() to initialize internal data structures and prepare host APIs. If Pa_Initialize() returns an error, do not call Pa_Terminate().

When finished, call Pa_Terminate() to deallocate resources. Failure to call this before exiting can lead to resource leaks, such as audio devices remaining unavailable until a reboot. If Pa_Initialize() was called multiple times, it must be matched with an equal number of Pa_Terminate() calls.

// Example lifecycle
let err = unsafe { Pa_Initialize() };
if err == PaErrorCode_paNoError {
    // ... use PortAudio ...
    unsafe { Pa_Terminate() };
}

A blocking stream allows you to read or write audio samples synchronously using Stream::read and Stream::write. The stream is opened in Blocking mode.

To open a blocking stream, use open_blocking_stream(settings) where settings implements StreamSettings (such as those produced by default_input_stream_settings or default_output_stream_settings).

// Example: Opening a default output stream
let settings = pa.default_output_stream_settings::<f32>(2, 44100.0, 256)?;
let stream = pa.open_blocking_stream(settings)?;

// The stream is returned in an inactive (stopped) state.
stream.start();

In Blocking mode, you can check how much data is ready to be processed without causing the thread to block using the _available methods. This is useful for preventing unnecessary waiting or managing buffer overflows/underflows.

• read_available(): Returns an Available enum. It can return Available::Frames(n) if n frames are ready, or error flags like Available::InputOverflowed or Available::OutputUnderflowed.
• write_available(): Returns an Available enum indicating how many frames can be written without blocking, or error flags like Available::OutputUnderflowed.