ref: 2557750095863a1f038b85700a4131d3e29a7405
parent: c248e6d0c261225f80c2e2568aca616467e3bfb6
author: Jean-Marc Valin <[email protected]>
date: Thu Sep 22 18:13:46 EDT 2011
API doc improvements
--- a/celt/opus_defines.h
+++ b/celt/opus_defines.h
@@ -111,28 +111,40 @@
#define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr)))
/** @endcond */
-/** @defgroup encoderctls Encoder related CTLs
- * @see genericctls,opusencoder
+/** @defgroup ctlvalues Pre-defined values for CTL interface
+ * @see genericctls,encoderctls
* @{*/
-/** @cond DOXYGEN_EXCLUDE */
/* Values for the various encoder CTLs */
-#define OPUS_AUTO -1000 /**<Auto bitrate @hideinitializer*/
+#define OPUS_AUTO -1000 /**<Auto/default setting @hideinitializer*/
#define OPUS_BITRATE_MAX -1 /**<Maximum bitrate @hideinitializer*/
+/** Best for "standard" VoIP/videoconference applications where listening quality and intelligibility matter most
+ * @hideinitializer */
#define OPUS_APPLICATION_VOIP 2048
+/** Best for broadcast/high-fidelity application where the decoded audio should be as close as possible to the input
+ * @hideinitializer */
#define OPUS_APPLICATION_AUDIO 2049
+/** Only use when lowest-achievable latency is what matters most. Voice-optimized modes cannot be used.
+ * @hideinitializer */
#define OPUS_APPLICATION_RESTRICTED_LOWDELAY 2051
-#define OPUS_SIGNAL_VOICE 3001
-#define OPUS_SIGNAL_MUSIC 3002
+#define OPUS_SIGNAL_VOICE 3001 /**< Signal being encoded is voice */
+#define OPUS_SIGNAL_MUSIC 3002 /**< Signal being encoded is music */
#define OPUS_BANDWIDTH_NARROWBAND 1101 /**< 4kHz bandpass @hideinitializer*/
#define OPUS_BANDWIDTH_MEDIUMBAND 1102 /**< 6kHz bandpass @hideinitializer*/
#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 */
+/**@}*/
+
+
+/** @defgroup encoderctls Encoder related CTLs
+ * @see genericctls,opusencoder
+ * @{+ */
+
/** Configures the encoder's computational complexity.
* The supported range is 0-10 inclusive with 10 representing the highest complexity.
* The default value is 10.
@@ -203,7 +215,7 @@
/** Configures the encoder's bandpass, @see OPUS_GET_BANDWIDTH
* The supported values are:
- * - OPUS_BANDWIDTH_AUTO (default)
+ * - OPUS_AUTO (default)
* - OPUS_BANDWIDTH_NARROWBAND 4kHz passband
* - OPUS_BANDWIDTH_MEDIUMBAND 6kHz passband
* - OPUS_BANDWIDTH_WIDEBAND 8kHz passband
@@ -257,17 +269,6 @@
* @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
--- a/src/opus.h
+++ b/src/opus.h
@@ -81,16 +81,10 @@
* enc = opus_encoder_create(Fs, channels, application, &error);
* @endcode
*
- * where
- * <ul>
- * <li>Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000</li>
- * <li>channels is the number of channels (1 or 2)</li>
- * <li>application is either OPUS_APPLICATION_VOIP or OPUS_APPLICATION_AUDIO</li>
- * <li>error will hold the error code in case or failure (or OPUS_OK on success)</li>
- * <li>the return value is a newly created encoder state to be used for encoding</li>
- * </ul>
+ * From this point, @c enc can be used for encoding an audio stream. An encoder state
+ * @b must @b not be used for more than one stream at the same time. Similarly, the encoder
+ * state @b must @b not be re-initialized for each frame.
*
- *
* While opus_encoder_create() allocates memory for the state, it's also possible
* to initialize pre-allocated memory:
*
@@ -120,11 +114,11 @@
* @endcode
*
* where
- * <ul>
- * <li>bitrate is in bits per second (b/s)</li>
- * <li>complexity is a value from 1 to 10 where 1 is the lowest complexity and 10 is the highest</li>
- * <li>signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC</li>
- * </ul>
+ *
+ * @arg bitrate is in bits per second (b/s)
+ * @arg complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest
+ * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC
+ *
* See @ref encoderctls and @ref genericctls for a complete list of parameters that can be set or queried. Most parameters can be set or changed at any time during a stream.
*
* To encode a frame, opus_encode() or opus_encode_float() must be called with exactly one frame (2.5, 5, 10, 20, 40 or 60 ms) of audio data:
@@ -141,7 +135,8 @@
* </ul>
*
* opus_encode() and opus_encode_frame() return the number of bytes actually written to the packet.
- * If that value is negative, then an error has occured. If the value is 1, then the packet does not need to be transmitted (DTX)
+ * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value
+ * is 1 byte, then the packet does not need to be transmitted (DTX).
*
* Once the encoder state if no longer needed, it can be destroyed with
*
@@ -169,23 +164,31 @@
/** Allocates and initializes an encoder state.
* There are three coding modes:
- * OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
+ *
+ * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
* signals. It enhances the input signal by high-pass filtering and
* emphasizing formants and harmonics. Optionally it includes in-band
* forward error correction to protect against packet loss. Use this
* mode for typical VoIP applications. Because of the enhancement,
* even at high bitrates the output may sound different from the input.
- * OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most
+ *
+ * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most
* non-voice signals like music. Use this mode for music and mixed
* (music/voice) content, broadcast, and applications requiring less
* than 15 ms of coding delay.
- * OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that
+ *
+ * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY 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).
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
- * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
- * @param [out] error <tt>int*</tt>: Error code
+ * @param [in] application <tt>int</tt>: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY)
+ * @param [out] error <tt>int*</tt>: @ref errorcodes
+ * @note Regardless of the sampling rate and number channels selected, the Opus encoder
+ * can switch to a lower audio audio bandwidth or number of channels if the bitrate
+ * selected is too low. This also means that it is safe to always use 48 kHz stereo input
+ * and let the encoder optimize the encoding.
*/
OPUS_EXPORT OpusEncoder *opus_encoder_create(
opus_int32 Fs,
@@ -196,13 +199,14 @@
/** Initializes a previously allocated encoder state
* The memory pointed to by st must be the size returned by opus_encoder_get_size.
- * This is intended for applications which use their own allocator instead of malloc. @see opus_encoder_create,opus_encoder_get_size
+ * This is intended for applications which use their own allocator instead of malloc.
+ * @see opus_encoder_create(),opus_encoder_get_size()
* To reset a previously initialized state use the OPUS_RESET_STATE CTL.
* @param [in] st <tt>OpusEncoder*</tt>: Encoder state
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
* @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
- * @retval OPUS_OK Success.
+ * @retval OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT int opus_encoder_init(
OpusEncoder *st,
@@ -221,7 +225,7 @@
* @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
* @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
* @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload; don't use for controlling bitrate
- * @returns length of the data payload (in bytes)
+ * @returns length of the data payload (in bytes) or @ref errorcodes
*/
OPUS_EXPORT int opus_encode(
OpusEncoder *st,
@@ -241,7 +245,7 @@
* @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
* @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
* @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload; don't use for controlling bitrate
- * @returns length of the data payload (in bytes)
+ * @returns length of the data payload (in bytes) or @ref errorcodes
*/
OPUS_EXPORT int opus_encode_float(
OpusEncoder *st,
@@ -328,7 +332,7 @@
/** Allocates and initializes a decoder state.
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
- * @param [out] error <tt>int*</tt>: Error code
+ * @param [out] error <tt>int*</tt>: OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT OpusDecoder *opus_decoder_create(
opus_int32 Fs,
@@ -343,7 +347,7 @@
* @param [in] st <tt>OpusDecoder*</tt>: Decoder state.
* @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
* @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
- * @retval OPUS_OK Success.
+ * @retval OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT int opus_decoder_init(
OpusDecoder *st,
@@ -361,7 +365,7 @@
* if less than the maximum frame size (120ms) some frames can not be decoded
* @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
* decoded. If no such data is available the frame is decoded as if it were lost.
- * @returns Number of decoded samples
+ * @returns Number of decoded samples or @ref errorcodes
*/
OPUS_EXPORT int opus_decode(
OpusDecoder *st,
@@ -382,7 +386,7 @@
* if less than the maximum frame size (120ms) some frames can not be decoded
* @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
* decoded. If no such data is available the frame is decoded as if it were lost.
- * @returns Number of decoded samples
+ * @returns Number of decoded samples or @ref errorcodes
*/
OPUS_EXPORT int opus_decode_float(
OpusDecoder *st,