Skip to content

cli.md

Latest commit

 

History

History
233 lines (183 loc) · 10.6 KB

cli.md

File metadata and controls

233 lines (183 loc) · 10.6 KB
Raw

Command-Line Interface

中文 | Python SDK | Model selection

Use funasr to transcribe local audio files, write structured results, or produce subtitles. This guide follows the parser and formatter in funasr/cli.py; it is not the HTTP server or the Hydra CLI.

Basic Usage

Transcribe one file with the default sensevoice model, or select a CLI alias:

funasr audio.wav
funasr audio.wav --model paraformer
funasr audio.wav --device cpu

Choose the next task: structured JSON, multiple files, subtitles, or speakers and hotwords. Inputs must be existing local files. Download remote audio yourself first; the CLI does not accept an audio URL as its positional input.

Installation

Install FunASR in your chosen Python environment, following the installation guide for prerequisites and optional model dependencies. These are usage commands, not a clean-install validation:

python -m pip install funasr
funasr --help
funasr --version

The selected models and VAD/punctuation/speaker components may download on first use. They need working hub access or a populated cache, enough memory, and the dependencies required by that checkpoint. --hub ms is the default; use --hub hf to select Hugging Face. Device selection is cuda:0 when PyTorch reports CUDA available, otherwise cpu; use --device to override it. This availability check does not guarantee enough GPU memory or a compatible model environment.

Output Formats

text (default)

Plain transcription text, one result per input file. Rich <|...|> model tags are removed, so this is not an emotion/event-tag output interface.

funasr audio.wav -f text -o ./transcripts

Without -o, the CLI prints results to stdout. --verbose adds CLI loading and timing messages to stderr; dependency/model logging may still appear on stdout. Use output files for automation that needs isolated payloads.

json

funasr audio.wav --timestamps -f json -o ./results
jq '.text' ./results/audio.json

This is an illustrative formatter fixture, not a measured transcription, performance result, or promise that every model returns these optional fields:

{
  "text": "Example.",
  "segments": [
    {"start": 0, "end": 1200, "text": "Example.", "timestamp": [[0, 1200]]}
  ],
  "timestamps": [[0, 1200]],
  "file": "audio.wav",
  "model": "sensevoice",
  "language": "auto",
  "audio_duration_s": 1.2,
  "processing_s": 0.01
}
Field Meaning
text Cleaned transcription text.
segments Included only when nonempty sentence_info produces segments. start/end are copied from the SDK (milliseconds for the sentence contract); text is cleaned. The per-segment timestamp can be null.
timestamps Optional top-level model timestamp data retained with --timestamps. The CLI does not normalize it to a universal word schema. Pair arrays in this example are milliseconds; model-specific dictionary timestamp representations may use seconds.
file Input basename, not its full path.
model Selected CLI alias, not an immutable checkpoint revision.
language Supplied hint or auto when omitted; not a detected-language result.
audio_duration_s Audio metadata duration in seconds, rounded to three decimals; null if soundfile.info cannot read it.
processing_s Per-file elapsed seconds around generation, rounded to three decimals. Excludes initial model loading and output formatting/writing; not end-to-end latency.

--timestamps retains timestamps already returned by the model. It does not request alignment or guarantee word-level timestamps. In JSON without this flag, the top-level field is omitted, but nested segment timestamps can remain. Plain text does not display timestamps. See the SDK output contract for model-dependent results.

Advanced Examples

Multiple Files

