app_amd: Correct documentation to reflect functionality

Update documentation to reflect that maximum_number_of_words
has functionality inconsistent with the variable name (and inconsistent
with prior documentation.)

Update documentation for silence_threshold, which previously implied
that it was measuring time, rather than noise averages in the sample.

Update the comments in amd.conf.sample.

ASTERISK-25639 #close
Change-Id: I4b1451e5dc9cb3cb06d59b6ab872f5275ba79093

diff --git a/apps/app_amd.c b/apps/app_amd.c
index a849aad93b47f13b3ad3b4f17e8be398e1e4057e..66aadf9904320830c7a2e627606843df9bb7b00c 100644 (file)
--- a/apps/app_amd.c
+++ b/apps/app_amd.c
@@ -50,19 +50,19 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
                <syntax>
                        <parameter name="initialSilence" required="false">
                                <para>Is maximum initial silence duration before greeting.</para>
-                               <para>If this is exceeded set as MACHINE</para>
+                               <para>If this is exceeded, the result is detection as a MACHINE</para>
                        </parameter>
                        <parameter name="greeting" required="false">
                                <para>is the maximum length of a greeting.</para>
-                               <para>If this is exceeded set as MACHINE</para>
+                               <para>If this is exceeded, the result is detection as a MACHINE</para>
                        </parameter>
                        <parameter name="afterGreetingSilence" required="false">
                                <para>Is the silence after detecting a greeting.</para>
-                               <para>If this is exceeded set as HUMAN</para>
+                               <para>If this is exceeded, the result is detection as a HUMAN</para>
                        </parameter>
                        <parameter name="totalAnalysis Time" required="false">
                                <para>Is the maximum time allowed for the algorithm</para>
-                               <para>to decide HUMAN or MACHINE</para>
+                               <para>to decide on whether the audio represents a HUMAN, or a MACHINE</para>
                        </parameter>
                        <parameter name="miniumWordLength" required="false">
                                <para>Is the minimum duration of Voice considered to be a word</para>
@@ -73,14 +73,14 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
                        </parameter>
                        <parameter name="maximumNumberOfWords" required="false">
                                <para>Is the maximum number of words in a greeting</para>
-                               <para>If this is exceeded set as MACHINE</para>
+                               <para>If this is REACHED, then the result is detection as a MACHINE</para>
                        </parameter>
                        <parameter name="silenceThreshold" required="false">
-                               <para>How long do we consider silence</para>
+                               <para>What is the average level of noise from 0 to 32767 which if not exceeded, should be considered silence?</para>
                        </parameter>
                        <parameter name="maximumWordLength" required="false">
                                <para>Is the maximum duration of a word to accept.</para>
-                               <para>If exceeded set as MACHINE</para>
+                               <para>If exceeded, then the result is detection as a MACHINE</para>
                        </parameter>
                </syntax>
                <description>
@@ -118,7 +118,7 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
                                        </value>
                                        <value name="MAXWORDS">
                                                Word Count - maximum number of words.
-                                       </value>        
+                                       </value>
                                </variable>
                        </variablelist>
                </description>

diff --git a/configs/amd.conf.sample b/configs/amd.conf.sample
index c4a5907c53ce6ee91a9560108c662bad7b391f2e..84b391ceaf1b42d90895569c539430a59aa53c90 100644 (file)
--- a/configs/amd.conf.sample
+++ b/configs/amd.conf.sample
@@ -3,17 +3,29 @@
 ;
 
 [general]
+total_analysis_time = 5000     ; Maximum time allowed for the algorithm to decide
+                               ; on whether the audio represents a HUMAN, or a MACHINE
+silence_threshold = 256                ; If the average level of noise in a sample does not reach
+                               ; this value, from a scale of 0 to 32767, then we will consider
+                               ; it to be silence.
+
+; Greeting ;
 initial_silence = 2500         ; Maximum silence duration before the greeting.
-                               ; If exceeded then MACHINE.
-greeting = 1500                        ; Maximum length of a greeting. If exceeded then MACHINE.
+                               ; If exceeded, then the result is detection as a MACHINE.
 after_greeting_silence = 800   ; Silence after detecting a greeting.
-                               ; If exceeded then HUMAN
-total_analysis_time = 5000     ; Maximum time allowed for the algorithm to decide
-                               ; on a HUMAN or MACHINE
+                               ; If exceeded, then the result is detection as a HUMAN
+greeting = 1500                        ; Maximum length of a greeting. If exceeded, then the
+                               ; result is detection as a MACHINE.
+
+; Word detection ;
 min_word_length = 100          ; Minimum duration of Voice to considered as a word
+maximum_word_length = 5000     ; Maximum duration of a single Voice utterance allowed.
 between_words_silence = 50     ; Minimum duration of silence after a word to consider
                                ; the audio what follows as a new word
-maximum_number_of_words = 3    ; Maximum number of words in the greeting.
-                               ; If exceeded then MACHINE
-maximum_word_length = 5000  ; Maximum duration of a single Voice utterance allowed.
-silence_threshold = 256
+
+maximum_number_of_words = 3    ; Maximum number of words in the greeting
+                               ; If REACHED, then the result is detection as a MACHINE
+                               ; WARNING: Releases prior to January 1 2016 documented
+                               ; maximum_number_of_words as 'if exceeded, then MACHINE',
+                               ; which did not reflect the true functionality.  In Asterisk 14,
+                               ; this functionality will change to reflect the variables' name.