#include <portaudio.h>

Inheritance diagram for PSoundChannelPortAudio:

Collaboration diagram for PSoundChannelPortAudio:

Public Member Functions
	PSoundChannelPortAudio ()

	~PSoundChannelPortAudio ()

bool	Open (const Params &params)
	Open the specified device for playing or recording. More...

bool	Setup ()

bool	Close ()
	Close the channel. More...

bool	IsOpen () const
	Determine if the channel is currently open and read and write operations can be executed on it. More...

bool	Write (const void *buf, PINDEX len)
	Low level write to the channel. More...

bool	Read (void *buf, PINDEX len)
	Low level read from the channel. More...

bool	SetFormat (unsigned numChannels, unsigned sampleRate, unsigned bitsPerSample)
	Set the format for play/record. More...

unsigned	GetChannels () const
	Get the number of channels (mono/stereo) in the sound. More...

unsigned	GetSampleRate () const
	Get the sample rate in samples per second. More...

unsigned	GetSampleSize () const
	Get the sample size in bits per sample. More...

bool	SetBuffers (PINDEX size, PINDEX count)
	Set the internal buffers for the sound channel I/O. More...

bool	GetBuffers (PINDEX &size, PINDEX &count)
	Get the internal buffers for the sound channel I/O. More...

bool	PlaySound (const PSound &sound, bool wait)
	Play a sound to the open device. More...

bool	PlayFile (const PFilePath &filename, bool wait)
	Play a sound file to the open device. More...

bool	HasPlayCompleted ()
	Indicate if the sound play begun with PlayBuffer() or PlayFile() has completed. More...

bool	WaitForPlayCompletion ()
	Block calling thread until the sound play begun with PlaySound() or PlayFile() has completed. More...

bool	RecordSound (PSound &sound)
	Record into the sound object all of the buffer's of sound data. More...

bool	RecordFile (const PFilePath &filename)
	Record into the platform dependent sound file all of the buffer's of sound data. More...

bool	StartRecording ()
	Start filling record buffers. More...

bool	IsRecordBufferFull ()
	Determine if a record buffer has been filled, so that the next Read() call will not block. More...

bool	AreAllRecordBuffersFull ()
	Determine if all of the record buffer allocated has been filled. More...

bool	WaitForRecordBufferFull ()
	Block the thread until a record buffer has been filled, so that the next Read() call will not block. More...

bool	WaitForAllRecordBuffersFull ()
	Block the thread until all of the record buffer allocated has been filled. More...

bool	Abort ()
	Abort the background playing/recording of the sound channel. More...

bool	SetVolume (unsigned newVal)
	Set the volume of the play/read process. More...

bool	GetVolume (unsigned &devVol)
	Get the volume of the play/read process. More...

bool	SetMute (bool mute)
	Set the mute state of the play/read process. More...

bool	GetMute (bool &mute)
	Get the mute state of the play/read process. More...

bool	OpenStream (unsigned numChannels, unsigned sampleRate, unsigned bitsPerSample)

bool	StartStream ()

bool	StopStream ()

virtual PString	GetName () const
	Get the name of the channel. More...

PString	GetErrorText (ErrorGroup group=NumErrorGroups) const
	Get error message description. More...

Public Member Functions inherited from PSoundChannel
	P_DECLARE_STREAMABLE_ENUM (Directions, Recorder, Player, Closed)

	PSoundChannel ()
	Create a sound channel. More...

	PSoundChannel (const Params &params)
	Create a sound channel. More...

	PSoundChannel (const PString &device, Directions dir, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16)

bool	Open (const PString &device, Directions dir, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16, PPluginManager *pluginMgr=NULL)

Directions	GetDirection () const
	Get the direction of the channel. More...

virtual const char *	GetDirectionText () const
	Get text representing the direction of the channel. More...

Static Public Member Functions
static PStringArray	GetDeviceNames (PSoundChannel::Directions=Player)

static PMutex &	GetInitMutex ()

static bool	Initialise ()

Static Public Member Functions inherited from PSoundChannel
static PStringArray	GetDriverNames (PPluginManager *pluginMgr=NULL)
	Get the list of available sound drivers (plug-ins) More...

static PStringArray	GetDriversDeviceNames (const PString &driverName, Directions direction, PPluginManager *pluginMgr=NULL)
	Get sound devices that correspond to the specified driver name. More...

static PStringArray	GetDeviceNames (const PString &driverName, Directions direction, PPluginManager *pluginMgr=NULL)

static PSoundChannel *	CreateChannel (const PString &driverName, PPluginManager *pluginMgr=NULL)
	Create the sound channel that corresponds to the specified driver name. More...

static PSoundChannel *	CreateChannelByName (const PString &deviceName, Directions direction, PPluginManager *pluginMgr=NULL)

