Xime 输入法

Appearance

语音转文本 ​

Xime 内置语音转文本功能，支持通过麦克风进行实时语音识别，将语音转换为文字输入。

权限声明

使用语音转文本功能需要以下权限：

  • 录音权限（必需） - 所有语音识别场景都需要麦克风权限来录制语音
  • 网络权限（在线模式必需） - 使用阿里百炼在线 API 时需要网络连接
  • 存储权限（本地模式可选） - 本地模型需要存储空间保存模型文件

首次使用时，系统会请求麦克风权限，请务必点击「允许」。如果拒绝权限，语音功能将无法使用。

功能定位

Xime 的语音转文本功能定位为基础可用级别，旨在提供离线可用、隐私安全的语音输入选项。

如果您追求更高的识别准确率、更快的响应速度或更丰富的功能（如语音命令、多语言混合识别等），建议使用商业输入法（如讯飞、百度、搜狗等）。这些商业产品依托强大的云端服务和长期积累的语音数据，能提供更优质的语音识别体验。

Xime 的语音功能适合以下场景：

  • 注重隐私，不愿语音数据上传到第三方
  • 无网络环境下的离线使用
  • 对识别准确率要求不高的简单输入场景

功能特点 ​

  • 双引擎支持 - 支持在线 API 和本地离线模型两种方式
  • 实时识别 - 边说边识别，无需等待录音结束
  • 流式输出 - 识别结果实时显示，支持部分结果展示
  • 音量可视化 - 显示麦克风音量波动
  • 离线可用 - 本地模型无需网络，隐私安全
  • 预缓冲机制 - 按住空格键时立即开始录音，缓存音频数据，防止语音丢失（吃字）
  • STT 开关 - 可在设置中启用或禁用语音转文字功能，禁用后长按空格键输出连续空格 │ │ │ ──────────── 统一输出接口 ──────────── │ │ │ │ │ ▼ │ │ ┌─────────────────────────┐ │ │ │ 标点预测 (可选) │ │ │ │ Transformer 模型 │ │ │ └─────────────────────────┘ │ │ │ │ │ ▼ │ │ 带标点的文本 │ └─────────────────────────────────────────────────────────────┘

## 引擎选择

Xime 提供两种语音识别引擎，用户可根据使用场景灵活切换：

### 对比

| 对比项 | 阿里百炼 FunAsr（在线） | Sherpa ONNX（本地） |
|--------|------------------------|---------------------|
| **运行方式** | 云端 API | 本地推理 |
| **网络需求** | 必须联网 | 无需网络（下载后） |
| **准确率** | 高（云端大模型） | 中等（本地小模型） |
| **标点支持** | 自带标点 | 需额外模型 |
| **延迟** | 低（WebSocket 流式） | 低（本地推理） |
| **隐私** | 语音上传云端 | 完全本地处理 |
| **费用** | 需要 API Key（有免费额度） | 完全免费 |
| **存储空间** | 无需存储 | 13-36 MB（模型文件） |
| **初始化** | 无需等待 | 首次需加载模型 |

### 使用场景推荐

| 场景 | 推荐引擎 | 原因 |
|------|----------|------|
| WiFi 环境、日常使用 | 在线 ASR | 高准确率、自带标点 |
| 无网络环境（地铁、飞行） | 本地模型 | 离线可用 |
| 隐私敏感内容（密码、私密信息） | 本地模型 | 数据不上传 |
| 长时间语音输入 | 在线 ASR | 无内存压力 |
| 弱网环境 | 本地模型 | 避免网络延迟 |

### 如何切换

在「设置 → 语音转文本」中切换「使用本地模型」开关：
- **关闭**：使用阿里百炼在线 API
- **开启**：使用本地 Sherpa ONNX 模型（需先下载模型）

## 在线 API 配置（阿里百炼 FunAsr）

### 获取 API Key

