Finalization of speech detect interface and API

This changes the core to have the necessary tools to create
a speech detection interface.

It also changes the code in javascript (mod_spidermonkey)
there are a few api changes in how it handles callbacks

It also adds grammars as a system dir to store asr grammars




git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@3291 d0543943-73ff-0310-b7d9-9358b9ac24b2

src/include/switch_am_config.h.in

@@ -124,5 +124,5 @@
 /* Define to rpl_malloc if the replacement function should be used. */
 #undef malloc
 
-/* Define to `unsigned int' if <sys/types.h> does not define. */
+/* Define to `unsigned' if <sys/types.h> does not define. */
 #undef size_t

src/include/switch_core.h

@@ -119,14 +119,21 @@ struct switch_core_port_allocator;
   \param session the session to add the bug to
   \param callback a callback for events
   \param user_data arbitrary user data
+  \param flags flags to choose the stream
   \param new_bug pointer to assign new bug to
   \return SWITCH_STATUS_SUCCESS if the operation was a success
 */
 SWITCH_DECLARE(switch_status_t) switch_core_media_bug_add(switch_core_session_t *session,
 														  switch_media_bug_callback_t callback,
 														  void *user_data,
+														  switch_media_bug_flag_t flags,
 														  switch_media_bug_t **new_bug);
-
+/*!
+  \brief Obtain private data from a media bug
+  \param session the session to obtain the private data from
+  \return the private data
+*/
+SWITCH_DECLARE(void *) switch_core_media_bug_get_user_data(switch_media_bug_t *bug);
 
 /*!
   \brief Remove a media bug from the session
@@ -1060,7 +1067,7 @@ SWITCH_DECLARE(switch_status_t) switch_core_file_close(switch_file_handle_t *fh)
   \param module_name the speech module to use
   \param voice_name the desired voice name
   \param rate the sampling rate
-  \param flags asr/tts flags
+  \param flags tts flags
   \param pool the pool to use (NULL for new pool)
   \return SWITCH_STATUS_SUCCESS if the handle is opened
 */
@@ -1070,28 +1077,6 @@ SWITCH_DECLARE(switch_status_t) switch_core_speech_open(switch_speech_handle_t *
 													  unsigned int rate,
 													  switch_speech_flag_t *flags,
 													  switch_memory_pool_t *pool);
-
-/*!
-  \brief Feed data to the ASR module
-  \param sh the speech handle to feed
-  \param data the buffer of audio data
-  \param len the in-use size of the buffer
-  \param rate the rate of the audio (in hz)
-  \param flags flags in/out for fine tuning
-  \return SWITCH_STATUS_SUCCESS with possible new flags on success
-*/
-SWITCH_DECLARE(switch_status_t) switch_core_speech_feed_asr(switch_speech_handle_t *sh, void *data, unsigned int *len, int rate, switch_speech_flag_t *flags);
-
-/*! 
-  \brief Get text back from the ASR module
-  \param sh the speech handle to read
-  \param buf the buffer to insert the text into
-  \param buflen the max size of the buffer
-  \param flags flags in/out for fine tuning
-  \return SWITCH_STATUS_SUCCESS with possible new flags on success
-*/
-SWITCH_DECLARE(switch_status_t) switch_core_speech_interpret_asr(switch_speech_handle_t *sh, char *buf, unsigned int buflen, switch_speech_flag_t *flags);
-
 /*! 
   \brief Feed text to the TTS module
   \param sh the speech handle to feed
@@ -1152,6 +1137,92 @@ SWITCH_DECLARE(switch_status_t) switch_core_speech_read_tts(switch_speech_handle
   \return SWITCH_STATUS_SUCCESS if the file handle was closed
 */
 SWITCH_DECLARE(switch_status_t) switch_core_speech_close(switch_speech_handle_t *sh, switch_speech_flag_t *flags);
