mica-voice 1.0.2 공개, Java 음성 AI 통합 패키지

一、프로젝트 소개

mica-voice는 mica-sherpa-onnx(Maven Central에 이미 배포된 sherpa-onnx 전 플랫폼 fat jar) 기반의 Java 음성 AI 풀 패키지로, ASR(음성 인식) / TTS(음성 합성) / 성문 인식 / VAD(음성 활동 감지) / 화자 분리 / 키워드 웨이크업 KWS / 오디오 노이즈 제거 등 7대 기능을 통합封装하여, 순수 Java 파사드, Spring Boot Starter, Solon Plugin과 함께 제공되는 예제 프로젝트를 제공하며, JDK 8 / 17 / 21 / 25와 호환되고 모델은 필요에 따라 다운로드하여 바로 사용할 수 있다. Apache2.0 오픈소스 라이선스.

二、이번 업데이트: v1.0.2(2026-09-03)

신규 기능

스트리밍 TTS 연동 실전: mica-voice-example-spring-web에 스트리밍 TTS WebSocket 예제를 추가했으며, 프런트엔드가 /mica/voice/ws/streaming-tts를 구독하면 서버가 100ms 단위로 슬라이스하여 PCM을 푸시하고, callback-sample-step과 함께 합성과 재생을 동시에 수행하여 첫 글자 지연을 낮춘다.

빌드 / 의존성

하부 native 의존성 mica-sherpa-onnx를 1.13.7로 업그레이드하고, 여러 JNI 호환성 문제를 함께 수정했다.

三、이전 업데이트

v1.0.1(2026-08-21)

mica-voice-core에 창 이동 비율(window-shift-ratio) 설정을 추가하고 화자 분리 서비스에 통합하여 오디오 창 슬라이딩 유연성을 향상시켰다.

각 Service Bean과 설정 클래스의 JavaDoc 주석을 보충하여 IDE 힌트와 유지보수성이 더욱 편리해졌다.

문제 수정

키워드 웨이크업 KWS: 키워드 인식 결과 처리 로직을 최적화하여 빈 결과나 비정상 출력을 방지했다(커뮤니티 @yaochao 피드백, Gitee Issue #IK9TAJ 감사).

키워드 웨이크업 KWS: KWS 모델 디렉터리 이름을 sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01로 수정하여 sherpa-onnx 공식 명명과 일치시켰다.

문서

메인 README를 다시 작성하고, mica-voice-examples 하위 모듈 설명을 개선했으며, starter 자동 구성 클래스의 중복 설명을 삭제했다.

하부 native 의존성 mica-sherpa-onnx를 1.13.6으로 업그레이드했다.

v1.0.0(2026-08-15) 최초 출시

mica-voice-core 핵심 SDK: 통합 음성 AI 파사드 MicaVoice로, 한 줄 호출만으로 오프라인 ASR, 온라인 스트리밍 ASR, TTS, 성문, VAD, 화자 분리, KWS, 오디오 노이즈 제거 등의 서비스를 얻을 수 있다(모두 AutoCloseable 구현).

오프라인 ASR: Paraformer / SenseVoice / Whisper / Moonshine / Zipformer / NeMo CTC 등 모델 패밀리를 지원하며, SenseVoice는 중 / 영 / 일 / 한 / 광둥어 다국어 인식과 역텍스트 정규화(숫자, 문장부호 복원)를 지원한다.

온라인 스트리밍 ASR: Streaming Paraformer와 X-ASR(Zipformer Transducer, 960ms 청크)을 지원하며, 엔드포인트 감지 규칙(문장 끝 무음 시 자동 종료)을 설정할 수 있다.

음성 합성 TTS: VITS 기반으로, 다화자 모델과 중영 혼합 모델(vits-melo-tts-zh_en)을 지원한다.

성문 인식: 등록 / 검증 / 검색, 3D-Speaker / eres2net 등 임베딩 모델을 지원하며 유사도 임계값을 조정할 수 있다.

화자 분리 + 전사 조합 서비스: "누가 언제 무엇을 말했는지"를 자동 출력한다.

mica-voice-spring-boot-starter: mica.voice.* 설정을 바로 사용할 수 있으며, 9개의 Service Bean(OfflineAsrService / OnlineAsrService / TtsService / SpeakerService / VadService / DiarizationService / KwsService / DenoiseService / OfflineDiarizationTranscribeService)을 자동 구성하고, 애플리케이션 종료 시 native 리소스를 일괄 해제한다.

mica-voice-solon-plugin: Spring Boot와 완전히 동일한 설정 트리로, 한 줄로 Solon 애플리케이션에 연동한다(JDK 8 ~ 26).

mica-voice-examples 통합 예제: 순수 Java 콘솔, Spring Boot Web(REST + 브라우저 마이크 → WebSocket 스트리밍 ASR), Solon Web.

모델 다운로드 스크립트: Linux / macOS / Windows를 지원하며, 다중 병렬 다운로드 + Range 이어받기를 지원한다.

mica-sherpa-onnx 1.13.5(전 플랫폼 native fat jar) 기반이며, JDK 8 / 17 / 21 / 25와 호환된다.

四、모듈 구조

모듈

역할

mica-voice-core

핵심 SDK(순수 Java), ASR / TTS / 성문 / VAD 등 API를 통합하며, mica-sherpa-onnx에 강하게 의존

mica-voice-spring-boot-starter

Spring Boot 자동 구성, mica.voice.* 설정으로 바로 사용 가능

mica-voice-solon-plugin

Solon 자동 구성 플러그인, 동일한 설정 트리로 한 줄로 Solon 애플리케이션에 연동

mica-voice-examples

통합 예제 집합, console / spring-web / solon-web 세 가지 프로젝트 포함

五、30초 시작하기

Maven 의존성

net.dreamlu mica-voice-core 1.0.2

Spring Boot 프로젝트는 mica-voice-spring-boot-starter로, Solon 프로젝트는 mica-voice-solon-plugin으로 교체하며 버전은 동일하다.

한 줄 ASR

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)) { System.out.println(svc.recognize(new File("test.wav")).getText()); }

Spring Boot 주입

mica: voice: asr: offline: model-dir-name: sherpa-onnx-paraformer-zh-small-2024-03-09 model-type: PARAFORMER

@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(); } } }

六、모델 준비

모델은 jar에 함께 배포되지 않으므로(용량이 큼), 필요에 따라 models/ 디렉터리에 다운로드한다(-Dmica.voice.models-dir=E:/.../models로 절대 경로를 지정할 수도 있다):

Linux / macOS bash models/scripts/download-models.sh asr # 필요에 따라 tts / speaker / asr-online / x-asr / all로 변경 bash models/scripts/parallel-download.sh all # 병렬 다운로드, 전체 다운로드 시 속도 향상에 적합 # Windows models\scripts\download-models.bat asr # CMD powershell -ExecutionPolicy Bypass -File models\scripts\download-models.ps1 asr # PowerShell

모델은 콰크网盘에도 업로드되어 있다: https://pan.quark.cn/s/d2da0116a472?pwd=kc5e 추출 코드: kc5e