---
url: https://www.dreamlu.net/mica-voice.md
---

# mica-voice

[![Java CI](https://github.com/lets-mica/mica-voice/actions/workflows/test-and-build.yml/badge.svg)](https://github.com/lets-mica/mica-voice/actions/workflows/test-and-build.yml)
![JDK 8+](https://img.shields.io/badge/JDK-8+-informational)
[![Maven release](https://img.shields.io/maven-central/v/net.dreamlu/mica-voice-core.svg?style=flat-square)](https://central.sonatype.com/artifact/net.dreamlu/mica-voice-core/versions)

> Java 生态的声音 AI 全家桶：ASR / TTS / 声纹 / VAD / 说话人分离 / 降噪 / KWS。
>
> 基于 [`mica-sherpa-onnx`](https://github.com/lets-mica/mica-sherpa-onnx)（已发布 Maven Central 的 sherpa-onnx 全平台 fat jar）。

`mica-voice` 把语音能力封装成统一门面：纯 Java 用 `MicaVoice` 一行拿到服务，Spring Boot / Solon 用同一套 `mica.voice.*` 配置树自动装配。

## 📦 模块导航

| 模块 | 作用 |
| ---- | ---- |
| `mica-voice-core` | **核心 SDK**（纯 Java）。统一 ASR / TTS / 声纹 / VAD 等 API，强依赖 `mica-sherpa-onnx` |
| `mica-voice-spring-boot-starter` | **Spring Boot 自动装配**。`mica.voice.*` 配置即开箱即用，注入 9 个 Service Bean |
| `mica-voice-solon-plugin` | **Solon 自动装配插件**。同样的配置树，一行接入 Solon 应用（JDK 8 ~ 26） |
| `mica-voice-examples` | **集成示例聚合**，展示真实业务场景下怎么用 |

### `mica-voice-examples` 子模块

| 子模块 | 作用 |
| ------ | ---- |
| `mica-voice-example-console` | 纯 Java main 示例：命令行测 ASR / SenseVoice / X-ASR / TTS / 声纹 / VAD / 分离 / KWS / 降噪 |
| `mica-voice-example-spring-web` | Spring Boot Web 示例：REST 做 ASR、TTS、声纹注册/验证，**浏览器麦克风 → WebSocket → 流式 ASR** |
| `mica-voice-example-solon-web` | Solon Web 示例：REST 做 ASR、TTS、声纹注册/验证（默认端口 8081） |

## ✨ 能力一览

`MicaVoice` 门面一行拿到对应服务（均实现 `AutoCloseable`，强烈建议 try-with-resources）：

| 能力 | 门面方法 | 配置文件 |
| ---- | -------- | -------- |
| 离线 ASR | `MicaVoice.asr(props, AsrConfig)` | `AsrConfig` |
| 在线流式 ASR | `MicaVoice.onlineAsr(props, OnlineAsrConfig)` | `OnlineAsrConfig` |
| 语音合成 TTS | `MicaVoice.tts(props, TtsConfig)` | `TtsConfig` |
| 声纹识别 | `MicaVoice.speaker(props, SpeakerConfig)` | `SpeakerConfig` |
| 语音活动检测 VAD | `MicaVoice.vad(props, VadConfig)` | `VadConfig` |
| 说话人分离 | `MicaVoice.diarization(props, DiarizationConfig)` | `DiarizationConfig` |
| 关键词唤醒 KWS | `MicaVoice.kws(props, KwsConfig)` | `KwsConfig` |
| 音频降噪 | `MicaVoice.denoise(props, DenoiseConfig)` | `DenoiseConfig` |
| 分离 + 转写 | `MicaVoice.transcribe(diarizationService, asrService)` | 组合 `DiarizationConfig` + `AsrConfig` |

Starter / Solon 插件自动装配同款 **9 个 Service Bean**：`OfflineAsrService` / `OnlineAsrService` / `TtsService` / `SpeakerService` / `VadService` / `DiarizationService` / `KwsService` / `DenoiseService` / `OfflineDiarizationTranscribeService`。

## 🚀 快速开始

### 1️⃣ 添加依赖

```xml
<!-- 纯 Java（非 Spring / Solon 项目） -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-voice-core</artifactId>
    <version>${mica-voice.version}</version>
</dependency>

<!-- Spring Boot -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-voice-spring-boot-starter</artifactId>
    <version>${mica-voice.version}</version>
</dependency>

<!-- Solon -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-voice-solon-plugin</artifactId>
    <version>${mica-voice.version}</version>
</dependency>
```

### 2️⃣ 准备模型

模型不随 jar 分发（体积大），按需下载到 `models/` 目录（默认从当前目录 `models/` 加载，也可用 `-Dmica.voice.models-dir=E:/.../models` 指定绝对路径）：

```bash
# Linux / macOS
bash models/scripts/download-models.sh asr          # 按需换 tts / speaker / asr-online / x-asr / all
bash models/scripts/parallel-download.sh all        # 并行下载，适合 all 全量时加速

# Windows（任选其一）
models\scripts\download-models.bat asr              # CMD
powershell -ExecutionPolicy Bypass -File models\scripts\download-models.ps1 asr   # PowerShell
```

> 完整 target 清单见仓库 `models/README.md`。VAD / 说话人分离 / KWS / 降噪模型暂无下载脚本 target，需自行从 sherpa-onnx release 下载到 `models/` 根目录。

### 3️⃣ 纯 Java：门面一行调用

```java
MicaVoiceConfig props = MicaVoiceConfig.builder()
    .modelsDir("models")
    .threads(2)
    .build();
AsrConfig config = AsrConfig.builder()
    .modelDirName("sherpa-onnx-paraformer-zh-small-2024-03-09")
    .modelType(AsrConfig.ModelType.PARAFORMER)
    .build();

try (AsrService svc = MicaVoice.asr(props, config)) {
    AsrResult result = svc.recognize(new File("test.wav"));
    System.out.println("识别结果: " + result.getText());
}
```

### 4️⃣ Spring Boot：注入即用

```yaml
mica:
  voice:
    models-dir: ./models
    asr:
      offline:
        enabled: true
        model-dir-name: sherpa-onnx-paraformer-zh-small-2024-03-09
        model-type: PARAFORMER
    tts:
      enabled: true
      model-dir-name: vits-icefall-zh-aishell3
      model-type: VITS
```

```java
@RestController
public class AsrController {

    private final OfflineAsrService offlineAsrService;

    public AsrController(OfflineAsrService offlineAsrService) {
        this.offlineAsrService = offlineAsrService;
    }

    @PostMapping("/asr")
    public String asr(@RequestParam("file") MultipartFile file) throws IOException {
        File tmp = File.createTempFile("asr", ".wav");
        file.transferTo(tmp);
        try {
            return offlineAsrService.recognize(tmp).getText();
        } finally {
            tmp.delete();
        }
    }
}
```

> **说明**：ASR 两个 Bean 不再注册为统一的 `AsrService` 接口类型，而是按具体类型 `OfflineAsrService` / `OnlineAsrService` 暴露，避免 Spring 容器同接口多 Bean 时的注入歧义。

### 5️⃣ Solon：注入即用

Solon 项目引入 `mica-voice-solon-plugin` 后，`app.yml` 里使用**与 Spring Boot 完全相同的 `mica.voice.*` 配置树**，自动装配同款 9 个 Service Bean：

```java
@Controller
public class AsrController {

    @Inject
    private OfflineAsrService offlineAsrService;

    @PostMapping("/asr")
    public String asr(@Body MultipartFile file) throws IOException {
        File tmp = File.createTempFile("asr", ".wav");
        file.transferTo(tmp);
        try {
            return offlineAsrService.recognize(tmp).getText();
        } finally {
            tmp.delete();
        }
    }
}
```

> 全部可配置字段（含各能力的 `enabled` / 模型名 / 阈值 / 端点规则等）与完整 Solon 示例，见仓库 README 的配置章节与 `mica-voice-examples/mica-voice-example-solon-web`。

## 🔗 关联项目

* [lets-mica/mica-sherpa-onnx](https://github.com/lets-mica/mica-sherpa-onnx) — sherpa-onnx 全平台 fat jar，本项目的 native 依赖来源
* [k2-fsa/sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) — 上游 ONNX 推理引擎与模型

## 📄 License

Apache License 2.0