asr_lib 0.4.0

On-device speech recognition for Flutter powered by sherpa-onnx.

sherpa-asr

On-device speech recognition for Flutter, powered by sherpa-onnx.

主要 API

AsrLib — 核心引擎

final asr = AsrLib();

方法	说明
initialize({AsrConfig? config})	初始化引擎，加载 VAD 和 ASR 模型
startRecording()	开始录音（自动 VAD + 识别循环）
stopRecording()	停止录音并刷新剩余 VAD 片段
transcribe(List<double> samples)	直接转写音频采样（不通过麦克风）
downloadModel({Map<String, String>? urls})	下载模型文件，默认下载 funasr-nano
isModelDownloaded()	检查模型是否已下载
release()	释放所有资源

属性/流	类型	说明
isReady	bool	引擎是否就绪（状态 == ready）
stateStream	Stream<AsrState>	状态流：idle → initializing → ready → recording → vadProcessing → transcribing → error
resultStream	Stream<AsrResult>	识别结果流，包含 text / isEndpoint / isFinal
progressStream	Stream<DownloadProgress>	下载进度流，包含 fileName / percent

AsrConfig — 配置

AsrConfig(
  sampleRate: 16000,
  enableVad: true,
  vadThreshold: 0.5,
  vadMinSilenceDuration: 0.25,
  vadMinSpeechDuration: 0.5,
  modelType: 'zipformer_ctc',    // zipformer_ctc | sense_voice | paraformer
  decodingMethod: 'greedy_search',
  numThreads: 2,
);

预置模型下载 URL：

• AsrConfig.defaultDownloadUrls — funasr-nano（ModelScope）
• AsrConfig.senseVoiceDownloadUrls — SenseVoice（HuggingFace）

AsrRegistry — 全局服务注册中心

单例模式，支持应用启动时预初始化：

AsrRegistry.instance;

方法/属性	说明
preInitialize({AsrConfig? config})	异步预初始化，不阻塞 UI
ensureInitialized({AsrConfig? config})	确保已初始化，未初始化则自动触发
startRecording()	便捷代理至 AsrLib
stopRecording()	便捷代理至 AsrLib
reset()	重置服务，释放所有资源
stateStream / resultStream / progressStream	代理至 AsrLib 的流

AsrPermissions — 麦克风权限

await AsrPermissions.requestMicrophone();
await AsrPermissions.checkMicrophone();
AsrPermissions.openSettings();

GlobalTextCorrector — 文本纠错

支持拼音匹配和模糊匹配，用于修正语音识别结果：

await GlobalTextCorrector.instance.loadFromAsset('assets/hotwords.json');
final corrected = GlobalTextCorrector.instance.correct('识别结果');

AsrState — 状态枚举

idle → initializing → ready → downloading → recording → vadProcessing → transcribing → error

AsrResult — 识别结果

字段	类型	说明
text	String	识别文本
isEndpoint	bool	是否为端点（VAD 段结束）
isFinal	bool	是否为最终结果

UI 组件

提供类似微信语音输入的交互组件。

VoiceRecordButton — 长按录音按钮

VoiceRecordButton(
  themeColor: Colors.blue,
  maxDuration: 10,
  onResult: (text) => print('识别结果: $text'),
  onPartialResult: (text) => print('中间结果: $text'),
  onError: (msg) => print('错误: $msg'),
)

参数	类型	默认值	说明
onResult	Function(String)?	—	最终识别结果回调
onPartialResult	Function(String)?	—	实时中间结果回调
onRecordingStateChanged	Function(bool)?	—	录音状态变化回调
onError	Function(String)?	—	错误回调
themeColor	Color?	Colors.blue	按钮主题色
size	double	64	按钮大小
maxDuration	int	10	最大录音时长（秒）
showDuration	bool	true	是否显示录音计时
showRipple	bool	true	是否显示波纹动画
enableHaptic	bool	true	是否启用触感反馈
useGlobalService	bool	true	是否使用 AsrRegistry 全局服务

showVoiceRecordOverlay — 全屏录音弹窗

final result = await showVoiceRecordOverlay(
  context: context,
  themeColor: Theme.of(context).primaryColor,
  maxDuration: 10,
);
if (result != null && result.isNotEmpty) {
  // 使用识别结果
}

包含：音量圆环指示器、波形显示、实时结果预览、取消/完成按钮。

动画组件

组件	说明
PulseAnimation	脉冲呼吸缩放动画
RippleAnimation	波纹扩散动画（同心圆环）
SoundLevelIndicator	音量圆环指示器
WaveformDisplay	动态波形显示条

完整使用示例

详见 example/example.md。

Dependencies

Package	Version	Purpose
sherpa_onnx	^1.13.2	ONNX inference engine
record	^6.0.0	Audio capture (mic → PCM16)
path_provider	^2.1.3	App document directories
permission_handler	^12.0.1	Microphone permissions
lpinyin	^2.0.3	Pinyin text correction

Commands

# Get dependencies
flutter pub get
# Analyze
flutter analyze
# Run tests
flutter test
# Publish to pub.dev
flutter pub publish

License

Apache 2.0 — see LICENSE for details.