PTLib  Version 2.10.11
PSoundChannel Class Reference

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:
PChannel PObject

Public Member Functions

Play functions
virtual PBoolean Write (const void *buf, PINDEX len)
 Low level write (or play) to the channel. More...
 
virtual PBoolean Write (const void *buf, PINDEX len, const void *mark)
 Low level write (or play) with watermark to the channel. More...
 
virtual PINDEX GetLastWriteCount () const
 Get number of bytes written in last Write() operation. More...
 
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...
 
Record functions
virtual PBoolean Read (void *buf, PINDEX len)
 Low level read from the channel. More...
 
PINDEX GetLastReadCount () const
 Return number of bytes read in last Read() call. More...
 
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...
 
- Public Member Functions inherited from PChannel
PBoolean SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
 Set error values to those specified. More...
 
 PChannel ()
 Create the channel. More...
 
 ~PChannel ()
 Close down the channel. More...
 
virtual Comparison Compare (const PObject &obj) const
 Get the relative rank of the two strings. More...
 
virtual PINDEX HashFunction () const
 Calculate a hash value for use in sets and dictionaries. More...
 
int GetHandle () const
 Get the integer operating system handle for the channel. More...
 
virtual PChannelGetBaseReadChannel () const
 Get the base channel of channel indirection using PIndirectChannel. More...
 
virtual PChannelGetBaseWriteChannel () const
 Get the base channel of channel indirection using PIndirectChannel. More...
 
void SetReadTimeout (const PTimeInterval &time)
 Set the timeout for read operations. More...
 
PTimeInterval GetReadTimeout () const
 Get the timeout for read operations. More...
 
virtual int ReadChar ()
 Read a single 8 bit byte from the channel. More...
 
PBoolean ReadBlock (void *buf, PINDEX len)
 Read len bytes into the buffer from the channel. More...
 
PString ReadString (PINDEX len)
 Read len character into a string from the channel. More...
 
virtual PBoolean ReadAsync (void *buf, PINDEX len)
 Begin an asynchronous read from channel. More...
 
virtual void OnReadComplete (void *buf, PINDEX len)
 User callback function for when a ReadAsync() call has completed or timed out. More...
 
void SetWriteTimeout (const PTimeInterval &time)
 Set the timeout for write operations to complete. More...
 
PTimeInterval GetWriteTimeout () const
 Get the timeout for write operations to complete. More...
 
PBoolean WriteChar (int c)
 Write a single character to the channel. More...
 
PBoolean WriteString (const PString &str)
 Write a string to the channel. More...
 
virtual PBoolean WriteAsync (const void *buf, PINDEX len)
 Begin an asynchronous write from channel. More...
 
virtual void OnWriteComplete (const void *buf, PINDEX len)
 User callback function for when a WriteAsync() call has completed or timed out. 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 bool FlowControl (const void *flowData)
 Flow Control information Pass data to the channel for flowControl determination. More...
 
PBoolean SetBufferSize (PINDEX newSize)
 Set the iostream buffer size for reads and writes. More...
 
PBoolean SendCommandString (const PString &command)
 Send a command meta-string. More...
 
void AbortCommandString ()
 Abort a command string that is in progress. More...
 
Errors GetErrorCode (ErrorGroup group=NumErrorGroups) const
 Get normalised error code. More...
 
int GetErrorNumber (ErrorGroup group=NumErrorGroups) const
 Get OS errro code. More...
 
virtual PString GetErrorText (ErrorGroup group=NumErrorGroups) const
 Get error message description. More...
 
virtual PBoolean Read (const VectorOfSlice &slices)
 Low level scattered read from the channel. More...
 
virtual PBoolean Write (const VectorOfSlice &slices)
 Low level scattered write to the channel. More...
 
- Public Member Functions inherited from PObject
virtual ~PObject ()
 
virtual PObjectClone () const
 Create a copy of the class on the heap. More...
 
