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 | /** Not enough bytes allocated in the buffer @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 | #ifndef OPUS_EXPORT |
67 | # if defined(_WIN32) |
68 | # if defined(OPUS_BUILD) && defined(DLL_EXPORT) |
69 | # define OPUS_EXPORT __declspec(dllexport) |
70 | # else |
71 | # define OPUS_EXPORT |
72 | # endif |
73 | # elif defined(__GNUC__) && defined(OPUS_BUILD) |
74 | # define OPUS_EXPORT __attribute__ ((visibility ("default"))) |
75 | # else |
76 | # define OPUS_EXPORT |
77 | # endif |
78 | #endif |
79 | |
80 | # if !defined(OPUS_GNUC_PREREQ) |
81 | # if defined(__GNUC__)&&defined(__GNUC_MINOR__) |
82 | # define OPUS_GNUC_PREREQ(_maj,_min) \ |
83 | ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min)) |
84 | # else |
85 | # define OPUS_GNUC_PREREQ(_maj,_min) 0 |
86 | # endif |
87 | # endif |
88 | |
89 | #if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) ) |
90 | # if OPUS_GNUC_PREREQ(3,0) |
91 | # define OPUS_RESTRICT __restrict__ |
92 | # elif (defined(_MSC_VER) && _MSC_VER >= 1400) |
93 | # define OPUS_RESTRICT __restrict |
94 | # else |
95 | # define OPUS_RESTRICT |
96 | # endif |
97 | #else |
98 | # define OPUS_RESTRICT restrict |
99 | #endif |
100 | |
101 | #if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) ) |
102 | # if OPUS_GNUC_PREREQ(2,7) |
103 | # define OPUS_INLINE __inline__ |
104 | # elif (defined(_MSC_VER)) |
105 | # define OPUS_INLINE __inline |
106 | # else |
107 | # define OPUS_INLINE |
108 | # endif |
109 | #else |
110 | # define OPUS_INLINE inline |
111 | #endif |
112 | |
113 | /**Warning attributes for opus functions |
114 | * NONNULL is not used in OPUS_BUILD to avoid the compiler optimizing out |
115 | * some paranoid null checks. */ |
116 | #if defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4) |
117 | # define OPUS_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__)) |
118 | #else |
119 | # define OPUS_WARN_UNUSED_RESULT |
120 | #endif |
121 | #if !defined(OPUS_BUILD) && defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4) |
122 | # define OPUS_ARG_NONNULL(_x) __attribute__ ((__nonnull__(_x))) |
123 | #else |
124 | # define OPUS_ARG_NONNULL(_x) |
125 | #endif |
126 | |
127 | /** These are the actual Encoder CTL ID numbers. |
128 | * They should not be used directly by applications. |
129 | * In general, SETs should be even and GETs should be odd.*/ |
130 | #define OPUS_SET_APPLICATION_REQUEST 4000 |
131 | #define OPUS_GET_APPLICATION_REQUEST 4001 |
132 | #define OPUS_SET_BITRATE_REQUEST 4002 |
133 | #define OPUS_GET_BITRATE_REQUEST 4003 |
134 | #define OPUS_SET_MAX_BANDWIDTH_REQUEST 4004 |
135 | #define OPUS_GET_MAX_BANDWIDTH_REQUEST 4005 |
136 | #define OPUS_SET_VBR_REQUEST 4006 |
137 | #define OPUS_GET_VBR_REQUEST 4007 |
138 | #define OPUS_SET_BANDWIDTH_REQUEST 4008 |
139 | #define OPUS_GET_BANDWIDTH_REQUEST 4009 |
140 | #define OPUS_SET_COMPLEXITY_REQUEST 4010 |
141 | #define OPUS_GET_COMPLEXITY_REQUEST 4011 |
142 | #define OPUS_SET_INBAND_FEC_REQUEST 4012 |
143 | #define OPUS_GET_INBAND_FEC_REQUEST 4013 |
144 | #define OPUS_SET_PACKET_LOSS_PERC_REQUEST 4014 |
145 | #define OPUS_GET_PACKET_LOSS_PERC_REQUEST 4015 |
146 | #define OPUS_SET_DTX_REQUEST 4016 |
147 | #define OPUS_GET_DTX_REQUEST 4017 |
148 | #define OPUS_SET_VBR_CONSTRAINT_REQUEST 4020 |
149 | #define OPUS_GET_VBR_CONSTRAINT_REQUEST 4021 |
150 | #define OPUS_SET_FORCE_CHANNELS_REQUEST 4022 |
151 | #define OPUS_GET_FORCE_CHANNELS_REQUEST 4023 |
152 | #define OPUS_SET_SIGNAL_REQUEST 4024 |
153 | #define OPUS_GET_SIGNAL_REQUEST 4025 |
154 | #define OPUS_GET_LOOKAHEAD_REQUEST 4027 |
155 | /* #define OPUS_RESET_STATE 4028 */ |
156 | #define OPUS_GET_SAMPLE_RATE_REQUEST 4029 |
157 | #define OPUS_GET_FINAL_RANGE_REQUEST 4031 |
158 | #define OPUS_GET_PITCH_REQUEST 4033 |
159 | #define OPUS_SET_GAIN_REQUEST 4034 |
160 | #define OPUS_GET_GAIN_REQUEST 4045 /* Should have been 4035 */ |
161 | #define OPUS_SET_LSB_DEPTH_REQUEST 4036 |
162 | #define OPUS_GET_LSB_DEPTH_REQUEST 4037 |
163 | #define OPUS_GET_LAST_PACKET_DURATION_REQUEST 4039 |
164 | #define OPUS_SET_EXPERT_FRAME_DURATION_REQUEST 4040 |
165 | #define OPUS_GET_EXPERT_FRAME_DURATION_REQUEST 4041 |
166 | #define OPUS_SET_PREDICTION_DISABLED_REQUEST 4042 |
167 | #define OPUS_GET_PREDICTION_DISABLED_REQUEST 4043 |
168 | /* Don't use 4045, it's already taken by OPUS_GET_GAIN_REQUEST */ |
169 | #define OPUS_SET_PHASE_INVERSION_DISABLED_REQUEST 4046 |
170 | #define OPUS_GET_PHASE_INVERSION_DISABLED_REQUEST 4047 |
171 | #define OPUS_GET_IN_DTX_REQUEST 4049 |
172 | #define OPUS_SET_DRED_DURATION_REQUEST 4050 |
173 | #define OPUS_GET_DRED_DURATION_REQUEST 4051 |
174 | #define OPUS_SET_DNN_BLOB_REQUEST 4052 |
175 | /*#define OPUS_GET_DNN_BLOB_REQUEST 4053 */ |
176 | |
177 | /** Defines for the presence of extended APIs. */ |
178 | #define OPUS_HAVE_OPUS_PROJECTION_H |
179 | |
180 | /* Macros to trigger compilation errors when the wrong types are provided to a CTL */ |
181 | #define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x)) |
182 | |
183 | #ifdef DISABLE_PTR_CHECK |
184 | /* Disable checks to prevent ubsan from complaining about NULL checks |
185 | in test_opus_api. */ |
186 | #define __opus_check_int_ptr(ptr) (ptr) |
187 | #define __opus_check_uint_ptr(ptr) (ptr) |
188 | #define __opus_check_uint8_ptr(ptr) (ptr) |
189 | #define __opus_check_val16_ptr(ptr) (ptr) |
190 | #define __opus_check_void_ptr(ptr) (ptr) |
191 | #else |
192 | #define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr))) |
193 | #define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr))) |
194 | #define __opus_check_uint8_ptr(ptr) ((ptr) + ((ptr) - (opus_uint8*)(ptr))) |
195 | #define __opus_check_val16_ptr(ptr) ((ptr) + ((ptr) - (opus_val16*)(ptr))) |
196 | #define __opus_check_void_ptr(x) ((void)((void *)0 == (x)), (x)) |
197 | #endif |
198 | /** @endcond */ |
199 | |
200 | /** @defgroup opus_ctlvalues Pre-defined values for CTL interface |
201 | * @see opus_genericctls, opus_encoderctls |
202 | * @{ |
203 | */ |
204 | /* Values for the various encoder CTLs */ |
205 | #define OPUS_AUTO -1000 /**<Auto/default setting @hideinitializer*/ |
206 | #define OPUS_BITRATE_MAX -1 /**<Maximum bitrate @hideinitializer*/ |
207 | |
208 | /** Best for most VoIP/videoconference applications where listening quality and intelligibility matter most |
209 | * @hideinitializer */ |
210 | #define OPUS_APPLICATION_VOIP 2048 |
211 | /** Best for broadcast/high-fidelity application where the decoded audio should be as close as possible to the input |
212 | * @hideinitializer */ |
213 | #define OPUS_APPLICATION_AUDIO 2049 |
214 | /** Only use when lowest-achievable latency is what matters most. Voice-optimized modes cannot be used. |
215 | * @hideinitializer */ |
216 | #define OPUS_APPLICATION_RESTRICTED_LOWDELAY 2051 |
217 | |
218 | #define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */ |
219 | #define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */ |
220 | #define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4 kHz bandpass @hideinitializer*/ |
221 | #define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6 kHz bandpass @hideinitializer*/ |
222 | #define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8 kHz bandpass @hideinitializer*/ |
223 | #define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12 kHz bandpass @hideinitializer*/ |
224 | #define OPUS_BANDWIDTH_FULLBAND 1105 /**<20 kHz bandpass @hideinitializer*/ |
225 | |
226 | #define OPUS_FRAMESIZE_ARG 5000 /**< Select frame size from the argument (default) */ |
227 | #define OPUS_FRAMESIZE_2_5_MS 5001 /**< Use 2.5 ms frames */ |
228 | #define OPUS_FRAMESIZE_5_MS 5002 /**< Use 5 ms frames */ |
229 | #define OPUS_FRAMESIZE_10_MS 5003 /**< Use 10 ms frames */ |
230 | #define OPUS_FRAMESIZE_20_MS 5004 /**< Use 20 ms frames */ |
231 | #define OPUS_FRAMESIZE_40_MS 5005 /**< Use 40 ms frames */ |
232 | #define OPUS_FRAMESIZE_60_MS 5006 /**< Use 60 ms frames */ |
233 | #define OPUS_FRAMESIZE_80_MS 5007 /**< Use 80 ms frames */ |
234 | #define OPUS_FRAMESIZE_100_MS 5008 /**< Use 100 ms frames */ |
235 | #define OPUS_FRAMESIZE_120_MS 5009 /**< Use 120 ms frames */ |
236 | |
237 | /**@}*/ |
238 | |
239 | |
240 | /** @defgroup opus_encoderctls Encoder related CTLs |
241 | * |
242 | * These are convenience macros for use with the \c opus_encode_ctl |
243 | * interface. They are used to generate the appropriate series of |
244 | * arguments for that call, passing the correct type, size and so |
245 | * on as expected for each particular request. |
246 | * |
247 | * Some usage examples: |
248 | * |
249 | * @code |
250 | * int ret; |
251 | * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO)); |
252 | * if (ret != OPUS_OK) return ret; |
253 | * |
254 | * opus_int32 rate; |
255 | * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate)); |
256 | * |
257 | * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); |
258 | * @endcode |
259 | * |
260 | * @see opus_genericctls, opus_encoder |
261 | * @{ |
262 | */ |
263 | |
264 | /** Configures the encoder's computational complexity. |
265 | * The supported range is 0-10 inclusive with 10 representing the highest complexity. |
266 | * @see OPUS_GET_COMPLEXITY |
267 | * @param[in] x <tt>opus_int32</tt>: Allowed values: 0-10, inclusive. |
268 | * |
269 | * @hideinitializer */ |
270 | #define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x) |
271 | /** Gets the encoder's complexity configuration. |
272 | * @see OPUS_SET_COMPLEXITY |
273 | * @param[out] x <tt>opus_int32 *</tt>: Returns a value in the range 0-10, |
274 | * inclusive. |
275 | * @hideinitializer */ |
276 | #define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x) |
277 | |
278 | /** Configures the bitrate in the encoder. |
279 | * Rates from 500 to 512000 bits per second are meaningful, as well as the |
280 | * special values #OPUS_AUTO and #OPUS_BITRATE_MAX. |
281 | * The value #OPUS_BITRATE_MAX can be used to cause the codec to use as much |
282 | * rate as it can, which is useful for controlling the rate by adjusting the |
283 | * output buffer size. |
284 | * @see OPUS_GET_BITRATE |
285 | * @param[in] x <tt>opus_int32</tt>: Bitrate in bits per second. The default |
286 | * is determined based on the number of |
287 | * channels and the input sampling rate. |
288 | * @hideinitializer */ |
289 | #define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x) |
290 | /** Gets the encoder's bitrate configuration. |
291 | * @see OPUS_SET_BITRATE |
292 | * @param[out] x <tt>opus_int32 *</tt>: Returns the bitrate in bits per second. |
293 | * The default is determined based on the |
294 | * number of channels and the input |
295 | * sampling rate. |
296 | * @hideinitializer */ |
297 | #define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x) |
298 | |
299 | /** Enables or disables variable bitrate (VBR) in the encoder. |
300 | * The configured bitrate may not be met exactly because frames must |
301 | * be an integer number of bytes in length. |
302 | * @see OPUS_GET_VBR |
303 | * @see OPUS_SET_VBR_CONSTRAINT |
304 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
305 | * <dl> |
306 | * <dt>0</dt><dd>Hard CBR. For LPC/hybrid modes at very low bit-rate, this can |
307 | * cause noticeable quality degradation.</dd> |
308 | * <dt>1</dt><dd>VBR (default). The exact type of VBR is controlled by |
309 | * #OPUS_SET_VBR_CONSTRAINT.</dd> |
310 | * </dl> |
311 | * @hideinitializer */ |
312 | #define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x) |
313 | /** Determine if variable bitrate (VBR) is enabled in the encoder. |
314 | * @see OPUS_SET_VBR |
315 | * @see OPUS_GET_VBR_CONSTRAINT |
316 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
317 | * <dl> |
318 | * <dt>0</dt><dd>Hard CBR.</dd> |
319 | * <dt>1</dt><dd>VBR (default). The exact type of VBR may be retrieved via |
320 | * #OPUS_GET_VBR_CONSTRAINT.</dd> |
321 | * </dl> |
322 | * @hideinitializer */ |
323 | #define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x) |
324 | |
325 | /** Enables or disables constrained VBR in the encoder. |
326 | * This setting is ignored when the encoder is in CBR mode. |
327 | * @warning Only the MDCT mode of Opus currently heeds the constraint. |
328 | * Speech mode ignores it completely, hybrid mode may fail to obey it |
329 | * if the LPC layer uses more bitrate than the constraint would have |
330 | * permitted. |
331 | * @see OPUS_GET_VBR_CONSTRAINT |
332 | * @see OPUS_SET_VBR |
333 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
334 | * <dl> |
335 | * <dt>0</dt><dd>Unconstrained VBR.</dd> |
336 | * <dt>1</dt><dd>Constrained VBR (default). This creates a maximum of one |
337 | * frame of buffering delay assuming a transport with a |
338 | * serialization speed of the nominal bitrate.</dd> |
339 | * </dl> |
340 | * @hideinitializer */ |
341 | #define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x) |
342 | /** Determine if constrained VBR is enabled in the encoder. |
343 | * @see OPUS_SET_VBR_CONSTRAINT |
344 | * @see OPUS_GET_VBR |
345 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
346 | * <dl> |
347 | * <dt>0</dt><dd>Unconstrained VBR.</dd> |
348 | * <dt>1</dt><dd>Constrained VBR (default).</dd> |
349 | * </dl> |
350 | * @hideinitializer */ |
351 | #define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x) |
352 | |
353 | /** Configures mono/stereo forcing in the encoder. |
354 | * This can force the encoder to produce packets encoded as either mono or |
355 | * stereo, regardless of the format of the input audio. This is useful when |
356 | * the caller knows that the input signal is currently a mono source embedded |
357 | * in a stereo stream. |
358 | * @see OPUS_GET_FORCE_CHANNELS |
359 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
360 | * <dl> |
361 | * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd> |
362 | * <dt>1</dt> <dd>Forced mono</dd> |
363 | * <dt>2</dt> <dd>Forced stereo</dd> |
364 | * </dl> |
365 | * @hideinitializer */ |
366 | #define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x) |
367 | /** Gets the encoder's forced channel configuration. |
368 | * @see OPUS_SET_FORCE_CHANNELS |
369 | * @param[out] x <tt>opus_int32 *</tt>: |
370 | * <dl> |
371 | * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd> |
372 | * <dt>1</dt> <dd>Forced mono</dd> |
373 | * <dt>2</dt> <dd>Forced stereo</dd> |
374 | * </dl> |
375 | * @hideinitializer */ |
376 | #define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x) |
377 | |
378 | /** Configures the maximum bandpass that the encoder will select automatically. |
379 | * Applications should normally use this instead of #OPUS_SET_BANDWIDTH |
380 | * (leaving that set to the default, #OPUS_AUTO). This allows the |
381 | * application to set an upper bound based on the type of input it is |
382 | * providing, but still gives the encoder the freedom to reduce the bandpass |
383 | * when the bitrate becomes too low, for better overall quality. |
384 | * @see OPUS_GET_MAX_BANDWIDTH |
385 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
386 | * <dl> |
387 | * <dt>OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
388 | * <dt>OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
389 | * <dt>OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
390 | * <dt>OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
391 | * <dt>OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd> |
392 | * </dl> |
393 | * @hideinitializer */ |
394 | #define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x) |
395 | |
396 | /** Gets the encoder's configured maximum allowed bandpass. |
397 | * @see OPUS_SET_MAX_BANDWIDTH |
398 | * @param[out] x <tt>opus_int32 *</tt>: Allowed values: |
399 | * <dl> |
400 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
401 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
402 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
403 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
404 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd> |
405 | * </dl> |
406 | * @hideinitializer */ |
407 | #define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) |
408 | |
409 | /** Sets the encoder's bandpass to a specific value. |
410 | * This prevents the encoder from automatically selecting the bandpass based |
411 | * on the available bitrate. If an application knows the bandpass of the input |
412 | * audio it is providing, it should normally use #OPUS_SET_MAX_BANDWIDTH |
413 | * instead, which still gives the encoder the freedom to reduce the bandpass |
414 | * when the bitrate becomes too low, for better overall quality. |
415 | * @see OPUS_GET_BANDWIDTH |
416 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
417 | * <dl> |
418 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
419 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
420 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
421 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
422 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
423 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd> |
424 | * </dl> |
425 | * @hideinitializer */ |
426 | #define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x) |
427 | |
428 | /** Configures the type of signal being encoded. |
429 | * This is a hint which helps the encoder's mode selection. |
430 | * @see OPUS_GET_SIGNAL |
431 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
432 | * <dl> |
433 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
434 | * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd> |
435 | * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd> |
436 | * </dl> |
437 | * @hideinitializer */ |
438 | #define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x) |
439 | /** Gets the encoder's configured signal type. |
440 | * @see OPUS_SET_SIGNAL |
441 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
442 | * <dl> |
443 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
444 | * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd> |
445 | * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd> |
446 | * </dl> |
447 | * @hideinitializer */ |
448 | #define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x) |
449 | |
450 | |
451 | /** Configures the encoder's intended application. |
452 | * The initial value is a mandatory argument to the encoder_create function. |
453 | * @see OPUS_GET_APPLICATION |
454 | * @param[in] x <tt>opus_int32</tt>: Returns one of the following values: |
455 | * <dl> |
456 | * <dt>#OPUS_APPLICATION_VOIP</dt> |
457 | * <dd>Process signal for improved speech intelligibility.</dd> |
458 | * <dt>#OPUS_APPLICATION_AUDIO</dt> |
459 | * <dd>Favor faithfulness to the original input.</dd> |
460 | * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt> |
461 | * <dd>Configure the minimum possible coding delay by disabling certain modes |
462 | * of operation.</dd> |
463 | * </dl> |
464 | * @hideinitializer */ |
465 | #define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x) |
466 | /** Gets the encoder's configured application. |
467 | * @see OPUS_SET_APPLICATION |
468 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
469 | * <dl> |
470 | * <dt>#OPUS_APPLICATION_VOIP</dt> |
471 | * <dd>Process signal for improved speech intelligibility.</dd> |
472 | * <dt>#OPUS_APPLICATION_AUDIO</dt> |
473 | * <dd>Favor faithfulness to the original input.</dd> |
474 | * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt> |
475 | * <dd>Configure the minimum possible coding delay by disabling certain modes |
476 | * of operation.</dd> |
477 | * </dl> |
478 | * @hideinitializer */ |
479 | #define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x) |
480 | |
481 | /** Gets the total samples of delay added by the entire codec. |
482 | * This can be queried by the encoder and then the provided number of samples can be |
483 | * skipped on from the start of the decoder's output to provide time aligned input |
484 | * and output. From the perspective of a decoding application the real data begins this many |
485 | * samples late. |
486 | * |
487 | * The decoder contribution to this delay is identical for all decoders, but the |
488 | * encoder portion of the delay may vary from implementation to implementation, |
489 | * version to version, or even depend on the encoder's initial configuration. |
490 | * Applications needing delay compensation should call this CTL rather than |
491 | * hard-coding a value. |
492 | * @param[out] x <tt>opus_int32 *</tt>: Number of lookahead samples |
493 | * @hideinitializer */ |
494 | #define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x) |
495 | |
496 | /** Configures the encoder's use of inband forward error correction (FEC). |
497 | * @note This is only applicable to the LPC layer |
498 | * @see OPUS_GET_INBAND_FEC |
499 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
500 | * <dl> |
501 | * <dt>0</dt><dd>Disable inband FEC (default).</dd> |
502 | * <dt>1</dt><dd>Inband FEC enabled. If the packet loss rate is sufficiently high, Opus will automatically switch to SILK even at high rates to enable use of that FEC.</dd> |
503 | * <dt>2</dt><dd>Inband FEC enabled, but does not necessarily switch to SILK if we have music.</dd> |
504 | * </dl> |
505 | * @hideinitializer */ |
506 | #define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x) |
507 | /** Gets encoder's configured use of inband forward error correction. |
508 | * @see OPUS_SET_INBAND_FEC |
509 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
510 | * <dl> |
511 | * <dt>0</dt><dd>Inband FEC disabled (default).</dd> |
512 | * <dt>1</dt><dd>Inband FEC enabled. If the packet loss rate is sufficiently high, Opus will automatically switch to SILK even at high rates to enable use of that FEC.</dd> |
513 | * <dt>2</dt><dd>Inband FEC enabled, but does not necessarily switch to SILK if we have music.</dd> |
514 | * </dl> |
515 | * @hideinitializer */ |
516 | #define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x) |
517 | |
518 | /** Configures the encoder's expected packet loss percentage. |
519 | * Higher values trigger progressively more loss resistant behavior in the encoder |
520 | * at the expense of quality at a given bitrate in the absence of packet loss, but |
521 | * greater quality under loss. |
522 | * @see OPUS_GET_PACKET_LOSS_PERC |
523 | * @param[in] x <tt>opus_int32</tt>: Loss percentage in the range 0-100, inclusive (default: 0). |
524 | * @hideinitializer */ |
525 | #define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x) |
526 | /** Gets the encoder's configured packet loss percentage. |
527 | * @see OPUS_SET_PACKET_LOSS_PERC |
528 | * @param[out] x <tt>opus_int32 *</tt>: Returns the configured loss percentage |
529 | * in the range 0-100, inclusive (default: 0). |
530 | * @hideinitializer */ |
531 | #define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x) |
532 | |
533 | /** Configures the encoder's use of discontinuous transmission (DTX). |
534 | * @note This is only applicable to the LPC layer |
535 | * @see OPUS_GET_DTX |
536 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
537 | * <dl> |
538 | * <dt>0</dt><dd>Disable DTX (default).</dd> |
539 | * <dt>1</dt><dd>Enabled DTX.</dd> |
540 | * </dl> |
541 | * @hideinitializer */ |
542 | #define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x) |
543 | /** Gets encoder's configured use of discontinuous transmission. |
544 | * @see OPUS_SET_DTX |
545 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
546 | * <dl> |
547 | * <dt>0</dt><dd>DTX disabled (default).</dd> |
548 | * <dt>1</dt><dd>DTX enabled.</dd> |
549 | * </dl> |
550 | * @hideinitializer */ |
551 | #define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x) |
552 | /** Configures the depth of signal being encoded. |
553 | * |
554 | * This is a hint which helps the encoder identify silence and near-silence. |
555 | * It represents the number of significant bits of linear intensity below |
556 | * which the signal contains ignorable quantization or other noise. |
557 | * |
558 | * For example, OPUS_SET_LSB_DEPTH(14) would be an appropriate setting |
559 | * for G.711 u-law input. OPUS_SET_LSB_DEPTH(16) would be appropriate |
560 | * for 16-bit linear pcm input with opus_encode_float(). |
561 | * |
562 | * When using opus_encode() instead of opus_encode_float(), or when libopus |
563 | * is compiled for fixed-point, the encoder uses the minimum of the value |
564 | * set here and the value 16. |
565 | * |
566 | * @see OPUS_GET_LSB_DEPTH |
567 | * @param[in] x <tt>opus_int32</tt>: Input precision in bits, between 8 and 24 |
568 | * (default: 24). |
569 | * @hideinitializer */ |
570 | #define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x) |
571 | /** Gets the encoder's configured signal depth. |
572 | * @see OPUS_SET_LSB_DEPTH |
573 | * @param[out] x <tt>opus_int32 *</tt>: Input precision in bits, between 8 and |
574 | * 24 (default: 24). |
575 | * @hideinitializer */ |
576 | #define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x) |
577 | |
578 | /** Configures the encoder's use of variable duration frames. |
579 | * When variable duration is enabled, the encoder is free to use a shorter frame |
580 | * size than the one requested in the opus_encode*() call. |
581 | * It is then the user's responsibility |
582 | * to verify how much audio was encoded by checking the ToC byte of the encoded |
583 | * packet. The part of the audio that was not encoded needs to be resent to the |
584 | * encoder for the next call. Do not use this option unless you <b>really</b> |
585 | * know what you are doing. |
586 | * @see OPUS_GET_EXPERT_FRAME_DURATION |
587 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
588 | * <dl> |
589 | * <dt>OPUS_FRAMESIZE_ARG</dt><dd>Select frame size from the argument (default).</dd> |
590 | * <dt>OPUS_FRAMESIZE_2_5_MS</dt><dd>Use 2.5 ms frames.</dd> |
591 | * <dt>OPUS_FRAMESIZE_5_MS</dt><dd>Use 5 ms frames.</dd> |
592 | * <dt>OPUS_FRAMESIZE_10_MS</dt><dd>Use 10 ms frames.</dd> |
593 | * <dt>OPUS_FRAMESIZE_20_MS</dt><dd>Use 20 ms frames.</dd> |
594 | * <dt>OPUS_FRAMESIZE_40_MS</dt><dd>Use 40 ms frames.</dd> |
595 | * <dt>OPUS_FRAMESIZE_60_MS</dt><dd>Use 60 ms frames.</dd> |
596 | * <dt>OPUS_FRAMESIZE_80_MS</dt><dd>Use 80 ms frames.</dd> |
597 | * <dt>OPUS_FRAMESIZE_100_MS</dt><dd>Use 100 ms frames.</dd> |
598 | * <dt>OPUS_FRAMESIZE_120_MS</dt><dd>Use 120 ms frames.</dd> |
599 | * </dl> |
600 | * @hideinitializer */ |
601 | #define OPUS_SET_EXPERT_FRAME_DURATION(x) OPUS_SET_EXPERT_FRAME_DURATION_REQUEST, __opus_check_int(x) |
602 | /** Gets the encoder's configured use of variable duration frames. |
603 | * @see OPUS_SET_EXPERT_FRAME_DURATION |
604 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
605 | * <dl> |
606 | * <dt>OPUS_FRAMESIZE_ARG</dt><dd>Select frame size from the argument (default).</dd> |
607 | * <dt>OPUS_FRAMESIZE_2_5_MS</dt><dd>Use 2.5 ms frames.</dd> |
608 | * <dt>OPUS_FRAMESIZE_5_MS</dt><dd>Use 5 ms frames.</dd> |
609 | * <dt>OPUS_FRAMESIZE_10_MS</dt><dd>Use 10 ms frames.</dd> |
610 | * <dt>OPUS_FRAMESIZE_20_MS</dt><dd>Use 20 ms frames.</dd> |
611 | * <dt>OPUS_FRAMESIZE_40_MS</dt><dd>Use 40 ms frames.</dd> |
612 | * <dt>OPUS_FRAMESIZE_60_MS</dt><dd>Use 60 ms frames.</dd> |
613 | * <dt>OPUS_FRAMESIZE_80_MS</dt><dd>Use 80 ms frames.</dd> |
614 | * <dt>OPUS_FRAMESIZE_100_MS</dt><dd>Use 100 ms frames.</dd> |
615 | * <dt>OPUS_FRAMESIZE_120_MS</dt><dd>Use 120 ms frames.</dd> |
616 | * </dl> |
617 | * @hideinitializer */ |
618 | #define OPUS_GET_EXPERT_FRAME_DURATION(x) OPUS_GET_EXPERT_FRAME_DURATION_REQUEST, __opus_check_int_ptr(x) |
619 | |
620 | /** If set to 1, disables almost all use of prediction, making frames almost |
621 | * completely independent. This reduces quality. |
622 | * @see OPUS_GET_PREDICTION_DISABLED |
623 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
624 | * <dl> |
625 | * <dt>0</dt><dd>Enable prediction (default).</dd> |
626 | * <dt>1</dt><dd>Disable prediction.</dd> |
627 | * </dl> |
628 | * @hideinitializer */ |
629 | #define OPUS_SET_PREDICTION_DISABLED(x) OPUS_SET_PREDICTION_DISABLED_REQUEST, __opus_check_int(x) |
630 | /** Gets the encoder's configured prediction status. |
631 | * @see OPUS_SET_PREDICTION_DISABLED |
632 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
633 | * <dl> |
634 | * <dt>0</dt><dd>Prediction enabled (default).</dd> |
635 | * <dt>1</dt><dd>Prediction disabled.</dd> |
636 | * </dl> |
637 | * @hideinitializer */ |
638 | #define OPUS_GET_PREDICTION_DISABLED(x) OPUS_GET_PREDICTION_DISABLED_REQUEST, __opus_check_int_ptr(x) |
639 | |
640 | /** If non-zero, enables Deep Redundancy (DRED) and use the specified maximum number of 10-ms redundant frames |
641 | * @hideinitializer */ |
642 | #define OPUS_SET_DRED_DURATION(x) OPUS_SET_DRED_DURATION_REQUEST, __opus_check_int(x) |
643 | /** Gets the encoder's configured Deep Redundancy (DRED) maximum number of frames. |
644 | * @hideinitializer */ |
645 | #define OPUS_GET_DRED_DURATION(x) OPUS_GET_DRED_DURATION_REQUEST, __opus_check_int_ptr(x) |
646 | |
647 | /** Provide external DNN weights from binary object (only when explicitly built without the weights) |
648 | * @hideinitializer */ |
649 | #define OPUS_SET_DNN_BLOB(data, len) OPUS_SET_DNN_BLOB_REQUEST, __opus_check_void_ptr(data), __opus_check_int(len) |
650 | |
651 | |
652 | /**@}*/ |
653 | |
654 | /** @defgroup opus_genericctls Generic CTLs |
655 | * |
656 | * These macros are used with the \c opus_decoder_ctl and |
657 | * \c opus_encoder_ctl calls to generate a particular |
658 | * request. |
659 | * |
660 | * When called on an \c OpusDecoder they apply to that |
661 | * particular decoder instance. When called on an |
662 | * \c OpusEncoder they apply to the corresponding setting |
663 | * on that encoder instance, if present. |
664 | * |
665 | * Some usage examples: |
666 | * |
667 | * @code |
668 | * int ret; |
669 | * opus_int32 pitch; |
670 | * ret = opus_decoder_ctl(dec_ctx, OPUS_GET_PITCH(&pitch)); |
671 | * if (ret == OPUS_OK) return ret; |
672 | * |
673 | * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); |
674 | * opus_decoder_ctl(dec_ctx, OPUS_RESET_STATE); |
675 | * |
676 | * opus_int32 enc_bw, dec_bw; |
677 | * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&enc_bw)); |
678 | * opus_decoder_ctl(dec_ctx, OPUS_GET_BANDWIDTH(&dec_bw)); |
679 | * if (enc_bw != dec_bw) { |
680 | * printf("packet bandwidth mismatch!\n"); |
681 | * } |
682 | * @endcode |
683 | * |
684 | * @see opus_encoder, opus_decoder_ctl, opus_encoder_ctl, opus_decoderctls, opus_encoderctls |
685 | * @{ |
686 | */ |
687 | |
688 | /** Resets the codec state to be equivalent to a freshly initialized state. |
689 | * This should be called when switching streams in order to prevent |
690 | * the back to back decoding from giving different results from |
691 | * one at a time decoding. |
692 | * @hideinitializer */ |
693 | #define OPUS_RESET_STATE 4028 |
694 | |
695 | /** Gets the final state of the codec's entropy coder. |
696 | * This is used for testing purposes, |
697 | * The encoder and decoder state should be identical after coding a payload |
698 | * (assuming no data corruption or software bugs) |
699 | * |
700 | * @param[out] x <tt>opus_uint32 *</tt>: Entropy coder state |
701 | * |
702 | * @hideinitializer */ |
703 | #define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x) |
704 | |
705 | /** Gets the encoder's configured bandpass or the decoder's last bandpass. |
706 | * @see OPUS_SET_BANDWIDTH |
707 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
708 | * <dl> |
709 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
710 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
711 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
712 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
713 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
714 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd> |
715 | * </dl> |
716 | * @hideinitializer */ |
717 | #define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) |
718 | |
719 | /** Gets the sampling rate the encoder or decoder was initialized with. |
720 | * This simply returns the <code>Fs</code> value passed to opus_encoder_init() |
721 | * or opus_decoder_init(). |
722 | * @param[out] x <tt>opus_int32 *</tt>: Sampling rate of encoder or decoder. |
723 | * @hideinitializer |
724 | */ |
725 | #define OPUS_GET_SAMPLE_RATE(x) OPUS_GET_SAMPLE_RATE_REQUEST, __opus_check_int_ptr(x) |
726 | |
727 | /** If set to 1, disables the use of phase inversion for intensity stereo, |
728 | * improving the quality of mono downmixes, but slightly reducing normal |
729 | * stereo quality. Disabling phase inversion in the decoder does not comply |
730 | * with RFC 6716, although it does not cause any interoperability issue and |
731 | * is expected to become part of the Opus standard once RFC 6716 is updated |
732 | * by draft-ietf-codec-opus-update. |
733 | * @see OPUS_GET_PHASE_INVERSION_DISABLED |
734 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
735 | * <dl> |
736 | * <dt>0</dt><dd>Enable phase inversion (default).</dd> |
737 | * <dt>1</dt><dd>Disable phase inversion.</dd> |
738 | * </dl> |
739 | * @hideinitializer */ |
740 | #define OPUS_SET_PHASE_INVERSION_DISABLED(x) OPUS_SET_PHASE_INVERSION_DISABLED_REQUEST, __opus_check_int(x) |
741 | /** Gets the encoder's configured phase inversion status. |
742 | * @see OPUS_SET_PHASE_INVERSION_DISABLED |
743 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
744 | * <dl> |
745 | * <dt>0</dt><dd>Stereo phase inversion enabled (default).</dd> |
746 | * <dt>1</dt><dd>Stereo phase inversion disabled.</dd> |
747 | * </dl> |
748 | * @hideinitializer */ |
749 | #define OPUS_GET_PHASE_INVERSION_DISABLED(x) OPUS_GET_PHASE_INVERSION_DISABLED_REQUEST, __opus_check_int_ptr(x) |
750 | /** Gets the DTX state of the encoder. |
751 | * Returns whether the last encoded frame was either a comfort noise update |
752 | * during DTX or not encoded because of DTX. |
753 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
754 | * <dl> |
755 | * <dt>0</dt><dd>The encoder is not in DTX.</dd> |
756 | * <dt>1</dt><dd>The encoder is in DTX.</dd> |
757 | * </dl> |
758 | * @hideinitializer */ |
759 | #define OPUS_GET_IN_DTX(x) OPUS_GET_IN_DTX_REQUEST, __opus_check_int_ptr(x) |
760 | |
761 | /**@}*/ |
762 | |
763 | /** @defgroup opus_decoderctls Decoder related CTLs |
764 | * @see opus_genericctls, opus_encoderctls, opus_decoder |
765 | * @{ |
766 | */ |
767 | |
768 | /** Configures decoder gain adjustment. |
769 | * Scales the decoded output by a factor specified in Q8 dB units. |
770 | * This has a maximum range of -32768 to 32767 inclusive, and returns |
771 | * OPUS_BAD_ARG otherwise. The default is zero indicating no adjustment. |
772 | * This setting survives decoder reset. |
773 | * |
774 | * gain = pow(10, x/(20.0*256)) |
775 | * |
776 | * @param[in] x <tt>opus_int32</tt>: Amount to scale PCM signal by in Q8 dB units. |
777 | * @hideinitializer */ |
778 | #define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x) |
779 | /** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN |
780 | * |
781 | * @param[out] x <tt>opus_int32 *</tt>: Amount to scale PCM signal by in Q8 dB units. |
782 | * @hideinitializer */ |
783 | #define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x) |
784 | |
785 | /** Gets the duration (in samples) of the last packet successfully decoded or concealed. |
786 | * @param[out] x <tt>opus_int32 *</tt>: Number of samples (at current sampling rate). |
787 | * @hideinitializer */ |
788 | #define OPUS_GET_LAST_PACKET_DURATION(x) OPUS_GET_LAST_PACKET_DURATION_REQUEST, __opus_check_int_ptr(x) |
789 | |
790 | /** Gets the pitch of the last decoded frame, if available. |
791 | * This can be used for any post-processing algorithm requiring the use of pitch, |
792 | * e.g. time stretching/shortening. If the last frame was not voiced, or if the |
793 | * pitch was not coded in the frame, then zero is returned. |
794 | * |
795 | * This CTL is only implemented for decoder instances. |
796 | * |
797 | * @param[out] x <tt>opus_int32 *</tt>: pitch period at 48 kHz (or 0 if not available) |
798 | * |
799 | * @hideinitializer */ |
800 | #define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x) |
801 | |
802 | /**@}*/ |
803 | |
804 | /** @defgroup opus_libinfo Opus library information functions |
805 | * @{ |
806 | */ |
807 | |
808 | /** Converts an opus error code into a human readable string. |
809 | * |
810 | * @param[in] error <tt>int</tt>: Error number |
811 | * @returns Error string |
812 | */ |
813 | OPUS_EXPORT const char *opus_strerror(int error); |
814 | |
815 | /** Gets the libopus version string. |
816 | * |
817 | * Applications may look for the substring "-fixed" in the version string to |
818 | * determine whether they have a fixed-point or floating-point build at |
819 | * runtime. |
820 | * |
821 | * @returns Version string |
822 | */ |
823 | OPUS_EXPORT const char *opus_get_version_string(void); |
824 | /**@}*/ |
825 | |
826 | #ifdef __cplusplus |
827 | } |
828 | #endif |
829 | |
830 | #endif /* OPUS_DEFINES_H */ |
831 | |