Mirage ASR

Mirage ASR 是一个面向中文场景的本地离线语音听写插件。

通过麦克风进行实时语音识别，并将识别结果直接插入当前编辑器光标位置。

语音识别、VAD 和标点恢复均在本机执行，不上传麦克风音频，不需要 API Key，也不依赖云端 ASR 服务。

核心 ASR runtime rasr 使用 Rust 实现，并基于 sherpa-onnx 与 ONNX Runtime 运行。

项目源码、CLI、模型管理、VS Code 插件以及发布构建均维护在同一仓库中：

GitHub — limeng32/mirage-asr

下载与安装

推荐直接从扩展市场安装 Mirage ASR：

也可以从 GitHub Releases 下载与你的平台匹配的 VSIX，然后在 VS Code / 兼容编辑器中选择：

Extensions
→ ...
→ Install from VSIX...

当前提供以下平台的原生 VSIX：

macOS Apple Silicon (darwin-arm64)
macOS Intel (darwin-x64)
Windows x64 (win32-x64)

快速开始

安装 Mirage ASR 后，VS Code 状态栏会出现两个操作入口：

左侧按钮：开始 / 停止实时听写
右侧按钮：打开模型管理器

将光标放到任意可编辑文本位置，然后点击左侧按钮开始说话。

识别结果会持续插入当前编辑器光标位置。

再次点击听写按钮即可停止。

模型管理

点击状态栏右侧按钮，可以打开 Mirage ASR 模型管理器：

模型管理器支持：

查看当前 ASR 模型
查看模型安装状态
下载推荐模型
取消正在进行的模型下载
加载 / 卸载当前 ASR 模型
删除用户下载的模型
查看模型磁盘占用
设置模型推理线程核数
修改本地模型目录

模型安装状态、当前模型和推理配置均由 Rust runtime rasr 统一管理，VS Code 插件本身只负责界面和编辑器集成。

主要特性

本地离线语音识别

ASR 推理完全在本机完成。

麦克风音频不会上传到云端语音识别服务。

安装所需模型后，可以在断网环境下继续使用。

实时麦克风听写

支持持续监听麦克风，并将识别结果直接写入当前编辑器。

适用于：

编写文档
写 Markdown
记录笔记
输入注释
编写 Prompt
日常文本输入

流式与非流式模型

Mirage ASR 同时支持 Streaming 和 Offline ASR 模型。

Streaming Zipformer

使用 OnlineRecognizer 进行真正的增量流式识别，可以在说话过程中持续产生识别结果。

Paraformer / SenseVoice

通过 Silero VAD 检测语音片段，然后交给 OfflineRecognizer 进行识别。

因此不同类型的模型可以根据准确率、资源占用和响应速度进行选择。

VAD 语音端点检测

内置 Silero VAD，用于检测语音开始与结束。

对于非流式模型，VAD 会自动将连续麦克风输入划分为适合识别的语音片段。

标点恢复

内置 CT-Transformer Punctuation 模型。

可以对识别结果进行中英文标点恢复，使连续听写结果更适合直接用于文档和日常文本输入。

本地模型管理

除默认内置模型之外，还可以通过模型管理器下载更大的 ASR 模型。

不同模型可以拥有独立的推理线程核数配置。

安装即可使用

Mirage ASR 的 VSIX 已内置基础听写所需要的三个模型：

模型	用途
Streaming Zipformer zh-14M	默认中文实时流式 ASR
Silero VAD	语音端点检测
CT-Transformer Punctuation	中英文标点恢复

因此，安装插件后即可进行基础离线听写，不要求首次启动时再下载大型 ASR 模型。

默认 ASR 模型：

streaming-zipformer-ctc-zh-14m

如果希望获得更高的识别效果，可以在模型管理器中继续下载 Paraformer、SenseVoice 或更大的 Streaming Zipformer 模型。

VS Code 命令

可以通过 Command Palette 执行以下命令：

命令	作用
`Mirage: 开始听写`	启动实时麦克风听写
`Mirage: 停止听写`	停止当前听写
`Mirage: 切换听写`	在开始 / 停止之间切换
`Mirage: 管理模型`	打开模型管理器

也可以直接使用状态栏按钮完成最常见的操作。

支持平台

当前提供以下平台的原生 VSIX：

平台	支持状态
macOS Apple Silicon	✅
macOS Intel	✅
Windows x64	✅
Windows ARM64	暂不支持
Linux	暂不提供预编译 VSIX

Mirage ASR 包含原生 Rust runtime，因此不同平台使用不同的 VSIX。

请安装与你当前操作系统和 CPU 架构匹配的版本。

模型下载

插件内置的基础模型无需额外下载。

下载其它模型时需要网络连接。

当前模型下载由 rasr 负责，并使用系统 curl。

如果模型下载失败，请确认终端可以正常执行：

curl --version

模型下载完成后，ASR 推理仍然在本地执行。

本地数据

用户下载的模型与 Mirage ASR 状态文件保存在本机。

macOS

默认位置：

~/.local/share/mirage-asr/