virtual const char * GetClass (unsigned ancestor=0) const
 Get the current dynamic type of the object instance. More...
 
PBoolean IsClass (const char *cls) const
 
virtual PBoolean InternalIsDescendant (const char *clsName) const
 Determine if the dynamic type of the current instance is a descendent of the specified class. More...
 
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
 Determine the byte wise comparison of two objects. More...
 
bool operator== (const PObject &obj) const
 Compare the two objects. More...
 
bool operator!= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator< (const PObject &obj) const
 Compare the two objects. More...
 
bool operator> (const PObject &obj) const
 Compare the two objects. More...
 
bool operator<= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator>= (const PObject &obj) const
 Compare the two objects. More...
 
virtual void PrintOn (ostream &strm) const
 Output the contents of the object to the stream. More...
 
virtual void ReadFrom (istream &strm)
 Input the contents of the object from the stream. More...
 

Protected Attributes

PSoundChannelm_baseChannel
 
PReadWriteMutex m_baseMutex
 
Directions activeDirection
 This is the direction that this sound channel is opened for use in. More...
 
- Protected Attributes inherited from PChannel
int 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
 
PMutex px_threadMutex
 
PXBlockType px_lastBlockType
 
PThreadpx_readThread
 
PThreadpx_writeThread
 
PMutex px_writeMutex
 
PThreadpx_selectThread [3]
 
PMutex px_selectMutex [3]
 

Construction

enum  Directions { Closed = -1, Recorder, Player }
 
 PSoundChannel ()
 Create a sound channel. More...
 
 PSoundChannel (const PString &device, Directions dir, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16)
 Create a sound channel. More...
 
virtual ~PSoundChannel ()
 

Open functions

virtual PBoolean Open (const PString &device, Directions dir, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16)
 Open the specified device for playing or recording. More...
 
virtual PBoolean IsOpen () const
 Test if this instance of PSoundChannel is open. More...
 
virtual PBoolean Close ()
 Close the channel, shutting down the link to the data source. More...
 
virtual int GetHandle () const
 Get the OS specific handle for the PSoundChannel. More...
 
virtual PString GetName () const
 Get the name of the open channel. More...
 
Directions GetDirection () const
 Get the direction of the channel. More...
 
virtual const char * GetDirectionText () const
 
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 PSoundChannelCreateChannel (const PString &driverName, PPluginManager *pluginMgr=NULL)
 Create the sound channel that corresponds to the specified driver name. More...
 
static PSoundChannelCreateChannelByName (const PString &deviceName, Directions direction, PPluginManager *pluginMgr=NULL)
 
static PSoundChannelCreateOpenedChannel (const PString &driverName, const PString &deviceName, Directions direction, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16, PPluginManager *pluginMgr=NULL)
 Create an opened sound channel that corresponds to the specified names. More...
 
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 the 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...
 

Additional Inherited Members

- Public Types inherited from PChannel
enum  PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }
 
enum  ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
 
enum  Errors {
  NoError, NotFound, FileExists, DiskFull,
  AccessDenied, DeviceInUse, BadParameter, NoMemory,
  NotOpen, Timeout, Interrupted, BufferTooSmall,
  Miscellaneous, ProtocolFailure, NumNormalisedErrors
}
 Normalised error codes. More...
 
enum  ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
 Error groups. More...
 
typedef std::vector< SliceVectorOfSlice
 
- Public Types inherited from PObject
enum  Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
 Result of the comparison operation performed by the Compare() function. More...
 
- Static Public Member Functions inherited from PChannel
static PBoolean ConvertOSError (int libcReturnValue, Errors &lastError, int &osError)
 Convert an operating system error into platform independent error. More...
 
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 Comparison InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
 Internal function caled from CompareObjectMemoryDirect() More...
 
- Protected Member Functions inherited from PChannel
 PChannel (const PChannel &)
 
PChanneloperator= (const PChannel &)
 
virtual PBoolean ConvertOSError (int 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)
 
