Documentation and API Reference. More...

Data Structures
struct	pjmedia_aud_driver

struct	pjmedia_aud_subsys

struct	pjmedia_aud_dev_info

struct	pjmedia_aud_param

Macros
#define	PJMEDIA_AUD_DEFAULT_CAPTURE_DEV -1

#define	PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV -2

#define	PJMEDIA_AUD_INVALID_DEV -3

#define	PJMEDIA_AUD_MAX_DRIVERS 16

#define	PJMEDIA_AUD_MAX_DEVS 64

Typedefs
typedef pj_int32_t	pjmedia_aud_dev_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)

typedef pj_status_t(*	pjmedia_aud_rec_cb) (void user_data, pjmedia_frame frame)

Enumerations
enum	pjmedia_aud_dev_cap { PJMEDIA_AUD_DEV_CAP_EXT_FORMAT = 1 , PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY = 2 , PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY = 4 , PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING = 8 , PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING = 16 , PJMEDIA_AUD_DEV_CAP_INPUT_SIGNAL_METER = 32 , PJMEDIA_AUD_DEV_CAP_OUTPUT_SIGNAL_METER = 64 , PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE = 128 , PJMEDIA_AUD_DEV_CAP_INPUT_SOURCE = 128 , PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE = 256 , PJMEDIA_AUD_DEV_CAP_EC = 512 , PJMEDIA_AUD_DEV_CAP_EC_TAIL = 1024 , PJMEDIA_AUD_DEV_CAP_VAD = 2048 , PJMEDIA_AUD_DEV_CAP_CNG = 4096 , PJMEDIA_AUD_DEV_CAP_PLC = 8192 , PJMEDIA_AUD_DEV_CAP_MAX = 16384 }

enum	pjmedia_aud_dev_route { PJMEDIA_AUD_DEV_ROUTE_DEFAULT = 0 , PJMEDIA_AUD_DEV_ROUTE_LOUDSPEAKER = 1 , PJMEDIA_AUD_DEV_ROUTE_EARPIECE = 2 , PJMEDIA_AUD_DEV_ROUTE_BLUETOOTH = 4 , PJMEDIA_AUD_DEV_ROUTE_CUSTOM = 128 }

Functions
pjmedia_aud_subsys *	pjmedia_get_aud_subsys (void)

pj_status_t	pjmedia_aud_driver_init (unsigned drv_idx, pj_bool_t refresh)

void	pjmedia_aud_driver_deinit (unsigned drv_idx)

const char *	pjmedia_aud_dev_cap_name (pjmedia_aud_dev_cap cap, const char **p_desc)

pj_status_t	pjmedia_aud_param_set_cap (pjmedia_aud_param param, pjmedia_aud_dev_cap cap, const void pval)

pj_status_t	pjmedia_aud_param_get_cap (const pjmedia_aud_param param, pjmedia_aud_dev_cap cap, void pval)

pj_status_t	pjmedia_aud_dev_refresh (void)

unsigned	pjmedia_aud_dev_count (void)

pj_status_t	pjmedia_aud_dev_get_info (pjmedia_aud_dev_index id, pjmedia_aud_dev_info *info)

pj_status_t	pjmedia_aud_dev_lookup (const char drv_name, const char dev_name, pjmedia_aud_dev_index *id)

pj_status_t	pjmedia_aud_dev_default_param (pjmedia_aud_dev_index id, pjmedia_aud_param *param)

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)

pj_status_t	pjmedia_aud_stream_get_param (pjmedia_aud_stream strm, pjmedia_aud_param param)

pj_status_t	pjmedia_aud_stream_get_cap (pjmedia_aud_stream strm, pjmedia_aud_dev_cap cap, void value)

pj_status_t	pjmedia_aud_stream_set_cap (pjmedia_aud_stream strm, pjmedia_aud_dev_cap cap, const void value)

pj_status_t	pjmedia_aud_stream_start (pjmedia_aud_stream *strm)

pj_status_t	pjmedia_aud_stream_stop (pjmedia_aud_stream *strm)

pj_status_t	pjmedia_aud_stream_destroy (pjmedia_aud_stream *strm)

Detailed Description

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

Macro Definition Documentation

◆ PJMEDIA_AUD_DEFAULT_CAPTURE_DEV

#define PJMEDIA_AUD_DEFAULT_CAPTURE_DEV -1

