net.java.sip.communicator.impl.neomedia.portaudio
Class PortAudio

java.lang.Object
  net.java.sip.communicator.impl.neomedia.portaudio.PortAudio

public final class PortAudio
extends Object

Provides the interface to the native PortAudio library.

Author:

Lyubomir Marinov, Damian Minkov, Sebastien Vincent

Nested Class Summary

static class

PortAudio.PaHostApiTypeId Unchanging unique identifiers for each supported host API.

Field Summary

static int	DEFAULT_MILLIS_PER_BUFFER The number of milliseconds to be read from or written to a native PortAudio stream in a single transfer of data.
static double	DEFAULT_SAMPLE_RATE The default value for the sample rate of the input and the output PortAudio streams with which they are to be opened if no other specific sample rate is specified to the PortAudio DataSource or PortAudioRenderer that they represent.
static long	FRAMES_PER_BUFFER_UNSPECIFIED Can be passed as the framesPerBuffer parameter to Pa_OpenStream() or Pa_OpenDefaultStream() to indicate that the stream callback will accept buffers of any size.
static double	LATENCY_HIGH Used when creating new stream parameters for suggested latency to use high input/output value.
static double	LATENCY_LOW Used when creating new stream parameters for suggested latency to use low input/default value.
static double	LATENCY_UNSPECIFIED Used when creating new stream parameters for suggested latency to use default value.
static int	paNoDevice PortAudio "no device" constant.
static long	SAMPLE_FORMAT_FLOAT32 A type used to specify one or more sample formats.
static long	SAMPLE_FORMAT_INT16 A type used to specify one or more sample formats.
static long	SAMPLE_FORMAT_INT24 A type used to specify one or more sample formats.
static long	SAMPLE_FORMAT_INT32 A type used to specify one or more sample formats.
static long	SAMPLE_FORMAT_INT8 A type used to specify one or more sample formats.
static long	SAMPLE_FORMAT_UINT8 A type used to specify one or more sample formats.
static long	STREAM_FLAGS_CLIP_OFF Disables default clipping of out of range samples.
static long	STREAM_FLAGS_DITHER_OFF Disables default dithering.
static long	STREAM_FLAGS_NEVER_DROP_INPUT Flag requests that where possible a full duplex stream will not discard overflowed input samples without calling the stream callback.
static long	STREAM_FLAGS_NO_FLAG Flags used to control the behavior of a stream.
static long	STREAM_FLAGS_PLATFORM_SPECIFIC_FLAGS A mask specifying the platform specific bits.
static long	STREAM_FLAGS_PRIME_OUTPUT_BUFFERS_USING_STREAM_CALLBACK Call the stream callback to fill initial output buffers, rather than the default behavior of priming the buffers with zeros (silence).

Method Summary