static PSoundChannel *	CreateOpenedChannel (const Params &params)
	Create an opened sound channel that corresponds to the specified names. More...

static PSoundChannel *	CreateOpenedChannel (const PString &driverName, const PString &deviceName, Directions direction, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16, PPluginManager *pluginMgr=NULL)

static PString	GetDefaultDevice (Directions dir)
	Get the name for the default sound devices/driver that is on this platform. More...

static PStringArray	GetDeviceNames (Directions direction, PPluginManager *pluginMgr=NULL)
	Get the list of all devices name for the default sound devices/driver that is on this platform. More...

static const char *	GetDirectionText (Directions dir)
	Get text representing the direction of a channel. More...

static PString	TestPlayer (const Params &params, const PNotifier &progress=PNotifier(), const char *toneSpec=NULL)
	Test the specified device for playing. More...

static PString	TestRecorder (const Params &recorderParams, const Params &playerParams, const PNotifier &progress=PNotifier(), unsigned seconds=5)
	Test the specified device for playing. More...

Protected Attributes
PMutex	m_mutex

int	m_channels

int	m_sampleRate

int	m_bitsPerSample

int	m_bytesPerSample

int	m_sampleFormat

const PaDeviceInfo *	m_deviceInfo

int	m_deviceId

PString	m_deviceName

bool	m_started

bool	m_mute

unsigned char *	m_muteBuffer

PINDEX	m_muteBufferSize

PaStream *	m_stream

PaStreamParameters	m_streamParms

int	m_volume

int	m_playBufferSize

int	m_playBufferCount

Protected Attributes inherited from PSoundChannel
Directions	activeDirection
	This is the direction that this sound channel is opened for use in. More...

Protected Attributes inherited from PIndirectChannel
PChannel *	readChannel
	Channel for read operations. More...

PBoolean	readAutoDelete
	Automatically delete read channel on destruction. More...

PChannel *	writeChannel
	Channel for write operations. More...

PBoolean	writeAutoDelete
	Automatically delete write channel on destruction. More...

PReadWriteMutex	channelPointerMutex
	Race condition prevention on closing channel. More...

Protected Attributes inherited from PChannel
P_INT_PTR	os_handle
	The operating system file handle return by standard open() function. More...

Errors	lastErrorCode [NumErrorGroups+1]
	The platform independant error code. More...

int	lastErrorNumber [NumErrorGroups+1]
	The operating system error number (eg as returned by errno). More...

PINDEX	lastReadCount
	Number of byte last read by the Read() function. More...

PINDEX	lastWriteCount
	Number of byte last written by the Write() function. More...

PTimeInterval	readTimeout
	Timeout for read operations. More...

PTimeInterval	writeTimeout
	Timeout for write operations. More...

PString	channelName
	Name of channel. More...

PMutex	px_threadMutex

PXBlockType	px_lastBlockType

PThread *	px_readThread

PThread *	px_writeThread

PMutex	px_writeMutex

PThread *	px_selectThread [3]

PMutex	px_selectMutex [3]

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Additional Inherited Members
Public Types inherited from PSoundChannel
enum	{ DefaultBufferSize = 320, DefaultBufferCount = 2 }

enum	{ MaxVolume = 100 }

Public Types inherited from PChannel
enum	PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }

enum	Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, Unavailable, NumNormalisedErrors }
	Normalised error codes. More...

enum	ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
	Error groups. More...

typedef PNotifierTemplate < PChannel::AsyncContext & >	AsyncNotifier

enum	ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }

Protected Member Functions inherited from PSoundChannel
PSoundChannel *	GetSoundChannel () const

	P_REMOVE_VIRTUAL (PBoolean, Open(const PString &, Directions, unsigned, unsigned, unsigned), false)

Friends inherited from PObject

Constructor & Destructor Documentation

PSoundChannelPortAudio::PSoundChannelPortAudio ( )

PSoundChannelPortAudio::~PSoundChannelPortAudio ( )

Member Function Documentation

bool PSoundChannelPortAudio::Abort ( )

virtual

Abort the background playing/recording of the sound channel.

There will be a logic assertion if you attempt to Abort a sound channel operation, when the device is currently closed.

Returns: true if the sound has successfully been aborted.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::AreAllRecordBuffersFull ( )

virtual

Determine if all of the record buffer allocated has been filled.

There is an implicit Abort() of the recording if this occurs and recording is stopped. The channel may need to be closed and opened again to start a new recording.

Returns: true if the sound driver has filled a buffer.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::Close ( )

virtual

Close the channel.

This will detach itself from the read and write channels and delete both of them if they are auto delete.

Returns: true if the channel is closed.

Reimplemented from PIndirectChannel.