funasr first.wav second.wav -f json -o ./results
funasr ./*.wav -f srt -o ./subs

One model instance is reused, and files are processed sequentially with batch_size=1. The shell expands the glob; this is not parallel batch inference. Outputs use each input's basename without its extension plus .txt, .json, .srt, or .tsv. The output directory is created when needed. Files with the same stem can overwrite each other, including results from previous runs.

Without -o, multiple JSON results are separate pretty-printed objects, not a JSON array or JSONL stream. A missing file stops execution with exit code 1; earlier output files remain. There is no resume or transactional batch option.

srt

funasr audio.wav -f srt -o ./subs
funasr audio.wav -f srt --subtitle-segment-mode sentence -o ./raw-subs

SRT uses HH:MM:SS,mmm cue times. SRT and TSV request sentence_timestamp, output_timestamp, and return_time_stamps from the SDK. The default SenseVoice subtitle path also adds ct-punc; output still depends on the model returning usable sentence_info and timing data.

The default readable mode groups eligible adjacent cues with a gap of at most 500 ms, a combined duration of at most 8 seconds, and at most 42 characters, without crossing a known speaker change. Long cues are split only when their available timestamps can support text alignment. These are grouping targets, not a guarantee that every cue fits: unalignable or indivisible text can remain over the limits. The CLI does not invent evenly spaced word timestamps. sentence mode keeps raw model sentence boundaries. JSON and TSV are not grouped.

Without sentence segments, SRT falls back to one cue using available timestamp bounds, then audio duration. If neither is available, the fallback can have zero duration; inspect timing before publishing subtitles.

tsv

funasr audio.wav -f tsv -o ./tables

TSV has start, end, and text columns, with start/end converted from sentence milliseconds to seconds at three decimal places. Without segments, it emits one text row with 0.000 start and end, not inferred alignment.

Speakers and Hotwords

funasr meeting.wav --model paraformer --spk --timestamps -f json -o ./meetings
funasr audio.wav --model paraformer --language zh --hotwords "FunASR,达摩院"
funasr audio.wav --hub hf --model fun-asr-nano

--spk adds the cam++ speaker model. JSON segments include speaker only when the SDK supplies spk in sentence_info. It does not identify people by name or guarantee diarization for every model. SRT grouping respects available speaker boundaries, but the CLI's text/SRT/TSV formatters do not print speaker labels.

Hotwords are comma-separated, trimmed, and empty items discarded. The paraformer alias forwards a space-joined hotword string; other aliases forward a hotwords list. Recognition support depends on the model, not merely the parser accepting the option. --language is also a model-specific hint: the parser accepts any string and does not validate model language coverage.

Limits

  • This is a local-file SDK wrapper, not streaming, a network service, or native vLLM serving. See the deployment matrix for those paths.
  • The four aliases below are the entire --model choice set. Arbitrary hub IDs, local model directories, and backend-selection flags are not supported here.
  • moss-transcribe-diarize is not a CLI choice. Use the separate AutoModel adapter or funasr-server path in the MOSS guide, with that guide's dependencies and limitations; do not pass it to --model.
  • Model loading happens before the per-file existence check. Invalid input can therefore still incur loading/download time. Inference or dependency errors are not converted into a stable JSON error envelope.
  • Timing, memory, language coverage, alignment, and speaker quality depend on checkpoint, hardware, environment, and audio. This guide makes no speed or production-capacity claim.

Options

audio is one or more local file paths. None below is the actual parser default, not a string to supply on the command line.

Option Short Parser default Meaning / choices
--model -m sensevoice sensevoice, paraformer, paraformer-en, fun-asr-nano.
--hub -H ms ms (ModelScope) or hf (Hugging Face).
--language -l None Omitted: no language argument is forwarded. Explicit hints such as zh, en, ja, ko, yue, auto depend on the model.
--device None Automatically cuda:0 if CUDA is available, otherwise cpu; explicit device string overrides this.
--output-format -f text text, json, srt, tsv.
--subtitle-segment-mode readable readable or sentence; affects SRT only.
--output-dir -o None Omitted: stdout. Otherwise write per-file results to this directory.
--timestamps False Retain available top-level timestamps; does not request alignment.
--spk False Add speaker model; JSON speaker fields depend on SDK results.
--hotwords None Comma-separated hints, forwarded according to the model alias.
--verbose -v False CLI loading/timing messages to stderr.
--version Not applicable Print installed FunASR package version and exit, not a model revision.
--help -h Not applicable Print parser help and exit.

Models

CLI alias ASR model mapping Scope
sensevoice iic/SenseVoiceSmall Chinese, English, Japanese, Korean, Cantonese; rich tags are stripped from CLI text.
paraformer paraformer-zh Chinese recognition with VAD and punctuation.
paraformer-en paraformer-en English recognition; the CLI also adds punctuation.
fun-asr-nano FunAudioLLM/Fun-ASR-Nano-2512 Chinese, English, Japanese and Chinese dialects/accents; additional model dependencies apply.

All four configurations include fsmn-vad; speaker and punctuation additions follow the selected options described above. These mappings do not pin a hub revision. The separate Fun-ASR-MLT-Nano checkpoint is not selected by the fun-asr-nano alias. For other checkpoints use the Python SDK and model selection guide.

Legacy CLI

The original Hydra-based entry point remains funasr-hydra:

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

Its ++key=value configuration is separate from the argparse flags documented here; do not mix the two syntaxes.