Audio play and record
[Public API functions]

Collaboration diagram for Audio play and record:

Classes

struct  VPB_PLAY
 Port playback parameters. More...
struct  VPB_RECORD
 Port recording parameters. More...

Defines

#define VPB_FINISH   1
 return code for vpb_play_buf_sync() and vpb_record_buf_sync().
#define VPB_RECORD_DIGIT   1
#define VPB_RECORD_TIMEOUT   2
#define VPB_RECORD_ENDOFDATA   3
#define VPB_RECORD_MAXDIGIT   4

Enumerations

enum  AudioCompress {
  VPB_LINEAR, VPB_ALAW, VPB_MULAW, VPB_OKIADPCM,
  VPB_OKIADPCM24, VPB_RAW
}
 Audio compression modes. More...
enum  AudioState {
  VPB_AUDIO_IDLE, VPB_AUDIO_PLAYING, VPB_AUDIO_RECORDING, VPB_AUDIO_TERMINATE,
  VPB_AUDIO_TERMINATE_SYNC
}
 play/record state flags More...

File playback

int WINAPI vpb_play_file_sync (VPBPortHandle handle, const std::string &file_name)
 Utility function to play a wav file to a port.
int WINAPI vpb_play_file_async (VPBPortHandle handle, const std::string &file_name, int data)
 Utility function to play a wav file to a port.
int WINAPI vpb_play_voxfile_sync (int handle, const std::string &file_name, AudioCompress mode)
 Utility function to play a wav file to a port.
int WINAPI vpb_play_voxfile_async (int handle, const std::string &file_name, AudioCompress mode, int data)
 Utility function to play a wav file to a port.

Buffer playback

void WINAPI vpb_play_buf_start (VPBPortHandle handle, AudioCompress mode)
 Prepare and seize a port for playing audio from a buffer.
int WINAPI vpb_play_buf_sync (VPBPortHandle handle, const char *buf, size_t len)
 Play a buffer of audio samples to a port.
int WINAPI vpb_play_buf_async (VPBPortHandle handle, const char *buf, size_t len)
 Play a buffer of audio samples to a port.
void WINAPI vpb_play_buf_finish (VPBPortHandle handle)
 Signal completion of audio playback and release a port for other users.
void WINAPI vpb_play_buf_finish_sync (VPBPortHandle handle)
 Signal completion of audio playback and release a port for other users.

Playback termination

int WINAPI vpb_play_terminate (int handle)
 Stop audio playback.
int WINAPI vpb_play_terminate_sync (int handle)
 Stop audio playback.

Playback configuration

void WINAPI vpb_play_set (VPBPortHandle handle, const VPB_PLAY &vpb_play)
 Set playback parameters for a port.
void WINAPI vpb_play_set (VPBPortHandle handle, const VPB_PLAY *vpb_play)
 Set playback parameters for a port.
AudioState WINAPI vpb_play_state (int handle)
 Return the current play state of a port.
void WINAPI vpb_play_set_gain (VPBPortHandle handle, float gain)
 Set the software play gain component for a port.
float WINAPI vpb_play_get_gain (VPBPortHandle handle)
 Return the software play gain for a port.
void WINAPI vpb_play_get_gain (VPBPortHandle handle, float *gain)
 Set playback parameters for a port.
void WINAPI vpb_play_set_hw_gain (VPBPortHandle handle, float gain)
 Set the hardware play gain component for a port.
float WINAPI vpb_play_get_hw_gain (VPBPortHandle handle)
 Return the hardware play gain for a port.

File recording

int WINAPI vpb_record_file_sync (VPBPortHandle handle, const std::string &file_name, AudioCompress mode)
 Utility function to record a wav file from a port.
int WINAPI vpb_record_file_async (VPBPortHandle handle, const std::string &file_name, AudioCompress mode)
 Utility function to record a wav file from a port.
int WINAPI vpb_record_voxfile_sync (int handle, const std::string &file_name, AudioCompress mode)
 Utility function to record a wav file from a port.
int WINAPI vpb_record_voxfile_async (int handle, const std::string &file_name, AudioCompress mode)
 Utility function to record a wav file from a port.

Buffer recording

void WINAPI vpb_record_buf_start (VPBPortHandle handle, AudioCompress mode)
 Prepare and seize a port for recording audio from a buffer.
