{"id":8187,"library":"funasr","title":"FunASR","description":"FunASR is a fundamental, end-to-end speech recognition toolkit from Alibaba DAMO Academy, currently at version 1.3.1. It provides a wide range of features including Automatic Speech Recognition (ASR), Voice Activity Detection (VAD), Punctuation Restoration, Language Models, Speaker Verification, and Speaker Diarization. The library is actively maintained with frequent updates, often releasing new models and features such as the Fun-ASR-Nano-2512 which supports 31 languages and low-latency real-time transcription.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/alibaba-damo-academy/FunASR.git","tags":["speech recognition","ASR","VAD","punctuation restoration","speaker diarization","audio","deep learning","modelscope","huggingface"],"install":[{"cmd":"pip install -U funasr","lang":"bash","label":"Standard Installation"},{"cmd":"pip install -U modelscope","lang":"bash","label":"Recommended for Pre-trained Models"}],"dependencies":[{"reason":"Essential for downloading and utilizing pre-trained models from ModelScope Hub.","package":"modelscope","optional":false},{"reason":"Core deep learning framework dependency for model execution.","package":"torch","optional":false},{"reason":"Required for ONNX-based inference, install `onnxruntime-gpu` for GPU acceleration.","package":"onnxruntime","optional":true}],"imports":[{"symbol":"AutoModel","correct":"from funasr import AutoModel"}],"quickstart":{"code":"from funasr import AutoModel\nimport soundfile as sf\nimport os\n\n# You might need to set an environment variable for modelscope token if hitting rate limits or private models\n# os.environ['MODELSCOPE_API_TOKEN'] = 'your_token_here'\n\n# Initialize the ASR model, will download 'paraformer-zh' from ModelScope if not local\n# 'paraformer-zh' is a multi-functional model, with VAD and PUNC integrated.\n# Use a public audio URL for demonstration\nmodel = AutoModel(model=\"paraformer-zh\", \n                  vad_model=\"fsmn-vad\", \n                  punc_model=\"ct-punc-c\",\n                  device=\"cpu\") # Specify 'cuda:0' for GPU if available\n\n# Example audio input: a remote URL or a local file path\n# For a local file, ensure it exists, e.g., 'path/to/your/audio.wav'\n# Using a provided example audio from FunASR's repository\naudio_input = \"https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav\"\n\nprint(f\"Processing audio: {audio_input}\")\n\n# Perform speech recognition\n# The generate method returns a list of dictionaries with transcription results\nresult = model.generate(input=audio_input)\n\n# Print the transcription result\nif result and result[0].get('text'):\n    print(f\"Transcription: {result[0]['text']}\")\nelse:\n    print(\"No transcription result found.\")\n\n# Example of VAD (Voice Activity Detection)\n# model_vad = AutoModel(model=\"fsmn-vad\", device=\"cpu\")\n# vad_result = model_vad.generate(input=audio_input)\n# print(f\"VAD Result: {vad_result}\")","lang":"python","description":"This quickstart demonstrates how to perform non-streaming Automatic Speech Recognition (ASR) using the `AutoModel` class. It downloads the `paraformer-zh` model (which often includes integrated VAD and Punctuation), processes a remote audio file, and prints the transcribed text. You can easily switch to local audio files or specify GPU usage."},"warnings":[{"fix":"For ONNX inference, consider `funasr_onnx` or refer to FunASR's runtime documentation for ONNX deployment within the main library. Ensure `onnxruntime` (and `onnxruntime-gpu` for GPU) is correctly installed.","message":"The `funasr` library primarily supports PyTorch-based inference, while `funasr_onnx` is a separate package designed for ONNX Runtime. Ensure you are using the correct library or runtime components for your desired deployment, especially if using ONNX for optimized inference.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Specify `hub=\"hf\"` in `AutoModel(model=\"your_model_name\", hub=\"hf\")` for Hugging Face models.","message":"When initializing `AutoModel`, models are downloaded from ModelScope by default. To use models hosted on Hugging Face, you must explicitly set `hub=\"hf\"` in the `AutoModel` constructor.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the model card for the recommended `model_revision` and include it in your `AutoModel` initialization, e.g., `AutoModel(model=\"paraformer-zh\", model_revision=\"v2.0.4\")`.","message":"Model interfaces or required revisions (`model_revision` parameter) may change frequently with updates. It's advisable to specify `model_revision` if a specific model version is needed for reproducibility or compatibility.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify your PyTorch version meets the requirements for export tasks. Upgrade PyTorch if necessary: `pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` (adjust for your CUDA version).","message":"For model export operations (e.g., to ONNX), specific PyTorch versions might be required. For example, `torch >= 1.11.0` is necessary for ONNX export functionality.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update `pip`, `setuptools`, and `wheel` before attempting installation: `pip install --upgrade pip setuptools wheel`. If installing from a cloned repository, then try `pip install -e .`.","cause":"This error typically occurs during installation from source or when `setuptools` or `pip` are outdated, preventing proper package metadata generation.","error":"× python setup.py egg_info did not run successfully."},{"fix":"Set `LD_LIBRARY_PATH` (Linux) or `PATH` (Windows) to include the directory containing your PyTorch installation's shared libraries (e.g., `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/pytorch/lib`). Reinstalling PyTorch or FunASR in a clean environment can also help.","cause":"The PyTorch (libtorch) shared libraries are not found in the system's dynamic linker search paths, often due to custom PyTorch installations or missing environment variables in containerized environments.","error":"error while loading shared libraries: libtorch_global_deps.so: cannot open shared object file: No such file or directory"},{"fix":"Ensure `funasr` and `modelscope` are updated to their latest versions: `pip install -U funasr modelscope`. Also, carefully review the model's documentation on ModelScope or Hugging Face for specific initialization parameters like `model_revision` or `trust_remote_code=True` that might be required.","cause":"This error arises when trying to use a specific model (e.g., `Fun-ASR-Nano-2512`) with an `funasr` library version that does not yet recognize or properly register that model's class, or if there's a model loading configuration mismatch.","error":"AssertionError: FunASRNano is not registered"}]}