PBoolean PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)
 
int PXClose ()
 
- Protected Member Functions inherited from PObject
 PObject ()
 Constructor for PObject, made protected so cannot ever create one on its own. More...
 

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

anonymous enum
Enumerator
MaxVolume 

§ Directions

Enumerator
Closed 
Recorder 
Player 

Constructor & Destructor Documentation

§ PSoundChannel() [1/2]

PSoundChannel::PSoundChannel ( )

Create a sound channel.

§ PSoundChannel() [2/2]

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

Create a sound channel.

Create a reference to the sound drivers for the platform.

Parameters
deviceName of sound driver/device
dirSound I/O direction
numChannelsNumber of channels eg mono/stereo
sampleRateSamples per second
bitsPerSampleNumber of bits per sample

§ ~PSoundChannel()

virtual PSoundChannel::~PSoundChannel ( )
virtual

Member Function Documentation

§ Abort()

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.

§ AreAllRecordBuffersFull()

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

§ Close()

virtual PBoolean PSoundChannel::Close ( )
virtual

Close the channel, shutting down the link to the data source.

Returns
true if the channel successfully closed.

Reimplemented from PChannel.

§ CreateChannel()

static PSoundChannel* PSoundChannel::CreateChannel ( const PString driverName,
PPluginManager pluginMgr = NULL 
)
static

Create the sound channel that corresponds to the specified driver name.

Parameters
driverNameName of driver
pluginMgrPlug in manager, use default if NULL

§ CreateChannelByName()

static PSoundChannel* PSoundChannel::CreateChannelByName ( const PString deviceName,
Directions  direction,
PPluginManager pluginMgr = NULL 
)
static
Parameters
deviceNameName of device
directionDirection for device (record or play)
pluginMgrPlug in manager, use default if NULL

§ CreateOpenedChannel()

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

Create an opened sound channel that corresponds to the specified names.

If the driverName parameter is an empty string or "*" then CreateChannelByName is used with the deviceName parameter which is assumed to be a value returned from GetAllDeviceNames().

Parameters
driverNameName of driver
deviceNameName of device
directionDirection for device (record or play)
numChannelsNumber of channels 1=mon, 2=stereo
sampleRateSample rate
bitsPerSampleBits per sample
pluginMgrPlug in manager, use default if NULL

§ GetBuffers()

virtual PBoolean PSoundChannel::GetBuffers ( PINDEX &  size,
PINDEX &  count 
)
virtual

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

Returns
true if the buffer size were obtained.

§ GetChannels()

virtual unsigned PSoundChannel::GetChannels ( ) const
virtual

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

§ GetDefaultDevice()

static PString PSoundChannel::GetDefaultDevice ( Directions  dir)
static

Get the name for the default sound devices/driver that is on this platform.

Note that a named device may not necessarily do both playing and recording so the string returned with the dir parameter in each value is not necessarily the same.

Returns
A platform dependent string for the sound player/recorder.

§ GetDeviceNames() [1/2]

static PStringArray PSoundChannel::GetDeviceNames ( const PString driverName,
Directions  direction,
PPluginManager pluginMgr = NULL 
)
inlinestatic

§ GetDeviceNames() [2/2]

static PStringArray PSoundChannel::GetDeviceNames ( Directions  direction,
PPluginManager pluginMgr = NULL 
)
static

Get the list of all devices name for the default sound devices/driver that is on this platform.

Note that a named device may not necessarily do both playing and recording so the arrays returned with the dir parameter in each value is not necessarily the same.

This will return a list of unique device names across all of the available drivers. If two drivers have identical names for devices, then the string returned will be of the form driver+'\t'+device.

Returns
Platform dependent strings for the sound player/recorder.
Parameters
directionDirection for device (record or play)
pluginMgrPlug in manager, use default if NULL

§ GetDirection()

Directions PSoundChannel::GetDirection ( ) const
inline

Get the direction of the channel.