int WINAPI vpb_record_buf_sync (VPBPortHandle handle, char *buf, size_t len)
 Record a buffer of audio samples from a port.
int WINAPI vpb_record_buf_async (VPBPortHandle handle, char *buf, size_t len)
 Record a buffer of audio samples from a port.
void WINAPI vpb_record_buf_finish (VPBPortHandle handle)
 Signal completion of audio recording and release a port for other users.

Recording termination

int WINAPI vpb_record_terminate (int handle)
 Stop audio recording.
int WINAPI vpb_record_terminate_sync (int handle)
 Stop audio recording.

Recording configuration

void WINAPI vpb_record_set (VPBPortHandle handle, const VPB_RECORD &vpb_record)
 Set recording parameters for a port.
void WINAPI vpb_record_set (VPBPortHandle handle, const VPB_RECORD *vpb_record)
 Set recording parameters for a port.
AudioState WINAPI vpb_record_state (int handle)
 Return the current record state of a port.
void WINAPI vpb_record_set_gain (VPBPortHandle handle, float gain)
 Set the software record gain component for a port.
float WINAPI vpb_record_get_gain (VPBPortHandle handle)
 Return the software record gain for a port.
void WINAPI vpb_record_get_gain (VPBPortHandle handle, float *gain)
 Set recording parameters for a port.
void WINAPI vpb_record_set_hw_gain (VPBPortHandle handle, float gain)
 Set the hardware record gain component for a port.
float WINAPI vpb_record_get_hw_gain (VPBPortHandle handle)
 Return the hardware record gain for a port.

Detailed Description

Todo:
Add appropriate bits of the sgml documentation here.

Enumeration Type Documentation

Audio compression modes.

Enumerator:
VPB_LINEAR  128 kbit/s 16 bit linear
VPB_ALAW  64 kbit/s A-law companded
VPB_MULAW  64 kbit/s mu-law companded
VPB_OKIADPCM  32 kbit/s OKI ADPCM
VPB_OKIADPCM24  24 kbit/s OKI ADPCM
VPB_RAW  Raw data, no encoding.

enum AudioState

play/record state flags

Enumerator:
VPB_AUDIO_IDLE  No port audio playing.
VPB_AUDIO_PLAYING  Port audio play in progress.
VPB_AUDIO_RECORDING  Port audio record in progress.
VPB_AUDIO_TERMINATE  Async terminate requested.
VPB_AUDIO_TERMINATE_SYNC  Sync terminate requested.


Function Documentation

int WINAPI vpb_play_buf_async ( VPBPortHandle  handle,
const char *  buf,
size_t  len 
)

Play a buffer of audio samples to a port.

This function will always return immediately.

Parameters:
handle The handle to the port to play audio on.
buf The buffer of samples to play. It must be encoded according to the mode that was specified the preceding call to vpb_play_buf_start().
len The number of bytes in buf.
Returns:
VPB_FINISH if the port has been signalled to terminate audio playback, VPB_OK if buf was successfully output, or -EAGAIN if there was insufficient space in the internal buffers for len bytes to be sent immediately.
Exceptions:
various exceptions may be thrown in the event of an error.
Note:
You must call vpb_play_buf_start() before making calls to this function and you must call vpb_play_buf_finish() after the last buffer full of data has been sent. This function may be called any number of times between those two calls.

void WINAPI vpb_play_buf_finish ( VPBPortHandle  handle  ) 

Signal completion of audio playback and release a port for other users.

This function will return immediately, enabling a subsequent or pending call to vpb_play_buf_start() to begin. The audio samples that were buffered prior to calling it may not yet have completed playing when it returns, but new samples will be able to be added to the buffers without further delay.

Parameters:
handle The handle to the port to complete playback on.
Exceptions:
various exceptions may be thrown in the event of an error.
See also:
vpb_play_buf_finish_sync() if following actions will expect the audio already buffered has played to completion.

Referenced by vpb_send_cid_t2_sync().

void WINAPI vpb_play_buf_finish_sync ( VPBPortHandle  handle  ) 

Signal completion of audio playback and release a port for other users.

This function will block until any audio remaining in the internal buffers has been played.

Parameters:
handle The handle to the port to complete playback on.
Exceptions:
various exceptions may be thrown in the event of an error.
See also:
vpb_play_buf_finish() if you do not need to wait for the audio to complete, only to signal that no further samples are to be transmitted.

