diff options
Diffstat (limited to 'lib/rbcodec/codecs/libopus/opus_defines.h')
-rw-r--r-- | lib/rbcodec/codecs/libopus/opus_defines.h | 644 |
1 files changed, 644 insertions, 0 deletions
diff --git a/lib/rbcodec/codecs/libopus/opus_defines.h b/lib/rbcodec/codecs/libopus/opus_defines.h new file mode 100644 index 0000000000..830d225f14 --- /dev/null +++ b/lib/rbcodec/codecs/libopus/opus_defines.h | |||
@@ -0,0 +1,644 @@ | |||
1 | /* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited | ||
2 | Written by Jean-Marc Valin and Koen Vos */ | ||
3 | /* | ||
4 | Redistribution and use in source and binary forms, with or without | ||
5 | modification, are permitted provided that the following conditions | ||
6 | are met: | ||
7 | |||
8 | - Redistributions of source code must retain the above copyright | ||
9 | notice, this list of conditions and the following disclaimer. | ||
10 | |||
11 | - Redistributions in binary form must reproduce the above copyright | ||
12 | notice, this list of conditions and the following disclaimer in the | ||
13 | documentation and/or other materials provided with the distribution. | ||
14 | |||
15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
16 | ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
17 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
18 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER | ||
19 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | ||
20 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | ||
21 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | ||
22 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | ||
23 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | ||
24 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
25 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
26 | */ | ||
27 | |||
28 | /** | ||
29 | * @file opus_defines.h | ||
30 | * @brief Opus reference implementation constants | ||
31 | */ | ||
32 | |||
33 | #ifndef OPUS_DEFINES_H | ||
34 | #define OPUS_DEFINES_H | ||
35 | |||
36 | #include "opus_types.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #endif | ||
41 | |||
42 | /** @defgroup opus_errorcodes Error codes | ||
43 | * @{ | ||
44 | */ | ||
45 | /** No error @hideinitializer*/ | ||
46 | #define OPUS_OK 0 | ||
47 | /** One or more invalid/out of range arguments @hideinitializer*/ | ||
48 | #define OPUS_BAD_ARG -1 | ||
49 | /** The mode struct passed is invalid @hideinitializer*/ | ||
50 | #define OPUS_BUFFER_TOO_SMALL -2 | ||
51 | /** An internal error was detected @hideinitializer*/ | ||
52 | #define OPUS_INTERNAL_ERROR -3 | ||
53 | /** The compressed data passed is corrupted @hideinitializer*/ | ||
54 | #define OPUS_INVALID_PACKET -4 | ||
55 | /** Invalid/unsupported request number @hideinitializer*/ | ||
56 | #define OPUS_UNIMPLEMENTED -5 | ||
57 | /** An encoder or decoder structure is invalid or already freed @hideinitializer*/ | ||
58 | #define OPUS_INVALID_STATE -6 | ||
59 | /** Memory allocation has failed @hideinitializer*/ | ||
60 | #define OPUS_ALLOC_FAIL -7 | ||
61 | /**@}*/ | ||
62 | |||
63 | /** @cond OPUS_INTERNAL_DOC */ | ||
64 | /**Export control for opus functions */ | ||
65 | |||
66 | #if defined(__GNUC__) && defined(OPUS_BUILD) | ||
67 | # define OPUS_EXPORT __attribute__ ((visibility ("default"))) | ||
68 | #elif defined(WIN32) && !defined(__MINGW32__) | ||
69 | # ifdef OPUS_BUILD | ||
70 | # define OPUS_EXPORT __declspec(dllexport) | ||
71 | # else | ||
72 | # define OPUS_EXPORT | ||
73 | # endif | ||
74 | #else | ||
75 | # define OPUS_EXPORT | ||
76 | #endif | ||
77 | |||
78 | # if !defined(OPUS_GNUC_PREREQ) | ||
79 | # if defined(__GNUC__)&&defined(__GNUC_MINOR__) | ||
80 | # define OPUS_GNUC_PREREQ(_maj,_min) \ | ||
81 | ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min)) | ||
82 | # else | ||
83 | # define OPUS_GNUC_PREREQ(_maj,_min) 0 | ||
84 | # endif | ||
85 | # endif | ||
86 | |||
87 | #if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) ) | ||
88 | # if OPUS_GNUC_PREREQ(3,0) | ||
89 | # define OPUS_RESTRICT __restrict__ | ||
90 | # elif (defined(_MSC_VER) && _MSC_VER >= 1400) | ||
91 | # define OPUS_RESTRICT __restrict | ||
92 | # else | ||
93 | # define OPUS_RESTRICT | ||
94 | # endif | ||
95 | #else | ||
96 | # define OPUS_RESTRICT restrict | ||
97 | #endif | ||
98 | |||
99 | /**Warning attributes for opus functions | ||
100 | * NONNULL is not used in OPUS_BUILD to avoid the compiler optimizing out | ||
101 | * some paranoid null checks. */ | ||
102 | #if defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4) | ||
103 | # define OPUS_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__)) | ||
104 | #else | ||
105 | # define OPUS_WARN_UNUSED_RESULT | ||
106 | #endif | ||
107 | #if !defined(OPUS_BUILD) && defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4) | ||
108 | # define OPUS_ARG_NONNULL(_x) __attribute__ ((__nonnull__(_x))) | ||
109 | #else | ||
110 | # define OPUS_ARG_NONNULL(_x) | ||
111 | #endif | ||
112 | |||
113 | /** These are the actual Encoder CTL ID numbers. | ||
114 | * They should not be used directly by applications. | ||
115 | * In general, SETs should be even and GETs should be odd.*/ | ||
116 | #define OPUS_SET_APPLICATION_REQUEST 4000 | ||
117 | #define OPUS_GET_APPLICATION_REQUEST 4001 | ||
118 | #define OPUS_SET_BITRATE_REQUEST 4002 | ||
119 | #define OPUS_GET_BITRATE_REQUEST 4003 | ||
120 | #define OPUS_SET_MAX_BANDWIDTH_REQUEST 4004 | ||
121 | #define OPUS_GET_MAX_BANDWIDTH_REQUEST 4005 | ||
122 | #define OPUS_SET_VBR_REQUEST 4006 | ||
123 | #define OPUS_GET_VBR_REQUEST 4007 | ||
124 | #define OPUS_SET_BANDWIDTH_REQUEST 4008 | ||
125 | #define OPUS_GET_BANDWIDTH_REQUEST 4009 | ||
126 | #define OPUS_SET_COMPLEXITY_REQUEST 4010 | ||
127 | #define OPUS_GET_COMPLEXITY_REQUEST 4011 | ||
128 | #define OPUS_SET_INBAND_FEC_REQUEST 4012 | ||
129 | #define OPUS_GET_INBAND_FEC_REQUEST 4013 | ||
130 | #define OPUS_SET_PACKET_LOSS_PERC_REQUEST 4014 | ||
131 | #define OPUS_GET_PACKET_LOSS_PERC_REQUEST 4015 | ||
132 | #define OPUS_SET_DTX_REQUEST 4016 | ||
133 | #define OPUS_GET_DTX_REQUEST 4017 | ||
134 | #define OPUS_SET_VBR_CONSTRAINT_REQUEST 4020 | ||
135 | #define OPUS_GET_VBR_CONSTRAINT_REQUEST 4021 | ||
136 | #define OPUS_SET_FORCE_CHANNELS_REQUEST 4022 | ||
137 | #define OPUS_GET_FORCE_CHANNELS_REQUEST 4023 | ||
138 | #define OPUS_SET_SIGNAL_REQUEST 4024 | ||
139 | #define OPUS_GET_SIGNAL_REQUEST 4025 | ||
140 | #define OPUS_GET_LOOKAHEAD_REQUEST 4027 | ||
141 | /* #define OPUS_RESET_STATE 4028 */ | ||
142 | #define OPUS_GET_SAMPLE_RATE_REQUEST 4029 | ||
143 | #define OPUS_GET_FINAL_RANGE_REQUEST 4031 | ||
144 | #define OPUS_GET_PITCH_REQUEST 4033 | ||
145 | #define OPUS_SET_GAIN_REQUEST 4034 | ||
146 | #define OPUS_GET_GAIN_REQUEST 4045 | ||
147 | #define OPUS_SET_LSB_DEPTH_REQUEST 4036 | ||
148 | #define OPUS_GET_LSB_DEPTH_REQUEST 4037 | ||
149 | |||
150 | /* Macros to trigger compilation errors when the wrong types are provided to a CTL */ | ||
151 | #define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x)) | ||
152 | #define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr))) | ||
153 | #define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr))) | ||
154 | /** @endcond */ | ||
155 | |||
156 | /** @defgroup opus_ctlvalues Pre-defined values for CTL interface | ||
157 | * @see opus_genericctls, opus_encoderctls | ||
158 | * @{ | ||
159 | */ | ||
160 | /* Values for the various encoder CTLs */ | ||
161 | #define OPUS_AUTO -1000 /**<Auto/default setting @hideinitializer*/ | ||
162 | #define OPUS_BITRATE_MAX -1 /**<Maximum bitrate @hideinitializer*/ | ||
163 | |||
164 | /** Best for most VoIP/videoconference applications where listening quality and intelligibility matter most | ||
165 | * @hideinitializer */ | ||
166 | #define OPUS_APPLICATION_VOIP 2048 | ||
167 | /** Best for broadcast/high-fidelity application where the decoded audio should be as close as possible to the input | ||
168 | * @hideinitializer */ | ||
169 | #define OPUS_APPLICATION_AUDIO 2049 | ||
170 | /** Only use when lowest-achievable latency is what matters most. Voice-optimized modes cannot be used. | ||
171 | * @hideinitializer */ | ||
172 | #define OPUS_APPLICATION_RESTRICTED_LOWDELAY 2051 | ||
173 | |||
174 | #define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */ | ||
175 | #define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */ | ||
176 | #define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4 kHz bandpass @hideinitializer*/ | ||
177 | #define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6 kHz bandpass @hideinitializer*/ | ||
178 | #define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8 kHz bandpass @hideinitializer*/ | ||
179 | #define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12 kHz bandpass @hideinitializer*/ | ||
180 | #define OPUS_BANDWIDTH_FULLBAND 1105 /**<20 kHz bandpass @hideinitializer*/ | ||
181 | |||
182 | /**@}*/ | ||
183 | |||
184 | |||
185 | /** @defgroup opus_encoderctls Encoder related CTLs | ||
186 | * | ||
187 | * These are convenience macros for use with the \c opus_encode_ctl | ||
188 | * interface. They are used to generate the appropriate series of | ||
189 | * arguments for that call, passing the correct type, size and so | ||
190 | * on as expected for each particular request. | ||
191 | * | ||
192 | * Some usage examples: | ||
193 | * | ||
194 | * @code | ||
195 | * int ret; | ||
196 | * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO)); | ||
197 | * if (ret != OPUS_OK) return ret; | ||
198 | * | ||
199 | * opus_int32 rate; | ||
200 | * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate)); | ||
201 | * | ||
202 | * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); | ||
203 | * @endcode | ||
204 | * | ||
205 | * @see opus_genericctls, opus_encoder | ||
206 | * @{ | ||
207 | */ | ||
208 | |||
209 | /** Configures the encoder's computational complexity. | ||
210 | * The supported range is 0-10 inclusive with 10 representing the highest complexity. | ||
211 | * @see OPUS_GET_COMPLEXITY | ||
212 | * @param[in] x <tt>opus_int32</tt>: Allowed values: 0-10, inclusive. | ||
213 | * | ||
214 | * @hideinitializer */ | ||
215 | #define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x) | ||
216 | /** Gets the encoder's complexity configuration. | ||
217 | * @see OPUS_SET_COMPLEXITY | ||
218 | * @param[out] x <tt>opus_int32 *</tt>: Returns a value in the range 0-10, | ||
219 | * inclusive. | ||
220 | * @hideinitializer */ | ||
221 | #define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x) | ||
222 | |||
223 | /** Configures the bitrate in the encoder. | ||
224 | * Rates from 500 to 512000 bits per second are meaningful, as well as the | ||
225 | * special values #OPUS_AUTO and #OPUS_BITRATE_MAX. | ||
226 | * The value #OPUS_BITRATE_MAX can be used to cause the codec to use as much | ||
227 | * rate as it can, which is useful for controlling the rate by adjusting the | ||
228 | * output buffer size. | ||
229 | * @see OPUS_GET_BITRATE | ||
230 | * @param[in] x <tt>opus_int32</tt>: Bitrate in bits per second. The default | ||
231 | * is determined based on the number of | ||
232 | * channels and the input sampling rate. | ||
233 | * @hideinitializer */ | ||
234 | #define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x) | ||
235 | /** Gets the encoder's bitrate configuration. | ||
236 | * @see OPUS_SET_BITRATE | ||
237 | * @param[out] x <tt>opus_int32 *</tt>: Returns the bitrate in bits per second. | ||
238 | * The default is determined based on the | ||
239 | * number of channels and the input | ||
240 | * sampling rate. | ||
241 | * @hideinitializer */ | ||
242 | #define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x) | ||
243 | |||
244 | /** Enables or disables variable bitrate (VBR) in the encoder. | ||
245 | * The configured bitrate may not be met exactly because frames must | ||
246 | * be an integer number of bytes in length. | ||
247 | * @warning Only the MDCT mode of Opus can provide hard CBR behavior. | ||
248 | * @see OPUS_GET_VBR | ||
249 | * @see OPUS_SET_VBR_CONSTRAINT | ||
250 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
251 | * <dl> | ||
252 | * <dt>0</dt><dd>Hard CBR. For LPC/hybrid modes at very low bit-rate, this can | ||
253 | * cause noticeable quality degradation.</dd> | ||
254 | * <dt>1</dt><dd>VBR (default). The exact type of VBR is controlled by | ||
255 | * #OPUS_SET_VBR_CONSTRAINT.</dd> | ||
256 | * </dl> | ||
257 | * @hideinitializer */ | ||
258 | #define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x) | ||
259 | /** Determine if variable bitrate (VBR) is enabled in the encoder. | ||
260 | * @see OPUS_SET_VBR | ||
261 | * @see OPUS_GET_VBR_CONSTRAINT | ||
262 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
263 | * <dl> | ||
264 | * <dt>0</dt><dd>Hard CBR.</dd> | ||
265 | * <dt>1</dt><dd>VBR (default). The exact type of VBR may be retrieved via | ||
266 | * #OPUS_GET_VBR_CONSTRAINT.</dd> | ||
267 | * </dl> | ||
268 | * @hideinitializer */ | ||
269 | #define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x) | ||
270 | |||
271 | /** Enables or disables constrained VBR in the encoder. | ||
272 | * This setting is ignored when the encoder is in CBR mode. | ||
273 | * @warning Only the MDCT mode of Opus currently heeds the constraint. | ||
274 | * Speech mode ignores it completely, hybrid mode may fail to obey it | ||
275 | * if the LPC layer uses more bitrate than the constraint would have | ||
276 | * permitted. | ||
277 | * @see OPUS_GET_VBR_CONSTRAINT | ||
278 | * @see OPUS_SET_VBR | ||
279 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
280 | * <dl> | ||
281 | * <dt>0</dt><dd>Unconstrained VBR.</dd> | ||
282 | * <dt>1</dt><dd>Constrained VBR (default). This creates a maximum of one | ||
283 | * frame of buffering delay assuming a transport with a | ||
284 | * serialization speed of the nominal bitrate.</dd> | ||
285 | * </dl> | ||
286 | * @hideinitializer */ | ||
287 | #define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x) | ||
288 | /** Determine if constrained VBR is enabled in the encoder. | ||
289 | * @see OPUS_SET_VBR_CONSTRAINT | ||
290 | * @see OPUS_GET_VBR | ||
291 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
292 | * <dl> | ||
293 | * <dt>0</dt><dd>Unconstrained VBR.</dd> | ||
294 | * <dt>1</dt><dd>Constrained VBR (default).</dd> | ||
295 | * </dl> | ||
296 | * @hideinitializer */ | ||
297 | #define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x) | ||
298 | |||
299 | /** Configures mono/stereo forcing in the encoder. | ||
300 | * This can force the encoder to produce packets encoded as either mono or | ||
301 | * stereo, regardless of the format of the input audio. This is useful when | ||
302 | * the caller knows that the input signal is currently a mono source embedded | ||
303 | * in a stereo stream. | ||
304 | * @see OPUS_GET_FORCE_CHANNELS | ||
305 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
306 | * <dl> | ||
307 | * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd> | ||
308 | * <dt>1</dt> <dd>Forced mono</dd> | ||
309 | * <dt>2</dt> <dd>Forced stereo</dd> | ||
310 | * </dl> | ||
311 | * @hideinitializer */ | ||
312 | #define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x) | ||
313 | /** Gets the encoder's forced channel configuration. | ||
314 | * @see OPUS_SET_FORCE_CHANNELS | ||
315 | * @param[out] x <tt>opus_int32 *</tt>: | ||
316 | * <dl> | ||
317 | * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd> | ||
318 | * <dt>1</dt> <dd>Forced mono</dd> | ||
319 | * <dt>2</dt> <dd>Forced stereo</dd> | ||
320 | * </dl> | ||
321 | * @hideinitializer */ | ||
322 | #define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x) | ||
323 | |||
324 | /** Configures the maximum bandpass that the encoder will select automatically. | ||
325 | * Applications should normally use this instead of #OPUS_SET_BANDWIDTH | ||
326 | * (leaving that set to the default, #OPUS_AUTO). This allows the | ||
327 | * application to set an upper bound based on the type of input it is | ||
328 | * providing, but still gives the encoder the freedom to reduce the bandpass | ||
329 | * when the bitrate becomes too low, for better overall quality. | ||
330 | * @see OPUS_GET_MAX_BANDWIDTH | ||
331 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
332 | * <dl> | ||
333 | * <dt>OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> | ||
334 | * <dt>OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> | ||
335 | * <dt>OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> | ||
336 | * <dt>OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> | ||
337 | * <dt>OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd> | ||
338 | * </dl> | ||
339 | * @hideinitializer */ | ||
340 | #define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x) | ||
341 | |||
342 | /** Gets the encoder's configured maximum allowed bandpass. | ||
343 | * @see OPUS_SET_MAX_BANDWIDTH | ||
344 | * @param[out] x <tt>opus_int32 *</tt>: Allowed values: | ||
345 | * <dl> | ||
346 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> | ||
347 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> | ||
348 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> | ||
349 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> | ||
350 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd> | ||
351 | * </dl> | ||
352 | * @hideinitializer */ | ||
353 | #define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) | ||
354 | |||
355 | /** Sets the encoder's bandpass to a specific value. | ||
356 | * This prevents the encoder from automatically selecting the bandpass based | ||
357 | * on the available bitrate. If an application knows the bandpass of the input | ||
358 | * audio it is providing, it should normally use #OPUS_SET_MAX_BANDWIDTH | ||
359 | * instead, which still gives the encoder the freedom to reduce the bandpass | ||
360 | * when the bitrate becomes too low, for better overall quality. | ||
361 | * @see OPUS_GET_BANDWIDTH | ||
362 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
363 | * <dl> | ||
364 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> | ||
365 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> | ||
366 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> | ||
367 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> | ||
368 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> | ||
369 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd> | ||
370 | * </dl> | ||
371 | * @hideinitializer */ | ||
372 | #define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x) | ||
373 | |||
374 | /** Configures the type of signal being encoded. | ||
375 | * This is a hint which helps the encoder's mode selection. | ||
376 | * @see OPUS_GET_SIGNAL | ||
377 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
378 | * <dl> | ||
379 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> | ||
380 | * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd> | ||
381 | * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd> | ||
382 | * </dl> | ||
383 | * @hideinitializer */ | ||
384 | #define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x) | ||
385 | /** Gets the encoder's configured signal type. | ||
386 | * @see OPUS_SET_SIGNAL | ||
387 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
388 | * <dl> | ||
389 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> | ||
390 | * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd> | ||
391 | * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd> | ||
392 | * </dl> | ||
393 | * @hideinitializer */ | ||
394 | #define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x) | ||
395 | |||
396 | |||
397 | /** Configures the encoder's intended application. | ||
398 | * The initial value is a mandatory argument to the encoder_create function. | ||
399 | * @see OPUS_GET_APPLICATION | ||
400 | * @param[in] x <tt>opus_int32</tt>: Returns one of the following values: | ||
401 | * <dl> | ||
402 | * <dt>#OPUS_APPLICATION_VOIP</dt> | ||
403 | * <dd>Process signal for improved speech intelligibility.</dd> | ||
404 | * <dt>#OPUS_APPLICATION_AUDIO</dt> | ||
405 | * <dd>Favor faithfulness to the original input.</dd> | ||
406 | * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt> | ||
407 | * <dd>Configure the minimum possible coding delay by disabling certain modes | ||
408 | * of operation.</dd> | ||
409 | * </dl> | ||
410 | * @hideinitializer */ | ||
411 | #define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x) | ||
412 | /** Gets the encoder's configured application. | ||
413 | * @see OPUS_SET_APPLICATION | ||
414 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
415 | * <dl> | ||
416 | * <dt>#OPUS_APPLICATION_VOIP</dt> | ||
417 | * <dd>Process signal for improved speech intelligibility.</dd> | ||
418 | * <dt>#OPUS_APPLICATION_AUDIO</dt> | ||
419 | * <dd>Favor faithfulness to the original input.</dd> | ||
420 | * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt> | ||
421 | * <dd>Configure the minimum possible coding delay by disabling certain modes | ||
422 | * of operation.</dd> | ||
423 | * </dl> | ||
424 | * @hideinitializer */ | ||
425 | #define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x) | ||
426 | |||
427 | /** Gets the sampling rate the encoder or decoder was initialized with. | ||
428 | * This simply returns the <code>Fs</code> value passed to opus_encoder_init() | ||
429 | * or opus_decoder_init(). | ||
430 | * @param[out] x <tt>opus_int32 *</tt>: Sampling rate of encoder or decoder. | ||
431 | * @hideinitializer | ||
432 | */ | ||
433 | #define OPUS_GET_SAMPLE_RATE(x) OPUS_GET_SAMPLE_RATE_REQUEST, __opus_check_int_ptr(x) | ||
434 | |||
435 | /** Gets the total samples of delay added by the entire codec. | ||
436 | * This can be queried by the encoder and then the provided number of samples can be | ||
437 | * skipped on from the start of the decoder's output to provide time aligned input | ||
438 | * and output. From the perspective of a decoding application the real data begins this many | ||
439 | * samples late. | ||
440 | * | ||
441 | * The decoder contribution to this delay is identical for all decoders, but the | ||
442 | * encoder portion of the delay may vary from implementation to implementation, | ||
443 | * version to version, or even depend on the encoder's initial configuration. | ||
444 | * Applications needing delay compensation should call this CTL rather than | ||
445 | * hard-coding a value. | ||
446 | * @param[out] x <tt>opus_int32 *</tt>: Number of lookahead samples | ||
447 | * @hideinitializer */ | ||
448 | #define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x) | ||
449 | |||
450 | /** Configures the encoder's use of inband forward error correction (FEC). | ||
451 | * @note This is only applicable to the LPC layer | ||
452 | * @see OPUS_GET_INBAND_FEC | ||
453 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
454 | * <dl> | ||
455 | * <dt>0</dt><dd>Disable inband FEC (default).</dd> | ||
456 | * <dt>1</dt><dd>Enable inband FEC.</dd> | ||
457 | * </dl> | ||
458 | * @hideinitializer */ | ||
459 | #define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x) | ||
460 | /** Gets encoder's configured use of inband forward error correction. | ||
461 | * @see OPUS_SET_INBAND_FEC | ||
462 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
463 | * <dl> | ||
464 | * <dt>0</dt><dd>Inband FEC disabled (default).</dd> | ||
465 | * <dt>1</dt><dd>Inband FEC enabled.</dd> | ||
466 | * </dl> | ||
467 | * @hideinitializer */ | ||
468 | #define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x) | ||
469 | |||
470 | /** Configures the encoder's expected packet loss percentage. | ||
471 | * Higher values with trigger progressively more loss resistant behavior in the encoder | ||
472 | * at the expense of quality at a given bitrate in the lossless case, but greater quality | ||
473 | * under loss. | ||
474 | * @see OPUS_GET_PACKET_LOSS_PERC | ||
475 | * @param[in] x <tt>opus_int32</tt>: Loss percentage in the range 0-100, inclusive (default: 0). | ||
476 | * @hideinitializer */ | ||
477 | #define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x) | ||
478 | /** Gets the encoder's configured packet loss percentage. | ||
479 | * @see OPUS_SET_PACKET_LOSS_PERC | ||
480 | * @param[out] x <tt>opus_int32 *</tt>: Returns the configured loss percentage | ||
481 | * in the range 0-100, inclusive (default: 0). | ||
482 | * @hideinitializer */ | ||
483 | #define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x) | ||
484 | |||
485 | /** Configures the encoder's use of discontinuous transmission (DTX). | ||
486 | * @note This is only applicable to the LPC layer | ||
487 | * @see OPUS_GET_DTX | ||
488 | * @param[in] x <tt>opus_int32</tt>: Allowed values: | ||
489 | * <dl> | ||
490 | * <dt>0</dt><dd>Disable DTX (default).</dd> | ||
491 | * <dt>1</dt><dd>Enabled DTX.</dd> | ||
492 | * </dl> | ||
493 | * @hideinitializer */ | ||
494 | #define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x) | ||
495 | /** Gets encoder's configured use of discontinuous transmission. | ||
496 | * @see OPUS_SET_DTX | ||
497 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
498 | * <dl> | ||
499 | * <dt>0</dt><dd>DTX disabled (default).</dd> | ||
500 | * <dt>1</dt><dd>DTX enabled.</dd> | ||
501 | * </dl> | ||
502 | * @hideinitializer */ | ||
503 | #define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x) | ||
504 | /**@}*/ | ||
505 | |||
506 | /** @defgroup opus_genericctls Generic CTLs | ||
507 | * | ||
508 | * These macros are used with the \c opus_decoder_ctl and | ||
509 | * \c opus_encoder_ctl calls to generate a particular | ||
510 | * request. | ||
511 | * | ||
512 | * When called on an \c OpusDecoder they apply to that | ||
513 | * particular decoder instance. When called on an | ||
514 | * \c OpusEncoder they apply to the corresponding setting | ||
515 | * on that encoder instance, if present. | ||
516 | * | ||
517 | * Some usage examples: | ||
518 | * | ||
519 | * @code | ||
520 | * int ret; | ||
521 | * opus_int32 pitch; | ||
522 | * ret = opus_decoder_ctl(dec_ctx, OPUS_GET_PITCH(&pitch)); | ||
523 | * if (ret == OPUS_OK) return ret; | ||
524 | * | ||
525 | * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); | ||
526 | * opus_decoder_ctl(dec_ctx, OPUS_RESET_STATE); | ||
527 | * | ||
528 | * opus_int32 enc_bw, dec_bw; | ||
529 | * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&enc_bw)); | ||
530 | * opus_decoder_ctl(dec_ctx, OPUS_GET_BANDWIDTH(&dec_bw)); | ||
531 | * if (enc_bw != dec_bw) { | ||
532 | * printf("packet bandwidth mismatch!\n"); | ||
533 | * } | ||
534 | * @endcode | ||
535 | * | ||
536 | * @see opus_encoder, opus_decoder_ctl, opus_encoder_ctl, opus_decoderctls, opus_encoderctls | ||
537 | * @{ | ||
538 | */ | ||
539 | |||
540 | /** Resets the codec state to be equivalent to a freshly initialized state. | ||
541 | * This should be called when switching streams in order to prevent | ||
542 | * the back to back decoding from giving different results from | ||
543 | * one at a time decoding. | ||
544 | * @hideinitializer */ | ||
545 | #define OPUS_RESET_STATE 4028 | ||
546 | |||
547 | /** Gets the final state of the codec's entropy coder. | ||
548 | * This is used for testing purposes, | ||
549 | * The encoder and decoder state should be identical after coding a payload | ||
550 | * (assuming no data corruption or software bugs) | ||
551 | * | ||
552 | * @param[out] x <tt>opus_uint32 *</tt>: Entropy coder state | ||
553 | * | ||
554 | * @hideinitializer */ | ||
555 | #define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x) | ||
556 | |||
557 | /** Gets the pitch of the last decoded frame, if available. | ||
558 | * This can be used for any post-processing algorithm requiring the use of pitch, | ||
559 | * e.g. time stretching/shortening. If the last frame was not voiced, or if the | ||
560 | * pitch was not coded in the frame, then zero is returned. | ||
561 | * | ||
562 | * This CTL is only implemented for decoder instances. | ||
563 | * | ||
564 | * @param[out] x <tt>opus_int32 *</tt>: pitch period at 48 kHz (or 0 if not available) | ||
565 | * | ||
566 | * @hideinitializer */ | ||
567 | #define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x) | ||
568 | |||
569 | /** Gets the encoder's configured bandpass or the decoder's last bandpass. | ||
570 | * @see OPUS_SET_BANDWIDTH | ||
571 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: | ||
572 | * <dl> | ||
573 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> | ||
574 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> | ||
575 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> | ||
576 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> | ||
577 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> | ||
578 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd> | ||
579 | * </dl> | ||
580 | * @hideinitializer */ | ||
581 | #define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) | ||
582 | |||
583 | /** Configures the depth of signal being encoded. | ||
584 | * This is a hint which helps the encoder identify silence and near-silence. | ||
585 | * @see OPUS_GET_LSB_DEPTH | ||
586 | * @param[in] x <tt>opus_int32</tt>: Input precision in bits, between 8 and 24 | ||
587 | * (default: 24). | ||
588 | * @hideinitializer */ | ||
589 | #define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x) | ||
590 | /** Gets the encoder's configured signal depth. | ||
591 | * @see OPUS_SET_LSB_DEPTH | ||
592 | * @param[out] x <tt>opus_int32 *</tt>: Input precision in bits, between 8 and | ||
593 | * 24 (default: 24). | ||
594 | * @hideinitializer */ | ||
595 | #define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x) | ||
596 | /**@}*/ | ||
597 | |||
598 | /** @defgroup opus_decoderctls Decoder related CTLs | ||
599 | * @see opus_genericctls, opus_encoderctls, opus_decoder | ||
600 | * @{ | ||
601 | */ | ||
602 | |||
603 | /** Configures decoder gain adjustment. | ||
604 | * Scales the decoded output by a factor specified in Q8 dB units. | ||
605 | * This has a maximum range of -32768 to 32767 inclusive, and returns | ||
606 | * OPUS_BAD_ARG otherwise. The default is zero indicating no adjustment. | ||
607 | * This setting survives decoder reset. | ||
608 | * | ||
609 | * gain = pow(10, x/(20.0*256)) | ||
610 | * | ||
611 | * @param[in] x <tt>opus_int32</tt>: Amount to scale PCM signal by in Q8 dB units. | ||
612 | * @hideinitializer */ | ||
613 | #define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x) | ||
614 | /** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN | ||
615 | * | ||
616 | * @param[out] x <tt>opus_int32 *</tt>: Amount to scale PCM signal by in Q8 dB units. | ||
617 | * @hideinitializer */ | ||
618 | #define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x) | ||
619 | |||
620 | /**@}*/ | ||
621 | |||
622 | /** @defgroup opus_libinfo Opus library information functions | ||
623 | * @{ | ||
624 | */ | ||
625 | |||
626 | /** Converts an opus error code into a human readable string. | ||
627 | * | ||
628 | * @param[in] error <tt>int</tt>: Error number | ||
629 | * @returns Error string | ||
630 | */ | ||
631 | OPUS_EXPORT const char *opus_strerror(int error); | ||
632 | |||
633 | /** Gets the libopus version string. | ||
634 | * | ||
635 | * @returns Version string | ||
636 | */ | ||
637 | OPUS_EXPORT const char *opus_get_version_string(void); | ||
638 | /**@}*/ | ||
639 | |||
640 | #ifdef __cplusplus | ||
641 | } | ||
642 | #endif | ||
643 | |||
644 | #endif /* OPUS_DEFINES_H */ | ||