Media Port Connection Abstraction to the Sound Device. More...

Modules
	Portable Sound Hardware Abstraction
	PJMEDIA abstraction for sound device hardware.

Data Structures
struct	pjmedia_snd_port_param

Typedefs
typedef struct pjmedia_snd_port	pjmedia_snd_port

Enumerations
enum	pjmedia_snd_port_option { PJMEDIA_SND_PORT_NO_AUTO_START = 1 }

Functions
void	pjmedia_snd_port_param_default (pjmedia_snd_port_param *prm)

pj_status_t	pjmedia_snd_port_create (pj_pool_t pool, int rec_id, int play_id, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned bits_per_sample, unsigned options, pjmedia_snd_port *p_port)

pj_status_t	pjmedia_snd_port_create_rec (pj_pool_t pool, int index, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned bits_per_sample, unsigned options, pjmedia_snd_port *p_port)

pj_status_t	pjmedia_snd_port_create_player (pj_pool_t pool, int index, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned bits_per_sample, unsigned options, pjmedia_snd_port *p_port)

pj_status_t	pjmedia_snd_port_create2 (pj_pool_t pool, const pjmedia_snd_port_param prm, pjmedia_snd_port **p_port)

pj_status_t	pjmedia_snd_port_destroy (pjmedia_snd_port *snd_port)

pjmedia_aud_stream *	pjmedia_snd_port_get_snd_stream (pjmedia_snd_port *snd_port)

pj_status_t	pjmedia_snd_port_set_ec (pjmedia_snd_port snd_port, pj_pool_t pool, unsigned tail_ms, unsigned options)

pj_status_t	pjmedia_snd_port_get_ec_tail (pjmedia_snd_port snd_port, unsigned p_length)

pj_status_t	pjmedia_snd_port_get_ec_stat (pjmedia_snd_port snd_port, pjmedia_echo_stat p_stat)

pjmedia_clock_src *	pjmedia_snd_port_get_clock_src (pjmedia_snd_port *snd_port, pjmedia_dir dir)

pj_status_t	pjmedia_snd_port_connect (pjmedia_snd_port snd_port, pjmedia_port port)

pjmedia_port *	pjmedia_snd_port_get_port (pjmedia_snd_port *snd_port)

pj_status_t	pjmedia_snd_port_disconnect (pjmedia_snd_port *snd_port)

Detailed Description

As explained in Portable Sound Hardware Abstraction, the sound hardware abstraction provides some callbacks for its user:

it calls rec_cb callback when it has finished capturing one media frame, and
it calls play_cb when it needs media frame to be played to the sound playback hardware.

The Sound Device Port (the object being explained here) add a thin wrapper to the hardware abstraction:

it will call downstream port's put_frame() when rec_cb() is called (i.e. when the sound hardware has finished capturing frame), and
it will call downstream port's get_frame() when play_cb() is called (i.e. every time the sound hardware needs more frames to be played to the playback hardware).

This simple abstraction enables media to flow automatically (and in timely manner) from the downstream media port to the sound device. In other words, the sound device port supplies media clock to the ports. The media clock concept is explained in Clock/Timing section.

Application registers downstream port to the sound device port by calling pjmedia_snd_port_connect();

Typedef Documentation

◆ pjmedia_snd_port

typedef struct pjmedia_snd_port pjmedia_snd_port

This opaque type describes sound device port connection. Sound device port is not a media port, but it is used to connect media port to the sound device.

Enumeration Type Documentation

◆ pjmedia_snd_port_option

enum pjmedia_snd_port_option

Sound port options.

Enumerator
PJMEDIA_SND_PORT_NO_AUTO_START	Don't start the audio device when creating a sound port.

Function Documentation

◆ pjmedia_snd_port_param_default()

void pjmedia_snd_port_param_default ( pjmedia_snd_port_param * prm )

Initialize pjmedia_snd_port_param with default values.

Parameters

prm	The parameter.

