class PSoundChannel

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

Inheritance:


Public Methods

[more] Construction
[more] Open functions
[more] Channel set up functions
[more] Play functions
[more] Record functions


Inherited from PChannel:

Public Methods

Overrides from class PObject

Information functions

Reading functions

Writing functions

Miscellaneous functions

ostatic BOOL ConvertOSError( int libcReturnValue, Errors & lastError, int & osError )

Public Members

Error functions

Protected Fields

oint os_handle
oErrors lastErrorCode[NumErrorGroups+1]
oint lastErrorNumber[NumErrorGroups+1]
oPINDEX lastReadCount
oPINDEX lastWriteCount
oPTimeInterval readTimeout
oPTimeInterval writeTimeout

Protected Methods

ovirtual BOOL ConvertOSError( int libcReturnValue, ErrorGroup group = LastGeneralError )
oBOOL SetErrorValues( Errors errorCode, int osError, ErrorGroup group = LastGeneralError )
oint ReadCharWithTimeout( PTimeInterval & timeout )


Inherited from PObject:

Public Methods

Run Time Type functions

I/O functions

Public Members

Comparison functions


Documentation

This class is both an 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 schannel. Drivers for real, platform dependent sound hardware will be ancestors of this class and can be found in the plugins section of PWLib.

A sound driver is either playing or recording. If simultaneous playing and recording is desired, two instances of PSoundChannel must be created.

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

o Construction

o PSoundChannel()
Create a sound channel

o 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:
- 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

o Open functions

ostatic PStringList GetDriverNames(PPluginManager* pluginMgr = NULL)
Return names of all plugins that correspond to sound devices

ostatic PStringList GetDeviceNames( const PString &driverName, const PSoundChannel::Directions, PPluginManager* pluginMgr = NULL )
Return sound devices that correspond to the specified name

ostatic PSoundChannel* CreateChannel( const PString &driverName, PPluginManager* pluginMgr = NULL )
Return sound channel object that correspond to the specified name

ostatic PSoundChannel* CreateOpenedChannel( const PString & driverName, const PString & deviceName, const PSoundChannel::Directions, unsigned numChannels = 1, unsigned sampleRate = 8000, unsigned bitsPerSample = 16 )
Return opened sound channel object that correspond to the specified name

ostatic PString GetDefaultDevice( Directions dir )
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 arrays returned with the dir parameter in each value is not necessarily the same.

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

ostatic PStringList GetDeviceNames( Directions dir )
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.

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

ovirtual BOOL Open( const PString & device, Directions dir, unsigned numChannels = 1, unsigned sampleRate = 8000, unsigned bitsPerSample = 16 )
Open the specified device for playing or recording. The device name is platform specific and is as returned in the GetDevices() function.

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
Returns:
TRUE if the sound device is valid for playing/recording.

ovirtual BOOL IsOpen() const
Test if this instance of PSoundChannel is open.

Returns:
TRUE if this instance is open.

ovirtual int GetHandle() const
Get the OS specific handle for the PSoundChannel.

Returns:
integer value of the handle.

ovirtual BOOL Abort()
Abort the background playing/recording of the sound channel.

Returns:
TRUE if the sound has successfully been aborted.

o Channel set up functions

ovirtual BOOL SetFormat( unsigned numChannels = 1, unsigned sampleRate = 8000, unsigned bitsPerSample = 16 )
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.

Parameters:
- numChannels Number of channels eg mono/stereo
- sampleRate Samples per second
bitsPerSample - Number of bits per sample
Returns:
TRUE if the format is valid.

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

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

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

ovirtual BOOL SetBuffers( PINDEX size, PINDEX count = 2 )
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.

Parameters:
- size Size of each buffer
- count Number of buffers
Returns:
TRUE if the sound device is valid for playing/recording.

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

Returns:
TRUE if the buffer size were obtained.

ovirtual BOOL SetVolume( unsigned volume )
Set the volume of the play/read process. The volume range is 0 == quiet. 100 == LOUD.

Parameters:
volume - New volume level
Returns:
TRUE if there were no errors.

ovirtual BOOL GetVolume( unsigned & volume )
Get the volume of the play/read process. The volume range is 0 == quiet. 100 == LOUD.

Parameters:
volume - Variable to receive volume level.
Returns:
TRUE if there were no errors.

o Play functions

ovirtual BOOL Write(const void* buf, PINDEX len)
Low level write (or play) 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.

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.

ovirtual BOOL PlaySound( const PSound & sound, BOOL wait = TRUE )
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 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.

Parameters:
sound - Sound to play.
wait - Flag to play sound synchronously.
Returns:
TRUE if the sound is playing or has played.

ovirtual BOOL PlayFile( const PFilePath & file, BOOL wait = TRUE )
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.

Parameters:
file - Sound file to play.
wait - Flag to play sound synchronously.
Returns:
TRUE if the sound is playing or has played.

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

Returns:
TRUE if the sound has completed playing.

ovirtual BOOL WaitForPlayCompletion()
Block the thread until the sound play begun with PlayBuffer() or PlayFile() has completed.

Returns:
TRUE if the sound has successfully completed playing.

o Record functions

ovirtual BOOL Read( void* buf, PINDEX len )
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.

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

Parameters:
buf - Pointer to a block of memory to receive the read bytes.
len - Maximum number of bytes to read into the buffer.
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.

ovirtual BOOL RecordSound( PSound & sound )
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.

Parameters:
sound - Sound recorded
Returns:
TRUE if the sound has been recorded.

ovirtual BOOL RecordFile( const PFilePath & file )
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.

Parameters:
file - Sound file recorded
Returns:
TRUE if the sound has been recorded.

ovirtual BOOL StartRecording()
Start filling record buffers. The first call to Read() will also initiate the recording.

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

ovirtual BOOL IsRecordBufferFull()
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.

ovirtual BOOL AreAllRecordBuffersFull()
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.

ovirtual BOOL WaitForRecordBufferFull()
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.

ovirtual BOOL WaitForAllRecordBuffersFull()
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.


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.