portaudio: github.com/gordonklaus/portaudio Index | Files | Directories

package portaudio

import "github.com/gordonklaus/portaudio"

Package portaudio applies Go bindings to the PortAudio library.

For the most part, these bindings parallel the underlying PortAudio API; please refer to http://www.portaudio.com/docs.html for details. Differences introduced by the bindings are documented here:

Instead of passing a flag to OpenStream, audio sample formats are inferred from the signature of the stream callback or, for a blocking stream, from the types of the buffers. See the StreamCallback and Buffer types for details.

Blocking I/O: Read and Write do not accept buffer arguments; instead they use the buffers (or pointers to buffers) provided to OpenStream. The number of samples to read or write is determined by the size of the buffers.

The StreamParameters struct combines parameters for both the input and the output device as well as the sample rate, buffer size, and flags.


Package Files



const FramesPerBufferUnspecified = C.paFramesPerBufferUnspecified

FramesPerBufferUnspecified ...

func Initialize Uses

func Initialize() error

Initialize initializes internal data structures and prepares underlying host APIs for use. With the exception of Version(), VersionText(), and ErrorText(), this function MUST be called before using any other PortAudio API functions.

If Initialize() is called multiple times, each successful call must be matched with a corresponding call to Terminate(). Pairs of calls to Initialize()/Terminate() may overlap, and are not required to be fully nested.

Note that if Initialize() returns an error code, Terminate() should NOT be called.

func IsFormatSupported Uses

func IsFormatSupported(p StreamParameters, args ...interface{}) error

IsFormatSupported Returns nil if the format is supported, otherwise an error. The args parameter has the same meaning as in OpenStream.

func Terminate Uses

func Terminate() error

Terminate deallocates all resources allocated by PortAudio since it was initialized by a call to Initialize().

In cases where Initialize() has been called multiple times, each call must be matched with a corresponding call to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically close any PortAudio streams that are still open..

Terminate MUST be called before exiting a program which uses PortAudio. Failure to do so may result in serious resource leaks, such as audio devices not being available until the next reboot.

func Version Uses

func Version() int

Version returns the release number of PortAudio.

func VersionText Uses

func VersionText() string

VersionText returns the textual description of the PortAudio release.

type Buffer Uses

type Buffer interface{}

Buffer exists for documentation purposes only.

A Buffer is of the form [][]SampleType or []SampleType where SampleType is float32, int32, Int24, int16, int8, or uint8.

In the first form, channels are non-interleaved: len(buf) == numChannels and len(buf[i]) == framesPerBuffer

In the second form, channels are interleaved: len(buf) == numChannels * framesPerBuffer

type DeviceInfo Uses