Device index constants. Constant to denote default capture device

◆ PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV

#define PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV -2

Constant to denote default playback device

◆ PJMEDIA_AUD_INVALID_DEV

#define PJMEDIA_AUD_INVALID_DEV -3

Constant to denote invalid device index.

Typedef Documentation

◆ pjmedia_aud_dev_index

typedef pj_int32_t pjmedia_aud_dev_index

Type for device index.

◆ pjmedia_aud_play_cb

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.

Parameters

user_data	User data associated with the stream.
frame	Audio frame, which buffer is to be filled in by the application.

Returns: Returning non-PJ_SUCCESS will cause the audio stream to stop

◆ pjmedia_aud_rec_cb

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.

Parameters

user_data	User data associated with the stream.
frame	Captured frame.

Returns: Returning non-PJ_SUCCESS will cause the audio stream to stop

Enumeration Type Documentation

◆ pjmedia_aud_dev_cap

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.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
PJMEDIA_AUD_DEV_CAP_MAX	End of capability

◆ pjmedia_aud_dev_route

enum pjmedia_aud_dev_route

This enumeration describes audio routing/source setting.

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.
PJMEDIA_AUD_DEV_ROUTE_LOUDSPEAKER	Route to loudspeaker
PJMEDIA_AUD_DEV_ROUTE_EARPIECE	Route to earpiece
PJMEDIA_AUD_DEV_ROUTE_BLUETOOTH	Route to paired Bluetooth device
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(&param, PJMEDIA_AUD_DEV_CAP_INPUT_SOURCE, &aud_source);

Function Documentation

◆ pjmedia_get_aud_subsys()

pjmedia_aud_subsys * pjmedia_get_aud_subsys ( void )

Get the audio subsystem.

Returns: The audio subsystem.

◆ pjmedia_aud_driver_init()

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.

◆ pjmedia_aud_driver_deinit()

void pjmedia_aud_driver_deinit ( unsigned drv_idx )

Deinitialize the audio driver.

Parameters

drv_idx The index of the audio driver.

◆ pjmedia_aud_dev_cap_name()

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.

◆ pjmedia_aud_param_set_cap()

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.

◆ pjmedia_aud_param_get_cap()

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.

◆ pjmedia_aud_dev_refresh()

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.

◆ pjmedia_aud_dev_count()

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.

Referenced by pjmedia_snd_get_dev_count().

◆ pjmedia_aud_dev_get_info()

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.

◆ pjmedia_aud_dev_lookup()

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.

◆ pjmedia_aud_dev_default_param()

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.

◆ pjmedia_aud_stream_create()

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.

◆ pjmedia_aud_stream_get_param()

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.

◆ pjmedia_aud_stream_get_cap()

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.

◆ pjmedia_aud_stream_set_cap()

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.

◆ pjmedia_aud_stream_start()

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.

◆ pjmedia_aud_stream_stop()

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.

◆ pjmedia_aud_stream_destroy()

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.

References PJ_END_DECL.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Hardware/Built-in Echo Cancellation

Macro Definition Documentation

◆ PJMEDIA_AUD_DEFAULT_CAPTURE_DEV

◆ PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV

◆ PJMEDIA_AUD_INVALID_DEV

Typedef Documentation

◆ pjmedia_aud_dev_index

◆ pjmedia_aud_play_cb

◆ pjmedia_aud_rec_cb

Enumeration Type Documentation

◆ pjmedia_aud_dev_cap

◆ pjmedia_aud_dev_route

Function Documentation

◆ pjmedia_get_aud_subsys()

◆ pjmedia_aud_driver_init()

◆ pjmedia_aud_driver_deinit()

◆ pjmedia_aud_dev_cap_name()

◆ pjmedia_aud_param_set_cap()

◆ pjmedia_aud_param_get_cap()

◆ pjmedia_aud_dev_refresh()

◆ pjmedia_aud_dev_count()

◆ pjmedia_aud_dev_get_info()

◆ pjmedia_aud_dev_lookup()

◆ pjmedia_aud_dev_default_param()

◆ pjmedia_aud_stream_create()

◆ pjmedia_aud_stream_get_param()

◆ pjmedia_aud_stream_get_cap()

◆ pjmedia_aud_stream_set_cap()

◆ pjmedia_aud_stream_start()

◆ pjmedia_aud_stream_stop()

◆ pjmedia_aud_stream_destroy()