1. 访问 [阿里云百炼平台](https://help.aliyun.com/zh/model-studio/get-api-key)
2. 登录/注册阿里云账号
3. 在模型广场获取 API Key

### 配置步骤

1. 进入输入法设置页面
2. 点击「语音转文本」设置
3. 选择「在线 ASR」标签页
4. 点击「阿里百炼 FunAsr」进入详细设置
5. 将 API Key 粘贴到输入框
6. 点击保存按钮保存设置
7. 授予麦克风权限

### 特点

- 自带标点符号，无需额外处理
- 实时流式识别，响应速度快
- 支持多种音频格式
- 高准确率

## 本地模型配置（Sherpa ONNX）

### 可用模型

| 模型 | 大小 | 架构 | 特点 | 推荐场景 |
|------|------|------|------|----------|
| 中文多方言 CTC int8 | 13 MB | CTC | 支持多种中文方言，int8 量化 | 快速识别，存储空间有限 |
| 中文 Zipformer int8 | 36 MB | Zipformer Transducer | 适合实时语音识别，int8 量化 | 日常使用，识别精度与速度均衡 |

### 模型下载

1. 进入「设置 → 语音转文本」
2. 选择「本地模型」标签页
3. 点击模型卡片上的「下载」按钮
4. 等待下载完成
5. 点击「使用」按钮选择该模型

### 模型管理

- **下载模型**：点击下载按钮，等待进度条完成
- **切换模型**：点击「使用」按钮切换到已下载的模型
- **删除模型**：点击「删除」按钮释放存储空间
- **保持常驻内存**：开启后模型保持加载状态，后续启动更快（可选）

### 特点

- 完全离线运行，无需网络
- 隐私安全，语音数据不上传
- 支持多种模型选择

## 标点预测模型

Xime 支持标点预测功能，可在语音识别结果中添加标点符号。

### 模型来源

标点预测模型基于 Transformer 架构训练，项目地址：
[https://github.com/ximeiorg/srf-punctuation](https://github.com/ximeiorg/srf-punctuation)

### 启用方法

1. 进入「设置 → 语音转文本」
2. 在「标点预测模型」区域点击下载模型
3. 下载完成后开启「启用标点预测」开关

### 技术参数

- **模型**：Transformer 标点预测模型
- **量化**：int8 量化
- **输入**：中文文本
- **输出**：带标点符号的文本
- **支持标点**：逗号、句号、问号、感叹号

## 使用方法

### 启用语音功能

在「设置 → 语音转文本」中开启语音转文字开关。如果关闭该开关，长按空格键将不会进入语音模式，而是连续输出空格字符。

### 启动语音输入

1. 在输入状态下，**长按空格键**进入语音模式
2. 或点击键盘上的麦克风图标
3. 开始说话，识别结果会实时显示

> **预缓冲机制**：长按空格键时，系统会立即开始录音并缓存音频数据，避免因录音启动延迟导致的语音丢失（吃字）。松开空格键后，缓存的音频会与后续录音一起发送给识别引擎。

### 结束语音输入

- 松开空格键：提交识别结果
- 点击发送按钮：提交结果并关闭语音模式
- 点击取消按钮：放弃结果并关闭语音模式

## 权限要求

语音转文本功能需要以下权限：

| 权限 | 用途 | 必需场景 | 如何授予 |
|------|------|----------|----------|
| 麦克风（RECORD_AUDIO） | 录制语音用于识别 | **所有场景必需** | 首次使用时弹窗请求，点击「允许」 |
| 网络（INTERNET） | 连接阿里云服务进行识别 | 仅在线 API 模式 | 应用安装时自动授予 |
| 存储（WRITE_EXTERNAL_STORAGE） | 存储本地模型文件 | 仅本地模型（可选） | 应用安装时自动授予 |

### 权限检查

如果语音功能无法使用，请检查权限设置：

1. 进入「系统设置 → 应用 → Xime → 权限」
2. 确保「麦克风」权限已开启
3. 在线模式还需确保网络连接正常

::: tip 提示
- 拒绝麦克风权限后，语音功能将完全无法使用
- 可以在系统设置中重新授予麦克风权限
- 本地模型下载完成后可完全离线使用
:::

## 技术细节

### 在线 API 技术参数

- **服务商**：阿里云百炼平台
- **模型**：fun-asr-realtime（实时语音识别）
- **协议**：WebSocket 实时通信
- **采样率**：16000 Hz
- **格式**：PCM 16-bit 单声道

### 本地模型技术参数

- **引擎**：Sherpa ONNX（基于 k2-fsa）
- **架构**：Zipformer / CTC
- **量化**：int8 量化，减少模型大小
- **采样率**：16000 Hz
- **格式**：PCM 16-bit 单声道

### 相关文件

| 文件 | 说明 |
|------|------|
| `SpeechRecognitionManager.kt` | 语音识别管理器 |
| `FunAsrWebSocketManager.kt` | FunAsr WebSocket 连接管理 |
| `FunAsrAsrBackend.kt` | FunAsr 后端实现 |
| `SherpaAsrEngine.kt` | Sherpa 本地引擎 |
| `SherpaAsrBackend.kt` | Sherpa 后端实现 |
| `ModelDownloadManager.kt` | 模型下载管理 |
| `VoiceRecognitionHandler.kt` | 语音识别 UI 处理 |
| `VoiceKeyboardLayout.kt` | 语音模式键盘布局 |
| `PunctuationInference.kt` | 标点预测推理引擎 |
| `PunctuationModelManager.kt` | 标点预测模型下载管理 |

### 相关项目

| 项目 | 说明 |
|------|------|
| [srf-punctuation](https://github.com/ximeiorg/srf-punctuation) | 标点预测模型训练与导出 |
| [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) | 本地 ASR 引擎 |

### 识别状态

```kotlin
enum class RecognitionState {
    IDLE,        // 空闲
    LISTENING,   // 正在监听
    PROCESSING,  // 处理中
    ERROR        // 错误
}

常见问题 ​

Q: 语音识别无反应？ ​

检查以下几点：

  1. 是否已授予麦克风权限
  2. API Key 是否正确配置（在线模式）
  3. 模型是否已下载并选择（本地模式）
  4. 网络连接是否正常（在线模式）

Q: 本地模型初始化失败？ ​

检查以下几点：

  1. 模型是否已完全下载
  2. 模型文件是否完整（可能需要重新下载）
  3. 是否已编译 Sherpa ONNX JNI 库

Q: 识别准确率低？ ​

  1. 确保在安静环境下使用
  2. 说话清晰，语速适中
  3. 麦克风没有被遮挡
  4. 本地模式可尝试使用更大的模型

Q: 连接失败？ ​

在线模式：

  1. 检查网络连接
  2. 确认 API Key 有效
  3. 稍后重试，可能是服务端临时故障

本地模式：

  1. 确认模型已下载
  2. 尝试重新选择模型

Q: 本地模型占用多少存储空间？ ​

根据选择的模型不同：

  • 小模型：约 13 MB
  • 中等模型：约 259 MB
  • 大模型：约 590 MB

建议优先使用 int8 量化模型以节省空间。

注意事项 ​

在线 API ​

  • 语音识别需要联网使用
  • API Key 请妥善保管，不要泄露
  • 语音数据会上传至阿里云进行处理
  • 建议在 WiFi 环境下使用，避免消耗移动数据流量

本地模型 ​

  • 模型下载需要网络连接
  • 首次使用需要下载模型（建议在 WiFi 环境下载）
  • 下载后可完全离线使用
  • 模型存储在应用内部存储空间，卸载应用会删除
  • 「保持模型常驻内存」会占用更多内存，但启动更快

构建本地引擎 ​

如需使用本地模型，需要先编译 Sherpa ONNX JNI 库：

powershell
# 运行构建脚本
.\build-sherpa-onnx.ps1

构建完成后，重新编译应用即可使用本地模型功能。

基于 GPLv3 许可发布

Copyright © 2024 Xime