bool PSoundChannelPortAudio::GetBuffers	(	PINDEX &	size,
		PINDEX &	count
	)

virtual

Get the internal buffers for the sound channel I/O.

Returns: true if the buffer size were obtained.

Reimplemented from PSoundChannel.

unsigned PSoundChannelPortAudio::GetChannels ( ) const

virtual

Get the number of channels (mono/stereo) in the sound.

Reimplemented from PSoundChannel.

static PStringArray PSoundChannelPortAudio::GetDeviceNames ( PSoundChannel::Directions = Player )

static

PString PSoundChannelPortAudio::GetErrorText ( ErrorGroup group = NumErrorGroups ) const

virtual

Get error message description.

Return a string indicating the error message that may be displayed to the user. The error for the last I/O operation in this object is used.

Returns: Operating System error description string.

Reimplemented from PIndirectChannel.

static PMutex& PSoundChannelPortAudio::GetInitMutex ( )

static

bool PSoundChannelPortAudio::GetMute ( bool & mute )

virtual

Get the mute state of the play/read process.

Returns: true if there were no errors.

Reimplemented from PSoundChannel.

virtual PString PSoundChannelPortAudio::GetName ( ) const

virtual

Get the name of the channel.

This is a combination of the channel pointers names (or simply the channel pointers name if the read and write channels are the same) or empty string if both null.

Returns: string for the channel names.

Reimplemented from PIndirectChannel.

unsigned PSoundChannelPortAudio::GetSampleRate ( ) const

virtual

Get the sample rate in samples per second.

Reimplemented from PSoundChannel.

unsigned PSoundChannelPortAudio::GetSampleSize ( ) const

virtual

Get the sample size in bits per sample.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::GetVolume ( unsigned & volume )

virtual

Get the volume of the play/read process.

The volume range is 0 == muted, 100 == LOUDEST. The volume is a logarithmic scale mapped from the lowest gain possible on the device to the highest gain.

Returns: true if there were no errors.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::HasPlayCompleted ( )

virtual

Indicate if the sound play begun with PlayBuffer() or PlayFile() has completed.

Returns: true if the sound has completed playing.

Reimplemented from PSoundChannel.

static bool PSoundChannelPortAudio::Initialise ( )

static

bool PSoundChannelPortAudio::IsOpen ( ) const

virtual

Determine if the channel is currently open and read and write operations can be executed on it.

For example, in the PFile class it returns if the file is currently open.

Returns: true if the channel is open.

Reimplemented from PIndirectChannel.

bool PSoundChannelPortAudio::IsRecordBufferFull ( )

virtual

Determine if a record buffer has been filled, so that the next Read() call will not block.

Provided that the amount of data read is less than the buffer size.

Returns: true if the sound driver has filled a buffer.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::Open ( const Params & params )

virtual

Open the specified device for playing or recording.

The device name is platform specific and is as returned in the GetDevices() function.

Returns: true if the sound device is valid for playing/recording.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::OpenStream	(	unsigned	numChannels,
		unsigned	sampleRate,
		unsigned	bitsPerSample
	)

bool PSoundChannelPortAudio::PlayFile	(	const PFilePath &	file,
		bool	wait
	)

virtual

Play a sound file to the open device.

If the wait parameter is true then the function does not return until the file has been played. If false then the sound play is begun asynchronously and the function returns immediately.

Note if the driver is closed of the object destroyed then the sound play is aborted.

Also note that not all possible sounds and sound files are playable by this library. No format conversions between sound object and driver are performed.

Returns: true if the sound is playing or has played.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::PlaySound	(	const PSound &	sound,
		bool	wait
	)

virtual

Play a sound to the open device.

If the wait parameter is true then the function does not return until the file has been played. If false then the sound play is begun asynchronously and the function returns immediately.

Note: if the driver is closed while playing the sound, the play operation stops immediately.

Also note that not all possible sounds and sound files are playable by this library. No format conversions between sound object and driver are performed.

Returns: true if the sound is playing or has played.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::Read	(	void *	buf,
		PINDEX	len
	)

virtual

Low level read from the channel.

This function may block until the requested number of characters were read or the read timeout was reached. The GetLastReadCount() function returns the actual number of bytes read.

This will use the readChannel pointer to actually do the read. If readChannel is null the this asserts.

The GetErrorCode() function should be consulted after Read() returns false to determine what caused the failure.

Returns: true indicates that at least one character was read from the channel. false means no bytes were read due to timeout or some other I/O error.

Reimplemented from PIndirectChannel.

bool PSoundChannelPortAudio::RecordFile ( const PFilePath & file )

virtual

Record into the platform dependent sound file all of the buffer's of sound data.

Use the SetBuffers() function to determine how long the recording will be made.

