Group PJMED_SND_PORT

group PJMED_SND_PORT

Media Port Connection Abstraction to the Sound Device.

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

  • it calls callback when it has finished capturing one media frame, and

  • it calls 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 is called (i.e. when the sound hardware has finished capturing frame), and

  • it will call downstream port’s get_frame() when 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();

Typedefs

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.

Enums

enum pjmedia_snd_port_option

Sound port options.

Values:

enumerator PJMEDIA_SND_PORT_NO_AUTO_START

Don’t start the audio device when creating a sound port.

Functions

void pjmedia_snd_port_param_default(pjmedia_snd_port_param *prm)

Initialize pjmedia_snd_port_param with default values.

Parameters

prm – The parameter.

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.

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.

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.

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.

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

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.

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.

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

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.

struct pjmedia_snd_port_param
#include <sound_port.h>

This structure specifies the parameters to create the sound port. Use pjmedia_snd_port_param_default() to initialize this structure with default values (mostly zeroes)