ref: f5b2d78f4af95b324f8bc00d6ef958862a4ef659
parent: b0794ba059ecb249e35788f2d94518b7e217ff58
author: Timothy B. Terriberry <[email protected]>
date: Tue Jul 17 07:49:45 EDT 2012
Clarify difference between user bandwidth settings.
--- a/include/opus_defines.h
+++ b/include/opus_defines.h
@@ -258,7 +258,13 @@
* @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 @@
* @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