Commit 03b5137ba9 for asterisk.org

commit 03b5137ba905a127870f788b1d54d251f8ae6993
Author: Jacky W J Li <fs_liwenjie@163.com>
Date:   Tue Aug 25 23:50:16 2026 +0800

    frame: Correct ast_frame_adjust_volume* documentation of 'adjustment'

    The documentation for ast_frame_adjust_volume() and
    ast_frame_adjust_volume_float() described the 'adjustment' parameter as a
    dB value. In reality the parameter is a linear gain factor applied
    directly to the audio samples: a positive value multiplies each sample,
    a negative value divides each sample, and 0 leaves the audio unchanged.

    The documentation block has also been reformatted to use the standard
    ' *' Doxygen style (asterisk in the second column) for consistency with
    the rest of the file.

    To convert a dB change to this factor use adjustment = 10^(dB/20)
    (for example, 2 ~= +6 dB and 10 ~= +20 dB).

    Resolves: #1167

diff --git a/include/asterisk/frame.h b/include/asterisk/frame.h
index a81ff92024..67ab1bf376 100644
--- a/include/asterisk/frame.h
+++ b/include/asterisk/frame.h
@@ -612,18 +612,28 @@ void ast_frame_dump(const char *name, struct ast_frame *f, char *prefix);
 struct ast_frame *ast_frame_enqueue(struct ast_frame *head, struct ast_frame *f, int maxlen, int dupe);

 /*!
-  \brief Adjusts the volume of the audio samples contained in a frame.
-  \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
-  \param adjustment The number of dB to adjust up or down.
-  \return 0 for success, non-zero for an error
+ * \brief Adjusts the volume of the audio samples contained in a frame.
+ * \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
+ * \param adjustment The linear gain factor applied to each sample.
+ *
+ * \note This is NOT a dB value.  A positive value multiplies each sample by the factor
+ * (e.g. 2 doubles the volume), a negative value divides each sample by the magnitude
+ * (e.g. -2 halves it), and 0 leaves the audio unchanged. To convert a dB change
+ *  to this factor use adjustment = 10^(dB/20) (so 10 ~= +20 dB and 2 ~= +6 dB).
+ * \return 0 for success, non-zero for an error
  */
 int ast_frame_adjust_volume(struct ast_frame *f, int adjustment);

 /*!
-  \brief Adjusts the volume of the audio samples contained in a frame.
-  \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
-  \param adjustment The number of dB to adjust up or down.
-  \return 0 for success, non-zero for an error
+ * \brief Adjusts the volume of the audio samples contained in a frame.
+ * \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
+ * \param adjustment The linear gain factor applied to each sample.
+ *
+ * \note This is NOT a dB value.  A positive value multiplies each sample by the factor
+ * (e.g. 2 doubles the volume), a negative value divides each sample by the magnitude
+ * (e.g. -2 halves it), and 0 leaves the audio unchanged. To convert a dB change
+ *  to this factor use adjustment = 10^(dB/20) (so 10 ~= +20 dB and 2 ~= +6 dB).
+ * \return 0 for success, non-zero for an error
  */
 int ast_frame_adjust_volume_float(struct ast_frame *f, float adjustment);