◆ pjmedia_snd_port_create()

pj_status_t pjmedia_snd_port_create	(	pj_pool_t *	pool,
		int	rec_id,
		int	play_id,
		unsigned	clock_rate,
		unsigned	channel_count,
		unsigned	samples_per_frame,
		unsigned	bits_per_sample,
		unsigned	options,
		pjmedia_snd_port **	p_port
	)

Create bidirectional sound port for both capturing and playback of audio samples.

Parameters

pool	Pool to allocate sound port structure.
rec_id	Device index for recorder/capture stream, or -1 to use the first capable device.
play_id	Device index for playback stream, or -1 to use the first capable device.
clock_rate	Sound device's clock rate to set.
channel_count	Set number of channels, 1 for mono, or 2 for stereo. The channel count determines the format of the frame.
samples_per_frame	Number of samples per frame.
bits_per_sample	Set the number of bits per sample. The normal value for this parameter is 16 bits per sample.
options	Options flag.
p_port	Pointer to receive the sound device port instance.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_create_rec()

pj_status_t pjmedia_snd_port_create_rec	(	pj_pool_t *	pool,
		int	index,
		unsigned	clock_rate,
		unsigned	channel_count,
		unsigned	samples_per_frame,
		unsigned	bits_per_sample,
		unsigned	options,
		pjmedia_snd_port **	p_port
	)

Create unidirectional sound device port for capturing audio streams from the sound device with the specified parameters.

Parameters

pool	Pool to allocate sound port structure.
index	Device index, or -1 to let the library choose the first available device.
clock_rate	Sound device's clock rate to set.
channel_count	Set number of channels, 1 for mono, or 2 for stereo. The channel count determines the format of the frame.
samples_per_frame	Number of samples per frame.
bits_per_sample	Set the number of bits per sample. The normal value for this parameter is 16 bits per sample.
options	Options flag.
p_port	Pointer to receive the sound device port instance.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_create_player()

pj_status_t pjmedia_snd_port_create_player	(	pj_pool_t *	pool,
		int	index,
		unsigned	clock_rate,
		unsigned	channel_count,
		unsigned	samples_per_frame,
		unsigned	bits_per_sample,
		unsigned	options,
		pjmedia_snd_port **	p_port
	)

Create unidirectional sound device port for playing audio streams with the specified parameters.

Parameters

pool	Pool to allocate sound port structure.
index	Device index, or -1 to let the library choose the first available device.
clock_rate	Sound device's clock rate to set.
channel_count	Set number of channels, 1 for mono, or 2 for stereo. The channel count determines the format of the frame.
samples_per_frame	Number of samples per frame.
bits_per_sample	Set the number of bits per sample. The normal value for this parameter is 16 bits per sample.
options	Options flag.
p_port	Pointer to receive the sound device port instance.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_create2()

pj_status_t pjmedia_snd_port_create2	(	pj_pool_t *	pool,
		const pjmedia_snd_port_param *	prm,
		pjmedia_snd_port **	p_port
	)

Create sound device port according to the specified parameters.

Parameters

pool	Pool to allocate sound port structure.
prm	Sound port parameter.
p_port	Pointer to receive the sound device port instance.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_destroy()

pj_status_t pjmedia_snd_port_destroy ( pjmedia_snd_port * snd_port )

Destroy sound device port.

Parameters

snd_port The sound device port.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_get_snd_stream()

pjmedia_aud_stream * pjmedia_snd_port_get_snd_stream ( pjmedia_snd_port * snd_port )

Retrieve the sound stream associated by this sound device port.

Parameters

snd_port The sound device port.

Returns: The sound stream instance.

◆ pjmedia_snd_port_set_ec()

pj_status_t pjmedia_snd_port_set_ec	(	pjmedia_snd_port *	snd_port,
		pj_pool_t *	pool,
		unsigned	tail_ms,
		unsigned	options
	)