static void	deviceChanged() Implements a (legacy) callback which gets called by the native PortAudio counterpart to notify the Java counterpart that the list of PortAudio devices has changed.
static void	devicesChangedCallback() Implements a callback which gets called by the native PortAudio counterpart to notify the Java counterpart that the list of PortAudio devices has changed.
static long	getPaSampleFormat(int sampleSizeInBits) Gets the native PaSampleFormat with a specific size in bits.
static double	getSuggestedLatency() Gets the suggested latency to be used when opening PortAudio streams.
static void	Pa_AbortStream(long stream) Terminates audio processing immediately without waiting for pending buffers to complete.
static void	Pa_CloseStream(long stream) Closes an audio stream.
static int	Pa_GetDefaultInputDevice() Retrieve the index of the default input device.
static int	Pa_GetDefaultOutputDevice() Retrieve the index of the default output device.
static int	Pa_GetDeviceCount() Retrieve the number of available devices.
static long	Pa_GetDeviceInfo(int deviceIndex) Retrieve a pointer to a PaDeviceInfo structure containing information about the specified device.
static long	Pa_GetHostApiInfo(int hostApiIndex) Retrieve a pointer to a structure containing information about a specific host Api.
static int	Pa_GetSampleSize(long format) Retrieve the size of a given sample format in bytes.
static long	Pa_GetStreamReadAvailable(long stream) Retrieve the number of frames that can be read from the stream without waiting.
static long	Pa_GetStreamWriteAvailable(long stream) Retrieve the number of frames that can be written to the stream without waiting.
static boolean	Pa_IsFormatSupported(long inputParameters, long outputParameters, double sampleRate) Determine whether it would be possible to open a stream with the specified parameters.
static long	Pa_OpenStream(long inputParameters, long outputParameters, double sampleRate, long framesPerBuffer, long streamFlags, PortAudioStreamCallback streamCallback) Opens a stream for either input, output or both.
static void	Pa_ReadStream(long stream, byte[] buffer, long frames) Read samples from an input stream.
static void	Pa_StartStream(long stream) Commences audio processing.
static void	Pa_StopStream(long stream) Terminates audio processing.
static void	Pa_UpdateAvailableDeviceList()
static void	Pa_WriteStream(long stream, byte[] buffer, int offset, long frames, int numberOfWrites) Writes samples to an output stream.
static void	Pa_WriteStream(long stream, byte[] buffer, long frames) Write samples to an output stream.
static double	PaDeviceInfo_getDefaultHighInputLatency(long deviceInfo) Returns defaultHighInputLatency for the device.
static double	PaDeviceInfo_getDefaultHighOutputLatency(long deviceInfo) Returns defaultHighOutputLatency for the device.
static double	PaDeviceInfo_getDefaultLowInputLatency(long deviceInfo) Returns defaultLowInputLatency for the device.
static double	PaDeviceInfo_getDefaultLowOutputLatency(long deviceInfo) Returns defaultLowOutputLatency for the device.
static double	PaDeviceInfo_getDefaultSampleRate(long deviceInfo) The default samplerate for the deviec.
static int	PaDeviceInfo_getHostApi(long deviceInfo) The host api of the device.
static int	PaDeviceInfo_getMaxInputChannels(long deviceInfo) Maximum input channels for the device.
static int	PaDeviceInfo_getMaxOutputChannels(long deviceInfo) Maximum output channels for the device.
static String	PaDeviceInfo_getName(long deviceInfo) Gets the human-readable name of the PaDeviceInfo specified by a pointer to it.
static int	PaHostApiInfo_getDefaultInputDevice(long hostApiInfo) The default input device for this host API.
static int	PaHostApiInfo_getDefaultOutputDevice(long hostApiInfo) The default output device for this host API.
static int	PaHostApiInfo_getDeviceCount(long hostApiInfo) The number of devices belonging to this host API.
static String	PaHostApiInfo_getName(long hostApiInfo) Deprecated. Presumes that the name of PaHostApiInfo is encoded in modified UTF-8
static int	PaHostApiInfo_getType(long hostApiInfo) The well known unique identifier of this host API.
static void	PaStreamParameters_free(long streamParameters) Free StreamParameters resources specified by a pointer to it.
static long	PaStreamParameters_new(int deviceIndex, int channelCount, long sampleFormat, double suggestedLatency) Creates parameters used for opening streams.
static void	setDenoise(long stream, boolean denoise) Sets the indicator which determines whether a specific (input) PortAudio stream is to have denoise performed on the audio data it provides.
static void	setDevicesChangedCallback(Runnable devicesChangedCallback)
static void	setEchoFilterLengthInMillis(long stream, long echoFilterLengthInMillis) Sets the number of milliseconds of echo to be canceled in the audio data provided by a specific (input) PortAudio stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MILLIS_PER_BUFFER

public static final int DEFAULT_MILLIS_PER_BUFFER

The number of milliseconds to be read from or written to a native PortAudio stream in a single transfer of data.

See Also:

Constant Field Values

DEFAULT_SAMPLE_RATE

public static final double DEFAULT_SAMPLE_RATE

The default value for the sample rate of the input and the output PortAudio streams with which they are to be opened if no other specific sample rate is specified to the PortAudio DataSource or PortAudioRenderer that they represent.

See Also:

Constant Field Values

FRAMES_PER_BUFFER_UNSPECIFIED

public static final long FRAMES_PER_BUFFER_UNSPECIFIED

Can be passed as the framesPerBuffer parameter to Pa_OpenStream() or Pa_OpenDefaultStream() to indicate that the stream callback will accept buffers of any size.

See Also:

Constant Field Values

LATENCY_HIGH

