app_amd: Correct maximum_number_of_words functionality & documentation
authorDade Brandon <dade@xencall.com>
Mon, 21 Dec 2015 03:33:02 +0000 (19:33 -0800)
committerDade Brandon <dade@xencall.com>
Tue, 22 Dec 2015 00:02:09 +0000 (16:02 -0800)
- 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

UPGRADE.txt
apps/app_amd.c
configs/samples/amd.conf.sample

index 91d9edc..6fb82c4 100644 (file)
@@ -64,5 +64,15 @@ AMI:
    Commands that fail to execute (no such command, invalid syntax etc.) now
    return an Error response instead of Success.
 
    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.
+
 ===========================================================
 ===========================================================
 ===========================================================
 ===========================================================
index ee421b6..83da533 100644 (file)
@@ -62,19 +62,19 @@ ASTERISK_REGISTER_FILE()
                <syntax>
                        <parameter name="initialSilence" required="false">
                                <para>Is maximum initial silence duration before greeting.</para>
                <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>
                        </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>
                        </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>
                        </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>
                        </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>
                        </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">
                        </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>
                        </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>
                        </parameter>
                </syntax>
                <description>
@@ -130,7 +130,7 @@ ASTERISK_REGISTER_FILE()
                                        </value>
                                        <value name="MAXWORDS">
                                                Word Count - maximum number of words.
                                        </value>
                                        <value name="MAXWORDS">
                                                Word Count - maximum number of words.
-                                       </value>        
+                                       </value>
                                </variable>
                        </variablelist>
                </description>
                                </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 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 */
 
 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;
                                }
                                        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");
                                        ast_verb(3, "AMD: Channel [%s]. ANSWERING MACHINE: iWordsCount:%d\n", ast_channel_name(chan), iWordsCount);
                                        ast_frfree(f);
                                        strcpy(amdStatus , "MACHINE");
index d7323ec..d1764b5 100644 (file)
@@ -3,17 +3,25 @@
 ;
 
 [general]
 ;
 
 [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.
 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.
 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
 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
 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