Commit 29095379 authored by Gregory Maxwell's avatar Gregory Maxwell
Browse files

Documentation updates.

parent 131d8882
......@@ -758,11 +758,11 @@ may be active.
bit- +-------+ | | | |conversion| v
stream | Range |---+ +-------+ +----------+ /---\ audio
------->|decoder| | + |------>
| |---+ +-------+ \---/
+-------+ | | CELT | ^
+->|decoder|--------------------+
| |
+-------+
| |---+ +-------+ \---/
+-------+ | | CELT | ^
+-------------->|decoder|-------+
| |
+-------+
]]>
</artwork>
</figure>
......@@ -808,8 +808,6 @@ Raw bits are only used in the CELT layer.
Each symbol coded by the range coder is drawn from a finite alphabet and coded
in a separate "context", which describes the size of the alphabet and the
relative frequency of each symbol in that alphabet.
Opus only uses static contexts.
They are not adapted to the statistics of the data as it is coded.
</t>
<t>
Suppose there is a context with n symbols, identified with an index that ranges
......@@ -818,8 +816,8 @@ The parameters needed to encode or decode a symbol in this context are
represented by a three-tuple (fl[k],&nbsp;fh[k],&nbsp;ft), with
0&nbsp;&lt;=&nbsp;fl[k]&nbsp;&lt;&nbsp;fh[k]&nbsp;&lt;=&nbsp;ft&nbsp;&lt;=&nbsp;65535.
The values of this tuple are derived from the probability model for the
symbol, represented by traditional "frequency counts" (although, since Opus
uses static contexts, these are not updated as symbols are decoded).
symbol, represented by traditional "frequency counts". Because Opus
uses static contexts these are not updated as symbols are decoded.
Let f[i] be the frequency of symbol i.
Then the three-tuple corresponding to symbol k is given by
</t>
......@@ -4160,7 +4158,7 @@ decode the trim value using the inverse CDF {127, 126, 124, 119, 109, 87, 41, 19
<t>For 10 ms and 20 ms frames using short blocks and that have at least LM+2 bits left prior to
the allocation process, then one anti-collapse bit is reserved in the allocation process so it can
be decoded later. Following the the anti-collapse reservation, one bit is reserved for skip is available.</t>
be decoded later. Following the the anti-collapse reservation, one bit is reserved for skip if available.</t>
<t>For stereo frames, bits are reserved for intensity stereo and for dual stereo. Intensity stereo
requires ilog2(end-start) bits. Those bits are reserved if there is enough bits left. Following this, one
......
......@@ -39,7 +39,7 @@
extern "C" {
#endif
/** \defgroup errorcodes Error codes
/** @defgroup errorcodes Error codes
* @{
*/
/** No error @hideinitializer*/
......@@ -60,7 +60,7 @@ extern "C" {
#define OPUS_ALLOC_FAIL -7
/**@}*/
/** \cond OPUS_INTERNAL_DOC */
/** @cond OPUS_INTERNAL_DOC */
/**Export control for opus functions */
#if defined(__GNUC__) && defined(OPUS_BUILD)
......@@ -108,14 +108,14 @@ extern "C" {
#define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x))
#define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr)))
#define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr)))
/** \endcond */
/** @endcond */
/** \defgroup encoderctls Encoder related CTLs
* @see [opus_encoder_ctl]
/** @defgroup encoderctls Encoder related CTLs
* @see opus_encoder_ctl
* @{
*/
/** \cond DOXYGEN_EXCLUDE */
/* Values for the varrious encoder CTLs */
/** @cond DOXYGEN_EXCLUDE */
/* Values for the various encoder CTLs */
#define OPUS_AUTO -1000 /**<Auto bitrate @hideinitializer*/
#define OPUS_BITRATE_MAX -1 /**<Maximum bitrate @hideinitializer*/
......@@ -130,17 +130,17 @@ extern "C" {
#define OPUS_BANDWIDTH_WIDEBAND 1103 /**< 8kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_SUPERWIDEBAND 1104 /**<12kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_FULLBAND 1105 /**<20kHz bandpass @hideinitializer*/
/** \endcond */
/** @endcond */
/** Configures the encoder's computational complexity.
* The supported range is 0-10 inclusive with 10 representing the highest complexity.
* The default value is inconsistent between modes
* @todo Complexity is inconsistent between modes
* \param[in] x <tt>int</tt>: 0-10, inclusive
* @param[in] x <tt>int</tt>: 0-10, inclusive
* @hideinitializer */
#define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x)
/** Gets the encoder's complexity configuration, @see [OPUS_SET_COMPLEXITY]
* \param[out] x <tt>int*</tt>: 0-10, inclusive
/** Gets the encoder's complexity configuration, @see OPUS_SET_COMPLEXITY
* @param[out] x <tt>int*</tt>: 0-10, inclusive
* @hideinitializer */
#define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x)
......@@ -150,11 +150,11 @@ extern "C" {
* The value OPUS_BITRATE_MAX can be used to cause the codec to use as much rate
* as it can, which is useful for controlling the rate by adjusting the output
* buffer size.
* \param[in] x <tt>opus_int32</tt>: bitrate in bits per second.
* @param[in] x <tt>opus_int32</tt>: bitrate in bits per second.
* @hideinitializer */
#define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x)
/** Gets the encoder's bitrate configuration, @see [OPUS_SET_BITRATE]
* \param[out] x <tt>opus_int32*</tt>: bitrate in bits per second.
/** Gets the encoder's bitrate configuration, @see OPUS_SET_BITRATE
* @param[out] x <tt>opus_int32*</tt>: bitrate in bits per second.
* @hideinitializer */
#define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x)
......@@ -165,11 +165,11 @@ extern "C" {
* The configured bitrate may not be met exactly because frames must
* be an integer number of bytes in length.
* @warning Only the MDCT mode of Opus can provide hard CBR behavior.
* \param[in] x <tt>int</tt>: 0 (default); 1
* @param[in] x <tt>int</tt>: 0 (default); 1
* @hideinitializer */
#define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x)
/** Gets the encoder's VBR configuration, @see [OPUS_SET_VBR]
* \param[out] x <tt>int*</tt>: 0; 1
/** Gets the encoder's VBR configuration, @see OPUS_SET_VBR
* @param[out] x <tt>int*</tt>: 0; 1
* @hideinitializer */
#define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x)
......@@ -182,22 +182,22 @@ extern "C" {
* Speech mode ignores it completely, hybrid mode may fail to obey it
* if the LPC layer uses more bitrate than the constraint would have
* permitted.
* \param[in] x <tt>int</tt>: 0; 1 (default)
* @param[in] x <tt>int</tt>: 0; 1 (default)
* @hideinitializer */
#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]
* \param[out] x <tt>int*</tt>: 0; 1
/** Gets the encoder's constrained VBR configuration @see OPUS_SET_VBR_CONSTRAINT
* @param[out] x <tt>int*</tt>: 0; 1
* @hideinitializer */
#define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x)
/** Configures mono/stereo forcing in the encoder.
* This is useful when the caller knows that the input signal is currently a mono
* source embedded in a stereo stream.
* \param[in] x <tt>int</tt>: OPUS_AUTO (default); 1 (forced mono); 2 (forced stereo)
* @param[in] x <tt>int</tt>: OPUS_AUTO (default); 1 (forced mono); 2 (forced stereo)
* @hideinitializer */
#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]
* \param[out] x <tt>int*</tt>: OPUS_AUTO; 0; 1
/** Gets the encoder's forced channel configuration, @see OPUS_SET_FORCE_CHANNELS
* @param[out] x <tt>int*</tt>: OPUS_AUTO; 0; 1
* @hideinitializer */
#define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x)
......@@ -208,12 +208,12 @@ extern "C" {
* - OPUS_BANDWIDTH_MEDIUMBAND 6kHz passband
* - OPUS_BANDWIDTH_WIDEBAND 8kHz passband
* - OPUS_BANDWIDTH_SUPERWIDEBAND 12kHz passband
* - OPUS_BANDWIDTH_FULLBAND 24kHz passband
* \param[in] x <tt>int</tt>: Bandwidth value
* - OPUS_BANDWIDTH_FULLBAND 20kHz passband
* @param[in] x <tt>int</tt>: Bandwidth value
* @hideinitializer */
#define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured bandpass, @see [OPUS_SET_BANDWIDTH]
* \param[out] x <tt>int*</tt>: Bandwidth value
/** Gets the encoder's configured bandpass, @see OPUS_SET_BANDWIDTH
* @param[out] x <tt>int*</tt>: Bandwidth value
* @hideinitializer */
#define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
......@@ -223,12 +223,12 @@ extern "C" {
* - OPUS_SIGNAL_AUTO (default)
* - OPUS_SIGNAL_VOICE
* - OPUS_SIGNAL_MUSIC
* \param[in] x <tt>int</tt>: Signal type
* @param[in] x <tt>int</tt>: Signal type
* @hideinitializer */
#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>int*</tt>: Signal type
* @hideinitializer */
#define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x)
......@@ -239,12 +239,12 @@ extern "C" {
* ultimately expected to bias an automatic signal classifier, but it currently
* just shifts the static bitrate to mode mapping around a little bit.
*
* \param[in] x <tt>int</tt>: Voice percentage in the range 0-100, inclusive.
* @param[in] x <tt>int</tt>: Voice percentage in the range 0-100, inclusive.
* @hideinitializer */
#define OPUS_SET_VOICE_RATIO(x) OPUS_SET_VOICE_RATIO_REQUEST, __opus_check_int(x)
/** Gets the encoder's configured voice ratio value, @see [OPUS_SET_VOICE_RATIO]
/** Gets the encoder's configured voice ratio value, @see OPUS_SET_VOICE_RATIO
*
* \param[out] x <tt>int*</tt>: Voice percentage in the range 0-100, inclusive.
* @param[out] x <tt>int*</tt>: Voice percentage in the range 0-100, inclusive.
* @hideinitializer */
#define OPUS_GET_VOICE_RATIO(x) OPUS_GET_VOICE_RATIO_REQUEST, __opus_check_int_ptr(x)
......@@ -253,15 +253,26 @@ extern "C" {
* The supported values are:
* - OPUS_APPLICATION_VOIP Process signal for improved speech intelligibility
* - OPUS_APPLICATION_AUDIO Favor faithfulness to the original input
* \param[in] x <tt>int</tt>: Application value
* @param[in] x <tt>int</tt>: Application value
* @hideinitializer */
#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>int*</tt>: Application value
* @hideinitializer */
#define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x)
/** Configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay.
* This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
* The setting can only be changed right after initialization or after a reset and changes the lookahead.
* @param[in] x <tt>int</tt>: 0 (default); 1 (lowdelay)
* @hideinitializer */
#define OPUS_SET_RESTRICTED_LOWDELAY(x) OPUS_SET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int(x)
/** Gets the encoder's forced channel configuration, @see OPUS_SET_RESTRICTED_LOWDELAY
* @param[out] x <tt>int*</tt>: 0; 1
* @hideinitializer */
#define OPUS_GET_RESTRICTED_LOWDELAY(x) OPUS_GET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int_ptr(x)
/** Gets the total samples of delay added by the entire codec.
* This can be queried by the encoder and then the provided number of samples can be
* skipped on from the start of the decoder's output to provide time aligned input
......@@ -273,19 +284,19 @@ extern "C" {
* version to version, or even depend on the encoder's initial configuration.
* Applications needing delay compensation should call this CTL rather than
* hard-coding a value.
* \param[out] x <tt>int*</tt>: Number of lookahead samples
* @param[out] x <tt>int*</tt>: Number of lookahead samples
* @hideinitializer */
#define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x)
/** Configures the encoder's use of inband forward error correction.
* @note This is only applicable to the LPC layer
*
* \param[in] x <tt>int</tt>: FEC flag, 0 (disabled) is default
* @param[in] x <tt>int</tt>: FEC flag, 0 (disabled) is default
* @hideinitializer */
#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>int*</tt>: FEC flag
* @hideinitializer */
#define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x)
......@@ -294,30 +305,30 @@ extern "C" {
* at the expense of quality at a given bitrate in the lossless case, but greater quality
* under loss.
*
* \param[in] x <tt>int</tt>: Loss percentage in the range 0-100, inclusive.
* @param[in] x <tt>int</tt>: Loss percentage in the range 0-100, inclusive.
* @hideinitializer */
#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>int*</tt>: Loss percentage in the range 0-100, inclusive.
* @hideinitializer */
#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.
* @note This is only applicable to the LPC layer
*
* \param[in] x <tt>int</tt>: DTX flag, 0 (disabled) is default
* @param[in] x <tt>int</tt>: DTX flag, 0 (disabled) is default
* @hideinitializer */
#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>int*</tt>: DTX flag
* @hideinitializer */
#define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x)
/**@}*/
/** \defgroup genericctls Generic CTLs
* @see [opus_encoder_ctl,opus_decoder_ctl]
/** @defgroup genericctls Generic CTLs
* @see opus_encoder_ctl,opus_decoder_ctl
* @{
*/
......@@ -333,39 +344,27 @@ extern "C" {
* The encoder and decoder state should be identical after coding a payload
* (assuming no data corruption or software bugs)
*
* \param[out] x <tt>opus_int32*</tt>: Entropy coder state
* @param[out] x <tt>opus_int32*</tt>: Entropy coder state
*
* @hideinitializer */
#define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x)
/** Configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay.
* This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
* The setting can only be changed right after initialization or after a reset.
* \param[in] x <tt>int</tt>: 0 (default); 1 (lowdelay)
* @hideinitializer */
#define OPUS_SET_RESTRICTED_LOWDELAY(x) OPUS_SET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int(x)
/** Gets the encoder's forced channel configuration, @see [OPUS_SET_RESTRICTED_LOWDELAY]
* \param[out] x <tt>int*</tt>: 0; 1
* @hideinitializer */
#define OPUS_GET_RESTRICTED_LOWDELAY(x) OPUS_GET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int_ptr(x)
/**@}*/
/** \defgroup libinfo Opus library information functions
/** @defgroup libinfo Opus library information functions
* @{
*/
/** Converts an opus error code into a human readable string.
*
* \param[in] error <tt>int</tt>: Error number
* \retval Error string
* @param[in] error <tt>int</tt>: Error number
* @retval Error string
*/
OPUS_EXPORT const char *opus_strerror(int error);
/** Gets the libopus version string.
*
* \retval Version string
* @retval Version string
*/
OPUS_EXPORT const char *opus_get_version_string(void);
/**@}*/
......
Markdown is supported
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