public static final double LATENCY_HIGH

Used when creating new stream parameters for suggested latency to use high input/output value.

See Also:

Constant Field Values

LATENCY_LOW

public static final double LATENCY_LOW

Used when creating new stream parameters for suggested latency to use low input/default value.

See Also:

Constant Field Values

LATENCY_UNSPECIFIED

public static final double LATENCY_UNSPECIFIED

Used when creating new stream parameters for suggested latency to use default value.

See Also:

Constant Field Values

paNoDevice

public static final int paNoDevice

PortAudio "no device" constant.

See Also:

Constant Field Values

SAMPLE_FORMAT_FLOAT32

public static final long SAMPLE_FORMAT_FLOAT32

A type used to specify one or more sample formats. The standard format paFloat32.

See Also:

Constant Field Values

SAMPLE_FORMAT_INT8

public static final long SAMPLE_FORMAT_INT8

A type used to specify one or more sample formats. The standard format paInt8.

See Also:

Constant Field Values

SAMPLE_FORMAT_INT16

public static final long SAMPLE_FORMAT_INT16

A type used to specify one or more sample formats. The standard format paInt16.

See Also:

Constant Field Values

SAMPLE_FORMAT_INT24

public static final long SAMPLE_FORMAT_INT24

A type used to specify one or more sample formats. The standard format paInt24.

See Also:

Constant Field Values

SAMPLE_FORMAT_INT32

public static final long SAMPLE_FORMAT_INT32

A type used to specify one or more sample formats. The standard format paInt32.

See Also:

Constant Field Values

SAMPLE_FORMAT_UINT8

public static final long SAMPLE_FORMAT_UINT8

A type used to specify one or more sample formats. The standard format paUInt8.

See Also:

Constant Field Values

STREAM_FLAGS_CLIP_OFF

public static final long STREAM_FLAGS_CLIP_OFF

Disables default clipping of out of range samples.

See Also:

Constant Field Values

STREAM_FLAGS_DITHER_OFF

public static final long STREAM_FLAGS_DITHER_OFF

Disables default dithering.

See Also:

Constant Field Values

STREAM_FLAGS_NEVER_DROP_INPUT

public static final long STREAM_FLAGS_NEVER_DROP_INPUT

Flag requests that where possible a full duplex stream will not discard overflowed input samples without calling the stream callback. This flag is only valid for full duplex callback streams and only when used in combination with the paFramesPerBufferUnspecified (0) framesPerBuffer parameter. Using this flag incorrectly results in a paInvalidFlag error being returned from Pa_OpenStream and Pa_OpenDefaultStream.

See Also:

Constant Field Values

STREAM_FLAGS_NO_FLAG

public static final long STREAM_FLAGS_NO_FLAG

Flags used to control the behavior of a stream. They are passed as parameters to Pa_OpenStream or Pa_OpenDefaultStream.

See Also:

Constant Field Values

STREAM_FLAGS_PLATFORM_SPECIFIC_FLAGS

public static final long STREAM_FLAGS_PLATFORM_SPECIFIC_FLAGS

A mask specifying the platform specific bits.

See Also:

Constant Field Values

STREAM_FLAGS_PRIME_OUTPUT_BUFFERS_USING_STREAM_CALLBACK

public static final long STREAM_FLAGS_PRIME_OUTPUT_BUFFERS_USING_STREAM_CALLBACK

Call the stream callback to fill initial output buffers, rather than the default behavior of priming the buffers with zeros (silence). This flag has no effect for input-only and blocking read/write streams.

See Also:

Constant Field Values

Method Detail

getPaSampleFormat

public static long getPaSampleFormat(int sampleSizeInBits)

Gets the native PaSampleFormat with a specific size in bits.

Parameters:

sampleSizeInBits - the size in bits of the native PaSampleFormat to get

Returns:

the native PaSampleFormat with the specified size in bits

getSuggestedLatency

public static double getSuggestedLatency()

Gets the suggested latency to be used when opening PortAudio streams.

Returns:

the suggested latency to be used when opening PortAudio streams

Pa_AbortStream

public static void Pa_AbortStream(long stream)
                           throws PortAudioException

Terminates audio processing immediately without waiting for pending buffers to complete.