+
+
+/*! 
+  \brief Open an asr handle
+  \param ah the asr handle to open
+  \param module_name the name of the asr module
+  \param codec the preferred codec
+  \param rate the preferred rate
+  \param dest the destination address
+  \param flags flags to influence behaviour
+  \param pool the pool to use (NULL for new pool)
+  \return SWITCH_STATUS_SUCCESS if the asr handle was opened
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_open(switch_asr_handle_t *ah,
+													 char *module_name,
+													 char *codec,
+													 int rate,
+													 char *dest,
+													 switch_asr_flag_t *flags,
+													 switch_memory_pool_t *pool);
+
+/*!
+  \brief Close an asr handle
+  \param ah the handle to close
+  \param flags flags to influence behaviour
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_close(switch_asr_handle_t *ah, switch_asr_flag_t *flags);
+
+/*!
+  \brief Feed audio data to an asr handle
+  \param ah the handle to feed data to
+  \param data a pointer to the data
+  \param len the size in bytes of the data
+  \param flags flags to influence behaviour
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_feed(switch_asr_handle_t *ah, void *data, unsigned int len, switch_asr_flag_t *flags);
+
+/*!
+  \brief Check an asr handle for results
+  \param ah the handle to check
+  \param flags flags to influence behaviour
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_check_results(switch_asr_handle_t *ah, switch_asr_flag_t *flags);
+
+/*!
+  \brief Get results from an asr handle
+  \param ah the handle to get results from
+  \param xmlstr a pointer to dynamically allocate an xml result string to
+  \param flags flags to influence behaviour
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_get_results(switch_asr_handle_t *ah, char **xmlstr, switch_asr_flag_t *flags);
+
+/*!
+  \brief Load a grammar to an asr handle
+  \param ah the handle to load to
+  \param grammar the name of the grammar
+  \param path the path to the grammaar file
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_load_grammar(switch_asr_handle_t *ah, char *grammar, char *path);
+
+/*!
+  \brief Unload a grammar from an asr handle
+  \param ah the handle to unload the grammar from
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_unload_grammar(switch_asr_handle_t *ah, char *grammar);
+
+/*!
+  \brief Pause detection on an asr handle
+  \param ah the handle to pause
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_pause(switch_asr_handle_t *ah);
+
+/*!
+  \brief Resume detection on an asr handle
+  \param ah the handle to resume
+  \return SWITCH_STATUS_SUCCESS
+*/
+SWITCH_DECLARE(switch_status_t) switch_core_asr_resume(switch_asr_handle_t *ah);
+
 ///\}
 
 

src/include/switch_ivr.h

@@ -69,12 +69,14 @@ SWITCH_DECLARE(switch_status_t) switch_ivr_park(switch_core_session_t *session);
   \param dtmf_callback code to execute if any dtmf is dialed during the recording
   \param buf an object to maintain across calls
   \param buflen the size of buf
