class PSoundChannel

A class representing a sound channel.

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

A class representing a sound channel. This class is provided mainly for the playback or recording of sounds on the system.

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 PStringArray GetDeviceNames( Directions dir )
Get all of the names for sound devices/drivers that are available 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:
An array of platform dependent strings for each sound player/recorder.

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.

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

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

Returns:
TRUE if the sound has successfully been aborted.

o Channel set up functions

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

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

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

ounsigned GetSampleSize() const
Get the sample size in bits per sample

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

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

Returns:
TRUE if the buffer size were obtained.

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

oBOOL 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

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

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

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

Returns:
TRUE if the sound has completed playing.

oBOOL 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

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

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

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

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

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

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

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