Parameters:

stream - the steam pointer.

Throws:

PortAudioException

Pa_CloseStream

public static void Pa_CloseStream(long stream)
                           throws PortAudioException

Closes an audio stream. If the audio stream is active it discards any pending buffers as if Pa_AbortStream() had been called.

Parameters:

stream - the steam pointer.

Throws:

PortAudioException

Pa_GetDefaultInputDevice

public static int Pa_GetDefaultInputDevice()

Retrieve the index of the default input device.

Returns:

The default input device index for the default host API, or paNoDevice if no default input device is available or an error was encountered.

Pa_GetDefaultOutputDevice

public static int Pa_GetDefaultOutputDevice()

Retrieve the index of the default output device.

Returns:

The default input device index for the default host API, or paNoDevice if no default input device is available or an error was encountered.

Pa_GetDeviceCount

public static int Pa_GetDeviceCount()
                             throws PortAudioException

Retrieve the number of available devices. The number of available devices may be zero.

Returns:

the number of devices.

Throws:

PortAudioException

Pa_GetDeviceInfo

public static long Pa_GetDeviceInfo(int deviceIndex)

Retrieve a pointer to a PaDeviceInfo structure containing information about the specified device.

Parameters:

deviceIndex - the device index

Returns:

pointer to device info structure.

Pa_GetHostApiInfo

public static long Pa_GetHostApiInfo(int hostApiIndex)

Retrieve a pointer to a structure containing information about a specific host Api.

Parameters:

hostApiIndex - host api index.

Returns:

A pointer to an immutable PaHostApiInfo structure describing a specific host API.

Pa_GetSampleSize

public static int Pa_GetSampleSize(long format)

Retrieve the size of a given sample format in bytes.

Parameters:

format - the format.

Returns:

The size in bytes of a single sample in the specified format, or paSampleFormatNotSupported if the format is not supported.

Pa_GetStreamReadAvailable

public static long Pa_GetStreamReadAvailable(long stream)

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

Parameters:

stream - pointer to the stream.

Returns:

returns a non-negative value representing the maximum number of frames that can be read from the stream without blocking or busy waiting or, a PaErrorCode (which are always negative) if PortAudio is not initialized or an error is encountered.

Pa_GetStreamWriteAvailable

public static long Pa_GetStreamWriteAvailable(long stream)

Retrieve the number of frames that can be written to the stream without waiting.

Parameters:

stream - pointer to the stream.

Returns:

returns a non-negative value representing the maximum number of frames that can be written to the stream without blocking or busy waiting or, a PaErrorCode (which are always negative) if PortAudio is not initialized or an error is encountered.

Pa_IsFormatSupported

public static boolean Pa_IsFormatSupported(long inputParameters,
                                           long outputParameters,
                                           double sampleRate)

Determine whether it would be possible to open a stream with the specified parameters.

Parameters:

inputParameters - A structure that describes the input parameters used to open a stream.

outputParameters - A structure that describes the output parameters used to open a stream.

sampleRate - The required sampleRate.

Returns:

returns 0 if the format is supported, and an error code indicating why the format is not supported otherwise. The constant paFormatIsSupported is provided to compare with the return value for success.

Pa_OpenStream

public static long Pa_OpenStream(long inputParameters,
                                 long outputParameters,
                                 double sampleRate,
                                 long framesPerBuffer,
                                 long streamFlags,
                                 PortAudioStreamCallback streamCallback)
                          throws PortAudioException

Opens a stream for either input, output or both.

Parameters:

inputParameters - the input params or 0 if absent.

outputParameters - the ouput params or 0 if absent.

sampleRate - The desired sampleRate.

framesPerBuffer - The number of frames passed to the stream callback function, or the preferred block granularity for a blocking read/write stream

streamFlags - Flags which modify the behaviour of the streaming process.

streamCallback - A pointer to a client supplied function that is responsible for processing and filling input and output buffers. If this parameter is NULL the stream will be opened in 'blocking read/write' mode.

Returns:

pointer to the opened stream.

Throws:

PortAudioException

Pa_ReadStream

public static void Pa_ReadStream(long stream,
                                 byte[] buffer,
                                 long frames)
                          throws PortAudioException

