app_confbridge: Update dsp_silence_threshold and dsp_talking_threshold docs.

The dsp_talking_threshold does not represent time in milliseconds.  It
represents the average magnitude per sample in the audio packets.  This is
what the DSP uses to determine if a packet is silence or talking/noise.

Change-Id: If6f939c100eb92a5ac6c21236559018eeaf58443

2 files changed, 50 insertions, 53 deletions

diff --git a/apps/confbridge/conf_config_parser.c b/apps/confbridge/conf_config_parser.c
index 99eea0a27..71da80206 100644
--- a/apps/confbridge/conf_config_parser.c
+++ b/apps/confbridge/conf_config_parser.c
@@ -144,72 +144,66 @@
 					</para></description>
 				</configOption>
 				<configOption name="dsp_silence_threshold">
-					<synopsis>The number of milliseconds of detected silence necessary to trigger silence detection</synopsis>
-					<description><para>
-					The time in milliseconds of sound falling within the what
-					the dsp has established as baseline silence before a user
-					is considered be silent.  This value affects several
-					operations and should not be changed unless the impact
-					on call quality is fully understood.</para>
-					<para>What this value affects internally:</para>
-					<para>
-						1. When talk detection AMI events are enabled, this value
+					<synopsis>The number of milliseconds of silence necessary to declare talking stopped.</synopsis>
+					<description>
+						<para>The time in milliseconds of sound falling below the
+						<replaceable>dsp_talking_threshold</replaceable> option when
+						a user is considered to stop talking.  This value affects several
+						operations and should not be changed unless the impact on call
+						quality is fully understood.
+						</para>
+						<para>What this value affects internally:
+						</para>
+						<para>1. When talk detection AMI events are enabled, this value
 						determines when the user has stopped talking after a
 						period of talking.  If this value is set too low
 						AMI events indicating the user has stopped talking
 						may get falsely sent out when the user briefly pauses
 						during mid sentence.
-					</para>
-					<para>
-						2. The <replaceable>drop_silence</replaceable> option depends on this value to
-						determine when the user's audio should begin to be
-						dropped from the conference bridge after the user
+						</para>
+						<para>2. The <replaceable>drop_silence</replaceable> option
+						depends on this value to determine when the user's audio should
+						begin to be dropped from the conference bridge after the user
 						stops talking.  If this value is set too low the user's
-						audio stream may sound choppy to the other participants.
-						This is caused by the user transitioning constantly from
-						silence to talking during mid sentence.
-					</para>
-					<para>
-						The best way to approach this option is to set it slightly above
-						the maximum amount of ms of silence a user may generate during
-						natural speech.
-					</para>
-					<para>By default this value is 2500ms. Valid values are 1 through 2^31.</para>
+						audio stream may sound choppy to the other participants.  This
+						is caused by the user transitioning constantly from silence to
+						talking during mid sentence.
+						</para>
+						<para>The best way to approach this option is to set it slightly
+						above the maximum amount of milliseconds of silence a user may
+						generate during natural speech.
+						</para>
+						<para>Valid values are 1 through 2^31.</para>
 					</description>
 				</configOption>
 				<configOption name="dsp_talking_threshold">
-					<synopsis>The number of milliseconds of detected non-silence necessary to triger talk detection</synopsis>
-					<description><para>
-						The time in milliseconds of sound above what the dsp has
-						established as base line silence for a user before a user
-						is considered to be talking.  This value affects several
-						operations and should not be changed unless the impact on
-						call quality is fully understood.</para>
-						<para>
-						What this value affects internally:
+					<synopsis>Average magnitude threshold to determine talking.</synopsis>
+					<description>
+						<para>The minimum average magnitude per sample in a frame
+						for the DSP to consider talking/noise present.  A value below
+						this level is considered silence.  This value affects several
+						operations and should not be changed unless the impact on call
+						quality is fully understood.
+						</para>
+						<para>What this value affects internally:
 						</para>
-						<para>
-						1. Audio is only mixed out of a user's incoming audio stream
-						if talking is detected.  If this value is set too
-						loose the user will hear themselves briefly each
-						time they begin talking until the dsp has time to
-						establish that they are in fact talking.
+						<para>1. Audio is only mixed out of a user's incoming audio
+						stream if talking is detected.  If this value is set too
+						high the user will hear himself talking.
 						</para>
-						<para>
-						2. When talk detection AMI events are enabled, this value
+						<para>2. When talk detection AMI events are enabled, this value
 						determines when talking has begun which results in
-						an AMI event to fire.  If this value is set too tight
+						an AMI event to fire.  If this value is set too low
 						AMI events may be falsely triggered by variants in
 						room noise.
 						</para>
-						<para>
-						3. The <replaceable>drop_silence</replaceable> option depends on this value to determine
-						when the user's audio should be mixed into the bridge
-						after periods of silence.  If this value is too loose
-						the beginning of a user's speech will get cut off as they
-						transition from silence to talking.
+						<para>3. The <replaceable>drop_silence</replaceable> option
+						depends on this value to determine when the user's audio should
+						be mixed into the bridge after periods of silence.  If this value
+						is too high the user's speech will get discarded as they will
+						be considered silent.
 						</para>
-						<para>By default this value is 160 ms. Valid values are 1 through 2^31</para>
+						<para>Valid values are 1 through 2^15.</para>
 					</description>
 				</configOption>
 				<configOption name="jitterbuffer">
@@ -1479,7 +1473,7 @@ static char *handle_cli_confbridge_show_user_profile(struct ast_cli_entry *e, in
 		"enabled" : "disabled");
 	ast_cli(a->fd,"Silence Threshold:       %ums\n",
 		u_profile.silence_threshold);
-	ast_cli(a->fd,"Talking Threshold:       %ums\n",
+	ast_cli(a->fd,"Talking Threshold:       %u\n",
 		u_profile.talking_threshold);
 	ast_cli(a->fd,"Denoise:                 %s\n",
 		u_profile.flags & USER_OPT_DENOISE ?
diff --git a/apps/confbridge/include/confbridge.h b/apps/confbridge/include/confbridge.h
index 162ff224c..044ab4003 100644
--- a/apps/confbridge/include/confbridge.h
+++ b/apps/confbridge/include/confbridge.h
@@ -41,7 +41,10 @@
 #define DEFAULT_BRIDGE_PROFILE "default_bridge"
 #define DEFAULT_MENU_PROFILE "default_menu"
 
+/*! Default minimum average magnitude threshold to determine talking by the DSP. */
 #define DEFAULT_TALKING_THRESHOLD 160
+
+/*! Default time in ms of silence necessary to declare talking stopped by the bridge. */
 #define DEFAULT_SILENCE_THRESHOLD 2500
 
 enum user_profile_flags {
@@ -140,9 +143,9 @@ struct user_profile {
 	char announcement[PATH_MAX];
 	unsigned int flags;
 	unsigned int announce_user_count_all_after;
-	/*! The time in ms of talking before a user is considered to be talking by the dsp. */
+	/*! Minimum average magnitude threshold to determine talking by the DSP. */
 	unsigned int talking_threshold;
-	/*! The time in ms of silence before a user is considered to be silent by the dsp. */
+	/*! Time in ms of silence necessary to declare talking stopped by the bridge. */
 	unsigned int silence_threshold;
 	/*! The time in ms the user may stay in the confbridge */
 	unsigned int timeout;