class PSoundChannel: public PChannel

A class representing a sound channel.

Inheritance:


Public

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


Inherited from PChannel:

Public Methods

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

Public

Overrides from class PObject

Information functions

Reading functions

Writing functions

Miscellaneous functions

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

Run Time Type functions

Comparison functions

I/O 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.

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

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.

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

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.

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

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

Returns:
TRUE if the buffer size were obtained.

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.

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

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.

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

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.

Returns:
TRUE if the sound has been recorded.
Parameters:
sound - Sound 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.

Returns:
TRUE if the sound has been recorded.
Parameters:
file - Sound file 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++.