Read samples from an input stream. The function doesn't return until the entire buffer has been filled - this may involve waiting for the operating system to supply the data.

Parameters:

stream - pointer to the stream.

buffer - a buffer of sample frames.

frames - The number of frames to be read into buffer.

Throws:

PortAudioException

Pa_StartStream

public static void Pa_StartStream(long stream)
                           throws PortAudioException

Commences audio processing.

Parameters:

stream - pointer to the stream

Throws:

PortAudioException

Pa_StopStream

public static void Pa_StopStream(long stream)
                          throws PortAudioException

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

Parameters:

stream - pointer to the stream

Throws:

PortAudioException

Pa_UpdateAvailableDeviceList

public static void Pa_UpdateAvailableDeviceList()

Pa_WriteStream

public static void Pa_WriteStream(long stream,
                                  byte[] buffer,
                                  long frames)
                           throws PortAudioException

Write samples to an output stream. This function doesn't return until the entire buffer has been consumed - this may involve waiting for the operating system to consume the data.

Parameters:

stream - pointer to the stream

buffer - A buffer of sample frames.

frames - The number of frames to be written from buffer.

Throws:

PortAudioException

Pa_WriteStream

public static void Pa_WriteStream(long stream,
                                  byte[] buffer,
                                  int offset,
                                  long frames,
                                  int numberOfWrites)
                           throws PortAudioException

Writes samples to an output stream. Does not return until the specified samples have been consumed - this may involve waiting for the operating system to consume the data.

Provides better efficiency than achieved through multiple consecutive calls to Pa_WriteStream(long, byte[], long) with one and the same buffer because the JNI access to the bytes of the buffer which is likely to copy the whole buffer is only performed once.

Parameters:

stream - the pointer to the PortAudio stream to write the samples to

buffer - the buffer containing the samples to be written

offset - the byte offset in buffer at which the samples to be written start

frames - the number of frames from buffer starting at offset are to be written with a single write

numberOfWrites - the number of writes each writing frames number of frames to be performed

Throws:

PortAudioException - if anything goes wrong while writing

PaDeviceInfo_getName

public static String PaDeviceInfo_getName(long deviceInfo)

Gets the human-readable name of the PaDeviceInfo specified by a pointer to it.

Parameters:

deviceInfo - the pointer to the PaDeviceInfo to get the human-readable name of

Returns:

the human-readable name of the PaDeviceInfo pointed to by deviceInfo

PaDeviceInfo_getDefaultHighInputLatency

public static double PaDeviceInfo_getDefaultHighInputLatency(long deviceInfo)

Returns defaultHighInputLatency for the device.

Parameters:

deviceInfo - device info pointer.

Returns:

defaultHighInputLatency for the device.

PaDeviceInfo_getDefaultHighOutputLatency

public static double PaDeviceInfo_getDefaultHighOutputLatency(long deviceInfo)

Returns defaultHighOutputLatency for the device.

Parameters:

deviceInfo - device info pointer.

Returns:

defaultHighOutputLatency for the device.

PaDeviceInfo_getDefaultLowInputLatency

public static double PaDeviceInfo_getDefaultLowInputLatency(long deviceInfo)

Returns defaultLowInputLatency for the device.

Parameters:

deviceInfo - device info pointer.

Returns:

defaultLowInputLatency for the device.

PaDeviceInfo_getDefaultLowOutputLatency

public static double PaDeviceInfo_getDefaultLowOutputLatency(long deviceInfo)

Returns defaultLowOutputLatency for the device.

Parameters:

deviceInfo - device info pointer.

Returns:

defaultLowOutputLatency for the device.

PaDeviceInfo_getDefaultSampleRate

public static double PaDeviceInfo_getDefaultSampleRate(long deviceInfo)

The default samplerate for the deviec.

Parameters:

deviceInfo - device info pointer.

Returns:

the default sameple rate for the device.

PaDeviceInfo_getHostApi

public static int PaDeviceInfo_getHostApi(long deviceInfo)

The host api of the device.

Parameters:

deviceInfo - device info pointer.

Returns:

The host api of the device.

PaDeviceInfo_getMaxInputChannels

public static int PaDeviceInfo_getMaxInputChannels(long deviceInfo)

Maximum input channels for the device.

Parameters:

