Skip to content
Snippets Groups Projects
Commit 07b8e612 authored by Timothy B. Terriberry's avatar Timothy B. Terriberry
Browse files

Documentation updates for the CTLs. 

In addition to general reformatting and cleanup, this fixes a
 couple of important mistakes:
- The arguments to OPUS_SET_FORCE_CHANNELS are now 1 and 2, not 0
   and 1 (as they were when this was called OPUS_SET_FORCE_MONO).
- The default encoder mode is now constrained VBR, not unconstrained
   VBR.
It also documents defaults for all the other parameters.
parent 417679c3
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 210 additions and 103 deletions
include/opus_defines.h
+ 210
− 103
View file @ 07b8e612
...@@ -171,11 +171,11 @@ extern "C" { ...@@ -171,11 +171,11 @@ extern "C" {
#define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */ #define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */
#define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */ #define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */
#define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4kHz bandpass @hideinitializer*/ #define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4 kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6kHz bandpass @hideinitializer*/ #define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6 kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8kHz bandpass @hideinitializer*/ #define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8 kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12kHz bandpass @hideinitializer*/ #define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12 kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_FULLBAND 1105 /**<20kHz bandpass @hideinitializer*/ #define OPUS_BANDWIDTH_FULLBAND 1105 /**<20 kHz bandpass @hideinitializer*/
/**@}*/ /**@}*/
...@@ -194,7 +194,7 @@ extern "C" { ...@@ -194,7 +194,7 @@ extern "C" {
* ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO)); * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO));
* if (ret != OPUS_OK) return ret; * if (ret != OPUS_OK) return ret;
* *
* int rate; * opus_int32 rate;
* opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate)); * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate));
* *
* opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE); * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
...@@ -206,141 +206,220 @@ extern "C" { ...@@ -206,141 +206,220 @@ extern "C" {
/** Configures the encoder's computational complexity. /** Configures the encoder's computational complexity.
* The supported range is 0-10 inclusive with 10 representing the highest complexity. * The supported range is 0-10 inclusive with 10 representing the highest complexity.
* The default value is 10. * @see OPUS_GET_COMPLEXITY
* @param[in] x <tt>int</tt>: 0-10, inclusive * @param[in] x <tt>opus_int32</tt>: Allowed values: 0-10, inclusive
* (default: 10).
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x) #define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x)
/** Gets the encoder's complexity configuration. @see OPUS_SET_COMPLEXITY /** Gets the encoder's complexity configuration.
* @param[out] x <tt>int*</tt>: 0-10, inclusive * @see OPUS_SET_COMPLEXITY
* @param[out] x <tt>opus_int32 *</tt>: Returns a value in the range 0-10,
* inclusive (default: 10).
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x)
/** Configures the bitrate in the encoder. /** Configures the bitrate in the encoder.
* Rates from 500 to 512000 bits per second are meaningful as well as the * Rates from 500 to 512000 bits per second are meaningful, as well as the
* special values OPUS_BITRATE_AUTO and OPUS_BITRATE_MAX. * special values #OPUS_BITRATE_AUTO and #OPUS_BITRATE_MAX.
* The value OPUS_BITRATE_MAX can be used to cause the codec to use as much rate * The value #OPUS_BITRATE_MAX can be used to cause the codec to use as much
* as it can, which is useful for controlling the rate by adjusting the output * rate as it can, which is useful for controlling the rate by adjusting the
* buffer size. * output buffer size.
* @param[in] x <tt>opus_int32</tt>: bitrate in bits per second. * @see OPUS_GET_BITRATE
* @param[in] x <tt>opus_int32</tt>: Bitrate in bits per second. The default
* is determined based on the number of
* channels and the input sampling rate.
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x) #define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x)
/** Gets the encoder's bitrate configuration. @see OPUS_SET_BITRATE /** Gets the encoder's bitrate configuration.
* @param[out] x <tt>opus_int32*</tt>: bitrate in bits per second. * @see OPUS_SET_BITRATE
* @param[out] x <tt>opus_int32 *</tt>: Returns the bitrate in bits per second.
* The default is determined based on the
* number of channels and the input
* sampling rate.
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x)
/** Configures VBR in the encoder. /** Enables or disables variable bitrate (VBR) in the encoder.
* The following values are currently supported:
* - 0 CBR
* - 1 VBR (default)
* The configured bitrate may not be met exactly because frames must * The configured bitrate may not be met exactly because frames must
* be an integer number of bytes in length. * be an integer number of bytes in length.
* @warning Only the MDCT mode of Opus can provide hard CBR behavior. * @warning Only the MDCT mode of Opus can provide hard CBR behavior.
* @param[in] x <tt>int</tt>: 0; 1 (default) * @see OPUS_GET_VBR
* @see OPUS_SET_VBR_CONSTRAINT
* @param[in] x <tt>opus_int32</tt>: Allowed values:
* <dl>
* <dt>0</dt><dd>Hard CBR. In the MDCT mode all packets will be the same size.
* In other modes, they will be as close as possible to that
* size.</dd>
* <dt>1</dt><dd>VBR (default). The exact type of VBR is controlled by
* #OPUS_SET_VBR_CONSTRAINT.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x) #define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x)
/** Gets the encoder's VBR configuration. @see OPUS_SET_VBR /** Determine if variable bitrate (VBR) is enabled in the encoder.
* @param[out] x <tt>int*</tt>: 0; 1 * @see OPUS_SET_VBR
* @see OPUS_GET_VBR_CONSTRAINT
* @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>0</dt><dd>Hard CBR.</dd>
* <dt>1</dt><dd>VBR (default). The exact type of VBR may be retrieved via
* #OPUS_GET_VBR_CONSTRAINT.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x)
/** Configures constrained VBR in the encoder. /** Enables or disables constrained VBR in the encoder.
* The following values are currently supported: * This setting is ignored when the encoder is in CBR mode.
* - 0 Unconstrained VBR (default)
* - 1 Maximum one frame buffering delay assuming transport with a serialization speed of the nominal bitrate
* This setting is irrelevant when the encoder is in CBR mode.
* @warning Only the MDCT mode of Opus currently heeds the constraint. * @warning Only the MDCT mode of Opus currently heeds the constraint.
* Speech mode ignores it completely, hybrid mode may fail to obey it * Speech mode ignores it completely, hybrid mode may fail to obey it
* if the LPC layer uses more bitrate than the constraint would have * if the LPC layer uses more bitrate than the constraint would have
* permitted. * permitted.
* @param[in] x <tt>int</tt>: 0 (default); 1 * @see OPUS_GET_VBR_CONSTRAINT
* @see OPUS_SET_VBR
* @param[in] x <tt>opus_int32</tt>: Allowed values:
* <dl>
* <dt>0</dt><dd>Unconstrained VBR.</dd>
* <dt>1</dt><dd>Constrained VBR (default). This creates a maximum of one
* frame of buffering delay assuming a transport with a
* serialization speed of the nominal bitrate.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x) #define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x)
/** Gets the encoder's constrained VBR configuration @see OPUS_SET_VBR_CONSTRAINT /** Determine if constrained VBR is enabled in the encoder.
* @param[out] x <tt>int*</tt>: 0; 1 * @see OPUS_SET_VBR_CONSTRAINT
* @see OPUS_GET_VBR
* @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>0</dt><dd>Unconstrained VBR.</dd>
* <dt>1</dt><dd>Constrained VBR (default).</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x)
/** Configures mono/stereo forcing in the encoder. /** Configures mono/stereo forcing in the encoder.
* This is useful when the caller knows that the input signal is currently a mono * This can force the encoder to produce packets encoded as either mono or
* source embedded in a stereo stream. * stereo, regardless of the format of the input audio. This is useful when
* @param[in] x <tt>int</tt>: OPUS_AUTO (default); 1 (forced mono); 2 (forced stereo) * the caller knows that the input signal is currently a mono source embedded
* in a stereo stream.
* @see OPUS_GET_FORCE_CHANNELS
* @param[in] x <tt>opus_int32</tt>: Allowed values:
* <dl>
* <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd>
* <dt>1</dt> <dd>Forced mono</dd>
* <dt>2</dt> <dd>Forced stereo</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x) #define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x)
/** Gets the encoder's forced channel configuration. @see OPUS_SET_FORCE_CHANNELS /** Gets the encoder's forced channel configuration.
* @param[out] x <tt>int*</tt>: OPUS_AUTO; 0; 1 * @see OPUS_SET_FORCE_CHANNELS
* @param[out] x <tt>opus_int32 *</tt>:
* <dl>
* <dt>#OPUS_AUTO</dt><dd>Not forced (default)</dd>
* <dt>1</dt> <dd>Forced mono</dd>
* <dt>2</dt> <dd>Forced stereo</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x)
/** Configures the maximum bandpass that the encoder will select automatically. /** Configures the maximum bandpass that the encoder will select automatically.
* Applications should normally use this instead of \a OPUS_SET_BANDWIDTH * Applications should normally use this instead of #OPUS_SET_BANDWIDTH
* (leaving that set to the default, \c OPUS_AUTO). This allows the * (leaving that set to the default, #OPUS_AUTO). This allows the
* application to set an upper bound based on the type of input it is * application to set an upper bound based on the type of input it is
* providing, but still gives the encoder the freedom to reduce the bandpass * providing, but still gives the encoder the freedom to reduce the bandpass
* when the bitrate becomes too low, for better overall quality. * when the bitrate becomes too low, for better overall quality.
* @see OPUS_GET_MAX_BANDWIDTH * @see OPUS_GET_MAX_BANDWIDTH
* The supported values are: * @param[in] x <tt>opus_int32</tt>: Allowed values:
* - OPUS_BANDWIDTH_NARROWBAND 4kHz passband * <dl>
* - OPUS_BANDWIDTH_MEDIUMBAND 6kHz passband * <dt>OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
* - OPUS_BANDWIDTH_WIDEBAND 8kHz passband * <dt>OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
* - OPUS_BANDWIDTH_SUPERWIDEBAND 12kHz passband * <dt>OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
* - OPUS_BANDWIDTH_FULLBAND 20kHz passband (default) * <dt>OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
* @param[in] x <tt>int</tt>: Bandwidth value * <dt>OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x) #define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured maximum bandpass allowed. @see OPUS_SET_MAX_BANDWIDTH /** Gets the encoder's configured maximum allowed bandpass.
* @param[out] x <tt>int*</tt>: Bandwidth value * @see OPUS_SET_MAX_BANDWIDTH
* @param[out] x <tt>opus_int32 *</tt>: Allowed values:
* <dl>
* <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband (default)</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
/** Sets the encoder's bandpass to a specific value. /** Sets the encoder's bandpass to a specific value.
* This prevents the encoder from automatically selecting the bandpass based * This prevents the encoder from automatically selecting the bandpass based
* on the available bitrate. If an application knows the bandpass of the input * on the available bitrate. If an application knows the bandpass of the input
* audio it is providing, it should normally use \a OPUS_SET_MAX_BANDWIDTH * audio it is providing, it should normally use #OPUS_SET_MAX_BANDWIDTH
* instead, which still gives the encoder the freedom to reduce the bandpass * instead, which still gives the encoder the freedom to reduce the bandpass
* when the bitrate becomes too low, for better overall quality. * when the bitrate becomes too low, for better overall quality.
* @see OPUS_GET_BANDWIDTH * @see OPUS_GET_BANDWIDTH
* The supported values are: * @param[in] x <tt>opus_int32</tt>: Allowed values:
* - OPUS_AUTO (default) * <dl>
* - OPUS_BANDWIDTH_NARROWBAND 4kHz passband * <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
* - OPUS_BANDWIDTH_MEDIUMBAND 6kHz passband * <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
* - OPUS_BANDWIDTH_WIDEBAND 8kHz passband * <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
* - OPUS_BANDWIDTH_SUPERWIDEBAND 12kHz passband * <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
* - OPUS_BANDWIDTH_FULLBAND 20kHz passband * <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
* @param[in] x <tt>int</tt>: Bandwidth value * <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x) #define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x)
/** Configures the type of signal being encoded. /** Configures the type of signal being encoded.
* This is a hint which helps the encoder's mode selection. * This is a hint which helps the encoder's mode selection.
* The supported values are: * @see OPUS_GET_SIGNAL
* - OPUS_SIGNAL_AUTO (default) * @param[in] x <tt>opus_int32</tt>: Allowed values:
* - OPUS_SIGNAL_VOICE * <dl>
* - OPUS_SIGNAL_MUSIC * <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
* @param[in] x <tt>int</tt>: Signal type * <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd>
* <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x) #define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured signal type. @see OPUS_SET_SIGNAL /** Gets the encoder's configured signal type.
* * @see OPUS_SET_SIGNAL
* @param[out] x <tt>int*</tt>: Signal type * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
* <dt>#OPUS_SIGNAL_VOICE</dt><dd>Bias thresholds towards choosing LPC or Hybrid modes.</dd>
* <dt>#OPUS_SIGNAL_MUSIC</dt><dd>Bias thresholds towards choosing MDCT modes.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x)
/** Configures the encoder's intended application. /** Configures the encoder's intended application.
* The initial value is a mandatory argument to the encoder_create function. * The initial value is a mandatory argument to the encoder_create function.
* The supported values are: * @see OPUS_GET_APPLICATION
* - OPUS_APPLICATION_VOIP Process signal for improved speech intelligibility * @param[in] x <tt>opus_int32</tt>: Returns one of the following values:
* - OPUS_APPLICATION_AUDIO Favor faithfulness to the original input * <dl>
* - OPUS_APPLICATION_RESTRICTED_LOWDELAY Configure the minimum possible coding delay * <dt>#OPUS_APPLICATION_VOIP</dt>
* * <dd>Process signal for improved speech intelligibility.</dd>
* @param[in] x <tt>int</tt>: Application value * <dt>#OPUS_APPLICATION_AUDIO</dt>
* <dd>Favor faithfulness to the original input.</dd>
* <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
* <dd>Configure the minimum possible coding delay by disabling certain modes
* of operation.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x) #define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured application. @see OPUS_SET_APPLICATION /** Gets the encoder's configured application.
* * @see OPUS_SET_APPLICATION
* @param[out] x <tt>int*</tt>: Application value * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>#OPUS_APPLICATION_VOIP</dt>
* <dd>Process signal for improved speech intelligibility.</dd>
* <dt>#OPUS_APPLICATION_AUDIO</dt>
* <dd>Favor faithfulness to the original input.</dd>
* <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
* <dd>Configure the minimum possible coding delay by disabling certain modes
* of operation.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x)
...@@ -355,19 +434,27 @@ extern "C" { ...@@ -355,19 +434,27 @@ extern "C" {
* version to version, or even depend on the encoder's initial configuration. * version to version, or even depend on the encoder's initial configuration.
* Applications needing delay compensation should call this CTL rather than * Applications needing delay compensation should call this CTL rather than
* hard-coding a value. * hard-coding a value.
* @param[out] x <tt>int*</tt>: Number of lookahead samples * @param[out] x <tt>opus_int32 *</tt>: Number of lookahead samples
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x)
/** Configures the encoder's use of inband forward error correction. /** Configures the encoder's use of inband forward error correction (FEC).
* @note This is only applicable to the LPC layer * @note This is only applicable to the LPC layer
* * @see OPUS_GET_INBAND_FEC
* @param[in] x <tt>int</tt>: FEC flag, 0 (disabled) is default * @param[in] x <tt>opus_int32</tt>: Allowed values:
* <dl>
* <dt>0</dt><dd>Disable inband FEC (default).</dd>
* <dt>1</dt><dd>Enable inband FEC.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x) #define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x)
/** Gets encoder's configured use of inband forward error correction. @see OPUS_SET_INBAND_FEC /** Gets encoder's configured use of inband forward error correction.
* * @see OPUS_SET_INBAND_FEC
* @param[out] x <tt>int*</tt>: FEC flag * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>0</dt><dd>Inband FEC disabled (default).</dd>
* <dt>1</dt><dd>Inband FEC enabled.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x)
...@@ -375,25 +462,34 @@ extern "C" { ...@@ -375,25 +462,34 @@ extern "C" {
* Higher values with trigger progressively more loss resistant behavior in the encoder * Higher values with trigger progressively more loss resistant behavior in the encoder
* at the expense of quality at a given bitrate in the lossless case, but greater quality * at the expense of quality at a given bitrate in the lossless case, but greater quality
* under loss. * under loss.
* * @see OPUS_GET_PACKET_LOSS_PERC
* @param[in] x <tt>int</tt>: Loss percentage in the range 0-100, inclusive. * @param[in] x <tt>opus_int32</tt>: Loss percentage in the range 0-100, inclusive (default: 0).
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x) #define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured packet loss percentage. @see OPUS_SET_PACKET_LOSS_PERC /** Gets the encoder's configured packet loss percentage.
* * @see OPUS_SET_PACKET_LOSS_PERC
* @param[out] x <tt>int*</tt>: Loss percentage in the range 0-100, inclusive. * @param[out] x <tt>opus_int32 *</tt>: Returns the configured loss percentage
* in the range 0-100, inclusive (default: 0).
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x)
/** Configures the encoder's use of discontinuous transmission. /** Configures the encoder's use of discontinuous transmission (DTX).
* @note This is only applicable to the LPC layer * @note This is only applicable to the LPC layer
* * @see OPUS_GET_DTX
* @param[in] x <tt>int</tt>: DTX flag, 0 (disabled) is default * @param[in] x <tt>opus_int32</tt>: Allowed values:
* <dl>
* <dt>0</dt><dd>Disable DTX (default).</dd>
* <dt>1</dt><dd>Enabled DTX.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x) #define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x)
/** Gets encoder's configured use of discontinuous transmission. @see OPUS_SET_DTX /** Gets encoder's configured use of discontinuous transmission.
* * @see OPUS_SET_DTX
* @param[out] x <tt>int*</tt>: DTX flag * @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>0</dt><dd>DTX disabled (default).</dd>
* <dt>1</dt><dd>DTX enabled.</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x)
/**@}*/ /**@}*/
...@@ -444,7 +540,7 @@ extern "C" { ...@@ -444,7 +540,7 @@ extern "C" {
* The encoder and decoder state should be identical after coding a payload * The encoder and decoder state should be identical after coding a payload
* (assuming no data corruption or software bugs) * (assuming no data corruption or software bugs)
* *
* @param[out] x <tt>opus_uint32*</tt>: Entropy coder state * @param[out] x <tt>opus_uint32 *</tt>: Entropy coder state
* *
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x) #define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x)
...@@ -456,25 +552,36 @@ extern "C" { ...@@ -456,25 +552,36 @@ extern "C" {
* *
* This CTL is only implemented for decoder instances. * This CTL is only implemented for decoder instances.
* *
* @param[out] x <tt>opus_int32*</tt>: pitch period at 48 kHz (or 0 if not available) * @param[out] x <tt>opus_int32 *</tt>: pitch period at 48 kHz (or 0 if not available)
* *
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x)
/** Gets the encoder's configured bandpass or the decoder's last bandpass. @see OPUS_SET_BANDWIDTH /** Gets the encoder's configured bandpass or the decoder's last bandpass.
* @param[out] x <tt>int*</tt>: Bandwidth value * @see OPUS_SET_BANDWIDTH
* @param[out] x <tt>opus_int32 *</tt>: Returns one of the following values:
* <dl>
* <dt>#OPUS_AUTO</dt> <dd>(default)</dd>
* <dt>#OPUS_BANDWIDTH_NARROWBAND</dt> <dd>4 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_MEDIUMBAND</dt> <dd>6 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_WIDEBAND</dt> <dd>8 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_SUPERWIDEBAND</dt><dd>12 kHz passband</dd>
* <dt>#OPUS_BANDWIDTH_FULLBAND</dt> <dd>20 kHz passband</dd>
* </dl>
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
/** Configures the depth of signal being encoded. /** Configures the depth of signal being encoded.
* This is a hint which helps the encoder identify silence and near-silence. * This is a hint which helps the encoder identify silence and near-silence.
* The supported values are between 8 and 24 (default) * @see OPUS_GET_LSB_DEPTH
* @param[in] x <tt>opus_int32</tt>: Input precision * @param[in] x <tt>opus_int32</tt>: Input precision in bits, between 8 and 24
* (default: 24).
* @hideinitializer */ * @hideinitializer */
#define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x) #define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured signal depth. @see OPUS_SET_LSB_DEPTH /** Gets the encoder's configured signal depth.
* * @see OPUS_SET_LSB_DEPTH
* @param[out] x <tt>opus_int32*</tt>: Input precision * @param[out] x <tt>opus_int32 *</tt>: Input precision in bits, between 8 and
* 24 (default: 24).
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x)
/**@}*/ /**@}*/
...@@ -497,7 +604,7 @@ extern "C" { ...@@ -497,7 +604,7 @@ extern "C" {
#define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x) #define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x)
/** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN /** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN
* *
* @param[out] x <tt>opus_int32*</tt>: Amount to scale PCM signal by in Q8 dB units. * @param[out] x <tt>opus_int32 *</tt>: Amount to scale PCM signal by in Q8 dB units.
* @hideinitializer */ * @hideinitializer */
#define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x) #define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x)
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment