pjsip logo pjsip.org
Open source SIP stack and media stack for presence, im/instant messaging, and multimedia communication

HOME

SIP/media Features
High Performance SIP
Small Footprint SIP
Symbian Port

FAQ

Documentation

Licensing

Download

Development (Trac)

Projects using pjsip

Mailing List

Open Source Links

About: PJLIB, PJLIB-UTIL, PJSIP, and PJMEDIA are created by: Benny Prijono
<bennylp@pjsip.org>

 

Home --> Documentations --> PJMEDIA Reference

Sound Device Port
[Clock/Timing]

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


Table of Contents

 Portable Sound Hardware Abstraction
 PJMEDIA abstraction for sound device hardware.

Typedefs

typedef struct pjmedia_snd_port pjmedia_snd_port

Functions

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_destroy (pjmedia_snd_port *snd_port)
pjmedia_snd_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_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)

Typedef Documentation

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.

Function Documentation

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, currently must be zero.
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, currently must be zero.
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, currently must be zero.
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_snd_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 
)

Configure the echo cancellation tail length. By default, echo canceller is enabled in the sound device with the default tail length. After the sound port is created, application can query the current echo canceller tail length by calling pjmedia_snd_port_get_ec_tail.

Note that you should only change the EC settings when the sound port is not connected to any downstream ports, otherwise race condition may occur.

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

 

PJMEDIA small footprint Open Source media stack
(C)2003-2008 Benny Prijono