Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

docs: add docstrings to utility functions

游雁eeedd25881e9
diff --git a/funasr/download/download_model_from_hub.py b/funasr/download/download_model_from_hub.py
index e0cc7477c..0cdab34c2 100644
--- a/funasr/download/download_model_from_hub.py
+++ b/funasr/download/download_model_from_hub.py
@@ -7,6 +7,20 @@ from funasr.download.name_maps_from_hub import name_maps_ms, name_maps_hf, name_
def download_model(**kwargs):
+
+ """Download model from hub and parse its configuration.
+
+ Resolves model name aliases, downloads from ModelScope or HuggingFace,
+ reads config.yaml and configuration.json, and returns complete kwargs
+ for model instantiation.
+
+ Args:
+ **kwargs: Must include 'model' (str). Optional: 'hub', 'model_revision',
+ 'is_training', etc.
+
+ Returns:
+ dict: Complete kwargs with resolved paths, model class name, and config.
+ """
hub = kwargs.get("hub", "ms")
if hub == "ms" or hub == "modelscope":
kwargs = download_from_ms(**kwargs)
diff --git a/funasr/utils/load_utils.py b/funasr/utils/load_utils.py
index 501e817c5..e287d0c7a 100644
--- a/funasr/utils/load_utils.py
+++ b/funasr/utils/load_utils.py
@@ -52,6 +52,17 @@ def load_audio_text_image_video(
tokenizer=None,
**kwargs,
):
+ """Load audio/text/image/video data from various input formats.
+
+ Args:
+ data_or_path_or_list: File path, URL, numpy array, torch Tensor, bytes, or list.
+ fs (int): Target sample rate (default 16000).
+ audio_fs (int): Source audio sample rate.
+ data_type (str): Input type ("sound", "text", "fbank").
+
+ Returns:
+ torch.Tensor or list: Loaded and resampled audio tensor(s).
+ """
if isinstance(data_or_path_or_list, (list, tuple)):
if data_type is not None and isinstance(data_type, (list, tuple)):
data_types = [data_type] * len(data_or_path_or_list)
@@ -173,6 +184,14 @@ def _is_audio_container(data: bytes) -> bool:
def load_bytes(input):
+ """Convert audio bytes to numpy array.
+
+ Args:
+ input (bytes): Raw audio bytes.
+
+ Returns:
+ numpy.ndarray: Decoded audio samples.
+ """
# Only run the (expensive) frame-rate validation when the payload is an
# actual audio container (WAV, MP3, OGG, …). Raw PCM buffers have no
# recognisable header and would cause pydub to spend ~200 ms before
@@ -229,6 +248,17 @@ def validate_frame_rate(
def extract_fbank(data, data_len=None, data_type: str = "sound", frontend=None, **kwargs):
+ """Extract filter-bank features from audio data.
+
+ Args:
+ data: Audio samples (list of numpy arrays or tensors).
+ data_len: Lengths of each sample.
+ data_type (str): Input type ("sound", "fbank").
+ frontend: Frontend instance for feature extraction.
+
+ Returns:
+ tuple: (features_tensor, feature_lengths, feature_times)
+ """
if isinstance(data, np.ndarray):
data = torch.from_numpy(data)
if len(data.shape) < 2:
diff --git a/funasr/utils/misc.py b/funasr/utils/misc.py
index eb17f9723..ba16e05c1 100644
--- a/funasr/utils/misc.py
+++ b/funasr/utils/misc.py
@@ -55,6 +55,15 @@ def load_scp_as_list(scp_path, value_type="str", kv_sep=" "):
def deep_update(original, update):
+
+ """Recursively merge update dict into original dict (in-place).
+
+ For nested dicts, merges recursively. For other types, overwrites.
+
+ Args:
+ original (dict): Target dict to be updated in-place.
+ update (dict): Source dict with new values.
+ """
for key, value in update.items():
if isinstance(value, dict) and key in original:
if len(value) == 0:
diff --git a/funasr/utils/timestamp_tools.py b/funasr/utils/timestamp_tools.py
index 37ce88683..ccfc1a91d 100644
--- a/funasr/utils/timestamp_tools.py
+++ b/funasr/utils/timestamp_tools.py
@@ -108,6 +108,19 @@ def ts_prediction_lfr6_standard(
def timestamp_sentence(
punc_id_list, timestamp_postprocessed, text_postprocessed, return_raw_text=False
):
+
+ """Split recognized text into sentences using punctuation, with timestamps.
+
+ Args:
+ punc_id_list (Tensor/list): Punctuation IDs from CT-Transformer.
+ Values: 1=none, 2=comma, 3=period, 4=question.
+ timestamp_postprocessed (list): Per-character timestamps [[start_ms, end_ms], ...].
+ text_postprocessed (str): Space-separated recognized text.
+ return_raw_text (bool): Include raw_text in output.
+
+ Returns:
+ list[dict]: Sentences with keys: text, start, end, timestamp, [raw_text].
+ """
punc_list = [",", "。", "?", "、"]
res = []
if text_postprocessed is None:
diff --git a/funasr/utils/vad_utils.py b/funasr/utils/vad_utils.py
index f87a85e71..8400e60b6 100644
--- a/funasr/utils/vad_utils.py
+++ b/funasr/utils/vad_utils.py
@@ -19,6 +19,18 @@ def slice_padding_fbank(speech, speech_lengths, vad_segments):
def slice_padding_audio_samples(speech, speech_lengths, vad_segments):
+
+ """Slice audio into VAD segments with proper padding.
+
+ Args:
+ speech (Tensor): Full audio tensor.
+ speech_lengths (int): Total audio length.
+ vad_segments (list): List of (segment_info, original_index) tuples,
+ where segment_info is [start_ms, end_ms].
+
+ Returns:
+ tuple: (speech_list, speech_lengths_list) - lists of numpy arrays and their lengths.
+ """
speech_list = []
speech_lengths_list = []
for i, segment in enumerate(vad_segments):
@@ -33,6 +45,17 @@ def slice_padding_audio_samples(speech, speech_lengths, vad_segments):
def merge_vad(vad_result, max_length=15000, min_length=0):
+
+ """Merge short VAD segments to reduce fragmentation.
+
+ Args:
+ vad_result (list): VAD segments [[start_ms, end_ms], ...].
+ max_length (int): Maximum merged segment length in ms (default 15000).
+ min_length (int): Minimum segment length; shorter ones get merged (default 0).
+
+ Returns:
+ list: Merged VAD segments [[start_ms, end_ms], ...].
+ """
new_result = []
if len(vad_result) <= 1:
return vad_result