README

portaudio

This package provides an interface to the PortAudio audio I/O library. See the package documentation for details.

To build this package you must first have the PortAudio development headers and libraries installed. Some systems provide a package for this; e.g., on Ubuntu you would want to run apt-get install portaudio19-dev. On other systems you might have to install from source.

Thanks to sqweek for motivating and contributing to host API and device enumeration.

Expand ▾ Collapse ▴

Documentation

Overview

    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.

    Index

    Constants

    View Source
    const FramesPerBufferUnspecified = C.paFramesPerBufferUnspecified

      FramesPerBufferUnspecified ...

      Variables

      This section is empty.

      Functions

      func Initialize

      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

        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

          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

            func Version() int

              Version returns the release number of PortAudio.

              func VersionText

              func VersionText() string

                VersionText returns the textual description of the PortAudio release.

                Types

                type Buffer

                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

                  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

                    func DefaultInputDevice() (*DeviceInfo, error)

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

                      func DefaultOutputDevice

                      func DefaultOutputDevice() (*DeviceInfo, error)

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

                        func Devices

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

                          Devices returns information for all available devices on the system.

                          type Error

                          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

                              func (err Error) Error() string

                              type HostApiInfo

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

                                HostApiInfo contains information for a HostApi.

                                func DefaultHostApi

                                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

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

                                    HostApi returns information for a requested HostApiType.

                                    func HostApis

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

                                      HostApis returns all information available for HostApis.

                                      type HostApiType

                                      type HostApiType int

                                        HostApiType maps ints to HostApi modes.

                                          PortAudio Api types.

                                          func (HostApiType) String

                                          func (t HostApiType) String() string

                                          type Int24

                                          type Int24 [3]byte

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

                                            func (*Int24) PutInt32

                                            func (i24 *Int24) PutInt32(i32 int32)

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

                                              type Stream

                                              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

                                                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

                                                  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

                                                    func (s *Stream) Abort() error

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

                                                      func (*Stream) AvailableToRead

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

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

                                                        func (*Stream) AvailableToWrite

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

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

                                                          func (*Stream) Close

                                                          func (s *Stream) Close() error

                                                            Close terminates the stream.

                                                            func (*Stream) CpuLoad

                                                            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

                                                              func (s *Stream) Info() *StreamInfo

                                                                Info returns information about the Stream instance.

                                                                func (*Stream) Read

                                                                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

                                                                  func (s *Stream) Start() error

                                                                    Start commences audio processing.

                                                                    func (*Stream) Stop

                                                                    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

                                                                      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

                                                                        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

                                                                          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

                                                                            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

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

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

                                                                                  type StreamDeviceParameters

                                                                                  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

                                                                                    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

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

                                                                                        StreamInfo contains information about the stream.

                                                                                        type StreamParameters

                                                                                        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

                                                                                          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

                                                                                            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

                                                                                              type UnanticipatedHostError struct {
                                                                                              	HostApiType HostApiType
                                                                                              	Code        int
                                                                                              	Text        string
                                                                                              }

                                                                                                UnanticipatedHostError contains details for ApiHost related errors.

                                                                                                func (UnanticipatedHostError) Error

                                                                                                func (err UnanticipatedHostError) Error() string

                                                                                                Source Files

                                                                                                Directories

                                                                                                Path Synopsis