UniMRCP: mrcp_recog_header.h Source File

00001 /*
00002  * Copyright 2008-2010 Arsen Chaloyan
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  * 
00016  * $Id: mrcp_recog_header.h 1632 2010-03-30 20:46:25Z achaloyan $
00017  */
00018 
00019 #ifndef MRCP_RECOG_HEADER_H
00020 #define MRCP_RECOG_HEADER_H
00021 
00022 /**
00023  * @file mrcp_recog_header.h
00024  * @brief MRCP Recognizer Header
00025  */ 
00026 
00027 #include "mrcp_types.h"
00028 #include "mrcp_header_accessor.h"
00029 
00030 APT_BEGIN_EXTERN_C
00031 
00032 /** MRCP recognizer header fields */
00033 typedef enum {
00034         RECOGNIZER_HEADER_CONFIDENCE_THRESHOLD,
00035         RECOGNIZER_HEADER_SENSITIVITY_LEVEL,
00036         RECOGNIZER_HEADER_SPEED_VS_ACCURACY,
00037         RECOGNIZER_HEADER_N_BEST_LIST_LENGTH,
00038         RECOGNIZER_HEADER_NO_INPUT_TIMEOUT,
00039         RECOGNIZER_HEADER_RECOGNITION_TIMEOUT,
00040         RECOGNIZER_HEADER_WAVEFORM_URI,
00041         RECOGNIZER_HEADER_COMPLETION_CAUSE,
00042         RECOGNIZER_HEADER_RECOGNIZER_CONTEXT_BLOCK,
00043         RECOGNIZER_HEADER_START_INPUT_TIMERS,
00044         RECOGNIZER_HEADER_SPEECH_COMPLETE_TIMEOUT,
00045         RECOGNIZER_HEADER_SPEECH_INCOMPLETE_TIMEOUT,
00046         RECOGNIZER_HEADER_DTMF_INTERDIGIT_TIMEOUT,
00047         RECOGNIZER_HEADER_DTMF_TERM_TIMEOUT,
00048         RECOGNIZER_HEADER_DTMF_TERM_CHAR,
00049         RECOGNIZER_HEADER_FAILED_URI,
00050         RECOGNIZER_HEADER_FAILED_URI_CAUSE,
00051         RECOGNIZER_HEADER_SAVE_WAVEFORM,
00052         RECOGNIZER_HEADER_NEW_AUDIO_CHANNEL,
00053         RECOGNIZER_HEADER_SPEECH_LANGUAGE,
00054 
00055         /** Additional header fields for MRCP v2 */
00056         RECOGNIZER_HEADER_INPUT_TYPE,
00057         RECOGNIZER_HEADER_INPUT_WAVEFORM_URI,
00058         RECOGNIZER_HEADER_COMPLETION_REASON,
00059         RECOGNIZER_HEADER_MEDIA_TYPE,
00060         RECOGNIZER_HEADER_VER_BUFFER_UTTERANCE,
00061         RECOGNIZER_HEADER_RECOGNITION_MODE,
00062         RECOGNIZER_HEADER_CANCEL_IF_QUEUE,
00063         RECOGNIZER_HEADER_HOTWORD_MAX_DURATION,
00064         RECOGNIZER_HEADER_HOTWORD_MIN_DURATION,
00065         RECOGNIZER_HEADER_INTERPRET_TEXT,
00066         RECOGNIZER_HEADER_DTMF_BUFFER_TIME,
00067         RECOGNIZER_HEADER_CLEAR_DTMF_BUFFER,
00068         RECOGNIZER_HEADER_EARLY_NO_MATCH,
00069 
00070         RECOGNIZER_HEADER_COUNT
00071 } mrcp_recognizer_header_id;
00072 
00073 
00074 /** MRCP recognizer completion-cause  */
00075 typedef enum {
00076         RECOGNIZER_COMPLETION_CAUSE_SUCCESS                 = 0,
00077         RECOGNIZER_COMPLETION_CAUSE_NO_MATCH                = 1,
00078         RECOGNIZER_COMPLETION_CAUSE_NO_INPUT_TIMEOUT        = 2,
00079         RECOGNIZER_COMPLETION_CAUSE_RECOGNITION_TIMEOUT     = 3,
00080         RECOGNIZER_COMPLETION_CAUSE_GRAM_LOAD_FAILURE       = 4,
00081         RECOGNIZER_COMPLETION_CAUSE_GRAM_COMP_FAILURE       = 5,
00082         RECOGNIZER_COMPLETION_CAUSE_ERROR                   = 6,
00083         RECOGNIZER_COMPLETION_CAUSE_SPEECH_TOO_EARLY        = 7,
00084         RECOGNIZER_COMPLETION_CAUSE_TOO_MUCH_SPEECH_TIMEOUT = 8,
00085         RECOGNIZER_COMPLETION_CAUSE_URI_FAILURE             = 9,
00086         RECOGNIZER_COMPLETION_CAUSE_LANGUAGE_UNSUPPORTED    = 10,
00087 
00088         /** Additional completion-cause for MRCP v2 */
00089         RECOGNIZER_COMPLETION_CAUSE_CANCELLED               = 11,
00090         RECOGNIZER_COMPLETION_CAUSE_SEMANTICS_FAILURE       = 12,
00091         RECOGNIZER_COMPLETION_CAUSE_PARTIAL_MATCH           = 13,
00092         RECOGNIZER_COMPLETION_CAUSE_PARTIAL_MATCH_MAXTIME   = 14,
00093         RECOGNIZER_COMPLETION_CAUSE_NO_MATCH_MAXTIME        = 15,
00094         RECOGNIZER_COMPLETION_CAUSE_GRAM_DEFINITION_FAILURE = 16,
00095 
00096         RECOGNIZER_COMPLETION_CAUSE_COUNT                   = 17,
00097         RECOGNIZER_COMPLETION_CAUSE_UNKNOWN                 = RECOGNIZER_COMPLETION_CAUSE_COUNT
00098 } mrcp_recog_completion_cause_e;
00099 
00100 
00101 
00102 /** MRCP recognizer-header declaration */
00103 typedef struct mrcp_recog_header_t mrcp_recog_header_t;
00104 
00105 /** MRCP recognizer-header */
00106 struct mrcp_recog_header_t {
00107         /** Tells the recognizer resource what confidence level the client considers a
00108     successful match */
00109         float                         confidence_threshold;
00110         /** To filter out background noise and not mistake it for speech */
00111         float                         sensitivity_level;
00112         /** Tunable towards Performance or Accuracy */
00113         float                         speed_vs_accuracy;
00114         /** The client, by setting this header, can ask the recognition resource 
00115         to send it more  than 1 alternative */
00116         apr_size_t                    n_best_list_length;
00117         /** The client can use the no-input-timeout header to set this timeout */
00118         apr_size_t                    no_input_timeout;
00119         /** The client can use the recognition-timeout header to set this timeout */
00120         apr_size_t                    recognition_timeout;
00121         /** MUST be present in the RECOGNITION-COMPLETE event if the Save-Waveform
00122         header was set to true */
00123         apt_str_t                     waveform_uri;
00124         /** MUST be part of a RECOGNITION-COMPLETE, event coming from
00125     the recognizer resource to the client */
00126         mrcp_recog_completion_cause_e completion_cause;
00127         /** MAY be sent as part of the SET-PARAMS or GET-PARAMS request */
00128         apt_str_t                     recognizer_context_block;
00129         /** MAY be sent as part of the RECOGNIZE request. A value of false tells
00130         the recognizer to start recognition, but not to start the no-input timer yet */
00131         apt_bool_t                    start_input_timers;
00132         /** Specifies the length of silence required following user
00133     speech before the speech recognizer finalizes a result */
00134         apr_size_t                    speech_complete_timeout;
00135         /** Specifies the required length of silence following user
00136     speech after which a recognizer finalizes a result */
00137         apr_size_t                    speech_incomplete_timeout;
00138         /** Specifies the inter-digit timeout value to use when
00139     recognizing DTMF input */
00140         apr_size_t                    dtmf_interdigit_timeout;
00141         /** Specifies the terminating timeout to use when 
00142         recognizing DTMF input*/
00143         apr_size_t                    dtmf_term_timeout;
00144         /** Specifies the terminating DTMF character for DTMF input
00145     recognition */
00146         char                          dtmf_term_char;
00147         /** When a recognizer needs to fetch or access a URI and the access fails
00148     the server SHOULD provide the failed URI in this header in the method response*/
00149         apt_str_t                     failed_uri;
00150         /** When a recognizer method needs a recognizer to fetch or access a URI
00151     and the access fails the server MUST provide the URI specific or
00152     protocol specific response code for the URI in the Failed-URI header */
00153         apt_str_t                     failed_uri_cause;
00154         /** Allows the client to request the recognizer resource to
00155     save the audio input to the recognizer */
00156         apt_bool_t                    save_waveform;
00157         /** MAY be specified in a RECOGNIZE request and allows the
00158     client to tell the server that, from this point on, further input
00159     audio comes from a different audio source */
00160         apt_bool_t                    new_audio_channel;
00161         /** Specifies the language of recognition grammar data within
00162     a session or request, if it is not specified within the data */
00163         apt_str_t                     speech_language;
00164 
00165         /** Additional header fields for MRCP v2 */
00166         /** Specifies if the input that caused a barge-in was DTMF or speech */
00167         apt_str_t                     input_type;
00168         /** Optional header specifies a URI pointing to audio content to be
00169     processed by the RECOGNIZE operation */
00170         apt_str_t                     input_waveform_uri;
00171         /** MAY be specified in a RECOGNITION-COMPLETE event coming from
00172     the recognizer resource to the client */
00173         apt_str_t                     completion_reason;
00174         /** tells the server resource the Media Type in which to store captured 
00175         audio such as the one captured and returned by the Waveform-URI header */
00176         apt_str_t                     media_type;
00177         /** lets the client request the server to buffer the
00178     utterance associated with this recognition request into a buffer
00179     available to a co-resident verification resource */
00180         apt_bool_t                    ver_buffer_utterance;
00181         /** Specifies what mode the RECOGNIZE method will operate in */
00182         apt_str_t                     recognition_mode;
00183         /** Specifies what will happen if the client attempts to
00184     invoke another RECOGNIZE method when this RECOGNIZE request is
00185     already in progress for the resource*/
00186         apt_bool_t                    cancel_if_queue;
00187         /** Specifies the maximum length of an utterance (in seconds) that will
00188     be considered for Hotword recognition */
00189         apr_size_t                    hotword_max_duration;
00190         /** Specifies the minimum length of an utterance (in seconds) that will
00191     be considered for Hotword recognition */
00192         apr_size_t                    hotword_min_duration;
00193         /** Provides a pointer to the text for which a natural language interpretation is desired */
00194         apt_str_t                     interpret_text;
00195         /** MAY be specified in a GET-PARAMS or SET-PARAMS method and
00196     is used to specify the size in time, in milliseconds, of the
00197     typeahead buffer for the recognizer */
00198         apr_size_t                    dtmf_buffer_time;
00199         /** MAY be specified in a RECOGNIZE method and is used to
00200     tell the recognizer to clear the DTMF type-ahead buffer before
00201     starting the recognize */
00202         apt_bool_t                    clear_dtmf_buffer;
00203         /** MAY be specified in a RECOGNIZE method and is used to
00204     tell the recognizer that it MUST not wait for the end of speech
00205     before processing the collected speech to match active grammars */
00206         apt_bool_t                    early_no_match;
00207 };
00208 
00209 
00210 /** Get recognizer header vtable */
00211 const mrcp_header_vtable_t* mrcp_recog_header_vtable_get(mrcp_version_e version);
00212 
00213 /** Get recognizer completion cause string */
00214 MRCP_DECLARE(const apt_str_t*) mrcp_recog_completion_cause_get(mrcp_recog_completion_cause_e completion_cause, mrcp_version_e version);
00215 
00216 APT_END_EXTERN_C
00217 
00218 #endif /* MRCP_RECOG_HEADER_H */