§ GetDirectionText() [1/2]

static const char* PSoundChannel::GetDirectionText ( Directions  dir)
static

Get text representing the direction of the channel.

§ GetDirectionText() [2/2]

virtual const char* PSoundChannel::GetDirectionText ( ) const
inlinevirtual

§ GetDriverNames()

static PStringArray PSoundChannel::GetDriverNames ( PPluginManager pluginMgr = NULL)
static

Get the list of available sound drivers (plug-ins)

Parameters
pluginMgrPlug in manager, use default if NULL

§ GetDriversDeviceNames()

static PStringArray PSoundChannel::GetDriversDeviceNames ( const PString driverName,
Directions  direction,
PPluginManager pluginMgr = NULL 
)
static

Get sound devices that correspond to the specified driver name.

If driverName is an empty string or the value "*" then GetAllDeviceNames() is used.

Parameters
driverNameName of driver
directionDirection for device (record or play)
pluginMgrPlug in manager, use default if NULL

§ GetHandle()

virtual int PSoundChannel::GetHandle ( ) const
virtual

Get the OS specific handle for the PSoundChannel.

Returns
integer value of the handle.

§ GetLastReadCount()

PINDEX PSoundChannel::GetLastReadCount ( ) const
virtual

Return number of bytes read in last Read() call.

Reimplemented from PChannel.

§ GetLastWriteCount()

virtual PINDEX PSoundChannel::GetLastWriteCount ( ) const
virtual

Get number of bytes written in last Write() operation.

Reimplemented from PChannel.

§ GetMute()

virtual bool PSoundChannel::GetMute ( bool &  mute)
virtual

Get the mute state of the play/read process.

Returns
true if there were no errors.
Parameters
muteVariable to receive mute state.

§ GetName()

virtual PString PSoundChannel::GetName ( ) const
virtual

Get the name of the open channel.

Reimplemented from PChannel.

§ GetSampleRate()

virtual unsigned PSoundChannel::GetSampleRate ( ) const
virtual

Get the sample rate in samples per second.

§ GetSampleSize()

virtual unsigned PSoundChannel::GetSampleSize ( ) const
virtual

Get the sample size in bits per sample.

§ GetVolume()

virtual PBoolean PSoundChannel::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.
Parameters
volumeVariable to receive volume level.

§ HasPlayCompleted()

virtual PBoolean PSoundChannel::HasPlayCompleted ( )
virtual

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

Returns
true if the sound has completed playing.

§ IsOpen()

virtual PBoolean PSoundChannel::IsOpen ( ) const
virtual

Test if this instance of PSoundChannel is open.

Returns
true if this instance is open.

Reimplemented from PChannel.

§ IsRecordBufferFull()

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

§ Open()

virtual PBoolean PSoundChannel::Open ( const PString device,
Directions  dir,
unsigned  numChannels = 1,
unsigned  sampleRate = 8000,
unsigned  bitsPerSample = 16 
)
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.
Parameters
deviceName of sound driver/device
dirSound I/O direction
numChannelsNumber of channels eg mono/stereo
sampleRateSamples per second
bitsPerSampleNumber of bits per sample

§ PlayFile()

virtual PBoolean PSoundChannel::PlayFile ( const PFilePath file,
PBoolean  wait = true 
)
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.
Parameters
fileSound file to play.
waitFlag to play sound synchronously.

§ PlaySound()

virtual PBoolean PSoundChannel::PlaySound ( const PSound sound,
PBoolean  wait = true 
)
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.
Parameters
soundSound to play.
waitFlag to play sound synchronously.

§ Read()

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

It will generate a logical assertion if you attempt to read from a PSoundChannel that is setup for playing.

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

