libvpb  4.2.61
Collaboration diagram for Audio play and record:

Modules

 Error handling
 

Classes

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

Macros

#define VPB_FINISH   1
 return code for vpb_play_buf_sync() and vpb_record_buf_sync().
 

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

Buffer playback

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

Playback termination

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

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. More...
 
void WINAPI vpb_play_set_gain (VPBPortHandle handle, float gain)
 Set the software play gain component for a port. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Buffer recording

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

Recording termination

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

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. More...
 
void WINAPI vpb_record_set_gain (VPBPortHandle handle, float gain)
 Set the software record gain component for a port. More...
 
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. More...
 
float WINAPI vpb_record_get_hw_gain (VPBPortHandle handle)
 Return the hardware record gain for a port.
 
#define VPB_RECORD_DIGIT   1
 Set recording parameters for a port.
 
#define VPB_RECORD_TIMEOUT   2
 Set recording parameters for a port.
 
#define VPB_RECORD_ENDOFDATA   3
 Set recording parameters for a port.
 
#define VPB_RECORD_MAXDIGIT   4
 Set recording parameters for a port.
 

Detailed Description

Todo:
Add appropriate bits of the sgml documentation here.

Enumeration Type Documentation

◆ AudioCompress

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.

◆ AudioState

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

◆ vpb_play_buf_async()

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
handleThe handle to the port to play audio on.
bufThe buffer of samples to play. It must be encoded according to the mode that was specified the preceding call to vpb_play_buf_start().
lenThe 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
variousexceptions 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.

◆ vpb_play_buf_finish()

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.

The output may be padded up to the transfer frame size of the hardware transmitting it (20 - 40ms), so if you require precise timing of any subsequent samples to be played, you should not release the buffer until you really have finished with it and are prepared to relinquish it to another user for output.

Parameters
handleThe handle to the port to complete playback on.
Exceptions
variousexceptions 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.

◆ vpb_play_buf_finish_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
handleThe handle to the port to complete playback on.
Exceptions
variousexceptions 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.

◆ vpb_play_buf_start()

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
handleThe handle to the port to play audio on.
modeThe compression mode the audio samples will use.
Exceptions
variousexceptions 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().

◆ vpb_play_buf_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
handleThe handle to the port to play audio on.
bufThe buffer of samples to play. It must be encoded according to the mode that was specified the preceding call to vpb_play_buf_start().
lenThe 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
variousexceptions 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.

◆ vpb_play_file_async()

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
handleThe handle of the port to play to.
file_nameThe path to the file to play.
dataUser defined data to include with the VPB_PLAYEND event.
Returns
VPB_OK if playback was started ok.
Exceptions
variousexceptions may be thrown if the file cannot be played.

◆ vpb_play_file_sync()

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
handleThe handle of the port to play to.
file_nameThe path to the file to play.
Returns
VPB_OK if playback completed ok.
Exceptions
variousexceptions may be thrown if the file cannot be played.

◆ vpb_play_set_gain()

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
handleThe handle to the port to adjust.
gainThe software gain in dB.
Exceptions
VpbExceptionmay be thrown if handle or gain is invalid.

◆ vpb_play_set_hw_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
handleThe handle to the port to adjust.
gainThe hardware gain value. -12.0 < gain < 12.0
Exceptions
VpbExceptionwill be thrown in the event of an error.

◆ vpb_play_state()

AudioState WINAPI vpb_play_state ( int  handle)

Return the current play state of a port.

Parameters
handleThe 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.

◆ vpb_play_terminate()

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
handleThe handle to the port to cease playback on.
Returns
VPB_OK if all went well.
Exceptions
variousexceptions 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.

◆ vpb_play_terminate_sync()

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
handleThe handle to the port to cease playback on.
Returns
VPB_OK if all went well.
Exceptions
variousexceptions 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.

◆ vpb_play_voxfile_async()

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
handleThe handle of the port to play to.
file_nameThe path to the file to play.
Returns
VPB_OK if playback completed ok.
Exceptions
variousexceptions may be thrown if the file cannot be played.

◆ vpb_play_voxfile_sync()

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
handleThe handle of the port to play to.
file_nameThe path to the file to play.
Returns
VPB_OK if playback completed ok.
Exceptions
variousexceptions may be thrown if the file cannot be played.

◆ vpb_record_buf_async()

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
handleThe handle to the port to record audio from.
bufA pointer to storage for the recorded samples.
lenThe 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
variousexceptions 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.

◆ vpb_record_buf_finish()

void WINAPI vpb_record_buf_finish ( VPBPortHandle  handle)

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

Parameters
handleThe handle to the port to complete recording on.
Exceptions
variousexceptions may be thrown in the event of an error.

◆ vpb_record_buf_start()

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
handleThe handle to the port to record audio from.
modeThe audio compression mode to use.
Exceptions
variousexceptions 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().

◆ vpb_record_buf_sync()

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
handleThe handle to the port to record audio from.
bufA pointer to storage for the recorded samples.
lenThe 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
variousexceptions 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.

◆ vpb_record_file_async()

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
handleThe handle of the port to record from.
file_nameThe path to the file to save wav data in.
modeThe file compression mode to use.
Returns
VPB_OK if recording was started ok.
Exceptions
variousexceptions may be thrown if the file cannot be recorded.

◆ vpb_record_file_sync()

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
handleThe handle of the port to record from.
file_nameThe path to the file to save wav data in.
Returns
VPB_OK if recording completed ok.
Exceptions
variousexceptions may be thrown if the file cannot be recorded.

◆ vpb_record_set_gain()

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
handleThe handle to the port to adjust.
gainThe software gain in dB.
Exceptions
VpbExceptionmay be thrown if handle or gain is invalid.

◆ vpb_record_set_hw_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
handleThe handle to the port to adjust.
gainThe hardware gain value. -12.0 < gain < 12.0
Exceptions
VpbExceptionwill be thrown in the event of an error.

◆ vpb_record_state()

AudioState WINAPI vpb_record_state ( int  handle)

Return the current record state of a port.

Parameters
handleThe 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.

◆ vpb_record_terminate()

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
handleThe handle to the port to cease recording on.
Returns
VPB_OK if all went well.
Exceptions
variousexceptions 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.

◆ vpb_record_terminate_sync()

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
handleThe handle to the port to cease recording on.
Returns
VPB_OK if all went well.
Exceptions
variousexceptions 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.

◆ vpb_record_voxfile_async()

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
handleThe handle of the port to record from.
file_nameThe path to the file to save wav data in.
Returns
VPB_OK if recording completed ok.
Exceptions
variousexceptions may be thrown if the file cannot be recorded.

◆ vpb_record_voxfile_sync()

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
handleThe handle of the port to record from.
file_nameThe path to the file to save wav data in.
Returns
VPB_OK if recording completed ok.
Exceptions
variousexceptions may be thrown if the file cannot be recorded.