Abstract class for a generalised sound channel, and an implementation of PSoundChannel for old code that is not plugin-aware. More...

#include <sound.h>

Inheritance diagram for PSoundChannel:

[legend]

Collaboration diagram for PSoundChannel:

[legend]

Classes
struct	Params
	Parameters for opening a sound channel. More...

Protected Member Functions
PSoundChannel *	GetSoundChannel () const

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

Protected Member Functions inherited from PIndirectChannel
virtual PBoolean	OnOpen ()
	This callback is executed when the Open() function is called with open channels. More...

Protected Member Functions inherited from PChannel
	PChannel (const PChannel &)

PChannel &	operator= (const PChannel &)

virtual PBoolean	ConvertOSError (P_INT_PTR libcReturnValue, ErrorGroup group=LastGeneralError)
	Convert an operating system error into platform independent error. More...

int	ReadCharWithTimeout (PTimeInterval &timeout)
	Read a character with specified timeout. More...

PBoolean	ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)

virtual int	os_errno () const

PBoolean	PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)

P_INT_PTR	GetOSHandleAsInt () const

int	PXClose ()

	PChannel ()
	Create the channel. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes
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

Construction
enum	{ DefaultBufferSize = 320, DefaultBufferCount = 2 }

	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)

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

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

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

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

Channel set up functions
enum	{ MaxVolume = 100 }

virtual PBoolean	SetFormat (unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16)
	Set the format for play/record. More...

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

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

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

virtual PBoolean	SetBuffers (PINDEX size, PINDEX count=2)
	Set the internal buffers for the sound channel I/O. More...

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

virtual PBoolean	SetVolume (unsigned volume)
	Set the volume of the play/read process. More...

virtual PBoolean	GetVolume (unsigned &volume)
	Get the volume of the play/read process. More...

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

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

Play functions
virtual PBoolean	PlaySound (const PSound &sound, PBoolean wait=true)
	Play a sound to the open device. More...

virtual PBoolean	PlayFile (const PFilePath &file, PBoolean wait=true)
	Play a sound file to the open device. More...

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

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

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

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

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

virtual PBoolean	StartRecording ()
	Start filling record buffers. More...

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

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

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

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

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

Additional Inherited Members
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 }

Public Member Functions inherited from PIndirectChannel
	PIndirectChannel ()
	Create a new indirect channel without any channels to redirect to. More...

	~PIndirectChannel ()
	Close the indirect channel, deleting read/write channels if desired. More...

Comparison	Compare (const PObject &obj) const
	Determine if the two objects refer to the same indirect channel. More...

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

virtual P_INT_PTR	GetHandle () const
	Get the OS specific handle for the PSoundChannel. More...

virtual PBoolean	Close ()
	Close the channel. More...

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

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

virtual int	ReadChar ()
	Read a single character from the channel. More...

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

virtual PBoolean	Shutdown (ShutdownValue option)
	Close one or both of the data streams associated with a channel. More...

virtual bool	SetLocalEcho (bool localEcho)
	Set local echo mode. More...

virtual PChannel *	GetBaseReadChannel () const
	This function returns the eventual base channel for reading of a series of indirect channels provided by descendents of `PIndirectChannel`. More...

virtual PChannel *	GetBaseWriteChannel () const
	This function returns the eventual base channel for writing of a series of indirect channels provided by descendents of `PIndirectChannel`. More...

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

PBoolean	Open (PChannel &channel)
	Set the channel for both read and write operations. More...

PBoolean	Open (PChannel *channel, PBoolean autoDelete=true)
	Set the channel for both read and write operations. More...

PBoolean	Open (PChannel readChannel, PChannel writeChannel, PBoolean autoDeleteRead=true, PBoolean autoDeleteWrite=true)
	Set the channel for both read and write operations. More...

PChannel *	Detach (ShutdownValue option=ShutdownReadAndWrite)
	Detach without closing the read/write channel. More...

PChannel *	GetReadChannel () const
	Get the channel used for read operations. More...

bool	SetReadChannel (PChannel *channel, bool autoDelete=true, bool closeExisting=false)
	Set the channel for read operations. More...

PChannel *	GetWriteChannel () const
	Get the channel used for write operations. More...