type DeviceInfo struct {
    Name                     string
    MaxInputChannels         int
    MaxOutputChannels        int
    DefaultLowInputLatency   time.Duration
    DefaultLowOutputLatency  time.Duration
    DefaultHighInputLatency  time.Duration
    DefaultHighOutputLatency time.Duration
    DefaultSampleRate        float64
    HostApi                  *HostApiInfo
    // contains filtered or unexported fields

DeviceInfo contains information for an audio device.

func DefaultInputDevice Uses

func DefaultInputDevice() (*DeviceInfo, error)

DefaultInputDevice returns information for the default input device on the system.

func DefaultOutputDevice Uses

func DefaultOutputDevice() (*DeviceInfo, error)

DefaultOutputDevice returns information for the default output device on the system.

func Devices Uses

func Devices() ([]*DeviceInfo, error)

Devices returns information for all available devices on the system.

type Error Uses

type Error C.PaError

Error wraps over PaError.

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

PortAudio Errors.

func (Error) Error Uses

func (err Error) Error() string

type HostApiInfo Uses

type HostApiInfo struct {
    Type                HostApiType
    Name                string
    DefaultInputDevice  *DeviceInfo
    DefaultOutputDevice *DeviceInfo
    Devices             []*DeviceInfo

HostApiInfo contains information for a HostApi.

func DefaultHostApi Uses

func DefaultHostApi() (*HostApiInfo, error)

DefaultHostApi returns information of the default HostApi available on the system.

The default host API will be the lowest common denominator host API on the current platform and is unlikely to provide the best performance.

func HostApi Uses

func HostApi(apiType HostApiType) (*HostApiInfo, error)

HostApi returns information for a requested HostApiType.

func HostApis Uses

func HostApis() ([]*HostApiInfo, error)

HostApis returns all information available for HostApis.

type HostApiType Uses

type HostApiType int

HostApiType maps ints to HostApi modes.

const (
    InDevelopment   HostApiType = C.paInDevelopment
    DirectSound     HostApiType = C.paDirectSound
    MME             HostApiType = C.paMME
    ASIO            HostApiType = C.paASIO
    SoundManager    HostApiType = C.paSoundManager
    CoreAudio       HostApiType = C.paCoreAudio
    OSS             HostApiType = C.paOSS
    ALSA            HostApiType = C.paALSA
    AL              HostApiType = C.paAL
    BeOS            HostApiType = C.paBeOS
    WDMkS           HostApiType = C.paWDMKS
    JACK            HostApiType = C.paJACK
    WASAPI          HostApiType = C.paWASAPI
    AudioScienceHPI HostApiType = C.paAudioScienceHPI

PortAudio Api types.

func (HostApiType) String Uses

func (t HostApiType) String() string

type Int24 Uses

type Int24 [3]byte

Int24 holds the bytes of a 24-bit signed integer in native byte order.

func (*Int24) PutInt32 Uses

func (i24 *Int24) PutInt32(i32 int32)

PutInt32 puts the three most significant bytes of i32 into i24.

type Stream Uses

type Stream struct {
    // contains filtered or unexported fields

Stream provides access to audio hardware represented by one or more PaDevices. Depending on the underlying Host API, it may be possible to open multiple streams using the same device, however this behavior is implementation defined.

Portable applications should assume that a Device may be simultaneously used by at most one Stream.

func OpenDefaultStream Uses

func OpenDefaultStream(numInputChannels, numOutputChannels int, sampleRate float64, framesPerBuffer int, args ...interface{}) (*Stream, error)

OpenDefaultStream is a simplified version of OpenStream that opens the default input and/or output devices.

The args parameter has the same meaning as in OpenStream.

func OpenStream Uses

func OpenStream(p StreamParameters, args ...interface{}) (*Stream, error)

OpenStream creates an instance of a Stream.

For an input- or output-only stream, p.Output.Device or p.Input.Device must be nil, respectively.

The args may consist of either a single StreamCallback or, for a blocking stream, two Buffers or pointers to Buffers.

For an input- or output-only stream, one of the Buffer args may be omitted.

func (*Stream) Abort Uses

func (s *Stream) Abort() error

Abort terminates audio processing immediately without waiting for pending buffers to complete.

func (*Stream) AvailableToRead Uses

func (s *Stream) AvailableToRead() (int, error)

AvailableToRead returns the number of frames that can be read from the stream without waiting.

func (*Stream) AvailableToWrite Uses

func (s *Stream) AvailableToWrite() (int, error)

AvailableToWrite returns the number of frames that can be written from the stream without waiting.

func (*Stream) Close Uses

func (s *Stream) Close() error

Close terminates the stream.

func (*Stream) CpuLoad Uses

func (s *Stream) CpuLoad() float64

CpuLoad returns the CPU usage information for the specified stream, where 0.0 is 0% usage and 1.0 is 100% usage.

The "CPU Load" is a fraction of total CPU time consumed by a callback stream's audio processing routines including, but not limited to the client supplied stream callback.

This function does not work with blocking read/write streams.

This function may be called from the stream callback function or the application.

func (*Stream) Info Uses

func (s *Stream) Info() *StreamInfo

Info returns information about the Stream instance.

func (*Stream) Read Uses

func (s *Stream) Read() error

Read uses the buffer provided to OpenStream. The number of samples to read is determined by the size of the buffer.

func (*Stream) Start Uses

func (s *Stream) Start() error

Start commences audio processing.

func (*Stream) Stop Uses

func (s *Stream) Stop() error

Stop terminates audio processing. It waits until all pending audio buffers have been played before it returns.

func (*Stream) Time Uses

func (s *Stream) Time() time.Duration

Time returns the current time in seconds for a lifespan of a stream. Starting and stopping the stream does not affect the passage of time.

func (*Stream) Write Uses

func (s *Stream) Write() error

Write uses the buffer provided to OpenStream. The number of samples to write is determined by the size of the buffer.

type StreamCallback Uses

type StreamCallback interface{}

StreamCallback exists for documentation purposes only.

A StreamCallback is a func whose signature resembles

func(in Buffer, out Buffer, timeInfo StreamCallbackTimeInfo, flags StreamCallbackFlags)

where the final one or two parameters may be omitted. For an input- or output-only stream, one of the Buffer parameters may also be omitted. The two Buffer types may be different.

type StreamCallbackFlags Uses

type StreamCallbackFlags C.PaStreamCallbackFlags

StreamCallbackFlags are flag bit constants for the statusFlags to StreamCallback.

const (
    // In a stream opened with FramesPerBufferUnspecified,
    // InputUnderflow indicates that input data is all silence (zeros)
    // because no real data is available.
    // In a stream opened without FramesPerBufferUnspecified,
    // InputUnderflow indicates that one or more zero samples have been inserted
    // into the input buffer to compensate for an input underflow.
    InputUnderflow StreamCallbackFlags = C.paInputUnderflow

    // In a stream opened with FramesPerBufferUnspecified,
    // indicates that data prior to the first sample of the
    // input buffer was discarded due to an overflow, possibly
    // because the stream callback is using too much CPU time.
    // Otherwise indicates that data prior to one or more samples
    // in the input buffer was discarded.
    InputOverflow StreamCallbackFlags = C.paInputOverflow

    // Indicates that output data (or a gap) was inserted,
    // possibly because the stream callback is using too much CPU time.
    OutputUnderflow StreamCallbackFlags = C.paOutputUnderflow

    // Indicates that output data will be discarded because no room is available.
    OutputOverflow StreamCallbackFlags = C.paOutputOverflow

    // Some of all of the output data will be used to prime the stream,
    // input data may be zero.
    PrimingOutput StreamCallbackFlags = C.paPrimingOutput

PortAudio stream callback flags.

type StreamCallbackTimeInfo Uses

type StreamCallbackTimeInfo struct {
    InputBufferAdcTime, CurrentTime, OutputBufferDacTime time.Duration

StreamCallbackTimeInfo contains timing information for the buffers passed to the stream callback.

type StreamDeviceParameters Uses

type StreamDeviceParameters struct {
    Device   *DeviceInfo
    Channels int
    Latency  time.Duration

StreamDeviceParameters specifies parameters for one device (either input or output) in a stream. A nil Device indicates that no device is to be used -- i.e., for an input- or output-only stream.

type StreamFlags Uses

type StreamFlags C.PaStreamFlags

StreamFlags ...

const (
    NoFlag                                StreamFlags = C.paNoFlag
    ClipOff                               StreamFlags = C.paClipOff
    DitherOff                             StreamFlags = C.paDitherOff
    NeverDropInput                        StreamFlags = C.paNeverDropInput
    PrimeOutputBuffersUsingStreamCallback StreamFlags = C.paPrimeOutputBuffersUsingStreamCallback
    PlatformSpecificFlags                 StreamFlags = C.paPlatformSpecificFlags

type StreamInfo Uses

type StreamInfo struct {
    InputLatency, OutputLatency time.Duration
    SampleRate                  float64

StreamInfo contains information about the stream.

type StreamParameters Uses

type StreamParameters struct {
    Input, Output   StreamDeviceParameters
    SampleRate      float64
    FramesPerBuffer int
    Flags           StreamFlags

StreamParameters includes all parameters required to open a stream except for the callback or buffers.

func HighLatencyParameters Uses

func HighLatencyParameters(in, out *DeviceInfo) (p StreamParameters)

HighLatencyParameters are mono in, stereo out (if supported), high latency, the smaller of the default sample rates of the two devices, and FramesPerBufferUnspecified. One of the devices may be nil.

func LowLatencyParameters Uses

func LowLatencyParameters(in, out *DeviceInfo) (p StreamParameters)

LowLatencyParameters are mono in, stereo out (if supported), low latency, the larger of the default sample rates of the two devices, and FramesPerBufferUnspecified. One of the devices may be nil.

type UnanticipatedHostError Uses

type UnanticipatedHostError struct {
    HostApiType HostApiType
    Code        int
    Text        string

UnanticipatedHostError contains details for ApiHost related errors.

func (UnanticipatedHostError) Error Uses

func (err UnanticipatedHostError) Error() string



Package portaudio imports 8 packages (graph) and is imported by 90 packages. Updated 2020-09-11. Refresh now. Tools for package owners.