Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 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 |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 49 | /** Not enough bytes allocated in the buffer @hideinitializer*/ |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 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) |
Felicia Lim | d03c373 | 2016-07-25 20:28:37 +0200 | [diff] [blame] | 68 | # if defined(OPUS_BUILD) && defined(DLL_EXPORT) |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 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 | |
| 169 | /* Don't use 4045, it's already taken by OPUS_GET_GAIN_REQUEST */ |
| 170 | |
| 171 | /* Macros to trigger compilation errors when the wrong types are provided to a CTL */ |
| 172 | #define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x)) |
| 173 | #define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr))) |
| 174 | #define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr))) |
| 175 | #define __opus_check_val16_ptr(ptr) ((ptr) + ((ptr) - (opus_val16*)(ptr))) |
| 176 | /** @endcond */ |
| 177 | |
| 178 | /** @defgroup opus_ctlvalues Pre-defined values for CTL interface |
| 179 | * @see opus_genericctls, opus_encoderctls |
| 180 | * @{ |
| 181 | */ |
| 182 | /* Values for the various encoder CTLs */ |
| 183 | #define OPUS_AUTO -1000 /**<Auto/default setting @hideinitializer*/ |
| 184 | #define OPUS_BITRATE_MAX -1 /**<Maximum bitrate @hideinitializer*/ |
| 185 | |
| 186 | /** Best for most VoIP/videoconference applications where listening quality and intelligibility matter most |
| 187 | * @hideinitializer */ |
| 188 | #define OPUS_APPLICATION_VOIP 2048 |
| 189 | /** Best for broadcast/high-fidelity application where the decoded audio should be as close as possible to the input |
| 190 | * @hideinitializer */ |
| 191 | #define OPUS_APPLICATION_AUDIO 2049 |
| 192 | /** Only use when lowest-achievable latency is what matters most. Voice-optimized modes cannot be used. |
| 193 | * @hideinitializer */ |
| 194 | #define OPUS_APPLICATION_RESTRICTED_LOWDELAY 2051 |
| 195 | |
| 196 | #define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */ |
| 197 | #define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */ |
| 198 | #define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4 kHz bandpass @hideinitializer*/ |
| 199 | #define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6 kHz bandpass @hideinitializer*/ |
| 200 | #define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8 kHz bandpass @hideinitializer*/ |
| 201 | #define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12 kHz bandpass @hideinitializer*/ |
| 202 | #define OPUS_BANDWIDTH_FULLBAND 1105 /**<20 kHz bandpass @hideinitializer*/ |
| 203 | |
| 204 | #define OPUS_FRAMESIZE_ARG 5000 /**< Select frame size from the argument (default) */ |
| 205 | #define OPUS_FRAMESIZE_2_5_MS 5001 /**< Use 2.5 ms frames */ |
| 206 | #define OPUS_FRAMESIZE_5_MS 5002 /**< Use 5 ms frames */ |
| 207 | #define OPUS_FRAMESIZE_10_MS 5003 /**< Use 10 ms frames */ |
| 208 | #define OPUS_FRAMESIZE_20_MS 5004 /**< Use 20 ms frames */ |
| 209 | #define OPUS_FRAMESIZE_40_MS 5005 /**< Use 40 ms frames */ |
| 210 | #define OPUS_FRAMESIZE_60_MS 5006 /**< Use 60 ms frames */ |
| 211 | |
| 212 | /**@}*/ |
| 213 | |
| 214 | |
| 215 | /** @defgroup opus_encoderctls Encoder related CTLs |
| 216 | * |
| 217 | * These are convenience macros for use with the \c opus_encode_ctl |
| 218 | * interface. They are used to generate the appropriate series of |
| 219 | * arguments for that call, passing the correct type, size and so |
| 220 | * on as expected for each particular request. |
| 221 | * |
| 222 | * Some usage examples: |
| 223 | * |
| 224 | * @code |
| 225 | * int ret; |
| 226 | * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO)); |
| 227 | * if (ret != OPUS_OK) return ret; |
| 228 | * |
| 229 | * opus_int32 rate; |
| 230 | * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate)); |
| 231 | * |
| 232 | * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); |
| 233 | * @endcode |
| 234 | * |
| 235 | * @see opus_genericctls, opus_encoder |
| 236 | * @{ |
| 237 | */ |
| 238 | |
| 239 | /** Configures the encoder's computational complexity. |
| 240 | * The supported range is 0-10 inclusive with 10 representing the highest complexity. |
| 241 | * @see OPUS_GET_COMPLEXITY |
| 242 | * @param[in] x <tt>opus_int32</tt>: Allowed values: 0-10, inclusive. |
| 243 | * |
| 244 | * @hideinitializer */ |
| 245 | #define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x) |
| 246 | /** Gets the encoder's complexity configuration. |
| 247 | * @see OPUS_SET_COMPLEXITY |
| 248 | * @param[out] x <tt>opus_int32 *</tt>: Returns a value in the range 0-10, |
| 249 | * inclusive. |
| 250 | * @hideinitializer */ |
| 251 | #define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x) |
| 252 | |
| 253 | /** Configures the bitrate in the encoder. |
| 254 | * Rates from 500 to 512000 bits per second are meaningful, as well as the |
| 255 | * special values #OPUS_AUTO and #OPUS_BITRATE_MAX. |
| 256 | * The value #OPUS_BITRATE_MAX can be used to cause the codec to use as much |
| 257 | * rate as it can, which is useful for controlling the rate by adjusting the |
| 258 | * output buffer size. |
| 259 | * @see OPUS_GET_BITRATE |
| 260 | * @param[in] x <tt>opus_int32</tt>: Bitrate in bits per second. The default |
| 261 | * is determined based on the number of |
| 262 | * channels and the input sampling rate. |
| 263 | * @hideinitializer */ |
| 264 | #define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x) |
| 265 | /** Gets the encoder's bitrate configuration. |
| 266 | * @see OPUS_SET_BITRATE |
| 267 | * @param[out] x <tt>opus_int32 *</tt>: Returns the bitrate in bits per second. |
| 268 | * The default is determined based on the |
| 269 | * number of channels and the input |
| 270 | * sampling rate. |
| 271 | * @hideinitializer */ |
| 272 | #define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x) |
| 273 | |
| 274 | /** Enables or disables variable bitrate (VBR) in the encoder. |
| 275 | * The configured bitrate may not be met exactly because frames must |
| 276 | * be an integer number of bytes in length. |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 277 | * @see OPUS_GET_VBR |
| 278 | * @see OPUS_SET_VBR_CONSTRAINT |
| 279 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 280 | * <dl> |
| 281 | * <dt>0</dt><dd>Hard CBR. For LPC/hybrid modes at very low bit-rate, this can |
| 282 | * cause noticeable quality degradation.</dd> |
| 283 | * <dt>1</dt><dd>VBR (default). The exact type of VBR is controlled by |
| 284 | * #OPUS_SET_VBR_CONSTRAINT.</dd> |
| 285 | * </dl> |
| 286 | * @hideinitializer */ |
| 287 | #define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x) |
| 288 | /** Determine if variable bitrate (VBR) is enabled in the encoder. |
| 289 | * @see OPUS_SET_VBR |
| 290 | * @see OPUS_GET_VBR_CONSTRAINT |
| 291 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 292 | * <dl> |
| 293 | * <dt>0</dt><dd>Hard CBR.</dd> |
| 294 | * <dt>1</dt><dd>VBR (default). The exact type of VBR may be retrieved via |
| 295 | * #OPUS_GET_VBR_CONSTRAINT.</dd> |
| 296 | * </dl> |
| 297 | * @hideinitializer */ |
| 298 | #define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x) |
| 299 | |
| 300 | /** Enables or disables constrained VBR in the encoder. |
| 301 | * This setting is ignored when the encoder is in CBR mode. |
| 302 | * @warning Only the MDCT mode of Opus currently heeds the constraint. |
| 303 | * Speech mode ignores it completely, hybrid mode may fail to obey it |
| 304 | * if the LPC layer uses more bitrate than the constraint would have |
| 305 | * permitted. |
| 306 | * @see OPUS_GET_VBR_CONSTRAINT |
| 307 | * @see OPUS_SET_VBR |
| 308 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 309 | * <dl> |
| 310 | * <dt>0</dt><dd>Unconstrained VBR.</dd> |
| 311 | * <dt>1</dt><dd>Constrained VBR (default). This creates a maximum of one |
| 312 | * frame of buffering delay assuming a transport with a |
| 313 | * serialization speed of the nominal bitrate.</dd> |
| 314 | * </dl> |
| 315 | * @hideinitializer */ |
| 316 | #define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x) |
| 317 | /** Determine if constrained VBR is enabled in the encoder. |
| 318 | * @see OPUS_SET_VBR_CONSTRAINT |
| 319 | * @see OPUS_GET_VBR |
| 320 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 321 | * <dl> |
| 322 | * <dt>0</dt><dd>Unconstrained VBR.</dd> |
| 323 | * <dt>1</dt><dd>Constrained VBR (default).</dd> |
| 324 | * </dl> |
| 325 | * @hideinitializer */ |
| 326 | #define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x) |
| 327 | |
| 328 | /** Configures mono/stereo forcing in the encoder. |
| 329 | * This can force the encoder to produce packets encoded as either mono or |
| 330 | * stereo, regardless of the format of the input audio. This is useful when |
| 331 | * the caller knows that the input signal is currently a mono source embedded |
| 332 | * in a stereo stream. |
| 333 | * @see OPUS_GET_FORCE_CHANNELS |
| 334 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 335 | * <dl> |
| 336 | * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd> |
| 337 | * <dt>1</dt> <dd>Forced mono</dd> |
| 338 | * <dt>2</dt> <dd>Forced stereo</dd> |
| 339 | * </dl> |
| 340 | * @hideinitializer */ |
| 341 | #define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x) |
| 342 | /** Gets the encoder's forced channel configuration. |
| 343 | * @see OPUS_SET_FORCE_CHANNELS |
| 344 | * @param[out] x <tt>opus_int32 *</tt>: |
| 345 | * <dl> |
| 346 | * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd> |
| 347 | * <dt>1</dt> <dd>Forced mono</dd> |
| 348 | * <dt>2</dt> <dd>Forced stereo</dd> |
| 349 | * </dl> |
| 350 | * @hideinitializer */ |
| 351 | #define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x) |
| 352 | |
| 353 | /** Configures the maximum bandpass that the encoder will select automatically. |
| 354 | * Applications should normally use this instead of #OPUS_SET_BANDWIDTH |
| 355 | * (leaving that set to the default, #OPUS_AUTO). This allows the |
| 356 | * application to set an upper bound based on the type of input it is |
| 357 | * providing, but still gives the encoder the freedom to reduce the bandpass |
| 358 | * when the bitrate becomes too low, for better overall quality. |
| 359 | * @see OPUS_GET_MAX_BANDWIDTH |
| 360 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 361 | * <dl> |
| 362 | * <dt>OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
| 363 | * <dt>OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
| 364 | * <dt>OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
| 365 | * <dt>OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
| 366 | * <dt>OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd> |
| 367 | * </dl> |
| 368 | * @hideinitializer */ |
| 369 | #define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x) |
| 370 | |
| 371 | /** Gets the encoder's configured maximum allowed bandpass. |
| 372 | * @see OPUS_SET_MAX_BANDWIDTH |
| 373 | * @param[out] x <tt>opus_int32 *</tt>: Allowed values: |
| 374 | * <dl> |
| 375 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
| 376 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
| 377 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
| 378 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
| 379 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd> |
| 380 | * </dl> |
| 381 | * @hideinitializer */ |
| 382 | #define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) |
| 383 | |
| 384 | /** Sets the encoder's bandpass to a specific value. |
| 385 | * This prevents the encoder from automatically selecting the bandpass based |
| 386 | * on the available bitrate. If an application knows the bandpass of the input |
| 387 | * audio it is providing, it should normally use #OPUS_SET_MAX_BANDWIDTH |
| 388 | * instead, which still gives the encoder the freedom to reduce the bandpass |
| 389 | * when the bitrate becomes too low, for better overall quality. |
| 390 | * @see OPUS_GET_BANDWIDTH |
| 391 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 392 | * <dl> |
| 393 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
| 394 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
| 395 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
| 396 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
| 397 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
| 398 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd> |
| 399 | * </dl> |
| 400 | * @hideinitializer */ |
| 401 | #define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x) |
| 402 | |
| 403 | /** Configures the type of signal being encoded. |
| 404 | * This is a hint which helps the encoder's mode selection. |
| 405 | * @see OPUS_GET_SIGNAL |
| 406 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 407 | * <dl> |
| 408 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
| 409 | * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd> |
| 410 | * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd> |
| 411 | * </dl> |
| 412 | * @hideinitializer */ |
| 413 | #define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x) |
| 414 | /** Gets the encoder's configured signal type. |
| 415 | * @see OPUS_SET_SIGNAL |
| 416 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 417 | * <dl> |
| 418 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
| 419 | * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd> |
| 420 | * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd> |
| 421 | * </dl> |
| 422 | * @hideinitializer */ |
| 423 | #define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x) |
| 424 | |
| 425 | |
| 426 | /** Configures the encoder's intended application. |
| 427 | * The initial value is a mandatory argument to the encoder_create function. |
| 428 | * @see OPUS_GET_APPLICATION |
| 429 | * @param[in] x <tt>opus_int32</tt>: Returns one of the following values: |
| 430 | * <dl> |
| 431 | * <dt>#OPUS_APPLICATION_VOIP</dt> |
| 432 | * <dd>Process signal for improved speech intelligibility.</dd> |
| 433 | * <dt>#OPUS_APPLICATION_AUDIO</dt> |
| 434 | * <dd>Favor faithfulness to the original input.</dd> |
| 435 | * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt> |
| 436 | * <dd>Configure the minimum possible coding delay by disabling certain modes |
| 437 | * of operation.</dd> |
| 438 | * </dl> |
| 439 | * @hideinitializer */ |
| 440 | #define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x) |
| 441 | /** Gets the encoder's configured application. |
| 442 | * @see OPUS_SET_APPLICATION |
| 443 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 444 | * <dl> |
| 445 | * <dt>#OPUS_APPLICATION_VOIP</dt> |
| 446 | * <dd>Process signal for improved speech intelligibility.</dd> |
| 447 | * <dt>#OPUS_APPLICATION_AUDIO</dt> |
| 448 | * <dd>Favor faithfulness to the original input.</dd> |
| 449 | * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt> |
| 450 | * <dd>Configure the minimum possible coding delay by disabling certain modes |
| 451 | * of operation.</dd> |
| 452 | * </dl> |
| 453 | * @hideinitializer */ |
| 454 | #define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x) |
| 455 | |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 456 | /** Gets the total samples of delay added by the entire codec. |
| 457 | * This can be queried by the encoder and then the provided number of samples can be |
| 458 | * skipped on from the start of the decoder's output to provide time aligned input |
| 459 | * and output. From the perspective of a decoding application the real data begins this many |
| 460 | * samples late. |
| 461 | * |
| 462 | * The decoder contribution to this delay is identical for all decoders, but the |
| 463 | * encoder portion of the delay may vary from implementation to implementation, |
| 464 | * version to version, or even depend on the encoder's initial configuration. |
| 465 | * Applications needing delay compensation should call this CTL rather than |
| 466 | * hard-coding a value. |
| 467 | * @param[out] x <tt>opus_int32 *</tt>: Number of lookahead samples |
| 468 | * @hideinitializer */ |
| 469 | #define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x) |
| 470 | |
| 471 | /** Configures the encoder's use of inband forward error correction (FEC). |
| 472 | * @note This is only applicable to the LPC layer |
| 473 | * @see OPUS_GET_INBAND_FEC |
| 474 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 475 | * <dl> |
| 476 | * <dt>0</dt><dd>Disable inband FEC (default).</dd> |
| 477 | * <dt>1</dt><dd>Enable inband FEC.</dd> |
| 478 | * </dl> |
| 479 | * @hideinitializer */ |
| 480 | #define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x) |
| 481 | /** Gets encoder's configured use of inband forward error correction. |
| 482 | * @see OPUS_SET_INBAND_FEC |
| 483 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 484 | * <dl> |
| 485 | * <dt>0</dt><dd>Inband FEC disabled (default).</dd> |
| 486 | * <dt>1</dt><dd>Inband FEC enabled.</dd> |
| 487 | * </dl> |
| 488 | * @hideinitializer */ |
| 489 | #define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x) |
| 490 | |
| 491 | /** Configures the encoder's expected packet loss percentage. |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 492 | * Higher values trigger progressively more loss resistant behavior in the encoder |
| 493 | * at the expense of quality at a given bitrate in the absence of packet loss, but |
| 494 | * greater quality under loss. |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 495 | * @see OPUS_GET_PACKET_LOSS_PERC |
| 496 | * @param[in] x <tt>opus_int32</tt>: Loss percentage in the range 0-100, inclusive (default: 0). |
| 497 | * @hideinitializer */ |
| 498 | #define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x) |
| 499 | /** Gets the encoder's configured packet loss percentage. |
| 500 | * @see OPUS_SET_PACKET_LOSS_PERC |
| 501 | * @param[out] x <tt>opus_int32 *</tt>: Returns the configured loss percentage |
| 502 | * in the range 0-100, inclusive (default: 0). |
| 503 | * @hideinitializer */ |
| 504 | #define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x) |
| 505 | |
| 506 | /** Configures the encoder's use of discontinuous transmission (DTX). |
| 507 | * @note This is only applicable to the LPC layer |
| 508 | * @see OPUS_GET_DTX |
| 509 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 510 | * <dl> |
| 511 | * <dt>0</dt><dd>Disable DTX (default).</dd> |
| 512 | * <dt>1</dt><dd>Enabled DTX.</dd> |
| 513 | * </dl> |
| 514 | * @hideinitializer */ |
| 515 | #define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x) |
| 516 | /** Gets encoder's configured use of discontinuous transmission. |
| 517 | * @see OPUS_SET_DTX |
| 518 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 519 | * <dl> |
| 520 | * <dt>0</dt><dd>DTX disabled (default).</dd> |
| 521 | * <dt>1</dt><dd>DTX enabled.</dd> |
| 522 | * </dl> |
| 523 | * @hideinitializer */ |
| 524 | #define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x) |
| 525 | /** Configures the depth of signal being encoded. |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 526 | * |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 527 | * This is a hint which helps the encoder identify silence and near-silence. |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 528 | * It represents the number of significant bits of linear intensity below |
| 529 | * which the signal contains ignorable quantization or other noise. |
| 530 | * |
| 531 | * For example, OPUS_SET_LSB_DEPTH(14) would be an appropriate setting |
| 532 | * for G.711 u-law input. OPUS_SET_LSB_DEPTH(16) would be appropriate |
| 533 | * for 16-bit linear pcm input with opus_encode_float(). |
| 534 | * |
| 535 | * When using opus_encode() instead of opus_encode_float(), or when libopus |
| 536 | * is compiled for fixed-point, the encoder uses the minimum of the value |
| 537 | * set here and the value 16. |
| 538 | * |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 539 | * @see OPUS_GET_LSB_DEPTH |
| 540 | * @param[in] x <tt>opus_int32</tt>: Input precision in bits, between 8 and 24 |
| 541 | * (default: 24). |
| 542 | * @hideinitializer */ |
| 543 | #define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x) |
| 544 | /** Gets the encoder's configured signal depth. |
| 545 | * @see OPUS_SET_LSB_DEPTH |
| 546 | * @param[out] x <tt>opus_int32 *</tt>: Input precision in bits, between 8 and |
| 547 | * 24 (default: 24). |
| 548 | * @hideinitializer */ |
| 549 | #define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x) |
| 550 | |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 551 | /** Configures the encoder's use of variable duration frames. |
| 552 | * When variable duration is enabled, the encoder is free to use a shorter frame |
| 553 | * size than the one requested in the opus_encode*() call. |
| 554 | * It is then the user's responsibility |
| 555 | * to verify how much audio was encoded by checking the ToC byte of the encoded |
| 556 | * packet. The part of the audio that was not encoded needs to be resent to the |
| 557 | * encoder for the next call. Do not use this option unless you <b>really</b> |
| 558 | * know what you are doing. |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 559 | * @see OPUS_GET_EXPERT_FRAME_DURATION |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 560 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 561 | * <dl> |
| 562 | * <dt>OPUS_FRAMESIZE_ARG</dt><dd>Select frame size from the argument (default).</dd> |
| 563 | * <dt>OPUS_FRAMESIZE_2_5_MS</dt><dd>Use 2.5 ms frames.</dd> |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 564 | * <dt>OPUS_FRAMESIZE_5_MS</dt><dd>Use 5 ms frames.</dd> |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 565 | * <dt>OPUS_FRAMESIZE_10_MS</dt><dd>Use 10 ms frames.</dd> |
| 566 | * <dt>OPUS_FRAMESIZE_20_MS</dt><dd>Use 20 ms frames.</dd> |
| 567 | * <dt>OPUS_FRAMESIZE_40_MS</dt><dd>Use 40 ms frames.</dd> |
| 568 | * <dt>OPUS_FRAMESIZE_60_MS</dt><dd>Use 60 ms frames.</dd> |
| 569 | * <dt>OPUS_FRAMESIZE_VARIABLE</dt><dd>Optimize the frame size dynamically.</dd> |
| 570 | * </dl> |
| 571 | * @hideinitializer */ |
| 572 | #define OPUS_SET_EXPERT_FRAME_DURATION(x) OPUS_SET_EXPERT_FRAME_DURATION_REQUEST, __opus_check_int(x) |
| 573 | /** Gets the encoder's configured use of variable duration frames. |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 574 | * @see OPUS_SET_EXPERT_FRAME_DURATION |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 575 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 576 | * <dl> |
| 577 | * <dt>OPUS_FRAMESIZE_ARG</dt><dd>Select frame size from the argument (default).</dd> |
| 578 | * <dt>OPUS_FRAMESIZE_2_5_MS</dt><dd>Use 2.5 ms frames.</dd> |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 579 | * <dt>OPUS_FRAMESIZE_5_MS</dt><dd>Use 5 ms frames.</dd> |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 580 | * <dt>OPUS_FRAMESIZE_10_MS</dt><dd>Use 10 ms frames.</dd> |
| 581 | * <dt>OPUS_FRAMESIZE_20_MS</dt><dd>Use 20 ms frames.</dd> |
| 582 | * <dt>OPUS_FRAMESIZE_40_MS</dt><dd>Use 40 ms frames.</dd> |
| 583 | * <dt>OPUS_FRAMESIZE_60_MS</dt><dd>Use 60 ms frames.</dd> |
| 584 | * <dt>OPUS_FRAMESIZE_VARIABLE</dt><dd>Optimize the frame size dynamically.</dd> |
| 585 | * </dl> |
| 586 | * @hideinitializer */ |
| 587 | #define OPUS_GET_EXPERT_FRAME_DURATION(x) OPUS_GET_EXPERT_FRAME_DURATION_REQUEST, __opus_check_int_ptr(x) |
| 588 | |
| 589 | /** If set to 1, disables almost all use of prediction, making frames almost |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 590 | * completely independent. This reduces quality. |
| 591 | * @see OPUS_GET_PREDICTION_DISABLED |
| 592 | * @param[in] x <tt>opus_int32</tt>: Allowed values: |
| 593 | * <dl> |
| 594 | * <dt>0</dt><dd>Enable prediction (default).</dd> |
| 595 | * <dt>1</dt><dd>Disable prediction.</dd> |
| 596 | * </dl> |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 597 | * @hideinitializer */ |
| 598 | #define OPUS_SET_PREDICTION_DISABLED(x) OPUS_SET_PREDICTION_DISABLED_REQUEST, __opus_check_int(x) |
| 599 | /** Gets the encoder's configured prediction status. |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 600 | * @see OPUS_SET_PREDICTION_DISABLED |
| 601 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 602 | * <dl> |
| 603 | * <dt>0</dt><dd>Prediction enabled (default).</dd> |
| 604 | * <dt>1</dt><dd>Prediction disabled.</dd> |
| 605 | * </dl> |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 606 | * @hideinitializer */ |
| 607 | #define OPUS_GET_PREDICTION_DISABLED(x) OPUS_GET_PREDICTION_DISABLED_REQUEST, __opus_check_int_ptr(x) |
| 608 | |
| 609 | /**@}*/ |
| 610 | |
| 611 | /** @defgroup opus_genericctls Generic CTLs |
| 612 | * |
| 613 | * These macros are used with the \c opus_decoder_ctl and |
| 614 | * \c opus_encoder_ctl calls to generate a particular |
| 615 | * request. |
| 616 | * |
| 617 | * When called on an \c OpusDecoder they apply to that |
| 618 | * particular decoder instance. When called on an |
| 619 | * \c OpusEncoder they apply to the corresponding setting |
| 620 | * on that encoder instance, if present. |
| 621 | * |
| 622 | * Some usage examples: |
| 623 | * |
| 624 | * @code |
| 625 | * int ret; |
| 626 | * opus_int32 pitch; |
| 627 | * ret = opus_decoder_ctl(dec_ctx, OPUS_GET_PITCH(&pitch)); |
| 628 | * if (ret == OPUS_OK) return ret; |
| 629 | * |
| 630 | * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); |
| 631 | * opus_decoder_ctl(dec_ctx, OPUS_RESET_STATE); |
| 632 | * |
| 633 | * opus_int32 enc_bw, dec_bw; |
| 634 | * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&enc_bw)); |
| 635 | * opus_decoder_ctl(dec_ctx, OPUS_GET_BANDWIDTH(&dec_bw)); |
| 636 | * if (enc_bw != dec_bw) { |
| 637 | * printf("packet bandwidth mismatch!\n"); |
| 638 | * } |
| 639 | * @endcode |
| 640 | * |
| 641 | * @see opus_encoder, opus_decoder_ctl, opus_encoder_ctl, opus_decoderctls, opus_encoderctls |
| 642 | * @{ |
| 643 | */ |
| 644 | |
| 645 | /** Resets the codec state to be equivalent to a freshly initialized state. |
| 646 | * This should be called when switching streams in order to prevent |
| 647 | * the back to back decoding from giving different results from |
| 648 | * one at a time decoding. |
| 649 | * @hideinitializer */ |
| 650 | #define OPUS_RESET_STATE 4028 |
| 651 | |
| 652 | /** Gets the final state of the codec's entropy coder. |
| 653 | * This is used for testing purposes, |
| 654 | * The encoder and decoder state should be identical after coding a payload |
| 655 | * (assuming no data corruption or software bugs) |
| 656 | * |
| 657 | * @param[out] x <tt>opus_uint32 *</tt>: Entropy coder state |
| 658 | * |
| 659 | * @hideinitializer */ |
| 660 | #define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x) |
| 661 | |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 662 | /** Gets the encoder's configured bandpass or the decoder's last bandpass. |
| 663 | * @see OPUS_SET_BANDWIDTH |
| 664 | * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values: |
| 665 | * <dl> |
| 666 | * <dt>#OPUS_AUTO</dt> <dd>(default)</dd> |
| 667 | * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd> |
| 668 | * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd> |
| 669 | * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd> |
| 670 | * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd> |
| 671 | * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd> |
| 672 | * </dl> |
| 673 | * @hideinitializer */ |
| 674 | #define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) |
| 675 | |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 676 | /** Gets the sampling rate the encoder or decoder was initialized with. |
| 677 | * This simply returns the <code>Fs</code> value passed to opus_encoder_init() |
| 678 | * or opus_decoder_init(). |
| 679 | * @param[out] x <tt>opus_int32 *</tt>: Sampling rate of encoder or decoder. |
| 680 | * @hideinitializer |
| 681 | */ |
| 682 | #define OPUS_GET_SAMPLE_RATE(x) OPUS_GET_SAMPLE_RATE_REQUEST, __opus_check_int_ptr(x) |
| 683 | |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 684 | /**@}*/ |
| 685 | |
| 686 | /** @defgroup opus_decoderctls Decoder related CTLs |
| 687 | * @see opus_genericctls, opus_encoderctls, opus_decoder |
| 688 | * @{ |
| 689 | */ |
| 690 | |
| 691 | /** Configures decoder gain adjustment. |
| 692 | * Scales the decoded output by a factor specified in Q8 dB units. |
| 693 | * This has a maximum range of -32768 to 32767 inclusive, and returns |
| 694 | * OPUS_BAD_ARG otherwise. The default is zero indicating no adjustment. |
| 695 | * This setting survives decoder reset. |
| 696 | * |
| 697 | * gain = pow(10, x/(20.0*256)) |
| 698 | * |
| 699 | * @param[in] x <tt>opus_int32</tt>: Amount to scale PCM signal by in Q8 dB units. |
| 700 | * @hideinitializer */ |
| 701 | #define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x) |
| 702 | /** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN |
| 703 | * |
| 704 | * @param[out] x <tt>opus_int32 *</tt>: Amount to scale PCM signal by in Q8 dB units. |
| 705 | * @hideinitializer */ |
| 706 | #define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x) |
| 707 | |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 708 | /** Gets the duration (in samples) of the last packet successfully decoded or concealed. |
| 709 | * @param[out] x <tt>opus_int32 *</tt>: Number of samples (at current sampling rate). |
| 710 | * @hideinitializer */ |
| 711 | #define OPUS_GET_LAST_PACKET_DURATION(x) OPUS_GET_LAST_PACKET_DURATION_REQUEST, __opus_check_int_ptr(x) |
| 712 | |
| 713 | /** Gets the pitch of the last decoded frame, if available. |
| 714 | * This can be used for any post-processing algorithm requiring the use of pitch, |
| 715 | * e.g. time stretching/shortening. If the last frame was not voiced, or if the |
| 716 | * pitch was not coded in the frame, then zero is returned. |
| 717 | * |
| 718 | * This CTL is only implemented for decoder instances. |
| 719 | * |
| 720 | * @param[out] x <tt>opus_int32 *</tt>: pitch period at 48 kHz (or 0 if not available) |
| 721 | * |
| 722 | * @hideinitializer */ |
| 723 | #define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x) |
| 724 | |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 725 | /**@}*/ |
| 726 | |
| 727 | /** @defgroup opus_libinfo Opus library information functions |
| 728 | * @{ |
| 729 | */ |
| 730 | |
| 731 | /** Converts an opus error code into a human readable string. |
| 732 | * |
| 733 | * @param[in] error <tt>int</tt>: Error number |
| 734 | * @returns Error string |
| 735 | */ |
| 736 | OPUS_EXPORT const char *opus_strerror(int error); |
| 737 | |
| 738 | /** Gets the libopus version string. |
| 739 | * |
flim | c91ee5b | 2016-01-26 14:33:44 +0100 | [diff] [blame] | 740 | * Applications may look for the substring "-fixed" in the version string to |
| 741 | * determine whether they have a fixed-point or floating-point build at |
| 742 | * runtime. |
| 743 | * |
Vignesh Venkatasubramanian | 2bd8b54 | 2014-02-20 10:50:35 -0800 | [diff] [blame] | 744 | * @returns Version string |
| 745 | */ |
| 746 | OPUS_EXPORT const char *opus_get_version_string(void); |
| 747 | /**@}*/ |
| 748 | |
| 749 | #ifdef __cplusplus |
| 750 | } |
| 751 | #endif |
| 752 | |
| 753 | #endif /* OPUS_DEFINES_H */ |