Referenced by vpb_ring_with_cid(), and vpb_send_cid_t2_sync().

void WINAPI vpb_play_buf_start ( VPBPortHandle  handle,
AudioCompress  mode 
)

Prepare and seize a port for playing audio from a buffer.

If audio from a file is playing when this function is called it will be signalled to terminate. This function will block until it does so, or until a previous call to vpb_play_buf_start has called vpb_play_buf_finish().

Parameters:
handle The handle to the port to play audio on.
mode The compression mode the audio samples will use.
Exceptions:
various exceptions may be thrown in the event of an error.
Note:
You must call vpb_play_buf_finish() for handle when you have finished sending audio data to the port. Between these calls you must not call any vpb_play_* function except vpb_play_buf_sync() or vpb_play_buf_async().

References CheckHandle().

Referenced by vpb_ring_with_cid(), and vpb_send_cid_t2_sync().

int WINAPI vpb_play_buf_sync ( VPBPortHandle  handle,
const char *  buf,
size_t  len 
)

Play a buffer of audio samples to a port.

This function will block until all of the samples in buf have been sent to the hardware driver. For time critical applications that may perform some immediate action at the end of playback, it should be noted that playback will not have fully completed until those internal buffers have also been processed. The size of the internal buffers is hardware dependent.

Parameters:
handle The handle to the port to play audio on.
buf The buffer of samples to play. It must be encoded according to the mode that was specified the preceding call to vpb_play_buf_start().
len The number of bytes in buf.
Returns:
VPB_FINISH if the port has been signalled to terminate audio playback. VPB_OK if buf was successfully output.
Exceptions:
various exceptions may be thrown in the event of an error.
Note:
You must call vpb_play_buf_start() before making calls to this function and you must call vpb_play_buf_finish() after the last buffer full of data has been sent. This function may be called any number of times between those two calls.

Referenced by vpb_ring_with_cid(), and vpb_send_cid_t2_sync().

int WINAPI vpb_play_file_async ( VPBPortHandle  handle,
const std::string &  file_name,
int  data 
)

Utility function to play a wav file to a port.

This function returns as soon as playing has started. It will post a VPB_PLAYEND event on the API event queue when playback has completed.

Parameters:
handle The handle of the port to play to.
file_name The path to the file to play.
data User defined data to include with the VPB_PLAYEND event.
Returns:
VPB_OK if playback was started ok.
Exceptions:
various exceptions may be thrown if the file cannot be played.

References VPB_LINEAR.

int WINAPI vpb_play_file_sync ( VPBPortHandle  handle,
const std::string &  file_name 
)

Utility function to play a wav file to a port.

This function will not return until playback has completed.

Parameters:
handle The handle of the port to play to.
file_name The path to the file to play.
Returns:
VPB_OK if playback completed ok.
Exceptions:
various exceptions may be thrown if the file cannot be played.

References VPB_LINEAR.

void WINAPI vpb_play_set_gain ( VPBPortHandle  handle,
float  gain 
)

Set the software play gain component for a port.

This gain will be applied to digital audio data that is sent from the host PC for output to a hardware port. The vpb_play_file* and vpb_play_buf* functions scale their data according to this level.

Parameters:
handle The handle to the port to adjust.
gain The software gain in dB.
Exceptions:
VpbException may be thrown if handle or gain is invalid.

References CheckHandle(), linear_gain, Play::list, and sw_gain.

void WINAPI vpb_play_set_hw_gain ( VPBPortHandle  handle,
float  gain 
)

Set the hardware play gain component for a port.

This should be set to match the line reqirements of the device that is connected to the port. It should not be used as a general purpose volume control. In most cases, the defalt hardware gains should not need to be adjusted.

Parameters:
handle The handle to the port to adjust.
gain The hardware gain value. -12.0 < gain < 12.0
Exceptions:
VpbException will be thrown in the event of an error.

References CheckHandle(), and vpb_c.

AudioState WINAPI vpb_play_state ( int  handle  ) 

Return the current play state of a port.

Parameters:
handle The handle to the port to check.
Note:
The real state of the port may already have changed again by the time this function has returned. Any subsequent code should not depend upon this value being correct and must be well behaved whatever the real state of the port may be.

References Play::list.

int WINAPI vpb_play_terminate ( int  handle  ) 

Stop audio playback.

