Group PJMEDIA_AUDIODEV_API
- group PJMEDIA_AUDIODEV_API
Documentation and API Reference.
Hardware/Built-in Echo Cancellation
On some platforms, audio device comes with built-in echo cancellation feature. This is usually done based on specific hardware configuration, such as the use of multiple microphones and/or a known fixed distance between the capture and playback device, in order to precalculate the echo time distance. Because of this, when using the hardware EC, users may not get the freedom to select their own audio devices. This is applicable for Mac (users must use default audio devices) and iOS (users must use the same built-in audio device).
In PJMEDIA, applications wishing to use sofware echo instead can pass PJMEDIA_ECHO_USE_SW_ECHO when calling pjmedia_snd_port_create2().
Defines
-
PJMEDIA_AUD_DEFAULT_CAPTURE_DEV
Device index constants. Constant to denote default capture device
-
PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV
Constant to denote default playback device
-
PJMEDIA_AUD_INVALID_DEV
Constant to denote invalid device index.
-
PJMEDIA_AUD_MAX_DRIVERS
-
PJMEDIA_AUD_MAX_DEVS
Typedefs
-
typedef pj_int32_t pjmedia_aud_dev_index
Type for device index.
-
typedef pjmedia_aud_dev_factory *(*pjmedia_aud_dev_factory_create_func_ptr)(pj_pool_factory*)
-
typedef pj_status_t (*pjmedia_aud_play_cb)(void *user_data, pjmedia_frame *frame)
This callback is called by player stream when it needs additional data to be played by the device. Application must fill in the whole of output buffer with audio samples.
The frame argument contains the following values:
timestamp Playback timestamp, in samples.
buf Buffer to be filled out by application.
size The size requested in bytes, which will be equal to the size of one whole packet.
- Param user_data
User data associated with the stream.
- Param frame
Audio frame, which buffer is to be filled in by the application.
- Return
Returning non-PJ_SUCCESS will cause the audio stream to stop
-
typedef pj_status_t (*pjmedia_aud_rec_cb)(void *user_data, pjmedia_frame *frame)
This callback is called by recorder stream when it has captured the whole packet worth of audio samples.
- Param user_data
User data associated with the stream.
- Param frame
Captured frame.
- Return
Returning non-PJ_SUCCESS will cause the audio stream to stop
Enums
-
enum pjmedia_aud_dev_cap
This enumeration identifies various audio device capabilities. These audio capabilities indicates what features are supported by the underlying audio device implementation.
Applications get these capabilities in the pjmedia_aud_dev_info structure.
Application can also set the specific features/capabilities when opening the audio stream by setting the flags member of pjmedia_aud_param structure.
Once audio stream is running, application can also retrieve or set some specific audio capability, by using pjmedia_aud_stream_get_cap() and pjmedia_aud_stream_set_cap() and specifying the desired capability. The value of the capability is specified as pointer, and application needs to supply the pointer with the correct value, according to the documentation of each of the capability.
Values:
-
enumerator PJMEDIA_AUD_DEV_CAP_EXT_FORMAT
Support for audio formats other than PCM. The value of this capability is represented by pjmedia_format structure.
-
enumerator PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY
Support for audio input latency control or query. The value of this capability is an unsigned integer containing milliseconds value of the latency.
-
enumerator PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY
Support for audio output latency control or query. The value of this capability is an unsigned integer containing milliseconds value of the latency.
-
enumerator PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING
Support for setting/retrieving the audio input device volume level. The value of this capability is an unsigned integer representing the input audio volume setting in percent.
-
enumerator PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING
Support for setting/retrieving the audio output device volume level. The value of this capability is an unsigned integer representing the output audio volume setting in percent.
-
enumerator PJMEDIA_AUD_DEV_CAP_INPUT_SIGNAL_METER
Support for monitoring the current audio input signal volume. The value of this capability is an unsigned integer representing the audio volume in percent.
-
enumerator PJMEDIA_AUD_DEV_CAP_OUTPUT_SIGNAL_METER
Support for monitoring the current audio output signal volume. The value of this capability is an unsigned integer representing the audio volume in percent.
-
enumerator PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE
Support for audio input routing/source. The value of this capability is an integer containing pjmedia_aud_dev_route enumeration.
-
enumerator PJMEDIA_AUD_DEV_CAP_INPUT_SOURCE
-
enumerator PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE
Support for audio output routing (e.g. loudspeaker vs earpiece). The value of this capability is an integer containing pjmedia_aud_dev_route enumeration.
-
enumerator PJMEDIA_AUD_DEV_CAP_EC
The audio device has echo cancellation feature. The value of this capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
-
enumerator PJMEDIA_AUD_DEV_CAP_EC_TAIL
The audio device supports setting echo cancellation fail length. The value of this capability is an unsigned integer representing the echo tail in milliseconds.
-
enumerator PJMEDIA_AUD_DEV_CAP_VAD
The audio device has voice activity detection feature. The value of this capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
-
enumerator PJMEDIA_AUD_DEV_CAP_CNG
The audio device has comfort noise generation feature. The value of this capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
-
enumerator PJMEDIA_AUD_DEV_CAP_PLC
The audio device has packet loss concealment feature. The value of this capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
-
enumerator PJMEDIA_AUD_DEV_CAP_MAX
End of capability
-
enumerator PJMEDIA_AUD_DEV_CAP_EXT_FORMAT
-
enum pjmedia_aud_dev_route
This enumeration describes audio routing/source setting.
Values:
-
enumerator PJMEDIA_AUD_DEV_ROUTE_DEFAULT
Default route/source, it is the default audio route/source of the audio framework backend, as in opening audio device without specifying any route/source setting or with specifying neutral route/source setting.
-
enumerator PJMEDIA_AUD_DEV_ROUTE_LOUDSPEAKER
Route to loudspeaker
-
enumerator PJMEDIA_AUD_DEV_ROUTE_EARPIECE
Route to earpiece
-
enumerator PJMEDIA_AUD_DEV_ROUTE_BLUETOOTH
Route to paired Bluetooth device
-
enumerator PJMEDIA_AUD_DEV_ROUTE_CUSTOM
Custom audio route/source, specific to each audio device backend.
For Android JNI audio device, the default is VOICE_COMMUNICATION (7). To change it to another value, set the input source capability of pjmedia_aud_param accordingly. For example: // 6 is VOICE_RECOGNITION unsigned aud_source = PJMEDIA_AUD_DEV_ROUTE_CUSTOM | 6; pjmedia_aud_param_set_cap(¶m, PJMEDIA_AUD_DEV_CAP_INPUT_SOURCE, &aud_source);
-
enumerator PJMEDIA_AUD_DEV_ROUTE_DEFAULT
Functions
-
pjmedia_aud_subsys *pjmedia_get_aud_subsys(void)
Get the audio subsystem.
- Returns
The audio subsystem.
-
pj_status_t pjmedia_aud_driver_init(unsigned drv_idx, pj_bool_t refresh)
Initialize the audio driver.
- Parameters
drv_idx – The index of the audio driver.
refresh – Specify non-zero to refresh the audio driver.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
void pjmedia_aud_driver_deinit(unsigned drv_idx)
Deinitialize the audio driver.
- Parameters
drv_idx – The index of the audio driver.
-
const char *pjmedia_aud_dev_cap_name(pjmedia_aud_dev_cap cap, const char **p_desc)
Get string info for the specified capability.
- Parameters
cap – The capability ID.
p_desc – Optional pointer which will be filled with longer description about the capability.
- Returns
Capability name.
-
pj_status_t pjmedia_aud_param_set_cap(pjmedia_aud_param *param, pjmedia_aud_dev_cap cap, const void *pval)
Set a capability field value in pjmedia_aud_param structure. This will also set the flags field for the specified capability in the structure.
- Parameters
param – The structure.
cap – The audio capability which value is to be set.
pval – Pointer to value. Please see the type of value to be supplied in the pjmedia_aud_dev_cap documentation.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_param_get_cap(const pjmedia_aud_param *param, pjmedia_aud_dev_cap cap, void *pval)
Get a capability field value from pjmedia_aud_param structure. This function will return PJMEDIA_EAUD_INVCAP error if the flag for that capability is not set in the flags field in the structure.
- Parameters
param – The structure.
cap – The audio capability which value is to be retrieved.
pval – Pointer to value. Please see the type of value to be supplied in the pjmedia_aud_dev_cap documentation.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_dev_refresh(void)
Refresh the list of sound devices installed in the system. This function will only refresh the list of audio device so all active audio streams will be unaffected. After refreshing the device list, application MUST make sure to update all index references to audio devices (i.e. all variables of type pjmedia_aud_dev_index) before calling any function that accepts audio device index as its parameter.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
unsigned pjmedia_aud_dev_count(void)
Get the number of sound devices installed in the system.
- Returns
The number of sound devices installed in the system.
-
pj_status_t pjmedia_aud_dev_get_info(pjmedia_aud_dev_index id, pjmedia_aud_dev_info *info)
Get device information.
- Parameters
id – The audio device ID.
info – The device information which will be filled in by this function once it returns successfully.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_dev_lookup(const char *drv_name, const char *dev_name, pjmedia_aud_dev_index *id)
Lookup device index based on the driver and device name.
- Parameters
drv_name – The driver name.
dev_name – The device name.
id – Pointer to store the returned device ID.
- Returns
PJ_SUCCESS if the device can be found.
-
pj_status_t pjmedia_aud_dev_default_param(pjmedia_aud_dev_index id, pjmedia_aud_param *param)
Initialize the audio device parameters with default values for the specified device.
- Parameters
id – The audio device ID.
param – The audio device parameters which will be initialized by this function once it returns successfully.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_create(const pjmedia_aud_param *param, pjmedia_aud_rec_cb rec_cb, pjmedia_aud_play_cb play_cb, void *user_data, pjmedia_aud_stream **p_strm)
Open audio stream object using the specified parameters.
- Parameters
param – Sound device parameters to be used for the stream.
rec_cb – Callback to be called on every input frame captured.
play_cb – Callback to be called everytime the sound device needs audio frames to be played back.
user_data – Arbitrary user data, which will be given back in the callbacks.
p_strm – Pointer to receive the audio stream.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_get_param(pjmedia_aud_stream *strm, pjmedia_aud_param *param)
Get the running parameters for the specified audio stream.
- Parameters
strm – The audio stream.
param – Audio stream parameters to be filled in by this function once it returns successfully.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_get_cap(pjmedia_aud_stream *strm, pjmedia_aud_dev_cap cap, void *value)
Get the value of a specific capability of the audio stream.
- Parameters
strm – The audio stream.
cap – The audio capability which value is to be retrieved.
value – Pointer to value to be filled in by this function once it returns successfully. Please see the type of value to be supplied in the pjmedia_aud_dev_cap documentation.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_set_cap(pjmedia_aud_stream *strm, pjmedia_aud_dev_cap cap, const void *value)
Set the value of a specific capability of the audio stream.
- Parameters
strm – The audio stream.
cap – The audio capability which value is to be set.
value – Pointer to value. Please see the type of value to be supplied in the pjmedia_aud_dev_cap documentation.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_start(pjmedia_aud_stream *strm)
Start the stream.
- Parameters
strm – The audio stream.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_stop(pjmedia_aud_stream *strm)
Stop the stream.
- Parameters
strm – The audio stream.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
pj_status_t pjmedia_aud_stream_destroy(pjmedia_aud_stream *strm)
Destroy the stream.
- Parameters
strm – The audio stream.
- Returns
PJ_SUCCESS on successful operation or the appropriate error code.
-
struct pjmedia_aud_driver
-
struct pjmedia_aud_subsys
-
struct pjmedia_aud_dev_info
- #include <audiodev.h>
Device information structure returned by pjmedia_aud_dev_get_info().
Public Members
-
pjmedia_aud_dev_index id
The device ID
-
char name[PJMEDIA_AUD_DEV_INFO_NAME_LEN]
The device name
-
unsigned input_count
Maximum number of input channels supported by this device. If the value is zero, the device does not support input operation (i.e. it is a playback only device).
-
unsigned output_count
Maximum number of output channels supported by this device. If the value is zero, the device does not support output operation (i.e. it is an input only device).
-
unsigned default_samples_per_sec
Default sampling rate.
-
char driver[32]
The underlying driver name
-
unsigned caps
Device capabilities, as bitmask combination of pjmedia_aud_dev_cap.
-
unsigned routes
Supported audio device routes/sources, as bitmask combination of pjmedia_aud_dev_route. The value may be zero if the device does not support changing audio routes/sources.
-
unsigned ext_fmt_cnt
Number of audio formats supported by this device. The value may be zero if the device does not support non-PCM format.
-
pjmedia_format ext_fmt[8]
Array of supported extended audio formats
-
pjmedia_aud_dev_index id
-
struct pjmedia_aud_param
- #include <audiodev.h>
This structure specifies the parameters to open the audio stream.
Public Members
-
pjmedia_dir dir
The audio direction. This setting is mandatory.
-
pjmedia_aud_dev_index rec_id
The audio recorder device ID. This setting is mandatory if the audio direction includes input/capture direction.
-
pjmedia_aud_dev_index play_id
The audio playback device ID. This setting is mandatory if the audio direction includes output/playback direction.
-
unsigned clock_rate
Clock rate/sampling rate. This setting is mandatory.
-
unsigned channel_count
Number of channels. This setting is mandatory.
-
unsigned samples_per_frame
Number of samples per frame. This setting is mandatory.
-
unsigned bits_per_sample
Number of bits per sample. This setting is mandatory.
-
unsigned flags
This flags specifies which of the optional settings are valid in this structure. The flags is bitmask combination of pjmedia_aud_dev_cap.
-
pjmedia_format ext_fmt
Set the audio format. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_EXT_FORMAT is set in the flags.
-
unsigned input_latency_ms
Input latency, in milliseconds. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY is set in the flags.
-
unsigned output_latency_ms
Input latency, in milliseconds. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY is set in the flags.
-
unsigned input_vol
Input volume setting, in percent. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING is set in the flags.
-
unsigned output_vol
Output volume setting, in percent. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING is set in the flags.
-
pjmedia_aud_dev_route input_route
Set the audio input route/source. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE/ PJMEDIA_AUD_DEV_CAP_INPUT_SOURCE is set in the flags.
-
pjmedia_aud_dev_route output_route
Set the audio output route. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE is set in the flags.
-
pj_bool_t ec_enabled
Enable/disable echo canceller, if the device supports it. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_EC is set in the flags.
-
unsigned ec_tail_ms
Set echo canceller tail length in milliseconds, if the device supports it. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_EC_TAIL is set in the flags.
-
pj_bool_t plc_enabled
Enable/disable PLC. This setting is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_PLC is set in the flags.
-
pjmedia_dir dir
-
PJMEDIA_AUD_DEFAULT_CAPTURE_DEV