+  \param timeout a timeout in milliseconds
   \return SWITCH_STATUS_SUCCESS to keep the collection moving.
 */
 SWITCH_DECLARE(switch_status_t) switch_ivr_collect_digits_callback(switch_core_session_t *session,
-																 switch_input_callback_function_t dtmf_callback,
-																 void *buf,
-																 unsigned int buflen);
+																   switch_input_callback_function_t dtmf_callback,
+																   void *buf,
+																   unsigned int buflen,
+																   unsigned int timeout);
 
 /*!
   \brief Wait for specified number of DTMF digits, untile terminator is received or until the channel hangs up.
@@ -95,6 +97,61 @@ SWITCH_DECLARE(switch_status_t) switch_ivr_collect_digits_count(switch_core_sess
 																char *terminator,
 																unsigned int timeout);
 
+/*!
+  \brief Engage background Speech detection on a session
+  \param session the session to attach
+  \param mod_name the module name of the ASR library
+  \param grammar the grammar name
+  \param path the path to the grammar file
+  \param dest the destination address
+  \param ah an ASR handle to use (NULL to create one)
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
+SWITCH_DECLARE(switch_status_t) switch_ivr_detect_speech(switch_core_session_t *session,
+														 char *mod_name,
+														 char *grammar,
+														 char *path,
+														 char *dest,
+														 switch_asr_handle_t *ah);
+
+/*!
+  \brief Stop background Speech detection on a session
+  \param session The session to stop detection on
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
+SWITCH_DECLARE(switch_status_t) switch_ivr_stop_detect_speech(switch_core_session_t *session);
+
+/*!
+  \brief Pause background Speech detection on a session
+  \param session The session to pause detection on
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
+SWITCH_DECLARE(switch_status_t) switch_ivr_pause_detect_speech(switch_core_session_t *session);
+
+/*!
+  \brief Resume background Speech detection on a session
+  \param session The session to resume detection on
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
+SWITCH_DECLARE(switch_status_t) switch_ivr_resume_detect_speech(switch_core_session_t *session);
+
+/*!
+  \brief Load a grammar on a background speech detection handle
+  \param session The session to change the grammar on
+  \param grammar the grammar name
+  \param path the grammar path
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
+SWITCH_DECLARE(switch_status_t) switch_ivr_detect_speech_load_grammar(switch_core_session_t *session, char *grammar, char *path);
+
+/*!
+  \brief Unload a grammar on a background speech detection handle
+  \param session The session to change the grammar on
+  \param grammar the grammar name
+  \return SWITCH_STATUS_SUCCESS if all is well
+*/
+SWITCH_DECLARE(switch_status_t) switch_ivr_detect_speech_unload_grammar(switch_core_session_t *session, char *grammar);
+
 /*!
   \brief Record a session to disk
   \param session the session to record

src/include/switch_loadable_module.h

@@ -75,6 +75,8 @@ struct switch_loadable_module_interface {
 	const switch_directory_interface_t *directory_interface;
 	/*! the table of chat interfaces the module has implmented */
 	const switch_chat_interface_t *chat_interface;
+	/*! the table of asr interfaces the module has implmented */
+	const switch_asr_interface_t *asr_interface;
 };
 
 /*!
@@ -158,6 +160,13 @@ SWITCH_DECLARE(switch_file_interface_t *) switch_loadable_module_get_file_interf
  */
 SWITCH_DECLARE(switch_speech_interface_t *) switch_loadable_module_get_speech_interface(char *name);
 
