asr_lib 0.1.0

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

sherpa-asr

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

Platform	Support
Android	✅ arm64-v8a (minSdk 24)
iOS	❌ (planned)

Model Support

Model	Status
funasr-nano	✅ Default
SenseVoice	✅ Supported (model switching not yet exposed — coming soon)

当前仅支持 funasr-nano 和 SenseVoice 两类 ASR 模型，默认使用 funasr-nano。 因此只下载两个文件：model.int8.onnx + tokens.txt。 后续会增加可选模型切换接口，支持在不同场景下选择 funasr-nano 或 SenseVoice 等模型。

Features

• On-device inference — no network needed after model download
• Dual mode — streaming (ONLINE) and full-utterance (OFFLINE) recognition
• Voice Activity Detection — Silero VAD for automatic speech segment detection
• Audio recording — built-in mic capture via Android AudioRecord
• Model auto-download — downloads funasr-nano model from ModelScope

Requirements

• Android SDK 24+ (minSdk 24)
• ARM64-v8a (only supported ABI)
• Permissions: RECORD_AUDIO, INTERNET, ACCESS_NETWORK_STATE

Usage

Flutter

import 'package:sherpa_asr/asr_lib.dart';

final asr = AsrLib();

// Listen to state changes
asr.stateStream.listen((state) {
  print('State: $state');
});

// Listen to recognition results
asr.resultStream.listen((result) {
  print('Recognized: ${result.text}');
});

// Initialize (downloads & loads model on first run)
await asr.initialize();

// Start recording with VAD
asr.startRecording();

// Stop
asr.stopRecording();

// Release
asr.release();

Kotlin (Native Android via AAR)

val context: Context = // your Android context
val engine = AsrEngine(context)

scope.launch {
    engine.result.collect { result ->
        Log.d("ASR", "Recognized: ${result.text}")
    }
}

engine.initialize()
engine.startRecording()
engine.stopRecording()
engine.release()

Configuration

val config = AsrConfig(
    sampleRate = 16000,
    enableVad = true,
    asrMode = AsrMode.ONLINE, // or OFFLINE
    decodingMethod = "greedy_search",
    numThreads = 2
)
val engine = AsrEngine(context, config)

Build

Flutter Plugin (recommended)

flutter pub get
cd example && flutter build apk

AAR (for native Android apps)

cd android
./gradlew assembleRelease

Output: android/build/outputs/aar/sherpa_asr-release.aar

Then add the AAR to your native Android project:

// app/build.gradle
dependencies {
    implementation files('libs/sherpa_asr-release.aar')
}

Verify & Publish

Local Verification

Before publishing, verify the plugin locally:

# 1. Get dependencies
flutter pub get

# 2. Analyze Dart code
flutter analyze

# 3. Simulate publish (checks for missing files, metadata issues)
flutter pub publish --dry-run

# 4. Build the example app (ensures Android native code compiles)
cd example && flutter build apk --debug && cd ..

Pre-publish Checklist

File	Required	Status
README.md	✅	Done
LICENSE	✅	Apache 2.0
CHANGELOG.md	✅	Records version history
pubspec.yaml fields	✅	name, description, version, homepage
.gitignore	✅	Excludes build artifacts

Publishing to pub.dev

# 1. Log in (one-time)
dart pub token add https://pub.dev

# 2. Final dry-run
flutter pub publish --dry-run

# 3. Publish
flutter pub publish

After publishing, update the example app to reference the published version:

# example/pubspec.yaml
dependencies:
  sherpa_asr: ^0.1.0  # instead of path: ..

Versioning

Follow semantic versioning:

• Patch (0.1.1) — bug fixes
• Minor (0.2.0) — new features, backwards compatible
• Major (1.0.0) — breaking changes

Update the version in pubspec.yaml and the CHANGELOG.md before each release.

Project Structure

sherpa-asr/
├── pubspec.yaml              # Flutter plugin declaration
├── lib/
│   └── asr_lib.dart         # Dart client
├── android/
│   ├── build.gradle.kts      # Android library build config
│   ├── libs/
│   │   └── sherpa-onnx.aar   # Pre-built sherpa-onnx binary
│   ├── src/main/kotlin/
│   │   └── com/wuyang/asr_lib/asr/
│   │       ├── AsrEngine.kt      # Main orchestrator (state machine)
│   │       ├── AsrConfig.kt      # Configuration
│   │       ├── AsrState.kt       # Lifecycle state enum
│   │       ├── AsrResult.kt      # Recognition result
│   │       ├── SherpaAsr.kt      # sherpa-onnx Kotlin wrapper
│   │       ├── AudioRecorder.kt  # MIC audio capture
│   │       ├── VadHandler.kt     # Silero VAD wrapper
│   │       ├── ModelDownloader.kt # HTTP model downloader
│   │       └── AsrPlugin.kt      # Flutter plugin bridge
│   └── proguard-rules.pro
├── example/
│   ├── pubspec.yaml
│   └── lib/main.dart         # Example Flutter app
└── AGENTS.md

Model

The library uses the funasr-nano pipeline model, auto-downloaded on first use from ModelScope:

• model.int8.onnx — quantized ONNX model
• tokens.txt — token vocabulary

Default download URLs point to wuyangwang/funasr-nano on ModelScope. Override via AsrConfig.downloadUrls for custom model sources.

License

Apache 2.0 — see LICENSE for details.