Note that this function will block until all of the data is buffered. If you wish to do this asynchronously, use StartRecording() and AreAllrecordBuffersFull() to determine when you can call RecordSound() without blocking.

Returns: true if the sound has been recorded.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::RecordSound ( PSound & sound )

virtual

Record into the sound object all of the buffer's of sound data.

Use the SetBuffers() function to determine how long the recording will be made.

For the Win32 platform, the most efficient way to record a PSound is to use the SetBuffers() function to set a single buffer of the desired size and then do the recording. For Linux OSS this can cause problems as the buffers are rounded up to a power of two, so to gain more accuracy you need a number of smaller buffers.

Note that this function will block until all of the data is buffered. If you wish to do this asynchronously, use StartRecording() and AreAllrecordBuffersFull() to determine when you can call RecordSound() without blocking.

Returns: true if the sound has been recorded.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::SetBuffers	(	PINDEX	size,
		PINDEX	count
	)

virtual

Set the internal buffers for the sound channel I/O.

Note that with Linux OSS, the size is always rounded up to the nearest power of two, so 20000 => 32768.

Returns: true if the sound device is valid for playing/recording.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::SetFormat	(	unsigned	numChannels,
		unsigned	sampleRate,
		unsigned	bitsPerSample
	)

virtual

Set the format for play/record.

Note that linear PCM data is the only one supported at this time.

Note that if the PlayFile() function is used, this may be overridden by information in the file being played.

Returns: true if the format is valid.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::SetMute ( bool mute )

virtual

Set the mute state of the play/read process.

Returns: true if there were no errors.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::Setup ( )

bool PSoundChannelPortAudio::SetVolume ( unsigned volume )

virtual

Set the volume of the play/read process.

The volume range is 0 == muted, 100 == LOUDEST. The volume is a logarithmic scale mapped from the lowest gain possible on the device to the highest gain.

Returns: true if there were no errors.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::StartRecording ( )

virtual

Start filling record buffers.

The first call to Read() will also initiate the recording.

Returns: true if the sound driver has successfully started recording.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::StartStream ( )

bool PSoundChannelPortAudio::StopStream ( )

bool PSoundChannelPortAudio::WaitForAllRecordBuffersFull ( )

virtual

Block the thread until all of the record buffer allocated has been filled.

There is an implicit Abort() of the recording if this occurs and recording is stopped. The channel may need to be closed and opened again to start a new recording.

Returns: true if the sound driver has filled a buffer.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::WaitForPlayCompletion ( )

virtual

Block calling thread until the sound play begun with PlaySound() or PlayFile() has completed.

Returns: true if the sound has successfully completed playing.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::WaitForRecordBufferFull ( )

virtual

Block the thread until a record buffer has been filled, so that the next Read() call will not block.

Provided that the amount of data read is less than the buffer size.

Returns: true if the sound driver has filled a buffer.

Reimplemented from PSoundChannel.

bool PSoundChannelPortAudio::Write	(	const void *	buf,
		PINDEX	len
	)

virtual

Low level write to the channel.

This function will block until the requested number of characters are written or the write timeout is reached. The GetLastWriteCount() function returns the actual number of bytes written.

This will use the writeChannel pointer to actually do the write. If writeChannel is null the this asserts.

The GetErrorCode() function should be consulted after Write() returns false to determine what caused the failure.

Returns: true if at least len bytes were written to the channel.

Reimplemented from PIndirectChannel.

Member Data Documentation

int PSoundChannelPortAudio::m_bitsPerSample

protected

int PSoundChannelPortAudio::m_bytesPerSample

protected

int PSoundChannelPortAudio::m_channels

protected

int PSoundChannelPortAudio::m_deviceId

protected

const PaDeviceInfo* PSoundChannelPortAudio::m_deviceInfo

protected

PString PSoundChannelPortAudio::m_deviceName

protected

bool PSoundChannelPortAudio::m_mute

protected

unsigned char* PSoundChannelPortAudio::m_muteBuffer

protected

PINDEX PSoundChannelPortAudio::m_muteBufferSize

protected

PMutex PSoundChannelPortAudio::m_mutex

protected

int PSoundChannelPortAudio::m_playBufferCount

protected

int PSoundChannelPortAudio::m_playBufferSize

protected

int PSoundChannelPortAudio::m_sampleFormat

protected

int PSoundChannelPortAudio::m_sampleRate

protected

bool PSoundChannelPortAudio::m_started

protected

PaStream* PSoundChannelPortAudio::m_stream

protected

PaStreamParameters PSoundChannelPortAudio::m_streamParms

protected

int PSoundChannelPortAudio::m_volume

protected

The documentation for this class was generated from the following file:

portaudio.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation