1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libopus/include/opus_defines.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,726 @@
1.4 +/* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited
1.5 + Written by Jean-Marc Valin and Koen Vos */
1.6 +/*
1.7 + Redistribution and use in source and binary forms, with or without
1.8 + modification, are permitted provided that the following conditions
1.9 + are met:
1.10 +
1.11 + - Redistributions of source code must retain the above copyright
1.12 + notice, this list of conditions and the following disclaimer.
1.13 +
1.14 + - Redistributions in binary form must reproduce the above copyright
1.15 + notice, this list of conditions and the following disclaimer in the
1.16 + documentation and/or other materials provided with the distribution.
1.17 +
1.18 + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.19 + ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.20 + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.21 + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
1.22 + OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
1.23 + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
1.24 + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1.25 + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1.26 + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1.27 + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1.28 + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.29 +*/
1.30 +
1.31 +/**
1.32 + * @file opus_defines.h
1.33 + * @brief Opus reference implementation constants
1.34 + */
1.35 +
1.36 +#ifndef OPUS_DEFINES_H
1.37 +#define OPUS_DEFINES_H
1.38 +
1.39 +#include "opus_types.h"
1.40 +
1.41 +#ifdef __cplusplus
1.42 +extern "C" {
1.43 +#endif
1.44 +
1.45 +/** @defgroup opus_errorcodes Error codes
1.46 + * @{
1.47 + */
1.48 +/** No error @hideinitializer*/
1.49 +#define OPUS_OK 0
1.50 +/** One or more invalid/out of range arguments @hideinitializer*/
1.51 +#define OPUS_BAD_ARG -1
1.52 +/** The mode struct passed is invalid @hideinitializer*/
1.53 +#define OPUS_BUFFER_TOO_SMALL -2
1.54 +/** An internal error was detected @hideinitializer*/
1.55 +#define OPUS_INTERNAL_ERROR -3
1.56 +/** The compressed data passed is corrupted @hideinitializer*/
1.57 +#define OPUS_INVALID_PACKET -4
1.58 +/** Invalid/unsupported request number @hideinitializer*/
1.59 +#define OPUS_UNIMPLEMENTED -5
1.60 +/** An encoder or decoder structure is invalid or already freed @hideinitializer*/
1.61 +#define OPUS_INVALID_STATE -6
1.62 +/** Memory allocation has failed @hideinitializer*/
1.63 +#define OPUS_ALLOC_FAIL -7
1.64 +/**@}*/
1.65 +
1.66 +/** @cond OPUS_INTERNAL_DOC */
1.67 +/**Export control for opus functions */
1.68 +
1.69 +#ifndef OPUS_EXPORT
1.70 +# if defined(WIN32)
1.71 +# ifdef OPUS_BUILD
1.72 +# define OPUS_EXPORT __declspec(dllexport)
1.73 +# else
1.74 +# define OPUS_EXPORT
1.75 +# endif
1.76 +# elif defined(__GNUC__) && defined(OPUS_BUILD)
1.77 +# define OPUS_EXPORT __attribute__ ((visibility ("default")))
1.78 +# else
1.79 +# define OPUS_EXPORT
1.80 +# endif
1.81 +#endif
1.82 +
1.83 +# if !defined(OPUS_GNUC_PREREQ)
1.84 +# if defined(__GNUC__)&&defined(__GNUC_MINOR__)
1.85 +# define OPUS_GNUC_PREREQ(_maj,_min) \
1.86 + ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
1.87 +# else
1.88 +# define OPUS_GNUC_PREREQ(_maj,_min) 0
1.89 +# endif
1.90 +# endif
1.91 +
1.92 +#if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) )
1.93 +# if OPUS_GNUC_PREREQ(3,0)
1.94 +# define OPUS_RESTRICT __restrict__
1.95 +# elif (defined(_MSC_VER) && _MSC_VER >= 1400)
1.96 +# define OPUS_RESTRICT __restrict
1.97 +# else
1.98 +# define OPUS_RESTRICT
1.99 +# endif
1.100 +#else
1.101 +# define OPUS_RESTRICT restrict
1.102 +#endif
1.103 +
1.104 +#if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) )
1.105 +# if OPUS_GNUC_PREREQ(2,7)
1.106 +# define OPUS_INLINE __inline__
1.107 +# elif (defined(_MSC_VER))
1.108 +# define OPUS_INLINE __inline
1.109 +# else
1.110 +# define OPUS_INLINE
1.111 +# endif
1.112 +#else
1.113 +# define OPUS_INLINE inline
1.114 +#endif
1.115 +
1.116 +/**Warning attributes for opus functions
1.117 + * NONNULL is not used in OPUS_BUILD to avoid the compiler optimizing out
1.118 + * some paranoid null checks. */
1.119 +#if defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4)
1.120 +# define OPUS_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__))
1.121 +#else
1.122 +# define OPUS_WARN_UNUSED_RESULT
1.123 +#endif
1.124 +#if !defined(OPUS_BUILD) && defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4)
1.125 +# define OPUS_ARG_NONNULL(_x) __attribute__ ((__nonnull__(_x)))
1.126 +#else
1.127 +# define OPUS_ARG_NONNULL(_x)
1.128 +#endif
1.129 +
1.130 +/** These are the actual Encoder CTL ID numbers.
1.131 + * They should not be used directly by applications.
1.132 + * In general, SETs should be even and GETs should be odd.*/
1.133 +#define OPUS_SET_APPLICATION_REQUEST 4000
1.134 +#define OPUS_GET_APPLICATION_REQUEST 4001
1.135 +#define OPUS_SET_BITRATE_REQUEST 4002
1.136 +#define OPUS_GET_BITRATE_REQUEST 4003
1.137 +#define OPUS_SET_MAX_BANDWIDTH_REQUEST 4004
1.138 +#define OPUS_GET_MAX_BANDWIDTH_REQUEST 4005
1.139 +#define OPUS_SET_VBR_REQUEST 4006
1.140 +#define OPUS_GET_VBR_REQUEST 4007
1.141 +#define OPUS_SET_BANDWIDTH_REQUEST 4008
1.142 +#define OPUS_GET_BANDWIDTH_REQUEST 4009
1.143 +#define OPUS_SET_COMPLEXITY_REQUEST 4010
1.144 +#define OPUS_GET_COMPLEXITY_REQUEST 4011
1.145 +#define OPUS_SET_INBAND_FEC_REQUEST 4012
1.146 +#define OPUS_GET_INBAND_FEC_REQUEST 4013
1.147 +#define OPUS_SET_PACKET_LOSS_PERC_REQUEST 4014
1.148 +#define OPUS_GET_PACKET_LOSS_PERC_REQUEST 4015
1.149 +#define OPUS_SET_DTX_REQUEST 4016
1.150 +#define OPUS_GET_DTX_REQUEST 4017
1.151 +#define OPUS_SET_VBR_CONSTRAINT_REQUEST 4020
1.152 +#define OPUS_GET_VBR_CONSTRAINT_REQUEST 4021
1.153 +#define OPUS_SET_FORCE_CHANNELS_REQUEST 4022
1.154 +#define OPUS_GET_FORCE_CHANNELS_REQUEST 4023
1.155 +#define OPUS_SET_SIGNAL_REQUEST 4024
1.156 +#define OPUS_GET_SIGNAL_REQUEST 4025
1.157 +#define OPUS_GET_LOOKAHEAD_REQUEST 4027
1.158 +/* #define OPUS_RESET_STATE 4028 */
1.159 +#define OPUS_GET_SAMPLE_RATE_REQUEST 4029
1.160 +#define OPUS_GET_FINAL_RANGE_REQUEST 4031
1.161 +#define OPUS_GET_PITCH_REQUEST 4033
1.162 +#define OPUS_SET_GAIN_REQUEST 4034
1.163 +#define OPUS_GET_GAIN_REQUEST 4045 /* Should have been 4035 */
1.164 +#define OPUS_SET_LSB_DEPTH_REQUEST 4036
1.165 +#define OPUS_GET_LSB_DEPTH_REQUEST 4037
1.166 +#define OPUS_GET_LAST_PACKET_DURATION_REQUEST 4039
1.167 +#define OPUS_SET_EXPERT_FRAME_DURATION_REQUEST 4040
1.168 +#define OPUS_GET_EXPERT_FRAME_DURATION_REQUEST 4041
1.169 +#define OPUS_SET_PREDICTION_DISABLED_REQUEST 4042
1.170 +#define OPUS_GET_PREDICTION_DISABLED_REQUEST 4043
1.171 +
1.172 +/* Don't use 4045, it's already taken by OPUS_GET_GAIN_REQUEST */
1.173 +
1.174 +/* Macros to trigger compilation errors when the wrong types are provided to a CTL */
1.175 +#define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x))
1.176 +#define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr)))
1.177 +#define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr)))
1.178 +#define __opus_check_val16_ptr(ptr) ((ptr) + ((ptr) - (opus_val16*)(ptr)))
1.179 +/** @endcond */
1.180 +
1.181 +/** @defgroup opus_ctlvalues Pre-defined values for CTL interface
1.182 + * @see opus_genericctls, opus_encoderctls
1.183 + * @{
1.184 + */
1.185 +/* Values for the various encoder CTLs */
1.186 +#define OPUS_AUTO -1000 /**<Auto/default setting @hideinitializer*/
1.187 +#define OPUS_BITRATE_MAX -1 /**<Maximum bitrate @hideinitializer*/
1.188 +
1.189 +/** Best for most VoIP/videoconference applications where listening quality and intelligibility matter most
1.190 + * @hideinitializer */
1.191 +#define OPUS_APPLICATION_VOIP 2048
1.192 +/** Best for broadcast/high-fidelity application where the decoded audio should be as close as possible to the input
1.193 + * @hideinitializer */
1.194 +#define OPUS_APPLICATION_AUDIO 2049
1.195 +/** Only use when lowest-achievable latency is what matters most. Voice-optimized modes cannot be used.
1.196 + * @hideinitializer */
1.197 +#define OPUS_APPLICATION_RESTRICTED_LOWDELAY 2051
1.198 +
1.199 +#define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */
1.200 +#define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */
1.201 +#define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4 kHz bandpass @hideinitializer*/
1.202 +#define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6 kHz bandpass @hideinitializer*/
1.203 +#define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8 kHz bandpass @hideinitializer*/
1.204 +#define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12 kHz bandpass @hideinitializer*/
1.205 +#define OPUS_BANDWIDTH_FULLBAND 1105 /**<20 kHz bandpass @hideinitializer*/
1.206 +
1.207 +#define OPUS_FRAMESIZE_ARG 5000 /**< Select frame size from the argument (default) */
1.208 +#define OPUS_FRAMESIZE_2_5_MS 5001 /**< Use 2.5 ms frames */
1.209 +#define OPUS_FRAMESIZE_5_MS 5002 /**< Use 5 ms frames */
1.210 +#define OPUS_FRAMESIZE_10_MS 5003 /**< Use 10 ms frames */
1.211 +#define OPUS_FRAMESIZE_20_MS 5004 /**< Use 20 ms frames */
1.212 +#define OPUS_FRAMESIZE_40_MS 5005 /**< Use 40 ms frames */
1.213 +#define OPUS_FRAMESIZE_60_MS 5006 /**< Use 60 ms frames */
1.214 +
1.215 +/**@}*/
1.216 +
1.217 +
1.218 +/** @defgroup opus_encoderctls Encoder related CTLs
1.219 + *
1.220 + * These are convenience macros for use with the \c opus_encode_ctl
1.221 + * interface. They are used to generate the appropriate series of
1.222 + * arguments for that call, passing the correct type, size and so
1.223 + * on as expected for each particular request.
1.224 + *
1.225 + * Some usage examples:
1.226 + *
1.227 + * @code
1.228 + * int ret;
1.229 + * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO));
1.230 + * if (ret != OPUS_OK) return ret;
1.231 + *
1.232 + * opus_int32 rate;
1.233 + * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate));
1.234 + *
1.235 + * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
1.236 + * @endcode
1.237 + *
1.238 + * @see opus_genericctls, opus_encoder
1.239 + * @{
1.240 + */
1.241 +
1.242 +/** Configures the encoder's computational complexity.
1.243 + * The supported range is 0-10 inclusive with 10 representing the highest complexity.
1.244 + * @see OPUS_GET_COMPLEXITY
1.245 + * @param[in] x <tt>opus_int32</tt>: Allowed values: 0-10, inclusive.
1.246 + *
1.247 + * @hideinitializer */
1.248 +#define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x)
1.249 +/** Gets the encoder's complexity configuration.
1.250 + * @see OPUS_SET_COMPLEXITY
1.251 + * @param[out] x <tt>opus_int32 *</tt>: Returns a value in the range 0-10,
1.252 + * inclusive.
1.253 + * @hideinitializer */
1.254 +#define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x)
1.255 +
1.256 +/** Configures the bitrate in the encoder.
1.257 + * Rates from 500 to 512000 bits per second are meaningful, as well as the
1.258 + * special values #OPUS_AUTO and #OPUS_BITRATE_MAX.
1.259 + * The value #OPUS_BITRATE_MAX can be used to cause the codec to use as much
1.260 + * rate as it can, which is useful for controlling the rate by adjusting the
1.261 + * output buffer size.
1.262 + * @see OPUS_GET_BITRATE
1.263 + * @param[in] x <tt>opus_int32</tt>: Bitrate in bits per second. The default
1.264 + * is determined based on the number of
1.265 + * channels and the input sampling rate.
1.266 + * @hideinitializer */
1.267 +#define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x)
1.268 +/** Gets the encoder's bitrate configuration.
1.269 + * @see OPUS_SET_BITRATE
1.270 + * @param[out] x <tt>opus_int32 *</tt>: Returns the bitrate in bits per second.
1.271 + * The default is determined based on the
1.272 + * number of channels and the input
1.273 + * sampling rate.
1.274 + * @hideinitializer */
1.275 +#define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x)
1.276 +
1.277 +/** Enables or disables variable bitrate (VBR) in the encoder.
1.278 + * The configured bitrate may not be met exactly because frames must
1.279 + * be an integer number of bytes in length.
1.280 + * @warning Only the MDCT mode of Opus can provide hard CBR behavior.
1.281 + * @see OPUS_GET_VBR
1.282 + * @see OPUS_SET_VBR_CONSTRAINT
1.283 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.284 + * <dl>
1.285 + * <dt>0</dt><dd>Hard CBR. For LPC/hybrid modes at very low bit-rate, this can
1.286 + * cause noticeable quality degradation.</dd>
1.287 + * <dt>1</dt><dd>VBR (default). The exact type of VBR is controlled by
1.288 + * #OPUS_SET_VBR_CONSTRAINT.</dd>
1.289 + * </dl>
1.290 + * @hideinitializer */
1.291 +#define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x)
1.292 +/** Determine if variable bitrate (VBR) is enabled in the encoder.
1.293 + * @see OPUS_SET_VBR
1.294 + * @see OPUS_GET_VBR_CONSTRAINT
1.295 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.296 + * <dl>
1.297 + * <dt>0</dt><dd>Hard CBR.</dd>
1.298 + * <dt>1</dt><dd>VBR (default). The exact type of VBR may be retrieved via
1.299 + * #OPUS_GET_VBR_CONSTRAINT.</dd>
1.300 + * </dl>
1.301 + * @hideinitializer */
1.302 +#define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x)
1.303 +
1.304 +/** Enables or disables constrained VBR in the encoder.
1.305 + * This setting is ignored when the encoder is in CBR mode.
1.306 + * @warning Only the MDCT mode of Opus currently heeds the constraint.
1.307 + * Speech mode ignores it completely, hybrid mode may fail to obey it
1.308 + * if the LPC layer uses more bitrate than the constraint would have
1.309 + * permitted.
1.310 + * @see OPUS_GET_VBR_CONSTRAINT
1.311 + * @see OPUS_SET_VBR
1.312 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.313 + * <dl>
1.314 + * <dt>0</dt><dd>Unconstrained VBR.</dd>
1.315 + * <dt>1</dt><dd>Constrained VBR (default). This creates a maximum of one
1.316 + * frame of buffering delay assuming a transport with a
1.317 + * serialization speed of the nominal bitrate.</dd>
1.318 + * </dl>
1.319 + * @hideinitializer */
1.320 +#define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x)
1.321 +/** Determine if constrained VBR is enabled in the encoder.
1.322 + * @see OPUS_SET_VBR_CONSTRAINT
1.323 + * @see OPUS_GET_VBR
1.324 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.325 + * <dl>
1.326 + * <dt>0</dt><dd>Unconstrained VBR.</dd>
1.327 + * <dt>1</dt><dd>Constrained VBR (default).</dd>
1.328 + * </dl>
1.329 + * @hideinitializer */
1.330 +#define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x)
1.331 +
1.332 +/** Configures mono/stereo forcing in the encoder.
1.333 + * This can force the encoder to produce packets encoded as either mono or
1.334 + * stereo, regardless of the format of the input audio. This is useful when
1.335 + * the caller knows that the input signal is currently a mono source embedded
1.336 + * in a stereo stream.
1.337 + * @see OPUS_GET_FORCE_CHANNELS
1.338 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.339 + * <dl>
1.340 + * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd>
1.341 + * <dt>1</dt> <dd>Forced mono</dd>
1.342 + * <dt>2</dt> <dd>Forced stereo</dd>
1.343 + * </dl>
1.344 + * @hideinitializer */
1.345 +#define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x)
1.346 +/** Gets the encoder's forced channel configuration.
1.347 + * @see OPUS_SET_FORCE_CHANNELS
1.348 + * @param[out] x <tt>opus_int32 *</tt>:
1.349 + * <dl>
1.350 + * <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd>
1.351 + * <dt>1</dt> <dd>Forced mono</dd>
1.352 + * <dt>2</dt> <dd>Forced stereo</dd>
1.353 + * </dl>
1.354 + * @hideinitializer */
1.355 +#define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x)
1.356 +
1.357 +/** Configures the maximum bandpass that the encoder will select automatically.
1.358 + * Applications should normally use this instead of #OPUS_SET_BANDWIDTH
1.359 + * (leaving that set to the default, #OPUS_AUTO). This allows the
1.360 + * application to set an upper bound based on the type of input it is
1.361 + * providing, but still gives the encoder the freedom to reduce the bandpass
1.362 + * when the bitrate becomes too low, for better overall quality.
1.363 + * @see OPUS_GET_MAX_BANDWIDTH
1.364 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.365 + * <dl>
1.366 + * <dt>OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
1.367 + * <dt>OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
1.368 + * <dt>OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
1.369 + * <dt>OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
1.370 + * <dt>OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd>
1.371 + * </dl>
1.372 + * @hideinitializer */
1.373 +#define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x)
1.374 +
1.375 +/** Gets the encoder's configured maximum allowed bandpass.
1.376 + * @see OPUS_SET_MAX_BANDWIDTH
1.377 + * @param[out] x <tt>opus_int32 *</tt>: Allowed values:
1.378 + * <dl>
1.379 + * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
1.380 + * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
1.381 + * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
1.382 + * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
1.383 + * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd>
1.384 + * </dl>
1.385 + * @hideinitializer */
1.386 +#define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
1.387 +
1.388 +/** Sets the encoder's bandpass to a specific value.
1.389 + * This prevents the encoder from automatically selecting the bandpass based
1.390 + * on the available bitrate. If an application knows the bandpass of the input
1.391 + * audio it is providing, it should normally use #OPUS_SET_MAX_BANDWIDTH
1.392 + * instead, which still gives the encoder the freedom to reduce the bandpass
1.393 + * when the bitrate becomes too low, for better overall quality.
1.394 + * @see OPUS_GET_BANDWIDTH
1.395 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.396 + * <dl>
1.397 + * <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
1.398 + * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
1.399 + * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
1.400 + * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
1.401 + * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
1.402 + * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd>
1.403 + * </dl>
1.404 + * @hideinitializer */
1.405 +#define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x)
1.406 +
1.407 +/** Configures the type of signal being encoded.
1.408 + * This is a hint which helps the encoder's mode selection.
1.409 + * @see OPUS_GET_SIGNAL
1.410 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.411 + * <dl>
1.412 + * <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
1.413 + * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd>
1.414 + * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd>
1.415 + * </dl>
1.416 + * @hideinitializer */
1.417 +#define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x)
1.418 +/** Gets the encoder's configured signal type.
1.419 + * @see OPUS_SET_SIGNAL
1.420 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.421 + * <dl>
1.422 + * <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
1.423 + * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd>
1.424 + * <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd>
1.425 + * </dl>
1.426 + * @hideinitializer */
1.427 +#define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x)
1.428 +
1.429 +
1.430 +/** Configures the encoder's intended application.
1.431 + * The initial value is a mandatory argument to the encoder_create function.
1.432 + * @see OPUS_GET_APPLICATION
1.433 + * @param[in] x <tt>opus_int32</tt>: Returns one of the following values:
1.434 + * <dl>
1.435 + * <dt>#OPUS_APPLICATION_VOIP</dt>
1.436 + * <dd>Process signal for improved speech intelligibility.</dd>
1.437 + * <dt>#OPUS_APPLICATION_AUDIO</dt>
1.438 + * <dd>Favor faithfulness to the original input.</dd>
1.439 + * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
1.440 + * <dd>Configure the minimum possible coding delay by disabling certain modes
1.441 + * of operation.</dd>
1.442 + * </dl>
1.443 + * @hideinitializer */
1.444 +#define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x)
1.445 +/** Gets the encoder's configured application.
1.446 + * @see OPUS_SET_APPLICATION
1.447 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.448 + * <dl>
1.449 + * <dt>#OPUS_APPLICATION_VOIP</dt>
1.450 + * <dd>Process signal for improved speech intelligibility.</dd>
1.451 + * <dt>#OPUS_APPLICATION_AUDIO</dt>
1.452 + * <dd>Favor faithfulness to the original input.</dd>
1.453 + * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
1.454 + * <dd>Configure the minimum possible coding delay by disabling certain modes
1.455 + * of operation.</dd>
1.456 + * </dl>
1.457 + * @hideinitializer */
1.458 +#define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x)
1.459 +
1.460 +/** Gets the sampling rate the encoder or decoder was initialized with.
1.461 + * This simply returns the <code>Fs</code> value passed to opus_encoder_init()
1.462 + * or opus_decoder_init().
1.463 + * @param[out] x <tt>opus_int32 *</tt>: Sampling rate of encoder or decoder.
1.464 + * @hideinitializer
1.465 + */
1.466 +#define OPUS_GET_SAMPLE_RATE(x) OPUS_GET_SAMPLE_RATE_REQUEST, __opus_check_int_ptr(x)
1.467 +
1.468 +/** Gets the total samples of delay added by the entire codec.
1.469 + * This can be queried by the encoder and then the provided number of samples can be
1.470 + * skipped on from the start of the decoder's output to provide time aligned input
1.471 + * and output. From the perspective of a decoding application the real data begins this many
1.472 + * samples late.
1.473 + *
1.474 + * The decoder contribution to this delay is identical for all decoders, but the
1.475 + * encoder portion of the delay may vary from implementation to implementation,
1.476 + * version to version, or even depend on the encoder's initial configuration.
1.477 + * Applications needing delay compensation should call this CTL rather than
1.478 + * hard-coding a value.
1.479 + * @param[out] x <tt>opus_int32 *</tt>: Number of lookahead samples
1.480 + * @hideinitializer */
1.481 +#define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x)
1.482 +
1.483 +/** Configures the encoder's use of inband forward error correction (FEC).
1.484 + * @note This is only applicable to the LPC layer
1.485 + * @see OPUS_GET_INBAND_FEC
1.486 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.487 + * <dl>
1.488 + * <dt>0</dt><dd>Disable inband FEC (default).</dd>
1.489 + * <dt>1</dt><dd>Enable inband FEC.</dd>
1.490 + * </dl>
1.491 + * @hideinitializer */
1.492 +#define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x)
1.493 +/** Gets encoder's configured use of inband forward error correction.
1.494 + * @see OPUS_SET_INBAND_FEC
1.495 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.496 + * <dl>
1.497 + * <dt>0</dt><dd>Inband FEC disabled (default).</dd>
1.498 + * <dt>1</dt><dd>Inband FEC enabled.</dd>
1.499 + * </dl>
1.500 + * @hideinitializer */
1.501 +#define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x)
1.502 +
1.503 +/** Configures the encoder's expected packet loss percentage.
1.504 + * Higher values with trigger progressively more loss resistant behavior in the encoder
1.505 + * at the expense of quality at a given bitrate in the lossless case, but greater quality
1.506 + * under loss.
1.507 + * @see OPUS_GET_PACKET_LOSS_PERC
1.508 + * @param[in] x <tt>opus_int32</tt>: Loss percentage in the range 0-100, inclusive (default: 0).
1.509 + * @hideinitializer */
1.510 +#define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x)
1.511 +/** Gets the encoder's configured packet loss percentage.
1.512 + * @see OPUS_SET_PACKET_LOSS_PERC
1.513 + * @param[out] x <tt>opus_int32 *</tt>: Returns the configured loss percentage
1.514 + * in the range 0-100, inclusive (default: 0).
1.515 + * @hideinitializer */
1.516 +#define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x)
1.517 +
1.518 +/** Configures the encoder's use of discontinuous transmission (DTX).
1.519 + * @note This is only applicable to the LPC layer
1.520 + * @see OPUS_GET_DTX
1.521 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.522 + * <dl>
1.523 + * <dt>0</dt><dd>Disable DTX (default).</dd>
1.524 + * <dt>1</dt><dd>Enabled DTX.</dd>
1.525 + * </dl>
1.526 + * @hideinitializer */
1.527 +#define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x)
1.528 +/** Gets encoder's configured use of discontinuous transmission.
1.529 + * @see OPUS_SET_DTX
1.530 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.531 + * <dl>
1.532 + * <dt>0</dt><dd>DTX disabled (default).</dd>
1.533 + * <dt>1</dt><dd>DTX enabled.</dd>
1.534 + * </dl>
1.535 + * @hideinitializer */
1.536 +#define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x)
1.537 +/** Configures the depth of signal being encoded.
1.538 + * This is a hint which helps the encoder identify silence and near-silence.
1.539 + * @see OPUS_GET_LSB_DEPTH
1.540 + * @param[in] x <tt>opus_int32</tt>: Input precision in bits, between 8 and 24
1.541 + * (default: 24).
1.542 + * @hideinitializer */
1.543 +#define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x)
1.544 +/** Gets the encoder's configured signal depth.
1.545 + * @see OPUS_SET_LSB_DEPTH
1.546 + * @param[out] x <tt>opus_int32 *</tt>: Input precision in bits, between 8 and
1.547 + * 24 (default: 24).
1.548 + * @hideinitializer */
1.549 +#define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x)
1.550 +
1.551 +/** Gets the duration (in samples) of the last packet successfully decoded or concealed.
1.552 + * @param[out] x <tt>opus_int32 *</tt>: Number of samples (at current sampling rate).
1.553 + * @hideinitializer */
1.554 +#define OPUS_GET_LAST_PACKET_DURATION(x) OPUS_GET_LAST_PACKET_DURATION_REQUEST, __opus_check_int_ptr(x)
1.555 +
1.556 +/** Configures the encoder's use of variable duration frames.
1.557 + * When variable duration is enabled, the encoder is free to use a shorter frame
1.558 + * size than the one requested in the opus_encode*() call.
1.559 + * It is then the user's responsibility
1.560 + * to verify how much audio was encoded by checking the ToC byte of the encoded
1.561 + * packet. The part of the audio that was not encoded needs to be resent to the
1.562 + * encoder for the next call. Do not use this option unless you <b>really</b>
1.563 + * know what you are doing.
1.564 + * @see OPUS_GET_EXPERT_VARIABLE_DURATION
1.565 + * @param[in] x <tt>opus_int32</tt>: Allowed values:
1.566 + * <dl>
1.567 + * <dt>OPUS_FRAMESIZE_ARG</dt><dd>Select frame size from the argument (default).</dd>
1.568 + * <dt>OPUS_FRAMESIZE_2_5_MS</dt><dd>Use 2.5 ms frames.</dd>
1.569 + * <dt>OPUS_FRAMESIZE_5_MS</dt><dd>Use 2.5 ms frames.</dd>
1.570 + * <dt>OPUS_FRAMESIZE_10_MS</dt><dd>Use 10 ms frames.</dd>
1.571 + * <dt>OPUS_FRAMESIZE_20_MS</dt><dd>Use 20 ms frames.</dd>
1.572 + * <dt>OPUS_FRAMESIZE_40_MS</dt><dd>Use 40 ms frames.</dd>
1.573 + * <dt>OPUS_FRAMESIZE_60_MS</dt><dd>Use 60 ms frames.</dd>
1.574 + * <dt>OPUS_FRAMESIZE_VARIABLE</dt><dd>Optimize the frame size dynamically.</dd>
1.575 + * </dl>
1.576 + * @hideinitializer */
1.577 +#define OPUS_SET_EXPERT_FRAME_DURATION(x) OPUS_SET_EXPERT_FRAME_DURATION_REQUEST, __opus_check_int(x)
1.578 +/** Gets the encoder's configured use of variable duration frames.
1.579 + * @see OPUS_SET_EXPERT_VARIABLE_DURATION
1.580 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.581 + * <dl>
1.582 + * <dt>OPUS_FRAMESIZE_ARG</dt><dd>Select frame size from the argument (default).</dd>
1.583 + * <dt>OPUS_FRAMESIZE_2_5_MS</dt><dd>Use 2.5 ms frames.</dd>
1.584 + * <dt>OPUS_FRAMESIZE_5_MS</dt><dd>Use 2.5 ms frames.</dd>
1.585 + * <dt>OPUS_FRAMESIZE_10_MS</dt><dd>Use 10 ms frames.</dd>
1.586 + * <dt>OPUS_FRAMESIZE_20_MS</dt><dd>Use 20 ms frames.</dd>
1.587 + * <dt>OPUS_FRAMESIZE_40_MS</dt><dd>Use 40 ms frames.</dd>
1.588 + * <dt>OPUS_FRAMESIZE_60_MS</dt><dd>Use 60 ms frames.</dd>
1.589 + * <dt>OPUS_FRAMESIZE_VARIABLE</dt><dd>Optimize the frame size dynamically.</dd>
1.590 + * </dl>
1.591 + * @hideinitializer */
1.592 +#define OPUS_GET_EXPERT_FRAME_DURATION(x) OPUS_GET_EXPERT_FRAME_DURATION_REQUEST, __opus_check_int_ptr(x)
1.593 +
1.594 +/** If set to 1, disables almost all use of prediction, making frames almost
1.595 + completely independent. This reduces quality. (default : 0)
1.596 + * @hideinitializer */
1.597 +#define OPUS_SET_PREDICTION_DISABLED(x) OPUS_SET_PREDICTION_DISABLED_REQUEST, __opus_check_int(x)
1.598 +/** Gets the encoder's configured prediction status.
1.599 + * @hideinitializer */
1.600 +#define OPUS_GET_PREDICTION_DISABLED(x) OPUS_GET_PREDICTION_DISABLED_REQUEST, __opus_check_int_ptr(x)
1.601 +
1.602 +/**@}*/
1.603 +
1.604 +/** @defgroup opus_genericctls Generic CTLs
1.605 + *
1.606 + * These macros are used with the \c opus_decoder_ctl and
1.607 + * \c opus_encoder_ctl calls to generate a particular
1.608 + * request.
1.609 + *
1.610 + * When called on an \c OpusDecoder they apply to that
1.611 + * particular decoder instance. When called on an
1.612 + * \c OpusEncoder they apply to the corresponding setting
1.613 + * on that encoder instance, if present.
1.614 + *
1.615 + * Some usage examples:
1.616 + *
1.617 + * @code
1.618 + * int ret;
1.619 + * opus_int32 pitch;
1.620 + * ret = opus_decoder_ctl(dec_ctx, OPUS_GET_PITCH(&pitch));
1.621 + * if (ret == OPUS_OK) return ret;
1.622 + *
1.623 + * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
1.624 + * opus_decoder_ctl(dec_ctx, OPUS_RESET_STATE);
1.625 + *
1.626 + * opus_int32 enc_bw, dec_bw;
1.627 + * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&enc_bw));
1.628 + * opus_decoder_ctl(dec_ctx, OPUS_GET_BANDWIDTH(&dec_bw));
1.629 + * if (enc_bw != dec_bw) {
1.630 + * printf("packet bandwidth mismatch!\n");
1.631 + * }
1.632 + * @endcode
1.633 + *
1.634 + * @see opus_encoder, opus_decoder_ctl, opus_encoder_ctl, opus_decoderctls, opus_encoderctls
1.635 + * @{
1.636 + */
1.637 +
1.638 +/** Resets the codec state to be equivalent to a freshly initialized state.
1.639 + * This should be called when switching streams in order to prevent
1.640 + * the back to back decoding from giving different results from
1.641 + * one at a time decoding.
1.642 + * @hideinitializer */
1.643 +#define OPUS_RESET_STATE 4028
1.644 +
1.645 +/** Gets the final state of the codec's entropy coder.
1.646 + * This is used for testing purposes,
1.647 + * The encoder and decoder state should be identical after coding a payload
1.648 + * (assuming no data corruption or software bugs)
1.649 + *
1.650 + * @param[out] x <tt>opus_uint32 *</tt>: Entropy coder state
1.651 + *
1.652 + * @hideinitializer */
1.653 +#define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x)
1.654 +
1.655 +/** Gets the pitch of the last decoded frame, if available.
1.656 + * This can be used for any post-processing algorithm requiring the use of pitch,
1.657 + * e.g. time stretching/shortening. If the last frame was not voiced, or if the
1.658 + * pitch was not coded in the frame, then zero is returned.
1.659 + *
1.660 + * This CTL is only implemented for decoder instances.
1.661 + *
1.662 + * @param[out] x <tt>opus_int32 *</tt>: pitch period at 48 kHz (or 0 if not available)
1.663 + *
1.664 + * @hideinitializer */
1.665 +#define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x)
1.666 +
1.667 +/** Gets the encoder's configured bandpass or the decoder's last bandpass.
1.668 + * @see OPUS_SET_BANDWIDTH
1.669 + * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
1.670 + * <dl>
1.671 + * <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
1.672 + * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
1.673 + * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
1.674 + * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
1.675 + * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
1.676 + * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd>
1.677 + * </dl>
1.678 + * @hideinitializer */
1.679 +#define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
1.680 +
1.681 +/**@}*/
1.682 +
1.683 +/** @defgroup opus_decoderctls Decoder related CTLs
1.684 + * @see opus_genericctls, opus_encoderctls, opus_decoder
1.685 + * @{
1.686 + */
1.687 +
1.688 +/** Configures decoder gain adjustment.
1.689 + * Scales the decoded output by a factor specified in Q8 dB units.
1.690 + * This has a maximum range of -32768 to 32767 inclusive, and returns
1.691 + * OPUS_BAD_ARG otherwise. The default is zero indicating no adjustment.
1.692 + * This setting survives decoder reset.
1.693 + *
1.694 + * gain = pow(10, x/(20.0*256))
1.695 + *
1.696 + * @param[in] x <tt>opus_int32</tt>: Amount to scale PCM signal by in Q8 dB units.
1.697 + * @hideinitializer */
1.698 +#define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x)
1.699 +/** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN
1.700 + *
1.701 + * @param[out] x <tt>opus_int32 *</tt>: Amount to scale PCM signal by in Q8 dB units.
1.702 + * @hideinitializer */
1.703 +#define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x)
1.704 +
1.705 +/**@}*/
1.706 +
1.707 +/** @defgroup opus_libinfo Opus library information functions
1.708 + * @{
1.709 + */
1.710 +
1.711 +/** Converts an opus error code into a human readable string.
1.712 + *
1.713 + * @param[in] error <tt>int</tt>: Error number
1.714 + * @returns Error string
1.715 + */
1.716 +OPUS_EXPORT const char *opus_strerror(int error);
1.717 +
1.718 +/** Gets the libopus version string.
1.719 + *
1.720 + * @returns Version string
1.721 + */
1.722 +OPUS_EXPORT const char *opus_get_version_string(void);
1.723 +/**@}*/
1.724 +
1.725 +#ifdef __cplusplus
1.726 +}
1.727 +#endif
1.728 +
1.729 +#endif /* OPUS_DEFINES_H */