This function does nothing if no audio is currently playing. Otherwise it will flag the playback to stop as soon as possible and return immediately.

Parameters:
handle The handle to the port to cease playback on.
Returns:
VPB_OK if all went well.
Exceptions:
various exceptions may be thrown if things do not go well.
See also:
vpb_play_terminate_sync() if you require the audio to have definitely ceased playing before proceeding with other operations.

References Play::list, mutex, state, VPB_AUDIO_PLAYING, and VPB_AUDIO_TERMINATE.

Referenced by vpb_reset().

int WINAPI vpb_play_terminate_sync ( int  handle  ) 

Stop audio playback.

This function does nothing if no audio is currently playing. Otherwise it will flag the playback to stop and block until it actually ceases before returning.

Parameters:
handle The handle to the port to cease playback on.
Returns:
VPB_OK if all went well.
Exceptions:
various exceptions may be thrown if things do not go well.
See also:
vpb_play_terminate() if you do not need to wait for the audio to actually cease playing, but only need to signal it to do so.

References Play::list, and mutex.

int WINAPI vpb_play_voxfile_async ( int  handle,
const std::string &  file_name,
AudioCompress  mode,
int  data 
)

Utility function to play a wav file to a port.

This function will not return until playback has completed.

Parameters:
handle The handle of the port to play to.
file_name The path to the file to play.
Returns:
VPB_OK if playback completed ok.
Exceptions:
various exceptions may be thrown if the file cannot be played.

int WINAPI vpb_play_voxfile_sync ( int  handle,
const std::string &  file_name,
AudioCompress  mode 
)

Utility function to play a wav file to a port.

This function will not return until playback has completed.

Parameters:
handle The handle of the port to play to.
file_name The path to the file to play.
Returns:
VPB_OK if playback completed ok.
Exceptions:
various exceptions may be thrown if the file cannot be played.

int WINAPI vpb_record_buf_async ( VPBPortHandle  handle,
char *  buf,
size_t  len 
)

Record a buffer of audio samples from a port.

This function will always return immediately.

Parameters:
handle The handle to the port to record audio from.
buf A pointer to storage for the recorded samples.
len The number of bytes to store in buf.
Returns:
VPB_FINISH if the port has been signalled to terminate audio recording, or if the VPB_RECORD time out has elapsed. VPB_OK if buf was successfully filled. -EAGAIN if there was insufficient data in the internal buffers for len bytes to be read immediately.
Exceptions:
various exceptions may be thrown in the event of an error.
Note:
You must call vpb_record_buf_start() before making calls to this function and you must call vpb_record_buf_finish() after the last buffer full of data has been read. This function may be called any number of times between those two calls.

void WINAPI vpb_record_buf_finish ( VPBPortHandle  handle  ) 

Signal completion of audio recording and release a port for other users.

Parameters:
handle The handle to the port to complete recording on.
Exceptions:
various exceptions may be thrown in the event of an error.

void WINAPI vpb_record_buf_start ( VPBPortHandle  handle,
AudioCompress  mode 
)

Prepare and seize a port for recording audio from a buffer.

If audio from a file is recording when this function is called it will be signalled to terminate. This function will block until it does so, or until a previous call to vpb_record_buf_start has called vpb_record_buf_finish().

Parameters:
handle The handle to the port to record audio from.
mode The audio compression mode to use.
Exceptions:
various exceptions may be thrown in the event of an error.
Note:
You must call vpb_record_buf_finish() for handle when you have finished recording audio data from the port. Between these calls you must not call any vpb_record_* function except vpb_record_buf_sync() or vpb_record_buf_async().

References CheckHandle().

int WINAPI vpb_record_buf_sync ( VPBPortHandle  handle,
char *  buf,
size_t  len 
)

Record a buffer of audio samples from a port.

This function will block until buf has been filled by the hardware driver.

Parameters:
handle The handle to the port to record audio from.
buf A pointer to storage for the recorded samples.
len The number of bytes to store in buf.
Returns:
VPB_FINISH if the port has been signalled to terminate audio recording, or if the VPB_RECORD time out has elapsed. VPB_OK if buf was successfully filled.
Exceptions:
various exceptions may be thrown in the event of an error.
Note:
You must call vpb_record_buf_start() before making calls to this function and you must call vpb_record_buf_finish() after the last buffer full of data has been read. This function may be called any number of times between those two calls.

