Add more doc for Rust API (k2-fsa#3378)

Author: csukuangfj

sherpa-onnx/rust/sherpa-onnx/src/kws.rs

@@ -1,3 +1,37 @@
+//! Streaming keyword spotting.
+//!
+//! This module detects predefined or per-stream override keywords from an
+//! online ASR model. See
+//! [`rust-api-examples/examples/keyword_spotter.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/keyword_spotter.rs)
+//! for a complete example.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use sherpa_onnx::{KeywordSpotter, KeywordSpotterConfig, Wave};
+//!
+//! let wave = Wave::read("./test.wav").expect("read wave");
+//! let mut config = KeywordSpotterConfig::default();
+//! config.model_config.transducer.encoder = Some("./kws/encoder.onnx".into());
+//! config.model_config.transducer.decoder = Some("./kws/decoder.onnx".into());
+//! config.model_config.transducer.joiner = Some("./kws/joiner.onnx".into());
+//! config.model_config.tokens = Some("./kws/tokens.txt".into());
+//! config.keywords_file = Some("./keywords.txt".into());
+//!
+//! let kws = KeywordSpotter::create(&config).expect("create keyword spotter");
+//! let stream = kws.create_stream();
+//! stream.accept_waveform(wave.sample_rate(), wave.samples());
+//! stream.input_finished();
+//!
+//! while kws.is_ready(&stream) {
+//!     kws.decode(&stream);
+//! }
+//!
+//! if let Some(result) = kws.get_result(&stream) {
+//!     println!("{}", result.keyword);
+//! }
+//! ```
+
 use crate::online_asr::{OnlineModelConfig, OnlineStream};
 use crate::utils::to_c_ptr;
 use sherpa_onnx_sys as sys;
@@ -8,11 +42,16 @@ fn c_ptr_to_string(ptr: *const c_char) -> String {
     if ptr.is_null() {
         String::new()
     } else {
-        unsafe { CStr::from_ptr(ptr).to_string_lossy().into_owned() }
+        unsafe {
+            CStr::from_ptr(ptr)
+                .to_string_lossy()
+                .into_owned()
+        }
     }
 }
 
 #[derive(Clone, Debug)]
+/// Configuration for [`KeywordSpotter`].
 pub struct KeywordSpotterConfig {
     pub feat_config: sys::FeatureConfig,
     pub model_config: OnlineModelConfig,
@@ -46,19 +85,25 @@ impl KeywordSpotterConfig {
     fn to_sys(&self, cstrings: &mut Vec<CString>) -> sys::KeywordSpotterConfig {
         sys::KeywordSpotterConfig {
             feat_config: self.feat_config,
-            model_config: self.model_config.to_sys(cstrings),
+            model_config: self
+                .model_config
+                .to_sys(cstrings),
             max_active_paths: self.max_active_paths,
             num_trailing_blanks: self.num_trailing_blanks,
             keywords_score: self.keywords_score,
             keywords_threshold: self.keywords_threshold,
             keywords_file: to_c_ptr(&self.keywords_file, cstrings),
             keywords_buf: to_c_ptr(&self.keywords_buf, cstrings),
-            keywords_buf_size: self.keywords_buf.as_ref().map_or(0, |s| s.len() as i32),
+            keywords_buf_size: self
+                .keywords_buf
+                .as_ref()
+                .map_or(0, |s| s.len() as i32),
         }
     }
 }
 
 #[derive(Clone, Debug)]
+/// Decoded keyword spotting result for one stream.
 pub struct KeywordResult {
     pub keyword: String,
     pub tokens: String,
@@ -68,13 +113,15 @@ pub struct KeywordResult {
     pub json: String,
 }
 
+/// Streaming keyword spotter.
 pub struct KeywordSpotter {
     ptr: *const sys::KeywordSpotter,
 }
 
 unsafe impl Send for KeywordSpotter {}
 
 impl KeywordSpotter {
+    /// Create a keyword spotter from [`KeywordSpotterConfig`].
     pub fn create(config: &KeywordSpotterConfig) -> Option<Self> {
         let mut cstrings = Vec::new();
         let sys_config = config.to_sys(&mut cstrings);
@@ -86,38 +133,47 @@ impl KeywordSpotter {
         }
     }
 
+    /// Create a stream that uses the keywords configured in [`KeywordSpotterConfig`].
     pub fn create_stream(&self) -> OnlineStream {
         let ptr = unsafe { sys::SherpaOnnxCreateKeywordStream(self.ptr) };
         OnlineStream { ptr }
     }
 
+    /// Create a stream that uses `keywords` instead of the configured keyword list.
     pub fn create_stream_with_keywords(&self, keywords: &str) -> OnlineStream {
         let keywords = CString::new(keywords).unwrap();
-        let ptr = unsafe {
-            sys::SherpaOnnxCreateKeywordStreamWithKeywords(self.ptr, keywords.as_ptr())
-        };
+        let ptr =
+            unsafe { sys::SherpaOnnxCreateKeywordStreamWithKeywords(self.ptr, keywords.as_ptr()) };
         OnlineStream { ptr }
     }
 
+    /// Return `true` if `stream` has enough audio for another decode step.
     pub fn is_ready(&self, stream: &OnlineStream) -> bool {
         unsafe { sys::SherpaOnnxIsKeywordStreamReady(self.ptr, stream.ptr) != 0 }
     }
 
+    /// Decode one incremental step for `stream`.
     pub fn decode(&self, stream: &OnlineStream) {
         unsafe { sys::SherpaOnnxDecodeKeywordStream(self.ptr, stream.ptr) }
     }
 
+    /// Decode multiple streams in one batch.
     pub fn decode_multiple_streams(&self, streams: &[&OnlineStream]) {
-        let ptrs: Vec<*const sys::OnlineStream> = streams.iter().map(|s| s.ptr).collect();
+        let ptrs: Vec<*const sys::OnlineStream> = streams
+            .iter()
+            .map(|s| s.ptr)
+            .collect();
         unsafe {
             sys::SherpaOnnxDecodeMultipleKeywordStreams(self.ptr, ptrs.as_ptr(), ptrs.len() as i32)
         }
     }
 
+    /// Reset the detector state for `stream`.
     pub fn reset(&self, stream: &OnlineStream) {
         unsafe { sys::SherpaOnnxResetKeywordStream(self.ptr, stream.ptr) }
     }
 
+    /// Get the structured keyword spotting result for `stream`.
     pub fn get_result(&self, stream: &OnlineStream) -> Option<KeywordResult> {
         unsafe {
             let p = sys::SherpaOnnxGetKeywordResult(self.ptr, stream.ptr);
@@ -126,7 +182,11 @@ impl KeywordSpotter {
             }
 
             let result = &*p;
-            let tokens_arr = if result.tokens_arr.is_null() || result.count <= 0 {
+            let tokens_arr = if result
+                .tokens_arr
+                .is_null()
+                || result.count <= 0
+            {
                 Vec::new()
             } else {
                 slice::from_raw_parts(result.tokens_arr, result.count as usize)
@@ -135,7 +195,11 @@ impl KeywordSpotter {
                     .collect()
             };
 
-            let timestamps = if result.timestamps.is_null() || result.count <= 0 {
+            let timestamps = if result
+                .timestamps
+                .is_null()
+                || result.count <= 0
+            {
                 Vec::new()
             } else {
                 slice::from_raw_parts(result.timestamps, result.count as usize).to_vec()
@@ -155,14 +219,17 @@ impl KeywordSpotter {
         }
     }
 
+    /// Get the result for `stream` as a JSON string.
     pub fn get_result_as_json(&self, stream: &OnlineStream) -> Option<String> {
         unsafe {
             let p = sys::SherpaOnnxGetKeywordResultAsJson(self.ptr, stream.ptr);
             if p.is_null() {
                 return None;
             }
 
-            let ans = CStr::from_ptr(p).to_string_lossy().into_owned();
+            let ans = CStr::from_ptr(p)
+                .to_string_lossy()
+                .into_owned();
             sys::SherpaOnnxFreeKeywordResultJson(p);
             Some(ans)
         }
@@ -172,7 +239,10 @@ impl KeywordSpotter {
 impl Drop for KeywordSpotter {
     fn drop(&mut self) {
         unsafe {
-            if !self.ptr.is_null() {
+            if !self
+                .ptr
+                .is_null()
+            {
                 sys::SherpaOnnxDestroyKeywordSpotter(self.ptr);
             }
         }

sherpa-onnx/rust/sherpa-onnx/src/lib.rs

@@ -37,7 +37,11 @@
 //! - [`pocket_tts.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/pocket_tts.rs)
 //! - [`silero_vad_remove_silence.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/silero_vad_remove_silence.rs)
 //! - [`online_punctuation.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/online_punctuation.rs)
+//! - [`offline_punctuation.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/offline_punctuation.rs)
+//! - [`keyword_spotter.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/keyword_spotter.rs)
+//! - [`spoken_language_identification.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/spoken_language_identification.rs)
 //! - [`offline_speaker_diarization.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/offline_speaker_diarization.rs)
+//! - [`speaker_embedding_manager.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/speaker_embedding_manager.rs)
 //!
 //! # Offline recognition example
 //!
@@ -130,140 +134,6 @@
 //! let tts = OfflineTts::create(&config).expect("create tts");
 //! println!("{}", tts.sample_rate());
 //! ```
-//! Safe Rust bindings for the public sherpa-onnx inference APIs.
-//!
-//! This crate wraps the sherpa-onnx C API with RAII-owned Rust types and
-//! idiomatic configuration structs. The main feature families are:
-//!
-//! - offline ASR through [`OfflineRecognizer`]
-//! - streaming ASR through [`OnlineRecognizer`]
-//! - offline text-to-speech through [`OfflineTts`]
-//! - voice activity detection through [`VoiceActivityDetector`]
-//! - speaker embeddings and diarization
-//! - online punctuation
-//! - offline and streaming speech denoising
-//! - audio tagging
-//! - WAV I/O helpers through [`Wave`] and [`write()`]
-//!
-//! # How the Rust API is organized
-//!
-//! Most APIs follow the same pattern:
-//!
-//! 1. Start with a `*Config` value and fill the fields for exactly one model
-//!    family.
-//! 2. Call `create()` to construct the runtime object.
-//! 3. Create a stream if the API is stream-based.
-//! 4. Feed audio or text, then fetch results with the provided accessor methods.
-//!
-//! All runtime wrappers automatically free their underlying C resources on drop.
-//!
-//! # Examples
-//!
-//! The repository contains end-to-end Rust examples under
-//! [`rust-api-examples/examples/`](https://github.com/k2-fsa/sherpa-onnx/tree/master/rust-api-examples/examples).
-//! Good entry points are:
-//!
-//! - [`sense_voice.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/sense_voice.rs)
-//! - [`nemo_parakeet.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/nemo_parakeet.rs)
-//! - [`streaming_zipformer.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/streaming_zipformer.rs)
-//! - [`pocket_tts.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/pocket_tts.rs)
-//! - [`silero_vad_remove_silence.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/silero_vad_remove_silence.rs)
-//! - [`online_punctuation.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/online_punctuation.rs)
-//! - [`offline_speaker_diarization.rs`](https://github.com/k2-fsa/sherpa-onnx/blob/master/rust-api-examples/examples/offline_speaker_diarization.rs)
-//!
-//! # Offline recognition example
-//!
-//! ```no_run
-//! use sherpa_onnx::{
-//!     OfflineRecognizer, OfflineRecognizerConfig, OfflineSenseVoiceModelConfig, Wave,
-//! };
-//!
-//! let wave = Wave::read("./test.wav").expect("read wave");
-//!
-//! let mut config = OfflineRecognizerConfig::default();
-//! config.model_config.sense_voice = OfflineSenseVoiceModelConfig {
-//!     model: Some(
-//!         "./sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17-int8/model.int8.onnx".into(),
-//!     ),
-//!     language: Some("auto".into()),
-//!     use_itn: true,
-//! };
-//! config.model_config.tokens = Some(
-//!     "./sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17-int8/tokens.txt".into(),
-//! );
-//!
-//! let recognizer = OfflineRecognizer::create(&config).expect("create recognizer");
-//! let stream = recognizer.create_stream();
-//! stream.accept_waveform(wave.sample_rate(), wave.samples());
-//! recognizer.decode(&stream);
-//!
-//! let result = stream.get_result().expect("result");
-//! println!("{}", result.text);
-//! ```
-//!
-//! # Streaming recognition example
-//!
-//! ```no_run
-//! use sherpa_onnx::{OnlineRecognizer, OnlineRecognizerConfig, Wave};
-//!
-//! let wave = Wave::read("./test.wav").expect("read wave");
-//!
-//! let mut config = OnlineRecognizerConfig::default();
-//! config.model_config.transducer.encoder = Some(
-//!     "./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/encoder-epoch-99-avg-1.int8.onnx".into(),
-//! );
-//! config.model_config.transducer.decoder = Some(
-//!     "./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/decoder-epoch-99-avg-1.onnx".into(),
-//! );
-//! config.model_config.transducer.joiner = Some(
-//!     "./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/joiner-epoch-99-avg-1.int8.onnx".into(),
-//! );
-//! config.model_config.tokens = Some(
-//!     "./sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20/tokens.txt".into(),
-//! );
-//! config.enable_endpoint = true;
-//! config.decoding_method = Some("greedy_search".into());
-//!
-//! let recognizer = OnlineRecognizer::create(&config).expect("create recognizer");
-//! let stream = recognizer.create_stream();
-//! stream.accept_waveform(wave.sample_rate(), wave.samples());
-//! stream.input_finished();
-//! while recognizer.is_ready(&stream) {
-//!     recognizer.decode(&stream);
-//! }
-//! ```
-//!
-//! # TTS example
-//!
-//! ```no_run
-//! use sherpa_onnx::{
-//!     OfflineTts, OfflineTtsConfig, OfflineTtsModelConfig, OfflineTtsPocketModelConfig,
-//! };
-//!
-//! let config = OfflineTtsConfig {
-//!     model: OfflineTtsModelConfig {
-//!         pocket: OfflineTtsPocketModelConfig {
-//!             lm_flow: Some("./sherpa-onnx-pocket-tts-int8-2026-01-26/lm_flow.int8.onnx".into()),
-//!             lm_main: Some("./sherpa-onnx-pocket-tts-int8-2026-01-26/lm_main.int8.onnx".into()),
-//!             encoder: Some("./sherpa-onnx-pocket-tts-int8-2026-01-26/encoder.onnx".into()),
-//!             decoder: Some("./sherpa-onnx-pocket-tts-int8-2026-01-26/decoder.int8.onnx".into()),
-//!             text_conditioner: Some(
-//!                 "./sherpa-onnx-pocket-tts-int8-2026-01-26/text_conditioner.onnx".into(),
-//!             ),
-//!             vocab_json: Some("./sherpa-onnx-pocket-tts-int8-2026-01-26/vocab.json".into()),
-//!             token_scores_json: Some(
-//!                 "./sherpa-onnx-pocket-tts-int8-2026-01-26/token_scores.json".into(),
-//!             ),
-//!             ..Default::default()
-//!         },
-//!         ..Default::default()
-//!     },
-//!     ..Default::default()
-//! };
-//!
-//! let tts = OfflineTts::create(&config).expect("create tts");
-//! println!("{}", tts.sample_rate());
-//! ```
 mod audio_tagging;
 mod display;
 mod kws;

sherpa-onnx/rust/sherpa-onnx/src/offline_asr.rs

@@ -673,7 +673,9 @@ impl OfflineStream {
             if p.is_null() {
                 String::new()
             } else {
-                CStr::from_ptr(p).to_string_lossy().into_owned()
+                CStr::from_ptr(p)
+                    .to_string_lossy()
+                    .into_owned()
             }
         }
     }