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 |
动态波形显示条 |
完整使用示例
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.