modelscope--funasr/docs/cli.md

Command-Line Interface

FunASR provides an agent-friendly CLI for speech recognition from the terminal. Designed for AI agents (Claude Code, Codex, Cursor), shell scripts, and automation pipelines.

Installation

pip install funasr

Basic Usage

# Transcribe audio (simplest)
funasr audio.wav

# Specify model
funasr audio.wav --model paraformer

# JSON output (structured, parseable)
funasr audio.wav --output-format json

# SRT subtitles
funasr audio.wav --output-format srt --output-dir ./subs

srt and tsv outputs request sentence-level timestamps. In FunASR 1.3.18 and newer, the default sensevoice CLI path also loads punctuation for subtitle generation, so subtitle files are split into sentence cues instead of one full-text block when the model returns sentence_info.

Options

Option	Short	Default	Description
--model	-m	sensevoice	Model: sensevoice, paraformer, paraformer-en, fun-asr-nano
--hub	-H	ms	Model hub: ms (ModelScope) or hf (Hugging Face)
--language	-l	auto	Language: zh, en, ja, ko, yue, auto
--device		auto	Device: cuda:0, cpu
--output-format	-f	text	Output: text, json, srt, tsv
--output-dir	-o	stdout	Write output files to directory
--timestamps		off	Include word-level timestamps
--spk		off	Enable speaker diarization
--hotwords		none	Comma-separated hotwords
--verbose	-v	off	Show loading/timing info on stderr

Output Formats

text (default)

Plain transcription text, one result per file. Best for piping:

funasr audio.wav | wc -w

json

Structured output for programmatic use:

{
  "text": "欢迎大家来体验达摩院推出的语音识别模型",
  "segments": [
    {"start": 0, "end": 5540, "text": "欢迎大家来体验达摩院推出的语音识别模型"}
  ],
  "file": "audio.wav",
  "model": "sensevoice",
  "language": "auto",
  "duration_s": 0.29
}

srt

SubRip subtitle format:

1
00:00:00,000 --> 00:00:01,200
第一句。

2
00:00:01,200 --> 00:00:02,600
第二句。

If a model does not return sentence-level timestamps, the CLI falls back to one valid cue spanning the known timestamp or audio duration.

tsv

Tab-separated values (start/end in seconds):

start	end	text
0.000	1.200	第一句。
1.200	2.600	第二句。

Advanced Examples

# Speaker diarization + JSON
funasr meeting.wav --spk --timestamps -f json

# Batch transcribe all WAV files
funasr *.wav --output-format srt --output-dir ./output

# Chinese with hotwords
funasr audio.wav --model paraformer --language zh --hotwords "FunASR,达摩院"

# Pipe to jq for processing
funasr audio.wav -f json | jq '.text'

# Load models from Hugging Face instead of ModelScope
funasr audio.wav --hub hf --model fun-asr-nano

# Use with AI agents
result=$(funasr audio.wav -f json)
echo "$result" | jq -r '.text'

Models

Model	Languages	Speed	Best for
sensevoice	zh/en/ja/ko/yue	~70ms/10s	CPU-friendly ASR, emotion/audio events
paraformer	zh + mixed	~60ms/10s	Chinese production (with punctuation)
paraformer-en	en	~60ms/10s	English
fun-asr-nano	zh/en/ja + Chinese dialects/accents	varies	Encoder+LLM, complex audio

Language coverage is checkpoint-specific. For example, the separate Fun-ASR-MLT-Nano checkpoint covers 31 languages, while the default CLI fun-asr-nano choice targets Chinese, English, Japanese, and Chinese dialects or accents.

Legacy CLI

The original Hydra-based CLI is available as funasr-hydra:

funasr-hydra ++model=paraformer-zh ++input=audio.wav