mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-30 10:33:13 +00:00
Move Speech* applications and functions documentation to XML.
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@161536 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Eliel C. Sardanons
@@ -37,62 +37,213 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
|
|||||||
#include "asterisk/app.h"
|
#include "asterisk/app.h"
|
||||||
#include "asterisk/speech.h"
|
#include "asterisk/speech.h"
|
||||||
|
|
||||||
/* Descriptions for each application */
|
/*** DOCUMENTATION
|
||||||
static char *speechcreate_descrip =
|
<application name="SpeechCreate" language="en_US">
|
||||||
" SpeechCreate(engine name):\n"
|
<synopsis>
|
||||||
"This application creates information to be used by all the other applications.\n"
|
Create a Speech Structure.
|
||||||
"It must be called before doing any speech recognition activities such as activating a grammar.\n"
|
</synopsis>
|
||||||
"It takes the engine name to use as the argument, if not specified the default engine will be used.\n";
|
<syntax>
|
||||||
|
<parameter name="engine_name" required="true" />
|
||||||
static char *speechactivategrammar_descrip =
|
</syntax>
|
||||||
" SpeechActivateGrammar(Grammar Name):\n"
|
<description>
|
||||||
"This activates the specified grammar to be recognized by the engine.\n"
|
<para>This application creates information to be used by all the other applications.
|
||||||
"A grammar tells the speech recognition engine what to recognize, and how to portray it back to you \n"
|
It must be called before doing any speech recognition activities such as activating a grammar.
|
||||||
"in the dialplan. The grammar name is the only argument to this application.\n";
|
It takes the engine name to use as the argument, if not specified the default engine will be used.</para>
|
||||||
|
</description>
|
||||||
static char *speechstart_descrip =
|
</application>
|
||||||
" SpeechStart():\n"
|
<application name="SpeechActivateGrammar" language="en_US">
|
||||||
"Tell the speech recognition engine that it should start trying to get results from audio being \n"
|
<synopsis>
|
||||||
"fed to it. This has no arguments.\n";
|
Activate a grammar.
|
||||||
|
</synopsis>
|
||||||
static char *speechbackground_descrip =
|
<syntax>
|
||||||
" SpeechBackground(<Sound File>[,Timeout[,options]]):\n"
|
<parameter name="grammar_name" required="true" />
|
||||||
"This application plays a sound file and waits for the person to speak. Once they start speaking playback\n"
|
</syntax>
|
||||||
"of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate\n"
|
<description>
|
||||||
"the speech recognition engine is working. Once results are available the application returns and results \n"
|
<para>This activates the specified grammar to be recognized by the engine.
|
||||||
"(score and text) are available using dialplan functions.\n"
|
A grammar tells the speech recognition engine what to recognize, and how to portray it back to you
|
||||||
" The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)}\n"
|
in the dialplan. The grammar name is the only argument to this application.</para>
|
||||||
"and ${SPEECH_SCORE(1)}.\n"
|
</description>
|
||||||
" The first argument is the sound file and the second is the timeout integer in seconds. Note the timeout will\n"
|
</application>
|
||||||
"only start once the sound file has stopped playing. The third argument specifies options:\n"
|
<application name="SpeechStart" language="en_US">
|
||||||
" Valid Options:\n"
|
<synopsis>
|
||||||
" n - Don't answer the channel if it has not already been answered.\n";
|
Start recognizing voice in the audio stream.
|
||||||
|
</synopsis>
|
||||||
static char *speechdeactivategrammar_descrip =
|
<syntax />
|
||||||
" SpeechDeactivateGrammar(Grammar Name):\n"
|
<description>
|
||||||
"This deactivates the specified grammar so that it is no longer recognized.\n"
|
<para>Tell the speech recognition engine that it should start trying to get results from audio being
|
||||||
"The only argument is the grammar name to deactivate.\n";
|
fed to it.</para>
|
||||||
|
</description>
|
||||||
static char *speechprocessingsound_descrip =
|
</application>
|
||||||
" SpeechProcessingSound(Sound File):\n"
|
<application name="SpeechBackground" language="en_US">
|
||||||
"This changes the processing sound that SpeechBackground plays back when the speech recognition engine is\n"
|
<synopsis>
|
||||||
"processing and working to get results.\n"
|
Play a sound file and wait for speech to be recognized.
|
||||||
"It takes the sound file as the only argument.\n";
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
static char *speechdestroy_descrip =
|
<parameter name="sound_file" required="true" />
|
||||||
" SpeechDestroy():\n"
|
<parameter name="timeout">
|
||||||
"This destroys the information used by all the other speech recognition applications.\n"
|
<para>Timeout integer in seconds. Note the timeout will only start
|
||||||
"If you call this application but end up wanting to recognize more speech, you must call SpeechCreate\n"
|
once the sound file has stopped playing.</para>
|
||||||
"again before calling any other application. It takes no arguments.\n";
|
</parameter>
|
||||||
|
<parameter name="options">
|
||||||
static char *speechload_descrip =
|
<optionlist>
|
||||||
" SpeechLoadGrammar(Grammar Name,Path):\n"
|
<option name="n">
|
||||||
"Load a grammar only on the channel, not globally.\n"
|
<para>Don't answer the channel if it has not already been answered.</para>
|
||||||
"It takes the grammar name as first argument and path as second.\n";
|
</option>
|
||||||
|
</optionlist>
|
||||||
static char *speechunload_descrip =
|
</parameter>
|
||||||
" SpeechUnloadGrammar(Grammar Name):\n"
|
</syntax>
|
||||||
"Unload a grammar. It takes the grammar name as the only argument.\n";
|
<description>
|
||||||
|
<para>This application plays a sound file and waits for the person to speak. Once they start speaking playback
|
||||||
|
of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate
|
||||||
|
the speech recognition engine is working. Once results are available the application returns and results
|
||||||
|
(score and text) are available using dialplan functions.</para>
|
||||||
|
<para>The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)}
|
||||||
|
and ${SPEECH_SCORE(1)}.</para>
|
||||||
|
<para>The first argument is the sound file and the second is the timeout integer in seconds.</para>
|
||||||
|
|
||||||
|
</description>
|
||||||
|
</application>
|
||||||
|
<application name="SpeechDeactivateGrammar" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Deactivate a grammar.
|
||||||
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
|
<parameter name="grammar_name" required="true">
|
||||||
|
<para>The grammar name to deactivate</para>
|
||||||
|
</parameter>
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>This deactivates the specified grammar so that it is no longer recognized.</para>
|
||||||
|
</description>
|
||||||
|
</application>
|
||||||
|
<application name="SpeechProcessingSound" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Change background processing sound.
|
||||||
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
|
<parameter name="sound_file" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>This changes the processing sound that SpeechBackground plays back when the speech recognition engine is
|
||||||
|
processing and working to get results.</para>
|
||||||
|
</description>
|
||||||
|
</application>
|
||||||
|
<application name="SpeechDestroy" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
End speech recognition.
|
||||||
|
</synopsis>
|
||||||
|
<syntax />
|
||||||
|
<description>
|
||||||
|
<para>This destroys the information used by all the other speech recognition applications.
|
||||||
|
If you call this application but end up wanting to recognize more speech, you must call SpeechCreate()
|
||||||
|
again before calling any other application.</para>
|
||||||
|
</description>
|
||||||
|
</application>
|
||||||
|
<application name="SpeechLoadGrammar" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Load a grammar.
|
||||||
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
|
<parameter name="grammar_name" required="true" />
|
||||||
|
<parameter name="path" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Load a grammar only on the channel, not globally.</para>
|
||||||
|
</description>
|
||||||
|
</application>
|
||||||
|
<application name="SpeechUnloadGrammar" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Unload a grammar.
|
||||||
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
|
<parameter name="grammar_name" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Unload a grammar.</para>
|
||||||
|
</description>
|
||||||
|
</application>
|
||||||
|
<function name="SPEECH_SCORE" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Gets the confidence score of a result.
|
||||||
|
</synopsis>
|
||||||
|
<syntax argsep="/">
|
||||||
|
<parameter name="nbest_number" />
|
||||||
|
<parameter name="result_number" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Gets the confidence score of a result.</para>
|
||||||
|
</description>
|
||||||
|
</function>
|
||||||
|
<function name="SPEECH_TEXT" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Gets the recognized text of a result.
|
||||||
|
</synopsis>
|
||||||
|
<syntax argsep="/">
|
||||||
|
<parameter name="nbest_number" />
|
||||||
|
<parameter name="result_number" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Gets the recognized text of a result.</para>
|
||||||
|
</description>
|
||||||
|
</function>
|
||||||
|
<function name="SPEECH_GRAMMAR" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Gets the matched grammar of a result if available.
|
||||||
|
</synopsis>
|
||||||
|
<syntax argsep="/">
|
||||||
|
<parameter name="nbest_number" />
|
||||||
|
<parameter name="result_number" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Gets the matched grammar of a result if available.</para>
|
||||||
|
</description>
|
||||||
|
</function>
|
||||||
|
<function name="SPEECH_ENGINE" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Change a speech engine specific attribute.
|
||||||
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
|
<parameter name="name" required="true" />
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Changes a speech engine specific attribute.</para>
|
||||||
|
</description>
|
||||||
|
</function>
|
||||||
|
<function name="SPEECH_RESULTS_TYPE" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Sets the type of results that will be returned.
|
||||||
|
</synopsis>
|
||||||
|
<syntax />
|
||||||
|
<description>
|
||||||
|
<para>Sets the type of results that will be returned. Valid options are normal or nbest.</para>
|
||||||
|
</description>
|
||||||
|
</function>
|
||||||
|
<function name="SPEECH" language="en_US">
|
||||||
|
<synopsis>
|
||||||
|
Gets information about speech recognition results.
|
||||||
|
</synopsis>
|
||||||
|
<syntax>
|
||||||
|
<parameter name="argument" required="true">
|
||||||
|
<enumlist>
|
||||||
|
<enum name="status">
|
||||||
|
<para>Returns <literal>1</literal> upon speech object existing,
|
||||||
|
or <literal>0</literal> if not</para>
|
||||||
|
</enum>
|
||||||
|
<enum name="spoke">
|
||||||
|
<para>Returns <literal>1</literal> if spoker spoke,
|
||||||
|
or <literal>0</literal> if not</para>
|
||||||
|
</enum>
|
||||||
|
<enum name="results">
|
||||||
|
<para>Returns number of results that were recognized.</para>
|
||||||
|
</enum>
|
||||||
|
</enumlist>
|
||||||
|
</parameter>
|
||||||
|
</syntax>
|
||||||
|
<description>
|
||||||
|
<para>Gets information about speech recognition results.</para>
|
||||||
|
</description>
|
||||||
|
</function>
|
||||||
|
***/
|
||||||
|
|
||||||
/*! \brief Helper function used by datastores to destroy the speech structure upon hangup */
|
/*! \brief Helper function used by datastores to destroy the speech structure upon hangup */
|
||||||
static void destroy_callback(void *data)
|
static void destroy_callback(void *data)
|
||||||
@@ -181,10 +332,6 @@ static int speech_score(struct ast_channel *chan, const char *cmd, char *data,
|
|||||||
|
|
||||||
static struct ast_custom_function speech_score_function = {
|
static struct ast_custom_function speech_score_function = {
|
||||||
.name = "SPEECH_SCORE",
|
.name = "SPEECH_SCORE",
|
||||||
.synopsis = "Gets the confidence score of a result.",
|
|
||||||
.syntax = "SPEECH_SCORE([nbest number/]result number)",
|
|
||||||
.desc =
|
|
||||||
"Gets the confidence score of a result.\n",
|
|
||||||
.read = speech_score,
|
.read = speech_score,
|
||||||
.write = NULL,
|
.write = NULL,
|
||||||
};
|
};
|
||||||
@@ -211,10 +358,6 @@ static int speech_text(struct ast_channel *chan, const char *cmd, char *data,
|
|||||||
|
|
||||||
static struct ast_custom_function speech_text_function = {
|
static struct ast_custom_function speech_text_function = {
|
||||||
.name = "SPEECH_TEXT",
|
.name = "SPEECH_TEXT",
|
||||||
.synopsis = "Gets the recognized text of a result.",
|
|
||||||
.syntax = "SPEECH_TEXT([nbest number/]result number)",
|
|
||||||
.desc =
|
|
||||||
"Gets the recognized text of a result.\n",
|
|
||||||
.read = speech_text,
|
.read = speech_text,
|
||||||
.write = NULL,
|
.write = NULL,
|
||||||
};
|
};
|
||||||
@@ -241,10 +384,6 @@ static int speech_grammar(struct ast_channel *chan, const char *cmd, char *data,
|
|||||||
|
|
||||||
static struct ast_custom_function speech_grammar_function = {
|
static struct ast_custom_function speech_grammar_function = {
|
||||||
.name = "SPEECH_GRAMMAR",
|
.name = "SPEECH_GRAMMAR",
|
||||||
.synopsis = "Gets the matched grammar of a result if available.",
|
|
||||||
.syntax = "SPEECH_GRAMMAR([nbest number/]result number)",
|
|
||||||
.desc =
|
|
||||||
"Gets the matched grammar of a result if available.\n",
|
|
||||||
.read = speech_grammar,
|
.read = speech_grammar,
|
||||||
.write = NULL,
|
.write = NULL,
|
||||||
};
|
};
|
||||||
@@ -265,10 +404,6 @@ static int speech_engine_write(struct ast_channel *chan, const char *cmd, char *
|
|||||||
|
|
||||||
static struct ast_custom_function speech_engine_function = {
|
static struct ast_custom_function speech_engine_function = {
|
||||||
.name = "SPEECH_ENGINE",
|
.name = "SPEECH_ENGINE",
|
||||||
.synopsis = "Change a speech engine specific attribute.",
|
|
||||||
.syntax = "SPEECH_ENGINE(name)=value",
|
|
||||||
.desc =
|
|
||||||
"Changes a speech engine specific attribute.\n",
|
|
||||||
.read = NULL,
|
.read = NULL,
|
||||||
.write = speech_engine_write,
|
.write = speech_engine_write,
|
||||||
};
|
};
|
||||||
@@ -291,10 +426,6 @@ static int speech_results_type_write(struct ast_channel *chan, const char *cmd,
|
|||||||
|
|
||||||
static struct ast_custom_function speech_results_type_function = {
|
static struct ast_custom_function speech_results_type_function = {
|
||||||
.name = "SPEECH_RESULTS_TYPE",
|
.name = "SPEECH_RESULTS_TYPE",
|
||||||
.synopsis = "Sets the type of results that will be returned.",
|
|
||||||
.syntax = "SPEECH_RESULTS_TYPE()=results type",
|
|
||||||
.desc =
|
|
||||||
"Sets the type of results that will be returned. Valid options are normal or nbest.",
|
|
||||||
.read = NULL,
|
.read = NULL,
|
||||||
.write = speech_results_type_write,
|
.write = speech_results_type_write,
|
||||||
};
|
};
|
||||||
@@ -343,13 +474,6 @@ static int speech_read(struct ast_channel *chan, const char *cmd, char *data,
|
|||||||
|
|
||||||
static struct ast_custom_function speech_function = {
|
static struct ast_custom_function speech_function = {
|
||||||
.name = "SPEECH",
|
.name = "SPEECH",
|
||||||
.synopsis = "Gets information about speech recognition results.",
|
|
||||||
.syntax = "SPEECH(argument)",
|
|
||||||
.desc =
|
|
||||||
"Gets information about speech recognition results.\n"
|
|
||||||
"status: Returns 1 upon speech object existing, or 0 if not\n"
|
|
||||||
"spoke: Returns 1 if spoker spoke, or 0 if not\n"
|
|
||||||
"results: Returns number of results that were recognized\n",
|
|
||||||
.read = speech_read,
|
.read = speech_read,
|
||||||
.write = NULL,
|
.write = NULL,
|
||||||
};
|
};
|
||||||
@@ -810,15 +934,15 @@ static int load_module(void)
|
|||||||
{
|
{
|
||||||
int res = 0;
|
int res = 0;
|
||||||
|
|
||||||
res = ast_register_application("SpeechCreate", speech_create, "Create a Speech Structure", speechcreate_descrip);
|
res = ast_register_application_xml("SpeechCreate", speech_create);
|
||||||
res |= ast_register_application("SpeechLoadGrammar", speech_load, "Load a Grammar", speechload_descrip);
|
res |= ast_register_application_xml("SpeechLoadGrammar", speech_load);
|
||||||
res |= ast_register_application("SpeechUnloadGrammar", speech_unload, "Unload a Grammar", speechunload_descrip);
|
res |= ast_register_application_xml("SpeechUnloadGrammar", speech_unload);
|
||||||
res |= ast_register_application("SpeechActivateGrammar", speech_activate, "Activate a Grammar", speechactivategrammar_descrip);
|
res |= ast_register_application_xml("SpeechActivateGrammar", speech_activate);
|
||||||
res |= ast_register_application("SpeechDeactivateGrammar", speech_deactivate, "Deactivate a Grammar", speechdeactivategrammar_descrip);
|
res |= ast_register_application_xml("SpeechDeactivateGrammar", speech_deactivate);
|
||||||
res |= ast_register_application("SpeechStart", speech_start, "Start recognizing voice in the audio stream", speechstart_descrip);
|
res |= ast_register_application_xml("SpeechStart", speech_start);
|
||||||
res |= ast_register_application("SpeechBackground", speech_background, "Play a sound file and wait for speech to be recognized", speechbackground_descrip);
|
res |= ast_register_application_xml("SpeechBackground", speech_background);
|
||||||
res |= ast_register_application("SpeechDestroy", speech_destroy, "End speech recognition", speechdestroy_descrip);
|
res |= ast_register_application_xml("SpeechDestroy", speech_destroy);
|
||||||
res |= ast_register_application("SpeechProcessingSound", speech_processing_sound, "Change background processing sound", speechprocessingsound_descrip);
|
res |= ast_register_application_xml("SpeechProcessingSound", speech_processing_sound);
|
||||||
res |= ast_custom_function_register(&speech_function);
|
res |= ast_custom_function_register(&speech_function);
|
||||||
res |= ast_custom_function_register(&speech_score_function);
|
res |= ast_custom_function_register(&speech_score_function);
|
||||||
res |= ast_custom_function_register(&speech_text_function);
|
res |= ast_custom_function_register(&speech_text_function);
|
||||||
|
|||||||
Reference in New Issue
Block a user