app_amd: Correct maximum_number_of_words functionality & documentation

- The maximum_number_of_words was previously documented as being
the number of words that when exceeded, would result in the AMD
application returning that the audio represents a machine.

This was inconsistent with its actual functionality - it was
a number of words that when REACHED, would result in determination
as a machine.

This update corrects the functionality to match the previously
documented functionality.  This is a backwards incompatible change
in configuration file, and has been added to UPGRADE.txt as a result.

The sample configuration file and application defaults have been updated
so that the default value is now 2, which reflects the same default
functionality as previous versions.

- 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/UPGRADE.txt b/UPGRADE.txt
index 91d9edc924932eaf5edbb93a79c981579cd07215..6fb82c43aa24c8e762eda37d9ae66ed0b608220e 100644 (file)
--- a/UPGRADE.txt
+++ b/UPGRADE.txt
@@ -64,5 +64,15 @@ AMI:
    Commands that fail to execute (no such command, invalid syntax etc.) now
    return an Error response instead of Success.
 
+app_amd:
+ - The 'maximum_number_of_words' configuration option and parameter to the AMD
+   application previously did not match the documented functionality + variable
+   name.  In Asterisk 13, a value of '3' would mean that if '3' words were detected,
+   the result would be detection as a 'MACHINE'.  As of this version, the value
+   reflects the maximum words that if EXCEEDED (rather than reached), would
+   result in detection as a machine.  This means that you should update this
+   value to be one higher than your previos value, if your previous value
+   was working well for you.
+
 ===========================================================
 ===========================================================

diff --git a/apps/app_amd.c b/apps/app_amd.c
index ee421b6bc345d074d20708528128280b2c0d54ec..83da5330d89d72958358524158836ae7a3e2ab0d 100644 (file)
--- a/apps/app_amd.c
+++ b/apps/app_amd.c
@@ -62,19 +62,19 @@ ASTERISK_REGISTER_FILE()
                <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>
@@ -85,14 +85,14 @@ ASTERISK_REGISTER_FILE()
                        </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 exceeded, 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>
@@ -130,7 +130,7 @@ ASTERISK_REGISTER_FILE()
                                        </value>
                                        <value name="MAXWORDS">
                                                Word Count - maximum number of words.
-                                       </value>        
+                                       </value>
                                </variable>
                        </variablelist>
                </description>
@@ -154,7 +154,7 @@ static int dfltAfterGreetingSilence = 800;
 static int dfltTotalAnalysisTime    = 5000;
 static int dfltMinimumWordLength    = 100;
 static int dfltBetweenWordsSilence  = 50;
-static int dfltMaximumNumberOfWords = 3;
+static int dfltMaximumNumberOfWords = 2;
 static int dfltSilenceThreshold     = 256;
 static int dfltMaximumWordLength    = 5000; /* Setting this to a large default so it is not used unless specify it in the configs or command line */
 
@@ -367,7 +367,7 @@ static void isAnsweringMachine(struct ast_channel *chan, const char *data)
                                        sprintf(amdCause , "MAXWORDLENGTH-%d", consecutiveVoiceDuration);
                                        break;
                                }
-                               if (iWordsCount >= maximumNumberOfWords) {
+                               if (iWordsCount > maximumNumberOfWords) {
                                        ast_verb(3, "AMD: Channel [%s]. ANSWERING MACHINE: iWordsCount:%d\n", ast_channel_name(chan), iWordsCount);
                                        ast_frfree(f);
                                        strcpy(amdStatus , "MACHINE");

diff --git a/configs/samples/amd.conf.sample b/configs/samples/amd.conf.sample
index d7323ecf225b3c35219584de18d3c78273382c26..d1764b50ceab7474ea64008f99e647ca8531bd96 100644 (file)
--- a/configs/samples/amd.conf.sample
+++ b/configs/samples/amd.conf.sample
@@ -3,17 +3,25 @@
 ;
 
 [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 = 2    ; Maximum number of words in the greeting
+                               ; If exceeded, then the result is detection as a MACHINE