Add phrase list support for speech recognizer (#31)

* Add phrase list support.

* Address Copilot code review feedbacks.

* Refactor GrammarPhrase into its own module

Moved the GrammarPhrase struct and its implementation from phrase_list_grammar.rs to a new grammar_phrase.rs module for better separation of concerns and code organization. Updated imports to use the new module.

Author: wangfu91

src/speech.rs

@@ -3,7 +3,9 @@ mod audio_data_stream;
 mod auto_detect_source_language_config;
 mod cancellation_details;
 mod embedded_speech_config;
+mod grammar_phrase;
 mod keyword_recognition_model;
+mod phrase_list_grammar;
 mod recognition_event;
 mod session_event;
 mod source_language_config;
@@ -28,6 +30,7 @@ pub use self::auto_detect_source_language_config::AutoDetectSourceLanguageConfig
 pub use self::cancellation_details::CancellationDetails;
 pub use self::embedded_speech_config::EmbeddedSpeechConfig;
 pub use self::keyword_recognition_model::KeywordRecognitionModel;
+pub use self::phrase_list_grammar::PhraseListGrammar;
 pub use self::recognition_event::RecognitionEvent;
 pub use self::session_event::SessionEvent;
 pub use self::source_language_config::SourceLanguageConfig;

src/speech/grammar_phrase.rs

@@ -0,0 +1,37 @@
+use std::{ffi::CString, mem::MaybeUninit};
+
+use crate::{
+    error::{convert_err, Result},
+    ffi::{
+        grammar_phrase_create_from_text, grammar_phrase_handle_release, SmartHandle,
+        SPXPHRASEHANDLE,
+    },
+};
+
+/// Represents base class grammar for customizing speech recognition. \
+/// Added in version 1.5.0.
+#[derive(Debug)]
+pub(crate) struct GrammarPhrase {
+    pub handle: SmartHandle<SPXPHRASEHANDLE>,
+}
+
+impl GrammarPhrase {
+    /// Creates a grammar phrase using the specified phrase text.
+    /// # Arguments
+    /// * `text` - The text representing a phrase that may be spoken by the user.
+    pub(crate) fn from_text(text: impl AsRef<str>) -> Result<GrammarPhrase> {
+        unsafe {
+            let mut handle: MaybeUninit<SPXPHRASEHANDLE> = MaybeUninit::uninit();
+            let c_text = CString::new(text.as_ref())?;
+            let ret = grammar_phrase_create_from_text(handle.as_mut_ptr(), c_text.as_ptr());
+            convert_err(ret, "GrammarPhrase::grammar_phrase_from_text error")?;
+            Ok(GrammarPhrase {
+                handle: SmartHandle::create(
+                    "GrammarPhrase",
+                    handle.assume_init(),
+                    grammar_phrase_handle_release,
+                ),
+            })
+        }
+    }
+}

src/speech/phrase_list_grammar.rs

@@ -0,0 +1,57 @@
+use std::ffi::CString;
+use std::mem::MaybeUninit;
+
+use crate::error::{convert_err, Result};
+use crate::ffi::{
+    grammar_handle_release, phrase_list_grammar_add_phrase, phrase_list_grammar_clear,
+    phrase_list_grammar_from_recognizer_by_name, SmartHandle, SPXGRAMMARHANDLE,
+};
+use crate::speech::grammar_phrase::GrammarPhrase;
+use crate::speech::SpeechRecognizer;
+
+/// Represents a phrase list grammar for dynamic grammar scenarios. \
+/// Added in version 1.5.0.
+#[derive(Debug)]
+pub struct PhraseListGrammar {
+    handle: SmartHandle<SPXGRAMMARHANDLE>,
+}
+
+impl PhraseListGrammar {
+    /// Creates a phrase list grammar for the specified recognizer.
+    pub fn from_recognizer(recognizer: &SpeechRecognizer) -> Result<PhraseListGrammar> {
+        unsafe {
+            let c_name = CString::new("")?;
+            let mut handle: MaybeUninit<SPXGRAMMARHANDLE> = MaybeUninit::uninit();
+            let ret = phrase_list_grammar_from_recognizer_by_name(
+                handle.as_mut_ptr(),
+                recognizer.handle.inner(),
+                c_name.as_ptr(),
+            );
+            convert_err(ret, "PhraseListGrammar::from_recognizer error")?;
+            Ok(PhraseListGrammar {
+                handle: SmartHandle::create(
+                    "PhraseListGrammar",
+                    handle.assume_init(),
+                    grammar_handle_release,
+                ),
+            })
+        }
+    }
+
+    /// AddPhrase adds a simple phrase that may be spoken by the user.
+    pub fn add_phrase(&self, text: impl AsRef<str>) -> Result<()> {
+        let grammar_phrase = GrammarPhrase::from_text(text)?;
+        let ret: usize = unsafe {
+            phrase_list_grammar_add_phrase(self.handle.inner(), grammar_phrase.handle.inner())
+        };
+        convert_err(ret, "PhraseListGrammar::add_phrase error")?;
+        Ok(())
+    }
+
+    /// Clears all phrases from the phrase list grammar.
+    pub fn clear(&self) -> Result<()> {
+        let ret = unsafe { phrase_list_grammar_clear(self.handle.inner()) };
+        convert_err(ret, "PhraseListGrammar::clear error")?;
+        Ok(())
+    }
+}

src/speech/speech_recognizer.rs

@@ -32,7 +32,7 @@ use std::os::raw::c_void;
 
 /// SpeechRecognizer struct holds functionality for speech-to-text recognition.
 pub struct SpeechRecognizer {
-    handle: SmartHandle<SPXRECOHANDLE>,
+    pub(crate) handle: SmartHandle<SPXRECOHANDLE>,
     properties: PropertyCollection,
     handle_async_start_continuous: Option<SmartHandle<SPXASYNCHANDLE>>,
     handle_async_stop_continuous: Option<SmartHandle<SPXASYNCHANDLE>>,

tests/integration_test.rs

@@ -1,4 +1,5 @@
 use cognitive_services_speech_sdk_rs as msspeech;
+use cognitive_services_speech_sdk_rs::speech::PhraseListGrammar;
 use log::*;
 use rust_embed::Embed;
 use std::env;
@@ -111,3 +112,37 @@ async fn text_to_speech() {
         }
     }
 }
