Commit 25577500 authored by Jean-Marc Valin's avatar Jean-Marc Valin
Browse files

API doc improvements

parent c248e6d0
......@@ -111,27 +111,39 @@ extern "C" {
#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.
......@@ -203,7 +215,7 @@ extern "C" {
/** 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
......@@ -258,17 +270,6 @@ extern "C" {
* @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
......
......@@ -81,15 +81,9 @@ extern "C" {
* 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 @@ extern "C" {
* @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 @@ extern "C" {
* </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 @@ OPUS_EXPORT int opus_encoder_get_size(int channels);
/** 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 @@ OPUS_EXPORT OpusEncoder *opus_encoder_create(
/** 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 @@ OPUS_EXPORT int opus_encoder_init(
* @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 @@ OPUS_EXPORT int opus_encode(
* @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 @@ OPUS_EXPORT int opus_decoder_get_size(int channels);
/** 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 @@ OPUS_EXPORT OpusDecoder *opus_decoder_create(
* @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 @@ OPUS_EXPORT int opus_decoder_init(
* 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 @@ OPUS_EXPORT int opus_decode(
* 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,
......
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