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 all core model classes and methods

游雁d97c22326fd2
diff --git a/funasr/models/campplus/model.py b/funasr/models/campplus/model.py
index e3a829b1f..6730ad589 100644
--- a/funasr/models/campplus/model.py
+++ b/funasr/models/campplus/model.py
@@ -36,6 +36,14 @@ else:
@tables.register("model_classes", "CAMPPlus")
class CAMPPlus(torch.nn.Module):
+ """CAM++ Speaker Verification Model.
+
+ Extracts fixed-dimensional speaker embeddings from variable-length audio.
+ Used for speaker verification and speaker diarization pipelines.
+
+ Output: 192-dimensional speaker embedding per utterance.
+ """
+
def __init__(
self,
feat_dim=80,
@@ -113,6 +121,15 @@ class CAMPPlus(torch.nn.Module):
torch.nn.init.zeros_(m.bias)
def forward(self, x):
+ """Extract speaker embedding from fbank features.
+
+ Args:
+ x (Tensor): Input fbank features, shape (batch, time, feat_dim).
+
+ Returns:
+ Tensor: Speaker embedding, shape (batch, embedding_size) for segment level,
+ or (batch, time, channels) for frame level.
+ """
x = x.permute(0, 2, 1) # (B,T,F) => (B,F,T)
x = self.head(x)
x = self.xvector(x)
@@ -129,6 +146,20 @@ class CAMPPlus(torch.nn.Module):
frontend=None,
**kwargs,
):
+ """Run speaker embedding extraction on audio input.
+
+ Args:
+ data_in: Audio input (file path, numpy array, or list).
+ data_lengths: Not used.
+ key (list): Sample identifiers.
+ tokenizer: Not used.
+ frontend: Not used.
+ **kwargs: Must include 'device' (str) and optional 'fs' (int, default 16000).
+
+ Returns:
+ tuple: (results, meta_data) where results is
+ [{"spk_embedding": Tensor of shape (1, 192)}]
+ """
# extract fbank feats
meta_data = {}
time1 = time.perf_counter()
diff --git a/funasr/models/ct_transformer/model.py b/funasr/models/ct_transformer/model.py
index f1a231893..ae2d318bc 100644
--- a/funasr/models/ct_transformer/model.py
+++ b/funasr/models/ct_transformer/model.py
@@ -33,7 +33,17 @@ else:
@tables.register("model_classes", "CTTransformer")
class CTTransformer(torch.nn.Module):
- """
+ """CT-Transformer: Punctuation Restoration Model.
+
+ Adds punctuation (comma, period, question mark) to unpunctuated text.
+ Supports Chinese and English. Used as punc_model in the ASR pipeline.
+
+ Output: {"key": "...", "text": "punctuated text", "punc_array": Tensor}
+ punc_array encoding: 1=none, 2=comma(,), 3=period(。), 4=question(?)
+
+ Note: Not needed for Fun-ASR-Nano/SenseVoice/Qwen3-ASR (they output punctuation natively).
+ Only required for Paraformer models.
+
Author: Speech Lab of DAMO Academy, Alibaba Group
CT-Transformer: Controllable time-delay transformer for real-time punctuation prediction and disfluency detection
https://arxiv.org/pdf/2003.01309.pdf
diff --git a/funasr/models/fsmn_vad_streaming/model.py b/funasr/models/fsmn_vad_streaming/model.py
index 8e43b559d..d4c91c8d5 100644
--- a/funasr/models/fsmn_vad_streaming/model.py
+++ b/funasr/models/fsmn_vad_streaming/model.py
@@ -281,7 +281,14 @@ class Stats(object):
@tables.register("model_classes", "FsmnVADStreaming")
class FsmnVADStreaming(nn.Module):
- """
+ """FSMN-based Voice Activity Detection (streaming/offline).
+
+ Detects speech segments in audio, returning start/end timestamps (milliseconds).
+ Supports both offline (full audio) and streaming (chunk-by-chunk) modes.
+
+ Offline output: [{"key": "...", "value": [[start_ms, end_ms], ...]}]
+ Streaming output: [[beg, -1]] (start), [[-1, end]] (end), [[beg, end]] (complete), [] (no event)
+
Author: Speech Lab of DAMO Academy, Alibaba Group
Deep-FSMN for Large Vocabulary Continuous Speech Recognition
https://arxiv.org/abs/1803.05030
diff --git a/funasr/models/fun_asr_nano/model.py b/funasr/models/fun_asr_nano/model.py
index a6507525d..f78d0e755 100644
--- a/funasr/models/fun_asr_nano/model.py
+++ b/funasr/models/fun_asr_nano/model.py
@@ -25,6 +25,26 @@ dtype_map = {"bf16": torch.bfloat16, "fp16": torch.float16, "fp32": torch.float3
@tables.register("model_classes", "FunASRNano")
class FunASRNano(nn.Module):
+ """Fun-ASR-Nano: End-to-End ASR Large Model.
+
+ Trained on tens of millions of hours of real speech data.
+ Supports 31 languages including Chinese dialects and regional accents.
+
+ Features:
+ - Character-level timestamps (via CTC forced alignment)
+ - Hotword customization
+ - Speaker diarization (when combined with spk_model)
+ - Lyrics and rap recognition
+ - Streaming chunk-by-chunk inference (demo2.py)
+
+ Output: {"key": ..., "text": ..., "timestamps": [{"token", "start_time", "end_time"}, ...],
+ "ctc_timestamps": [...]}
+
+ Note: Outputs punctuation natively — punc_model is NOT needed.
+
+ Requirements: pip install tiktoken huggingface_hub
+ """
+
def __init__(
self,
audio_encoder: str = None,
diff --git a/funasr/models/paraformer/model.py b/funasr/models/paraformer/model.py
index 85967af3e..fc20c13de 100644
--- a/funasr/models/paraformer/model.py
+++ b/funasr/models/paraformer/model.py
@@ -28,7 +28,23 @@ from funasr.utils.load_utils import load_audio_text_image_video, extract_fbank
@tables.register("model_classes", "Paraformer")
class Paraformer(torch.nn.Module):
- """
+ """Paraformer: Non-autoregressive End-to-End ASR Model.
+
+ High-accuracy speech recognition for Chinese/English. The production workhorse.
+
+ Features:
+ - Non-autoregressive (parallel decoding, fast inference)
+ - Character-level timestamps via CIF predictor
+ - Streaming and offline modes
+ - Hotword customization
+ - Speaker diarization (with spk_model)
+ - ONNX export support
+
+ Output: {"key": "...", "text": "recognized text", "timestamp": [[start_ms, end_ms], ...]}
+
+ Note: Requires punc_model="ct-punc" for punctuation (unlike Fun-ASR-Nano/SenseVoice
+ which output punctuation natively).
+
Author: Speech Lab of DAMO Academy, Alibaba Group
Paraformer: Fast and Accurate Parallel Transformer for Non-autoregressive End-to-End Speech Recognition
https://arxiv.org/abs/2206.08317
diff --git a/funasr/models/qwen3_asr/model.py b/funasr/models/qwen3_asr/model.py
index fb86a6cd0..0054ebc42 100644
--- a/funasr/models/qwen3_asr/model.py
+++ b/funasr/models/qwen3_asr/model.py
@@ -14,6 +14,19 @@ from funasr.register import tables
@tables.register("model_classes", "Qwen/Qwen3-ASR-1.7B")
@tables.register("model_classes", "Qwen/Qwen3-ASR-0.6B")
class Qwen3ASR(nn.Module):
+ """Qwen3-ASR: Large Language Model based ASR supporting 52 languages.
+
+ Wraps the qwen-asr package's Qwen3ASRModel for use within FunASR's AutoModel interface.
+ Supports auto language detection, contextual recognition, and optional forced alignment
+ for character-level timestamps.
+
+ Requirements:
+ pip install qwen-asr
+
+ Models:
+ - Qwen/Qwen3-ASR-0.6B (lighter, ~4GB GPU memory)
+ - Qwen/Qwen3-ASR-1.7B (more accurate, ~8GB GPU memory)
+ """
def __init__(self, **kwargs):
super().__init__()
@@ -59,6 +72,16 @@ class Qwen3ASR(nn.Module):
logging.info(f"Qwen3ASR model loaded from {model_path}")
def _resolve_model_path(self, model_path, hub, kwargs):
+ """Resolve model path: use local if exists, otherwise download from hub.
+
+ Args:
+ model_path (str): Model name or local path.
+ hub (str): "ms" for ModelScope, "hf" for HuggingFace.
+ kwargs (dict): Additional options (model_revision, etc.)
+
+ Returns:
+ str: Resolved local path to model files.
+ """
if os.path.exists(model_path):
return model_path
@@ -86,6 +109,30 @@ class Qwen3ASR(nn.Module):
frontend=None,
**kwargs,
):
+ """Run Qwen3-ASR speech recognition.
+
+ Args:
+ data_in: Audio input. Accepts:
+ - list of file paths/URLs
+ - list of (numpy_array, sample_rate) tuples
+ - single numpy array or torch Tensor
+ data_lengths: Not used.
+ key (list): Sample identifiers.
+ tokenizer: Not used (Qwen3-ASR has internal tokenizer).
+ frontend: Not used (Qwen3-ASR has internal audio processing).
+ **kwargs: Runtime parameters:
+ - language (str): Language hint (e.g. "Chinese", "English") or None for auto-detect.
+ - return_time_stamps (bool): Return character-level timestamps (requires forced_aligner).
+ - output_timestamp (bool): Same as return_time_stamps (for pipeline compatibility).
+ - context (str): Context prompt for contextual recognition.
+
+ Returns:
+ tuple: (results, meta_data) where results is list of dicts:
+ - "key" (str): Sample ID
+ - "text" (str): Recognized text (with punctuation)
+ - "language" (str): Detected language (if available)
+ - "timestamp" (list): [[start_ms, end_ms], ...] (if timestamps enabled)
+ """
meta_data = {}
time1 = time.perf_counter()