add API function to perform volume adjustment on a frame of SLINEAR data

documentation cleanup


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@6874 65c4cc65-6c06-0410-ace0-fbb531ad65f3

frame.c

@@ -1252,3 +1252,22 @@ int ast_codec_get_len(int format, int samples)
 
 	return len;
 }
+
+int ast_frame_adjust_volume(struct ast_frame *f, int adjustment)
+{
+	int count;
+	short *fdata = f->data;
+
+	if ((f->frametype != AST_FRAME_VOICE) || (f->subclass != AST_FORMAT_SLINEAR))
+		return -1;
+
+	for (count = 0; count < f->samples; count++) {
+		if (adjustment > 0) {
+			fdata[count] *= abs(adjustment);
+		} else if (adjustment < 0) {
+			fdata[count] /= abs(adjustment);
+		}
+	}
+
+	return 0;
+}

include/asterisk/frame.h

@@ -49,7 +49,7 @@ struct ast_frame {
 	int samples;				
 	/*! Was the data malloc'd?  i.e. should we free it when we discard the frame? */
 	int mallocd;				
-	/*! How far into "data" the data really starts */
+	/*! How many bytes exist _before_ "data" that can be used if needed */
 	int offset;				
 	/*! Optional source of frame for debugging */
 	const char *src;				
@@ -64,8 +64,8 @@ struct ast_frame {
 };
 
 #define AST_FRIENDLY_OFFSET 	64		/*! It's polite for a a new frame to
-						    				have this number of bytes for additional
-											headers.  */
+						  have this number of bytes for additional
+						  headers.  */
 #define AST_MIN_OFFSET 		32		/*! Make sure we keep at least this much handy */
 
 /*! Need the header be free'd? */
@@ -419,6 +419,14 @@ static inline int ast_codec_interp_len(int format)
 	return (format == AST_FORMAT_ILBC) ? 30 : 20;
 }
 
+/*!
+  \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
+ */
+int ast_frame_adjust_volume(struct ast_frame *f, int adjustment);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif