portaudio Go Wrapper

PortAudio supports two modes of audio processing: Callback-based and Blocking I/O.

1. Callback-based Streams

In this mode, you provide a StreamCallback function to OpenStream. The library calls this function periodically to process audio.

StreamCallback Signature: func(in Buffer, out Buffer, timeInfo StreamCallbackTimeInfo, flags StreamCallbackFlags)

The final one or two parameters may be omitted depending on whether the stream is input-only, output-only, or both.

Buffer Formats:

• Non-interleaved: [][]SampleType (where len(buf) == numChannels and len(buf[i]) == framesPerBuffer).
• Interleaved: []SampleType (where len(buf) == numChannels * framesPerBuffer).

2. Blocking I/O (Read/Write)

In this mode, you provide buffers to OpenStream instead of a callback. The Read() and Write() methods do not accept buffer arguments; they use the buffers provided during stream initialization. The number of samples processed is determined by the size of those buffers.

Note: You cannot use Read() or Write() on a stream opened with a callback.

// Example Callback Signature
func myCallback(in [][]float32, out [][]float32, timeInfo portaudio.StreamCallbackTimeInfo, flags portaudio.StreamCallbackFlags) {
    // Process audio here
}

PortAudio allows you to inspect available audio hardware and host APIs (like ALSA, CoreAudio, ASIO, etc.).

• HostApis(): Returns a slice of all available HostApiInfo objects.
• HostApi(apiType HostApiType): Returns information for a specific HostApiType.
• DefaultHostApi(): Returns the default HostApiInfo for the current platform.
• Devices(): Returns a slice of all available DeviceInfo objects.
• DefaultInputDevice(): Returns the default input DeviceInfo.
• DefaultOutputDevice(): Returns the default output DeviceInfo.

DeviceInfo Fields:

• Index: The device index.
• Name: The device name.
• MaxInputChannels / MaxOutputChannels: Maximum channel counts.
• DefaultLowInputLatency / DefaultLowOutputLatency: Recommended low-latency durations.
• DefaultHighInputLatency / DefaultHighOutputLatency: Recommended high-latency durations.
• DefaultSampleRate: The device's default sample rate.

devs, err := portaudio.Devices()
for _, dev := range devs {
    fmt.Printf("Device %d: %s\n", dev.Index, dev.Name)
}

OpenStream creates an instance of a Stream. It requires a StreamParameters object and arguments that define the processing mode.

Arguments:

• For Callback streams: Pass a single StreamCallback function.
• For Blocking streams: Pass one or two Buffer arguments (pointers to slices) representing the input and/or output buffers. For an input-only stream, the output buffer argument can be omitted. For an output-only stream, the input buffer argument can be omitted.

StreamParameters: Combines StreamDeviceParameters for both input and output, the SampleRate, FramesPerBuffer, and Flags.

// Callback stream example
params := portaudio.StreamParameters{
    Input:  portaudio.StreamDeviceParameters{Device: inDev, Channels: 1, Latency: time.Millisecond * 10},
    Output: portaudio.StreamDeviceParameters{Device: outDev, Channels: 2, Latency: time.Millisecond * 10},
    SampleRate: 44100,
    FramesPerBuffer: 256,
}
stream, err := portaudio.OpenStream(params, myCallback)

// Blocking stream example
inBuf := make([]float32, 1024)
outBuf := make([]float32, 1024)
stream, err := portaudio.OpenStream(params, &inBuf, &outBuf)

The Error type wraps PaError. When an error occurs, it can be checked against these constants.

const (
	NotInitialized                        Error = C.paNotInitialized
	InvalidChannelCount                   Error = C.paInvalidChannelCount
	InvalidSampleRate                     Error = C.paInvalidSampleRate
	InvalidDevice                         Error = C.paInvalidDevice
	InvalidFlag                           Error = C.paInvalidFlag
	SampleFormatNotSupported              Error = C.paSampleFormatNotSupported
	BadIODeviceCombination                Error = C.paBadIODeviceCombination
	InsufficientMemory                    Error = C.paInsufficientMemory
	BufferTooBig                          Error = C.paBufferTooBig
	BufferTooSmall                        Error = C.paBufferTooSmall
	NullCallback                          Error = C.paNullCallback
	BadStreamPtr                          Error = C.paBadStreamPtr
	TimedOut                              Error = C.paTimedOut
	InternalError                         Error = C.paInternalError
	DeviceUnavailable                     Error = C.paDeviceUnavailable
	IncompatibleHostApiSpecificStreamInfo Error = C.paIncompatibleHostApiSpecificStreamInfo
	StreamIsStopped                       Error = C.paStreamIsStopped
	StreamIsNotStopped                    Error = C.paStreamIsNotStopped
	InputOverflowed                       Error = C.paInputOverflowed
	OutputUnderflowed                     Error = C.paOutputUnderflowed
	HostApiNotFound                       Error = C.paHostApiNotFound
	InvalidHostApi                        Error = C.paInvalidHostApi
	CanNotReadFromACallbackStream         Error = C.paCanNotReadFromACallbackStream
	CanNotWriteToACallbackStream         Error = C.paCanNotWriteToACallbackStream
	CanNotReadFromAnOutputOnlyStream      Error = C.paCanNotReadFromAnOutputOnlyStream
	CanNotWriteToAnInputOnlyStream        Error = C.paCanNotWriteToAnInputOnlyStream
	IncompatibleStreamHostApi             Error = C.paIncompatibleStreamHostApi
	BadBufferPtr                          Error = C.paBadBufferPtr
	NoDefaultInputDevice                  Error = -1
	NoDefaultOutputDevice                 Error = -2
)