Loading...
Searching...
No Matches
Audio play and record
Public API functions » Port initialisation » Card information » Port control » Event handling
Collaboration diagram for Audio play and record:

## Topics

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

enum 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

  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.

## 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

  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().

## 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

  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().

## 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

  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().

## 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

  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().

## 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

  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.

## 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

  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.

## 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

  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(), Audio::linear_gain, Play::list, and Audio::sw_gain.

## 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

  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.

## vpb_play_state()

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.

## 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

  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, Audio::mutex, Audio::state, VPB_AUDIO_PLAYING, and VPB_AUDIO_TERMINATE.

Referenced by vpb_reset().

## 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

  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 Audio::mutex.

## 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

  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.

## 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

  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.

## 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

  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.

## 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

  handle | The handle to the port to complete recording on.

Exceptions

  various | exceptions 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

  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().

## 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

  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.

## 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

  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.

## 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

  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.

## 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

  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(), Audio::linear_gain, Record::list, and Audio::sw_gain.

## 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

  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.

## vpb_record_state()

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.

## 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

  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, Audio::mutex, Audio::state, VPB_AUDIO_RECORDING, and VPB_AUDIO_TERMINATE.

Referenced by vpb_reset().

## 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

  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 Audio::mutex.

## 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

  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.

## 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

  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.