Clarify difference between user bandwidth settings.

1 files changed, 14 insertions, 2 deletions

diff --git a/include/opus_defines.h b/include/opus_defines.h
index 0b828179..aad47fc4 100644
--- a/include/opus_defines.h
+++ b/include/opus_defines.h
@@ -258,7 +258,13 @@ extern "C" {
   * @hideinitializer */
 #define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x)
 
-/** Configures the encoder's maximum bandpass allowed. @see OPUS_GET_MAX_BANDWIDTH
+/** Configures the maximum bandpass that the encoder will select automatically.
+  * Applications should normally use this instead of \a OPUS_SET_BANDWIDTH
+  * (leaving that set to the default, \c OPUS_AUTO). This allows the
+  * 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
+  * when the bitrate becomes too low, for better overall quality.
+  * @see OPUS_GET_MAX_BANDWIDTH
   * The supported values are:
   *  - OPUS_BANDWIDTH_NARROWBAND     4kHz passband
   *  - OPUS_BANDWIDTH_MEDIUMBAND     6kHz passband
@@ -274,7 +280,13 @@ extern "C" {
   * @hideinitializer */
 #define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
 
-/** Configures the encoder's bandpass. @see OPUS_GET_BANDWIDTH
+/** Sets the encoder's bandpass to a specific value.
+  * This prevents the encoder from automatically selecting the bandpass based
+  * 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
+  * instead, which still gives the encoder the freedom to reduce the bandpass
+  * when the bitrate becomes too low, for better overall quality.
+  * @see OPUS_GET_BANDWIDTH
   * The supported values are:
   *  - OPUS_AUTO (default)
   *  - OPUS_BANDWIDTH_NARROWBAND     4kHz passband