Waveform Similarity Based Overlap-Add (WSOLA)
[Audio Manipulation Algorithms]

Time-scale modification to audio without affecting the pitch. More...

Typedefs
typedef typedefPJ_BEGIN_DECL struct pjmedia_wsola	pjmedia_wsola
Enumerations
enum	pjmedia_wsola_option {   PJMEDIA_WSOLA_NO_HANNING = 1,   PJMEDIA_WSOLA_NO_PLC = 2,   PJMEDIA_WSOLA_NO_DISCARD = 4,   PJMEDIA_WSOLA_NO_FADING = 8 }
Functions
pj_status_t	pjmedia_wsola_create (pj_pool_t *pool, unsigned clock_rate, unsigned samples_per_frame, unsigned channel_count, unsigned options, pjmedia_wsola **p_wsola)
pj_status_t	pjmedia_wsola_set_max_expand (pjmedia_wsola *wsola, unsigned msec)
pj_status_t	pjmedia_wsola_destroy (pjmedia_wsola *wsola)
pj_status_t	pjmedia_wsola_reset (pjmedia_wsola *wsola, unsigned options)
pj_status_t	pjmedia_wsola_save (pjmedia_wsola *wsola, pj_int16_t frm[], pj_bool_t prev_lost)
pj_status_t	pjmedia_wsola_generate (pjmedia_wsola *wsola, pj_int16_t frm[])
pj_status_t	pjmedia_wsola_discard (pjmedia_wsola *wsola, pj_int16_t buf1[], unsigned buf1_cnt, pj_int16_t buf2[], unsigned buf2_cnt, unsigned *erase_cnt)

---

Detailed Description

This section describes Waveform Similarity Based Overlap-Add (WSOLA) implementation in PJMEDIA. The WSOLA API here can be used both to compress (speed-up) and stretch (expand, slow down) audio playback without altering the pitch, or as a mean for performing packet loss concealment (WSOLA).

The WSOLA implementation is used by Adaptive Delay Buffer and Packet Lost Concealment (PLC).

---

Typedef Documentation

typedef typedefPJ_BEGIN_DECL struct pjmedia_wsola pjmedia_wsola

Opaque declaration for WSOLA structure.

---

Enumeration Type Documentation

enum pjmedia_wsola_option

WSOLA options, can be combined with bitmask operation.

Enumerator:

PJMEDIA_WSOLA_NO_HANNING	Disable Hanning window to conserve memory.
PJMEDIA_WSOLA_NO_PLC	Specify that the WSOLA will not be used for PLC.
PJMEDIA_WSOLA_NO_DISCARD	Specify that the WSOLA will not be used to discard frames in non-contiguous buffer.
PJMEDIA_WSOLA_NO_FADING	Disable fade-in and fade-out feature in the transition between actual and synthetic frames in WSOLA. With fade feature enabled, WSOLA will only generate a limited number of synthetic frames (configurable with pjmedia_wsola_set_max_expand()), fading out the volume on every more samples it generates, and when it reaches the limit it will only generate silence.

---

Function Documentation

pj_status_t pjmedia_wsola_create	(	pj_pool_t *	pool,
		unsigned	clock_rate,
		unsigned	samples_per_frame,
		unsigned	channel_count,
		unsigned	options,
		pjmedia_wsola **	p_wsola
	)

Create and initialize WSOLA.

Parameters:

	pool	Pool to allocate memory for WSOLA.
	clock_rate	Sampling rate of audio playback.
	samples_per_frame	Number of samples per frame.
	channel_count	Number of channels.
	options	Option flags, bitmask combination of pjmedia_wsola_option.
	p_wsola	Pointer to receive WSOLA structure.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pjmedia_wsola_set_max_expand	(	pjmedia_wsola *	wsola,
		unsigned	msec
	)

Specify maximum number of continuous synthetic frames that can be generated by WSOLA, in milliseconds. This option will only take effect if fading is not disabled via the option when the WSOLA session was created. Default value is PJMEDIA_WSOLA_MAX_EXPAND_MSEC (see also the documentation of PJMEDIA_WSOLA_MAX_EXPAND_MSEC for more information).

Parameters:

	wsola	The WSOLA session
	msec	The duration.

Returns:

PJ_SUCCESS normally.

pj_status_t pjmedia_wsola_destroy

(

pjmedia_wsola *

wsola

)

Destroy WSOLA.

Parameters:

wsola

WSOLA session.

Returns:

PJ_SUCCESS normally.

pj_status_t pjmedia_wsola_reset	(	pjmedia_wsola *	wsola,
		unsigned	options
	)

Reset the buffer contents of WSOLA.

Parameters:

	wsola	WSOLA session.
	options	Reset options, must be zero for now.

Returns:

PJ_SUCCESS normally.

pj_status_t pjmedia_wsola_save	(	pjmedia_wsola *	wsola,
		pj_int16_t	frm[],
		pj_bool_t	prev_lost
	)

Give one good frame to WSOLA to be kept as reference. Application must continuously give WSOLA good frames to keep its session up to date with current playback. Depending on the WSOLA implementation, this function may modify the content of the frame.

Parameters:

	wsola	WSOLA session.
	frm	The frame, which length must match the samples per frame setting of the WSOLA session.
	prev_lost	If application previously generated a synthetic frame with pjmedia_wsola_generate() before calling this function, specify whether that was because of packet lost. If so, set this parameter to PJ_TRUE to make WSOLA interpolate this frame with its buffer. Otherwise if this value is PJ_FALSE, WSOLA will just append this frame to the end of its buffer.

Returns:

PJ_SUCCESS normally.

pj_status_t pjmedia_wsola_generate	(	pjmedia_wsola *	wsola,
		pj_int16_t	frm[]
	)

Generate one synthetic frame from WSOLA.

Parameters:

	wsola	WSOLA session.
	frm	Buffer to receive the frame.

Returns:

PJ_SUCCESS normally.

pj_status_t pjmedia_wsola_discard	(	pjmedia_wsola *	wsola,
		pj_int16_t	buf1[],
		unsigned	buf1_cnt,
		pj_int16_t	buf2[],
		unsigned	buf2_cnt,
		unsigned *	erase_cnt
	)

Compress or compact the specified buffer by removing some audio samples from the buffer, without altering the pitch. For this function to work, total length of the buffer must be more than twice erase_cnt.

Parameters:

	wsola	WSOLA session.
	buf1	Pointer to buffer.
	buf1_cnt	Number of samples in the buffer.
	buf2	Pointer to second buffer, if the buffer is not contiguous. Otherwise this parameter must be NULL.
	buf2_cnt	Number of samples in the second buffer, if the buffer is not contiguous. Otherwise this parameter should be zero.
	erase_cnt	On input, specify the number of samples to be erased. This function may erase more or less than the requested number, and the actual number of samples erased will be given on this argument upon returning from the function.

Returns:

PJ_SUCCESS if some samples have been erased, PJ_ETOOSMALL if buffer is too small to be reduced, PJ_EINVAL if any of the parameters are not valid.