Change the echo cancellation settings. The echo cancellation settings should have been specified when this sound port was created, by setting the appropriate fields in the pjmedia_aud_param, because not all sound device implementation supports changing the EC setting once the device has been opened.

The behavior of this function depends on whether device or software AEC is being used. If the device supports AEC, this function will forward the change request to the device and it will be up to the device whether to support the request. If software AEC is being used (the software EC will be used if the device does not support AEC), this function will change the software EC settings.

Parameters

snd_port	The sound device port.
pool	Pool to re-create the echo canceller if necessary.
tail_ms	Maximum echo tail length to be supported, in miliseconds. If zero is specified, the EC would be disabled.
options	The options to be passed to pjmedia_echo_create(). This is only used if software EC is being used.

Returns: PJ_SUCCESS on success.

◆ pjmedia_snd_port_get_ec_tail()

pj_status_t pjmedia_snd_port_get_ec_tail	(	pjmedia_snd_port *	snd_port,
		unsigned *	p_length
	)

Get current echo canceller tail length, in miliseconds. The tail length will be zero if EC is not enabled.

Parameters

snd_port	The sound device port.
p_length	Pointer to receive the tail length.

Returns: PJ_SUCCESS on success.

◆ pjmedia_snd_port_get_ec_stat()

pj_status_t pjmedia_snd_port_get_ec_stat	(	pjmedia_snd_port *	snd_port,
		pjmedia_echo_stat *	p_stat
	)

Get echo canceller statistics.

Parameters

snd_port	The sound device port.
p_stat	Pointer to receive the stat.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_get_clock_src()

pjmedia_clock_src * pjmedia_snd_port_get_clock_src	(	pjmedia_snd_port *	snd_port,
		pjmedia_dir	dir
	)

Get a clock source from the sound port.

Parameters

snd_port	The sound port.
dir	Sound port's direction.

Returns: The clock source.

◆ pjmedia_snd_port_connect()

pj_status_t pjmedia_snd_port_connect	(	pjmedia_snd_port *	snd_port,
		pjmedia_port *	port
	)

Connect a port to the sound device port. If the sound device port has a sound recorder device, then this will start periodic function call to the port's put_frame() function. If the sound device has a sound player device, then this will start periodic function call to the port's get_frame() function.

For this version of PJMEDIA, the media port MUST have the same audio settings as the sound device port, or otherwise the connection will fail. This means the port MUST have the same clock_rate, channel count, samples per frame, and bits per sample as the sound device port.

Parameters

snd_port	The sound device port.
port	The media port to be connected.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjmedia_snd_port_get_port()

pjmedia_port * pjmedia_snd_port_get_port ( pjmedia_snd_port * snd_port )

Retrieve the port instance currently attached to the sound port, if any.

Parameters

snd_port The sound device port.

Returns: The port instance currently attached to the sound device port, or NULL if there is no port currently attached to the sound device port.

◆ pjmedia_snd_port_disconnect()

pj_status_t pjmedia_snd_port_disconnect ( pjmedia_snd_port * snd_port )

Disconnect currently attached port from the sound device port.

Parameters

snd_port The sound device port.

Returns: PJ_SUCCESS on success.

Modules

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ pjmedia_snd_port

Enumeration Type Documentation

◆ pjmedia_snd_port_option

Function Documentation

◆ pjmedia_snd_port_param_default()

◆ pjmedia_snd_port_create()

◆ pjmedia_snd_port_create_rec()

◆ pjmedia_snd_port_create_player()

◆ pjmedia_snd_port_create2()

◆ pjmedia_snd_port_destroy()

◆ pjmedia_snd_port_get_snd_stream()

◆ pjmedia_snd_port_set_ec()

◆ pjmedia_snd_port_get_ec_tail()

◆ pjmedia_snd_port_get_ec_stat()

◆ pjmedia_snd_port_get_clock_src()

◆ pjmedia_snd_port_connect()

◆ pjmedia_snd_port_get_port()

◆ pjmedia_snd_port_disconnect()