net.java.sip.communicator.impl.media.protocol.portaudio
Class PortAudio

java.lang.Object
  net.java.sip.communicator.impl.media.protocol.portaudio.PortAudio

public final class PortAudio
extends Object

PortAudio functions.

Author:

Lubomir Marinov

Field Summary

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.
static double	LATENCY_LOW Used when creating new stream parameters for suggested latency.
static double	LATENCY_UNSPECIFIED Used when creating new stream parameters for suggested latency.
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 Disable default clipping of out of range samples.
static long	STREAM_FLAGS_DITHER_OFF Disable 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	initialize() Used to initialize the portaudio lib.
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_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) The name of the device.
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) A textual description of the host API for display on user interfaces.
static int	PaHostApiInfo_GetType(long hostApiInfo) The well known unique identifier of this host API.
static long	PaStreamParameters_new(int deviceIndex, int channelCount, long sampleFormat, double suggestedLatency) Creates parameters used for opening streams.
static void	setEchoCancelParams(long inputStream, long outputStream, boolean enableDenoise, boolean enableEchoCancel, int frameSize, int filterLength) Set params for echocancel and turns on/off noise suppression.

Methods inherited from class java.lang.Object

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

Field Detail

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

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_FLOAT32

public static final long SAMPLE_FORMAT_FLOAT32

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

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 format paInt32.

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 format paInt24.

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 format paInt8.

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 format paUInt8.

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_CLIP_OFF

public static final long STREAM_FLAGS_CLIP_OFF

Disable default clipping of out of range samples.

See Also:

Constant Field Values

STREAM_FLAGS_DITHER_OFF

public static final long STREAM_FLAGS_DITHER_OFF

Disable 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_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

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

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

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

Method Detail

initialize

public static void initialize()
                       throws PortAudioException

Used to initialize the portaudio lib.

Throws:

PortAudioException - if error comes from portaudio.

setEchoCancelParams

public static void setEchoCancelParams(long inputStream,
                                       long outputStream,
                                       boolean enableDenoise,
                                       boolean enableEchoCancel,
                                       int frameSize,
                                       int filterLength)

Set params for echocancel and turns on/off noise suppression.

Parameters:

inputStream - the input stream.

outputStream - the output stream.

enableDenoise - is noise suppression enabled.

enableEchoCancel - is echo cancel enabled.

frameSize - Number of samples to process at one time (should correspond to 10-20 ms)

filterLength - Number of samples of echo to cancel (should generally correspond to 100-500 ms)

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_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_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_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_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_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_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_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_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_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_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.

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.

PaDeviceInfo_getName

public static String PaDeviceInfo_getName(long deviceInfo)

The name of the device.

Parameters:

deviceInfo - device info pointer.

Returns:

The name of 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_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_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.

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.

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

PaHostApiInfo_GetName

public static String PaHostApiInfo_GetName(long hostApiInfo)

A textual description of the host API for display on user interfaces.

Parameters:

hostApiInfo - pointer to host api info structure.

Returns:

host api name.

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_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.

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.