libvpb
4.2.61
|
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. | |
enum AudioCompress |
enum AudioState |
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.
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. |
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.various | exceptions may be thrown in the event of an error. |
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.
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.
handle | The handle to the port to complete playback on. |
various | exceptions may be thrown in the event of an error. |
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.
handle | The handle to the port to complete playback on. |
various | exceptions may be thrown in the event of an error. |
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()
.
handle | The handle to the port to play audio on. |
mode | The compression mode the audio samples will use. |
various | exceptions may be thrown in the event of an error. |
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()
. 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.
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. |
VPB_FINISH
if the port has been signalled to terminate audio playback. VPB_OK
if buf was successfully output.various | exceptions may be thrown in the event of an error. |
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. 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.
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. |
VPB_OK
if playback was started ok. various | exceptions may be thrown if the file cannot be played. |
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.
handle | The handle of the port to play to. |
file_name | The path to the file to play. |
VPB_OK
if playback completed ok. various | exceptions may be thrown if the file cannot be played. |
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.
handle | The handle to the port to adjust. |
gain | The software gain in dB . |
VpbException | may be thrown if handle or gain is invalid. |
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.
handle | The handle to the port to adjust. |
gain | The hardware gain value. -12.0 < gain < 12.0 |
VpbException | will be thrown in the event of an error. |
AudioState WINAPI vpb_play_state | ( | int | handle | ) |
Return the current play state of a port.
handle | The handle to the port to check. |
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.
handle | The handle to the port to cease playback on. |
VPB_OK
if all went well.various | exceptions may be thrown if things do not go well. |
vpb_play_terminate_sync()
if you require the audio to have definitely ceased playing before proceeding with other operations. 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.
handle | The handle to the port to cease playback on. |
VPB_OK
if all went well.various | exceptions may be thrown if things do not go well. |
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. 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.
handle | The handle of the port to play to. |
file_name | The path to the file to play. |
VPB_OK
if playback completed ok. 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.
handle | The handle of the port to play to. |
file_name | The path to the file to play. |
VPB_OK
if playback completed ok. 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.
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. |
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.various | exceptions may be thrown in the event of an error. |
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.
handle | The handle to the port to complete recording on. |
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()
.
handle | The handle to the port to record audio from. |
mode | The audio compression mode to use. |
various | exceptions may be thrown in the event of an error. |
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()
. 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.
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. |
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.various | exceptions may be thrown in the event of an error. |
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.
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. |
VPB_OK
if recording was started ok. 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.
handle | The handle of the port to record from. |
file_name | The path to the file to save wav data in. |
VPB_OK
if recording completed ok. 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.
handle | The handle to the port to adjust. |
gain | The software gain in dB . |
VpbException | may be thrown if handle or gain is invalid. |
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.
handle | The handle to the port to adjust. |
gain | The hardware gain value. -12.0 < gain < 12.0 |
VpbException | will be thrown in the event of an error. |
AudioState WINAPI vpb_record_state | ( | int | handle | ) |
Return the current record state of a port.
handle | The handle to the port to check. |
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.
handle | The handle to the port to cease recording on. |
VPB_OK
if all went well.various | exceptions may be thrown if things do not go well. |
vpb_record_terminate_sync()
if you require the audio to have definitely ceased recording before proceeding with other operations. 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.
handle | The handle to the port to cease recording on. |
VPB_OK
if all went well.various | exceptions may be thrown if things do not go well. |
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. 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.
handle | The handle of the port to record from. |
file_name | The path to the file to save wav data in. |
VPB_OK
if recording completed ok. 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.
handle | The handle of the port to record from. |
file_name | The path to the file to save wav data in. |
VPB_OK
if recording completed ok. various | exceptions may be thrown if the file cannot be recorded. |