int WINAPI vpb_record_file_async ( VPBPortHandle  handle,
const std::string &  file_name,
AudioCompress  mode 
)

Utility function to record a wav file from a port.

This function returns as soon as recording has started. It will post a VPB_RECORDEND event on the API event queue when recording has completed.

Parameters:
handle The handle of the port to record from.
file_name The path to the file to save wav data in.
mode The file compression mode to use.
Returns:
VPB_OK if recording was started ok.
Exceptions:
various exceptions may be thrown if the file cannot be recorded.

int WINAPI vpb_record_file_sync ( VPBPortHandle  handle,
const std::string &  file_name,
AudioCompress  mode 
)

Utility function to record a wav file from a port.

This function will not return until recording has completed.

Parameters:
handle The handle of the port to record from.
file_name The path to the file to save wav data in.
Returns:
VPB_OK if recording completed ok.
Exceptions:
various exceptions may be thrown if the file cannot be recorded.

void WINAPI vpb_record_set_gain ( VPBPortHandle  handle,
float  gain 
)

Set the software record gain component for a port.

This gain will be applied to digital audio data that is received by the host PC from a hardware port. The vpb_record_file* and vpb_record_buf* functions scale their data according to this level.

Parameters:
handle The handle to the port to adjust.
gain The software gain in dB.
Exceptions:
VpbException may be thrown if handle or gain is invalid.

References CheckHandle(), linear_gain, Record::list, and sw_gain.

void WINAPI vpb_record_set_hw_gain ( VPBPortHandle  handle,
float  gain 
)

Set the hardware record gain component for a port.

This should be set to match the line conditions presented by the device connected to the port. It should not be used as a general purpose volume control. In most cases, the defalt hardware gains should not need to be adjusted.

Parameters:
handle The handle to the port to adjust.
gain The hardware gain value. -12.0 < gain < 12.0
Exceptions:
VpbException will be thrown in the event of an error.

References CheckHandle(), and vpb_c.

AudioState WINAPI vpb_record_state ( int  handle  ) 

Return the current record state of a port.

Parameters:
handle The handle to the port to check.
Note:
The real state of the port may already have changed again by the time this function has returned. Any subsequent code should not depend upon this value being correct and must be well behaved whatever the real state of the port may be.

References Record::list.

int WINAPI vpb_record_terminate ( int  handle  ) 

Stop audio recording.

This function does nothing if no audio is currently being recorded. Otherwise it will flag the recording to stop as soon as possible and return immediately.

Parameters:
handle The handle to the port to cease recording on.
Returns:
VPB_OK if all went well.
Exceptions:
various exceptions may be thrown if things do not go well.
See also:
vpb_record_terminate_sync() if you require the audio to have definitely ceased recording before proceeding with other operations.

References Record::list, mutex, state, VPB_AUDIO_RECORDING, and VPB_AUDIO_TERMINATE.

Referenced by vpb_reset().

int WINAPI vpb_record_terminate_sync ( int  handle  ) 

Stop audio recording.

This function does nothing if no audio is currently being recorded. Otherwise it will flag the recording to stop and block until it actually ceases before returning.

Parameters:
handle The handle to the port to cease recording on.
Returns:
VPB_OK if all went well.
Exceptions:
various exceptions may be thrown if things do not go well.
See also:
vpb_record_terminate() if you do not need to wait for the audio to actually cease recording, but only need to signal it to do so.

References Record::list, and mutex.

int WINAPI vpb_record_voxfile_async ( int  handle,
const std::string &  file_name,
AudioCompress  mode 
)

Utility function to record a wav file from a port.

This function will not return until recording has completed.

Parameters:
handle The handle of the port to record from.
file_name The path to the file to save wav data in.
Returns:
VPB_OK if recording completed ok.
Exceptions:
various exceptions may be thrown if the file cannot be recorded.

int WINAPI vpb_record_voxfile_sync ( int  handle,
const std::string &  file_name,
AudioCompress  mode 
)

Utility function to record a wav file from a port.

This function will not return until recording has completed.

Parameters:
handle The handle of the port to record from.
file_name The path to the file to save wav data in.
Returns:
VPB_OK if recording completed ok.
Exceptions:
various exceptions may be thrown if the file cannot be recorded.


Generated on Wed Jul 29 00:52:39 2009 for libvpb by  doxygen 1.5.9