deviceInfo - device info pointer.

Returns:

Maximum input channels for the device.

PaDeviceInfo_getMaxOutputChannels

public static int PaDeviceInfo_getMaxOutputChannels(long deviceInfo)

Maximum output channels for the device.

Parameters:

deviceInfo - device info pointer.

Returns:

Maximum output channels for the device.

PaHostApiInfo_getDefaultInputDevice

public static int PaHostApiInfo_getDefaultInputDevice(long hostApiInfo)

The default input device for this host API.

Parameters:

hostApiInfo - pointer to host api info structure.

Returns:

The default input device for this host API.

PaHostApiInfo_getDefaultOutputDevice

public static int PaHostApiInfo_getDefaultOutputDevice(long hostApiInfo)

The default output device for this host API.

Parameters:

hostApiInfo - pointer to host api info structure.

Returns:

The default output device for this host API.

PaHostApiInfo_getDeviceCount

public static int PaHostApiInfo_getDeviceCount(long hostApiInfo)

The number of devices belonging to this host API.

Parameters:

hostApiInfo - pointer to host api info structure.

Returns:

The number of devices belonging to this host API.

PaHostApiInfo_getName

@Deprecated
public static String PaHostApiInfo_getName(long hostApiInfo)

Deprecated. Presumes that the name of PaHostApiInfo is encoded in modified UTF-8

Gets the human-readable name of the PaHostApiInfo specified by a pointer to it.

Parameters:

hostApiInfo - the pointer to the PaHostApiInfo to get the human-readable name of

Returns:

the human-readable name of the PaHostApiInfo pointed to by hostApiInfo

PaHostApiInfo_getType

public static int PaHostApiInfo_getType(long hostApiInfo)

The well known unique identifier of this host API.

Parameters:

hostApiInfo - pointer to host api info structure.

Returns:

The well known unique identifier of this host API. Enumerator: paInDevelopment paDirectSound paMME paASIO paSoundManager paCoreAudio paOSS paALSA paAL paBeOS paWDMKS paJACK paWASAPI paAudioScienceHPI

PaStreamParameters_free

public static void PaStreamParameters_free(long streamParameters)

Free StreamParameters resources specified by a pointer to it.

Parameters:

streamParameters - the pointer to the PaStreamParameters to free

PaStreamParameters_new

public static long PaStreamParameters_new(int deviceIndex,
                                          int channelCount,
                                          long sampleFormat,
                                          double suggestedLatency)

Creates parameters used for opening streams.

Parameters:

deviceIndex - the device.

channelCount - the channels to be used.

sampleFormat - the sample format.

suggestedLatency - the suggested latency in milliseconds: LATENCY_UNSPECIFIED - use default(default high input/output latency) LATENCY_HIGH - use default high input/output latency LATENCY_LOW - use default low input/output latency ... - any other value in milliseconds (e.g. 0.1 is acceptable)

Returns:

pointer to the params used for Pa_OpenStream.

setDenoise

public static void setDenoise(long stream,
                              boolean denoise)

Sets the indicator which determines whether a specific (input) PortAudio stream is to have denoise performed on the audio data it provides.

Parameters:

stream - the (input) PortAudio stream for which denoise is to be enabled or disabled

denoise - true if denoise is to be performed on the audio data provided by stream; otherwise, false

setEchoFilterLengthInMillis

public static void setEchoFilterLengthInMillis(long stream,
                                               long echoFilterLengthInMillis)

Sets the number of milliseconds of echo to be canceled in the audio data provided by a specific (input) PortAudio stream.

Parameters:

stream - the (input) PortAudio stream for which the number of milliseconds of echo to be canceled is to be set

echoFilterLengthInMillis - the number of milliseconds of echo to be canceled in the audio data provided by stream

deviceChanged

public static void deviceChanged()

Implements a (legacy) callback which gets called by the native PortAudio counterpart to notify the Java counterpart that the list of PortAudio devices has changed.

devicesChangedCallback

public static void devicesChangedCallback()

Implements a callback which gets called by the native PortAudio counterpart to notify the Java counterpart that the list of PortAudio devices has changed.

setDevicesChangedCallback

public static void setDevicesChangedCallback(Runnable devicesChangedCallback)