1
/* $Id: wsola.h 3553 2011-05-05 06:14:19Z nanang $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#ifndef __PJMEDIA_WSOLA_H__
21
#define __PJMEDIA_WSOLA_H__
25
* @brief Waveform Similarity Based Overlap-Add (WSOLA)
27
#include <pjmedia/types.h>
30
* @defgroup PJMED_WSOLA Waveform Similarity Based Overlap-Add (WSOLA)
31
* @ingroup PJMEDIA_FRAME_OP
32
* @brief Time-scale modification to audio without affecting the pitch
35
* This section describes Waveform Similarity Based Overlap-Add (WSOLA)
36
* implementation in PJMEDIA. The WSOLA API here can be used both to
37
* compress (speed-up) and stretch (expand, slow down) audio playback
38
* without altering the pitch, or as a mean for performing packet loss
39
* concealment (WSOLA).
41
* The WSOLA implementation is used by \ref PJMED_DELAYBUF and \ref PJMED_PLC.
48
* Opaque declaration for WSOLA structure.
50
typedef struct pjmedia_wsola pjmedia_wsola;
54
* WSOLA options, can be combined with bitmask operation.
56
enum pjmedia_wsola_option
59
* Disable Hanning window to conserve memory.
61
PJMEDIA_WSOLA_NO_HANNING = 1,
64
* Specify that the WSOLA will not be used for PLC.
66
PJMEDIA_WSOLA_NO_PLC = 2,
69
* Specify that the WSOLA will not be used to discard frames in
70
* non-contiguous buffer.
72
PJMEDIA_WSOLA_NO_DISCARD = 4,
75
* Disable fade-in and fade-out feature in the transition between
76
* actual and synthetic frames in WSOLA. With fade feature enabled,
77
* WSOLA will only generate a limited number of synthetic frames
78
* (configurable with #pjmedia_wsola_set_max_expand()), fading out
79
* the volume on every more samples it generates, and when it reaches
80
* the limit it will only generate silence.
82
PJMEDIA_WSOLA_NO_FADING = 8
88
* Create and initialize WSOLA.
90
* @param pool Pool to allocate memory for WSOLA.
91
* @param clock_rate Sampling rate of audio playback.
92
* @param samples_per_frame Number of samples per frame.
93
* @param channel_count Number of channels.
94
* @param options Option flags, bitmask combination of
95
* #pjmedia_wsola_option.
96
* @param p_wsola Pointer to receive WSOLA structure.
98
* @return PJ_SUCCESS or the appropriate error code.
100
PJ_DECL(pj_status_t) pjmedia_wsola_create(pj_pool_t *pool,
102
unsigned samples_per_frame,
103
unsigned channel_count,
105
pjmedia_wsola **p_wsola);
109
* Specify maximum number of continuous synthetic frames that can be
110
* generated by WSOLA, in milliseconds. This option will only take
111
* effect if fading is not disabled via the option when the WSOLA
112
* session was created. Default value is PJMEDIA_WSOLA_MAX_EXPAND_MSEC
113
* (see also the documentation of PJMEDIA_WSOLA_MAX_EXPAND_MSEC for
116
* @param wsola The WSOLA session
117
* @param msec The duration.
119
* @return PJ_SUCCESS normally.
121
PJ_DECL(pj_status_t) pjmedia_wsola_set_max_expand(pjmedia_wsola *wsola,
128
* @param wsola WSOLA session.
130
* @return PJ_SUCCESS normally.
132
PJ_DECL(pj_status_t) pjmedia_wsola_destroy(pjmedia_wsola *wsola);
136
* Reset the buffer contents of WSOLA.
138
* @param wsola WSOLA session.
139
* @param options Reset options, must be zero for now.
141
* @return PJ_SUCCESS normally.
143
PJ_DECL(pj_status_t) pjmedia_wsola_reset(pjmedia_wsola *wsola,
148
* Give one good frame to WSOLA to be kept as reference. Application
149
* must continuously give WSOLA good frames to keep its session up to
150
* date with current playback. Depending on the WSOLA implementation,
151
* this function may modify the content of the frame.
153
* @param wsola WSOLA session.
154
* @param frm The frame, which length must match the samples per
155
* frame setting of the WSOLA session.
156
* @param prev_lost If application previously generated a synthetic
157
* frame with #pjmedia_wsola_generate() before calling
158
* this function, specify whether that was because of
159
* packet lost. If so, set this parameter to PJ_TRUE
160
* to make WSOLA interpolate this frame with its buffer.
161
* Otherwise if this value is PJ_FALSE, WSOLA will
162
* just append this frame to the end of its buffer.
164
* @return PJ_SUCCESS normally.
166
PJ_DECL(pj_status_t) pjmedia_wsola_save(pjmedia_wsola *wsola,
168
pj_bool_t prev_lost);
171
* Generate one synthetic frame from WSOLA.
173
* @param wsola WSOLA session.
174
* @param frm Buffer to receive the frame.
176
* @return PJ_SUCCESS normally.
178
PJ_DECL(pj_status_t) pjmedia_wsola_generate(pjmedia_wsola *wsola,
183
* Compress or compact the specified buffer by removing some audio samples
184
* from the buffer, without altering the pitch. For this function to work,
185
* total length of the buffer must be more than twice \a erase_cnt.
187
* @param wsola WSOLA session.
188
* @param buf1 Pointer to buffer.
189
* @param buf1_cnt Number of samples in the buffer.
190
* @param buf2 Pointer to second buffer, if the buffer is not
191
* contiguous. Otherwise this parameter must be NULL.
192
* @param buf2_cnt Number of samples in the second buffer, if the buffer
193
* is not contiguous. Otherwise this parameter should be
195
* @param erase_cnt On input, specify the number of samples to be erased.
196
* This function may erase more or less than the requested
197
* number, and the actual number of samples erased will be
198
* given on this argument upon returning from the function.
200
* @return PJ_SUCCESS if some samples have been erased, PJ_ETOOSMALL
201
* if buffer is too small to be reduced, PJ_EINVAL if any
202
* of the parameters are not valid.
204
PJ_DECL(pj_status_t) pjmedia_wsola_discard(pjmedia_wsola *wsola,
209
unsigned *erase_cnt);
218
#endif /* __PJMEDIA_WSOLA_H__ */