PBoolean	SetWriteChannel (PChannel *channel, bool autoDelete=true, bool closeExisting=false)
	Set the channel for read operations. More...

Static Public Member Functions inherited from PChannel
static PString	GetErrorText (Errors lastError, int osError=0)
	Get error message description. More...

Static Public Member Functions inherited from PObject
static const char *	Class ()
	Get the name of the class as a C string. More...

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

Friends inherited from PObject

Detailed Description

Abstract class for a generalised sound channel, and an implementation of PSoundChannel for old code that is not plugin-aware.

When instantiated, it selects the first plugin of the base class "PSoundChannel"

As an abstract class, this represents a sound channel. Drivers for real, platform dependent sound hardware will be ancestors of this class and can be found in the plugins section of PTLib.

A sound channel is either playing or recording. If simultaneous playing and recording is desired, two instances of PSoundChannel must be created. It is an error for the same thread to attempt to both read and write audio data to once instance of a PSoundChannel class.

PSoundChannel instances are designed to be reentrant. The actual usage model employed is left to the developer. One model could be where one thread is responsible for construction, setup, opening and read/write operations. After creating and eventually opening the channel this thread is responsible for handling read/writes fast enough to avoid gaps in the generated audio stream.

Remaining operations may beinvoked from other threads. This includes Close() and actually gathering the necessary data to be sent to the device.

Besides the basic I/O task, the Read()/Write(() functions have well defined timing characteristics. When a PSoundChannel instance is used from Opal, the read/write operations are designed to also act as timers so as to nicely space the generated network packets of audio/ sound packets to the speaker.

Read and Writes of audio data to a PSoundChannel are blocking. The length of time required to read/write a block of audio from/to a PSoundChannel instance is equal to the time required for that block of audio to record/play. So for a sound rate of 8khz, 240 samples, it is going to take 30ms to do a read/write.

Since the Read()/Write(() functions have well defined timing characteristics; they are designed to also act as timers in a loop involving data transfers to/from the codecs.

The sound is buffered and the size and number of buffers should be set before playing/recording. Each call to Write() will use one buffer, so care needs to be taken not to use a large number of small writes but tailor the buffers to the size of each write you make.

Similarly for reading, an entire buffer must be read before any of it is available to a Read() call. Note that once a buffer is filled you can read it a byte at a time if desired, but as soon as all the data in the buffer is used, the next read will wait until the entire next buffer is read from the hardware. So again, tailor the number and size of buffers to the application. To avoid being blocked until the buffer fills, you can use the StartRecording() function to initiate the buffer filling, and the IsRecordingBufferFull() function to determine when the Read() function will no longer block.

Note that this sound channel is implicitly a linear PCM channel. No data conversion is performed on data to/from the channel.

Member Enumeration Documentation

anonymous enum

Enumerator
DefaultBufferSize
DefaultBufferCount

anonymous enum

Enumerator
MaxVolume

Constructor & Destructor Documentation

PSoundChannel::PSoundChannel ( )

Create a sound channel.

PSoundChannel::PSoundChannel ( const Params & params )

Create a sound channel.

Create a reference to the sound drivers for the platform.

Parameters

params Parameters for opening channel

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

Parameters

device	Name of sound driver/device
dir	Sound I/O direction
numChannels	Number of channels eg mono/stereo
sampleRate	Samples per second
bitsPerSample	Number of bits per sample

Member Function Documentation

virtual PBoolean PSoundChannel::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.

driverName	Name of driver
pluginMgr	Plug in manager, use default if NULL

deviceName	Name of device
direction	Direction for device (record or play)
pluginMgr	Plug in manager, use default if NULL

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

PSoundChannel::P_DECLARE_STREAMABLE_ENUM	(	Directions	,
		Recorder	,
		Player	,
		Closed
	)

file	Sound file to play.
wait	Flag to play sound synchronously.

params	Parameters for opening channel
progress	Call back for progress in playback
toneSpec	Tones as used by PTones class.

recorderParams	Parameters for opening channel
playerParams	Parameters for opening channel
progress	Call back for progress in playback
seconds	Seconds to record

Classes

Protected Member Functions

Protected Attributes

Construction

Open functions

Channel set up functions

Play functions

Record functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation