BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

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_streampjmedia_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)
 
pjmedia_clock_srcpjmedia_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_portpjmedia_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

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

Sound port options.

Enumerator
PJMEDIA_SND_PORT_NO_AUTO_START 

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

Function Documentation

void pjmedia_snd_port_param_default ( pjmedia_snd_port_param prm)

Initialize pjmedia_snd_port_param with default values.

Parameters
prmThe 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
poolPool to allocate sound port structure.
rec_idDevice index for recorder/capture stream, or -1 to use the first capable device.
play_idDevice index for playback stream, or -1 to use the first capable device.
clock_rateSound device's clock rate to set.
channel_countSet number of channels, 1 for mono, or 2 for stereo. The channel count determines the format of the frame.
samples_per_frameNumber of samples per frame.
bits_per_sampleSet the number of bits per sample. The normal value for this parameter is 16 bits per sample.
optionsOptions flag.
p_portPointer 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
poolPool to allocate sound port structure.
indexDevice index, or -1 to let the library choose the first available device.
clock_rateSound device's clock rate to set.
channel_countSet number of channels, 1 for mono, or 2 for stereo. The channel count determines the format of the frame.
samples_per_frameNumber of samples per frame.
bits_per_sampleSet the number of bits per sample. The normal value for this parameter is 16 bits per sample.
optionsOptions flag.
p_portPointer 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
poolPool to allocate sound port structure.
indexDevice index, or -1 to let the library choose the first available device.
clock_rateSound device's clock rate to set.
channel_countSet number of channels, 1 for mono, or 2 for stereo. The channel count determines the format of the frame.
samples_per_frameNumber of samples per frame.
bits_per_sampleSet the number of bits per sample. The normal value for this parameter is 16 bits per sample.
optionsOptions flag.
p_portPointer 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
poolPool to allocate sound port structure.
prmSound port parameter.
p_portPointer 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_portThe 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_portThe 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_portThe sound device port.
poolPool to re-create the echo canceller if necessary.
tail_msMaximum echo tail length to be supported, in miliseconds. If zero is specified, the EC would be disabled.
optionsThe 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_portThe sound device port.
p_lengthPointer to receive the tail length.
Returns
PJ_SUCCESS on success.
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_portThe sound port.
dirSound port's direction.
Returns
The clock source.
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_portThe sound device port.
portThe 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_portThe 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_portThe sound device port.
Returns
PJ_SUCCESS on success.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.