+/*!
+  \brief Retrieve the asr interface by it's registered name
+  \param name the name of the asr interface
+  \return the desired asr interface
+ */
+SWITCH_DECLARE(switch_asr_interface_t *) switch_loadable_module_get_asr_interface(char *name);
+
 /*!
   \brief Retrieve the directory interface by it's registered name
   \param name the name of the directory interface

src/include/switch_module_interfaces.h

@@ -315,6 +315,53 @@ struct switch_file_handle {
 	switch_buffer_t *audio_buffer;
 };
 
+/*! \brief Abstract interface to an asr module */
+struct switch_asr_interface {
+	/*! the name of the interface */
+	const char *interface_name;
+	/*! function to open the asr interface */
+	switch_status_t (*asr_open)(switch_asr_handle_t *ah,
+								char *codec,
+								int rate,
+								char *dest,
+								switch_asr_flag_t *flags);
+	/*! function to load a grammar to the asr interface */
+	switch_status_t (*asr_load_grammar)(switch_asr_handle_t *ah, char *grammar, char *path);
+	/*! function to unload a grammar to the asr interface */
+	switch_status_t (*asr_unload_grammar)(switch_asr_handle_t *ah, char *grammar);
+	/*! function to close the asr interface */
+	switch_status_t (*asr_close)(switch_asr_handle_t *ah, switch_asr_flag_t *flags);
+	/*! function to feed audio to the ASR*/
+	switch_status_t (*asr_feed)(switch_asr_handle_t *ah, void *data, unsigned int len, switch_asr_flag_t *flags);
+	/*! function to resume the ASR*/
+	switch_status_t (*asr_resume)(switch_asr_handle_t *ah);
+	/*! function to pause the ASR*/
+	switch_status_t (*asr_pause)(switch_asr_handle_t *ah);
+	/*! function to read results from the ASR*/
+	switch_status_t (*asr_check_results)(switch_asr_handle_t *ah, switch_asr_flag_t *flags);
+	/*! function to read results from the ASR*/
+	switch_status_t (*asr_get_results)(switch_asr_handle_t *ah, char **xmlstr, switch_asr_flag_t *flags);
+	const struct switch_asr_interface *next;
+};
+
+/*! an abstract representation of an asr speech interface. */
+struct switch_asr_handle {
+	/*! the interface of the module that implemented the current speech interface */
+	const switch_asr_interface_t *asr_interface;
+	/*! flags to control behaviour */
+	uint32_t flags;
+	/*! The Name*/
+	char *name;
+	/*! The Codec*/
+	char *codec;
+	/*! The Rate*/
+	uint32_t rate;
+	char *grammar;
+	/*! the handle's memory pool */
+	switch_memory_pool_t *memory_pool;
+	/*! private data for the format module to store handle specific info */
+	void *private_info;
+};
 
 /*! \brief Abstract interface to a speech module */
 struct switch_speech_interface {
@@ -328,10 +375,6 @@ struct switch_speech_interface {
 	/*! function to close the speech interface */
 	switch_status_t (*speech_close)(switch_speech_handle_t *, switch_speech_flag_t *flags);
 	/*! function to feed audio to the ASR*/
-	switch_status_t (*speech_feed_asr)(switch_speech_handle_t *sh, void *data, unsigned int *len, int rate, switch_speech_flag_t *flags);
-	/*! function to read text from the ASR*/
-	switch_status_t (*speech_interpret_asr)(switch_speech_handle_t *sh, char *buf, unsigned int buflen, switch_speech_flag_t *flags);
-	/*! function to feed text to the TTS*/
 	switch_status_t (*speech_feed_tts)(switch_speech_handle_t *sh, char *text, switch_speech_flag_t *flags);
 	/*! function to read audio from the TTS*/
 	switch_status_t (*speech_read_tts)(switch_speech_handle_t *sh,

src/include/switch_types.h

@@ -72,6 +72,10 @@ SWITCH_BEGIN_EXTERN_C
 #define SWITCH_HTDOCS_DIR SWITCH_PREFIX_DIR SWITCH_PATH_SEPARATOR "htdocs"
 #endif
 
+#ifndef SWITCH_GRAMMAR_DIR
+#define SWITCH_GRAMMAR_DIR SWITCH_PREFIX_DIR SWITCH_PATH_SEPARATOR "grammar"
+#endif
+
 #define SWITCH_R_SDP_VARIABLE "_switch_r_sdp_"
 #define SWITCH_L_SDP_VARIABLE "_switch_l_sdp_"
 #define SWITCH_B_SDP_VARIABLE "_switch_m_sdp_"
@@ -82,7 +86,7 @@ SWITCH_BEGIN_EXTERN_C
 #define SWITCH_LOCAL_MEDIA_PORT_VARIABLE "_local_media_port_"
 #define SWITCH_REMOTE_MEDIA_IP_VARIABLE "_remote_media_ip_"
 #define SWITCH_REMOTE_MEDIA_PORT_VARIABLE "_remote_media_port_"
-
+#define SWITCH_SPEECH_KEY "_speech_"
 
 #define SWITCH_BITS_PER_BYTE 8
 typedef uint8_t switch_byte_t;
@@ -132,6 +136,7 @@ struct switch_directories {
 	char *script_dir;
 	char *temp_dir;
 	char *htdocs_dir;
+	char *grammar_dir;
 };
 
 typedef struct switch_directories switch_directories;
@@ -313,6 +318,7 @@ typedef enum {
     SWITCH_STATUS_SOCKERR   - A socket error
 	SWITCH_STATUS_MORE_DATA - Need More Data
 	SWITCH_STATUS_NOTFOUND  - Not Found
+	SWITCH_STATUS_UNLOAD    - Unload
 </pre>
  */
 typedef enum {
@@ -330,7 +336,8 @@ typedef enum {
 	SWITCH_STATUS_BREAK,
 	SWITCH_STATUS_SOCKERR,
 	SWITCH_STATUS_MORE_DATA,
-	SWITCH_STATUS_NOTFOUND
+	SWITCH_STATUS_NOTFOUND,
+	SWITCH_STATUS_UNLOAD
 } switch_status_t;
 
 
@@ -522,26 +529,42 @@ typedef enum {
   \enum switch_speech_flag_t
   \brief Speech related flags
 <pre>
-SWITCH_SPEECH_FLAG_TTS =			(1 <<  0) - Interface can/should convert text to speech.
-SWITCH_SPEECH_FLAG_ASR =			(1 <<  1) - Interface can/should convert audio to text.
-SWITCH_SPEECH_FLAG_HASTEXT =		(1 <<  2) - Interface is has text to read.
-SWITCH_SPEECH_FLAG_PEEK =			(1 <<  3) - Read data but do not erase it.
-SWITCH_SPEECH_FLAG_FREE_POOL =		(1 <<  4) - Free interface's pool on destruction.
-SWITCH_SPEECH_FLAG_BLOCKING =       (1 <<  5) - Indicate that a blocking call is desired 
-SWITCH_SPEECH_FLAG_PAUSE = 			(1 <<  6) - Pause toggle for playback
+SWITCH_SPEECH_FLAG_HASTEXT =		(1 <<  0) - Interface is has text to read.
+SWITCH_SPEECH_FLAG_PEEK =			(1 <<  1) - Read data but do not erase it.
+SWITCH_SPEECH_FLAG_FREE_POOL =		(1 <<  2) - Free interface's pool on destruction.
+SWITCH_SPEECH_FLAG_BLOCKING =       (1 <<  3) - Indicate that a blocking call is desired 
+SWITCH_SPEECH_FLAG_PAUSE = 			(1 <<  4) - Pause toggle for playback
 </pre>
 */
 typedef enum {
-	SWITCH_SPEECH_FLAG_TTS =			(1 <<  0),
-	SWITCH_SPEECH_FLAG_ASR =			(1 <<  1),
-	SWITCH_SPEECH_FLAG_HASTEXT =		(1 <<  2),
-	SWITCH_SPEECH_FLAG_PEEK =			(1 <<  3),
-	SWITCH_SPEECH_FLAG_FREE_POOL =		(1 <<  4),
-	SWITCH_SPEECH_FLAG_BLOCKING =		(1 <<  5),
-	SWITCH_SPEECH_FLAG_PAUSE =			(1 <<  6)
+	SWITCH_SPEECH_FLAG_NONE =			0,
+	SWITCH_SPEECH_FLAG_HASTEXT =		(1 <<  0),
+	SWITCH_SPEECH_FLAG_PEEK =			(1 <<  1),
+	SWITCH_SPEECH_FLAG_FREE_POOL =		(1 <<  2),
+	SWITCH_SPEECH_FLAG_BLOCKING =		(1 <<  3),
+	SWITCH_SPEECH_FLAG_PAUSE =			(1 <<  4)
 
 } switch_speech_flag_t;
 
+/*!
+  \enum switch_asr_flag_t
+  \brief Asr related flags
+<pre>
+SWITCH_ASR_FLAG_DATA =			(1 <<  0) - Interface has data
+SWITCH_ASR_FLAG_FREE_POOL =		(1 <<  1) - Pool needs to be freed
+SWITCH_ASR_FLAG_CLOSED = 		(1 <<  2) - Interface has been closed
+SWITCH_ASR_FLAG_FIRE_EVENTS =	(1 <<  3) - Fire all speech events
+SWITCH_ASR_FLAG_AUTO_RESUME =   (1 <<  4) - Auto Resume
+</pre>
+*/
+typedef enum {
+	SWITCH_ASR_FLAG_NONE =			0,
+	SWITCH_ASR_FLAG_DATA =			(1 <<  0),
+	SWITCH_ASR_FLAG_FREE_POOL =		(1 <<  1),
+	SWITCH_ASR_FLAG_CLOSED =		(1 <<  2),
+	SWITCH_ASR_FLAG_FIRE_EVENTS =	(1 <<  3),
+	SWITCH_ASR_FLAG_AUTO_RESUME = 	(1 <<  4)
+} switch_asr_flag_t;
 
 /*!
   \enum switch_directory_flag_t
@@ -584,6 +607,21 @@ typedef enum {
 		SWITCH_TIMER_FLAG_FREE_POOL =		(1 <<  0),
 } switch_timer_flag_t;
 
+
+/*!
+  \enum switch_timer_flag_t
+  \brief Timer related flags
+<pre>
+SMBF_READ_STREAM - Include the Read Stream
+SMBF_WRITE_STREAM - Include the Write Stream
+</pre>
+*/
+typedef enum {
+	SMBF_BOTH = 0,
+	SMBF_READ_STREAM = (1 << 0),
+	SMBF_WRITE_STREAM = (1 << 1)
+} switch_media_bug_flag_t;
+
 /*!
   \enum switch_file_flag_t
   \brief File flags
@@ -653,6 +691,7 @@ typedef enum {
 	SWITCH_EVENT_PRESENCE			- Presence Info
 	SWITCH_EVENT_CODEC				- Codec Change
 	SWITCH_EVENT_BACKGROUND_JOB		- Background Job
+	SWITCH_EVENT_DETECTED_SPEECH	- Detected Speech
     SWITCH_EVENT_ALL				- All events at once
 </pre>
 
@@ -690,6 +729,7 @@ typedef enum {
 	SWITCH_EVENT_ROSTER,
 	SWITCH_EVENT_CODEC,
 	SWITCH_EVENT_BACKGROUND_JOB,
+	SWITCH_EVENT_DETECTED_SPEECH,
 	SWITCH_EVENT_ALL
 } switch_event_types_t;
 
@@ -800,10 +840,9 @@ typedef struct switch_io_event_hook_waitfor_write switch_io_event_hook_waitfor_w
 typedef struct switch_io_event_hook_send_dtmf switch_io_event_hook_send_dtmf_t;
 typedef struct switch_io_routines switch_io_routines_t;
 typedef struct switch_io_event_hooks switch_io_event_hooks_t;
-
 typedef struct switch_speech_handle switch_speech_handle_t;
+typedef struct switch_asr_handle switch_asr_handle_t;
 typedef struct switch_directory_handle switch_directory_handle_t;
-
 typedef struct switch_loadable_module_interface switch_loadable_module_interface_t;
 typedef struct switch_endpoint_interface switch_endpoint_interface_t;
 typedef struct switch_timer_interface switch_timer_interface_t;
@@ -813,6 +852,7 @@ typedef struct switch_application_interface switch_application_interface_t;
 typedef struct switch_api_interface switch_api_interface_t;
 typedef struct switch_file_interface switch_file_interface_t;
 typedef struct switch_speech_interface switch_speech_interface_t;
+typedef struct switch_asr_interface switch_asr_interface_t;
 typedef struct switch_directory_interface switch_directory_interface_t;
 typedef struct switch_chat_interface switch_chat_interface_t;
 typedef struct switch_core_port_allocator switch_core_port_allocator_t;