主要结构：

mirage-asr/
├── state.json
├── downloads.json
└── models/

Windows

默认位置：

%LOCALAPPDATA%\mirage-asr\

主要结构：

mirage-asr\
├── state.json
├── downloads.json
└── models\

隐私

Mirage ASR 的设计目标是尽可能在本地完成语音处理。

麦克风音频不会上传到云端 ASR 服务
ASR 推理在本机完成
VAD 在本机完成
标点恢复在本机完成
不需要 API Key
不依赖按调用次数或 Token 计费的云端语音识别服务
已安装模型后可以在断网环境下使用

后续计划

Mirage ASR 将继续完善本地语音输入体验，包括：

GPU 推理支持
本地录音文件转写功能
更多中文 Streaming ASR 模型
用户自定义模型
热词配置功能

CPU 推理将继续作为基础运行方式保留。

`rasr`

Mirage ASR 插件的核心语音识别能力由独立 Rust runtime rasr 提供。

VS Code
   │
   │ spawn
   ▼
mirage-asr extension
   │
   ▼
rasr
   │
   ├── ASR
   ├── VAD
   ├── Punctuation
   ├── Model Management
   └── Download Management

rasr 是独立运行的 Rust runtime，不依赖于 VS Code 插件。

构建 rasr

在仓库根目录执行：

cargo build --release

生成：

target/release/rasr

Windows 下为：

target\release\rasr.exe

开发阶段建议同时运行：

cargo test

项目设计

Mirage ASR 将 VS Code 插件保持为轻量 UI 层。

主要职责划分：

VS Code / TypeScript
├── 状态栏
├── 命令
├── 模型管理界面
├── 编辑器文本插入
└── 启动 rasr

rasr / Rust
├── ASR 推理
├── VAD
├── 标点恢复
├── 模型状态
├── 模型下载
├── 模型删除
├── 当前模型
└── 推理线程配置

模型和运行状态以 rasr 为事实来源，插件不会自行维护另一套 ASR 状态。

从源码构建

环境要求

建议准备以下开发环境：

Rust stable / Cargo
rustup
Node.js 22+
pnpm 10.2.1
curl
unzip

Windows 构建原生 runtime 时，需要可用的 MSVC Rust toolchain。

克隆仓库

git clone https://github.com/limeng32/mirage-asr.git
cd mirage-asr

构建 Rust runtime

cargo test
cargo build --release

安装 VS Code 插件依赖

cd vscode-extension

pnpm install --frozen-lockfile
pnpm compile

项目固定使用：

pnpm 10.2.1

构建平台 VSIX

仓库提供统一的平台打包脚本。

在仓库根目录执行：

macOS Apple Silicon：

bash vscode-extension/scripts/package-all.sh darwin-arm64

macOS Intel：

bash vscode-extension/scripts/package-all.sh darwin-x64

Windows x64：

bash vscode-extension/scripts/package-all.sh win32-x64

生成的 VSIX 文件名类似：

mirage-asr-darwin-arm64-<version>.vsix
mirage-asr-darwin-x64-<version>.vsix
mirage-asr-win32-x64-<version>.vsix

由于 Mirage ASR 包含原生 Rust runtime 和平台相关动态库，建议在对应操作系统上构建对应平台的正式发布包。

项目结构

.
├── Cargo.toml
├── Cargo.lock
├── README.md
├── LICENSE
├── media/
│   ├── asr_status_item_black.png
│   └── model_manager_black.png
│
├── src/
│   ├── main.rs
│   ├── cli.rs
│   ├── config.rs
│   ├── download.rs
│   ├── download_state.rs
│   ├── state.rs
│   ├── listen.rs
│   ├── transcribe.rs
│   ├── fs_util.rs
│   ├── asr/
│   ├── audio/
│   ├── models/
│   └── output/
│
└── vscode-extension/
    ├── src/
    ├── bin/
    ├── models/
    ├── licenses/
    ├── scripts/
    ├── THIRD_PARTY_MODELS.md
    ├── THIRD_PARTY_SOFTWARE.md
    ├── package.json
    └── pnpm-lock.yaml

问题反馈

如果遇到识别、模型下载、平台兼容或插件使用问题，可以在 GitHub 提交 Issue：

GitHub Issues

提交问题时建议附带：

操作系统
CPU 架构
Mirage ASR 版本
当前 ASR 模型
错误信息或日志

请不要在 Issue 中提交包含敏感信息的音频或日志内容。

第三方软件和模型

Mirage ASR 使用多个第三方开源软件和模型。

其中包括：

sherpa-onnx
ONNX Runtime
Silero VAD
Streaming Zipformer
CT-Transformer
其它相关 runtime 与模型组件

第三方组件和模型拥有各自独立的许可证。

详细信息请参见：

Mirage ASR 自身采用 Apache License 2.0，并不改变第三方模型和软件原有的许可证条件。

License

Mirage ASR source code is licensed under the Apache License 2.0.

See LICENSE.

Mirage ASR — Local speech recognition, directly inside your editor.