Parameters
lenNr of bytes to endeaveour to read from the sound device. If len equals the buffer size set by SetBuffers() it will block for (1000*len)/(samplesize*samplerate) ms. Typically, the sample size is 2 bytes. If len == 0, this will return immediately, where the return value is equal to the value of IsOpen().
bufis a pointer to the empty data area, which will contain the data collected from the sound device. It is an error for this pointer to be NULL. A logical assert will be generated when buf is NULL.
Returns
true indicates that at least one character was read from the channel. false means no bytes were read due to some I/O error, (which includes timeout or some other thread closed the device).
Parameters
bufPointer to a block of memory to receive the read bytes.
lenMaximum number of bytes to read into the buffer.

Reimplemented from PChannel.

§ RecordFile()

virtual PBoolean PSoundChannel::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.
Parameters
fileSound file recorded

§ RecordSound()

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

§ SetBuffers()

virtual PBoolean PSoundChannel::SetBuffers ( PINDEX  size,
PINDEX  count = 2 
)
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.
Parameters
sizeSize of each buffer
countNumber of buffers

§ SetFormat()

virtual PBoolean PSoundChannel::SetFormat ( unsigned  numChannels = 1,
unsigned  sampleRate = 8000,
unsigned  bitsPerSample = 16 
)
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.
Parameters
numChannelsNumber of channels eg mono/stereo
sampleRateSamples per second
bitsPerSampleNumber of bits per sample

§ SetMute()

virtual bool PSoundChannel::SetMute ( bool  mute)
virtual

Set the mute state of the play/read process.

Returns
true if there were no errors.
Parameters
muteNew mute state

§ SetVolume()

virtual PBoolean PSoundChannel::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.
Parameters
volumeNew volume level

§ StartRecording()

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

§ WaitForAllRecordBuffersFull()

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

§ WaitForPlayCompletion()

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

§ WaitForRecordBufferFull()

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

§ Write() [1/2]

virtual PBoolean PSoundChannel::Write ( const void *  buf,
PINDEX  len 
)
virtual

Low level write (or play) to the channel.

It will generate a logical assertion if you attempt write to a channel set up for recording.

Parameters
bufis a pointer to the data to be written to the channel. It is an error for this pointer to be NULL. A logical assert will be generated when buf is NULL.
lenNr of bytes to send. If len equals the buffer size set by SetBuffers() it will block for (1000*len)/(samplesize*samplerate) ms. Typically, the sample size is 2 bytes. If len == 0, this will return immediately, where the return value is equal to the value of IsOpen().
Returns
true if len bytes were written to the channel, otherwise false. The GetErrorCode() function should be consulted after Write() returns false to determine what caused the failure.

Reimplemented from PChannel.

§ Write() [2/2]

virtual PBoolean PSoundChannel::Write ( const void *  buf,
PINDEX  len,
const void *  mark 
)
virtual

Low level write (or play) with watermark to the channel.

It will generate a logical assertion if you attempt write to a channel set up for recording.

Parameters
bufis a pointer to the data to be written to the channel. It is an error for this pointer to be NULL. A logical assert will be generated when buf is NULL.
lenNr of bytes to send. If len equals the buffer size set by SetBuffers() it will block for (1000*len)/(samplesize*samplerate) ms. Typically, the sample size is 2 bytes. If len == 0, this will return immediately, where the return value is equal to the value of IsOpen().
markUnique identifer to identify the write
Returns
PTrue if len bytes were written to the channel, otherwise PFalse. The GetErrorCode() function should be consulted after Write() returns PFalse to determine what caused the failure.
Parameters
bufPointer to a block of memory to write.
lenNumber of bytes to write.
markUnique Marker to identify write

Reimplemented from PChannel.

Member Data Documentation

§ activeDirection

Directions PSoundChannel::activeDirection
protected

This is the direction that this sound channel is opened for use in.

Should the user attempt to used this opened class instance in a direction opposite to that specified in activeDirection, an assert happens.

§ m_baseChannel

PSoundChannel* PSoundChannel::m_baseChannel
protected

§ m_baseMutex

PReadWriteMutex PSoundChannel::m_baseMutex
protected

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