+
+#[tokio::test]
+async fn phrase_list_test() {
+    let current_dir = std::env::current_dir().expect("Failed to get current directory");
+    let mut file_path = PathBuf::from(&current_dir);
+    file_path.push("examples");
+    file_path.push("sample_files");
+    file_path.push("peloozoid.wav");
+    let file_path_str = &file_path.into_os_string().into_string().unwrap();
+    let audio_config = msspeech::audio::AudioConfig::from_wav_file_input(file_path_str).unwrap();
+
+    // before running this text export the below listed variables. Example:
+    // export MSSubscriptionKey=32...
+    // export MSServiceRegion=westeurope
+    let speech_config = msspeech::speech::SpeechConfig::from_subscription(
+        env::var("MSSubscriptionKey").unwrap(),
+        env::var("MSServiceRegion").unwrap_or("westeurope".to_string()),
+    )
+    .unwrap();
+
+    let mut speech_recognizer =
+        msspeech::speech::SpeechRecognizer::from_config(speech_config, audio_config).unwrap();
+
+    let grammar = PhraseListGrammar::from_recognizer(&speech_recognizer).unwrap();
+    grammar.add_phrase("peloozoid").unwrap();
+
+    let result = speech_recognizer.recognize_once_async().await.unwrap();
+    // "That shape is a Peloozoid."
+    println!(
+        "[phrase_list_test] got recognition result: {:?}",
+        result.text
+    );
+    assert!(result.text.to_lowercase().contains("peloozoid"));
+}