본문으로 건너뛰기
시골프로그래머의 블로그
블로그 메뉴

키를 누르고 말하면 커서 자리에 글자가 — UlanzeAgent

키를 누른 채 말하면 내 PC의 GPU에서 Whisper가 한국어를 받아 적어 커서 위치에 붙여 넣는 Windows용 음성 입력 도구입니다. Ulanzi AU05 키에 맞췄지만 일반 마이크와 키보드로도 씁니다.

풀빛컴퓨팅3분 읽기#오픈소스#Python#음성 인식#Whisper

Windows에는 Win+H로 여는 음성 입력이 들어 있습니다. 쓸 만하지만, 받아 적은 글을 손으로 고치는 일이 잦으면 결국 키보드로 돌아가게 됩니다. 개발 이야기처럼 "깃허브", "JSON", "마이그레이션" 같은 용어가 섞이는 말은 더 그렇습니다.

UlanzeAgent는 Windows 내장 음성 입력보다 인식률을 높이려고 만든 도구입니다. 키를 누르고 있는 동안 녹음하고, 키를 떼면 내 PC의 GPU에서 Whisper(large-v3-turbo, faster-whisper)가 한국어로 받아 적어 지금 커서가 있는 자리에 붙여 넣습니다.

Voice Key(F13) 누름 -> AU05 마이크 녹음 -> faster-whisper(CUDA) -> 용어 치환 -> Ctrl+V 붙여넣기

기본 설정은 Ulanzi AU05 Vibe Key의 음성 입력 버튼(F13을 보내도록 지정)과 AU05 마이크에 맞춰져 있습니다. 설정 파일에서 키와 마이크를 바꾸면 일반 마이크와 키보드로도 씁니다. 모델을 처음 내려받을 때만 인터넷이 필요하고, 그 뒤로는 오프라인으로 동작합니다.

Ulanzi Studio에서 키에 F13을 지정하는 화면

써 보기

uv가 Python 3.12와 라이브러리를 알아서 받아 줍니다.

cd app
uv sync
uv run stt.py

처음 실행하면 모델(약 1.6GB)을 Hugging Face에서 받습니다. 준비가 끝나면 트레이 아이콘이 초록(대기), 빨강(녹음 중), 주황(인식 중)으로 상태를 보여 줍니다. autostart.ps1로 로그인할 때 자동 실행되게 등록할 수 있습니다.

일반 키보드와 마이크로 쓰려면 config.toml을 이렇게 바꿉니다.

[hotkey]
key = "ctrl+win"        # 이 두 키를 누르고 있는 동안 녹음

[audio]
device = ""             # Windows 기본 마이크. 특정 마이크는 번호(2) 또는 이름 일부("Realtek")

인식률을 올리는 설정

설정 하는 일
whisper.initial_prompt 자주 쓰는 용어를 미리 알려 줌
replacements 인식 결과를 원하는 표기로 바꿈(예: "제이슨" → "JSON")
hallucinations.phrases 무음에서 Whisper가 지어내는 문장("시청해 주셔서 감사합니다" 등)을 버림
audio.preroll_ms 키를 누르기 직전 소리까지 넣어 첫 음절이 잘리지 않게 함

bench/ 폴더에는 내 마이크로 모델별 인식률과 지연 시간을 비교하는 벤치마크가 있습니다. 결과는 large-v3-turbo가 large-v3와 정확도가 같고 약 2.7배 빨랐고, 용어 힌트를 넣었을 때 글자 오류율(CER)이 12.2%에서 6.2%로 내려갔습니다. 10문장, 화자 한 명으로 잰 값이라 참고용입니다.

RTX 3090에서 잰 인식 지연은 평균 약 270ms, VRAM 사용량은 약 2.4GB입니다.

알아 둘 점

NVIDIA GPU가 필요합니다

기본 설정은 CUDA로 돌아갑니다. NVIDIA GPU(VRAM 여유 3GB 이상)와 CUDA 12를 지원하는 드라이버가 있어야 합니다. CPU로 돌리려면 stt.py의 설정을 바꿔야 하고 지연이 크게 늘어납니다.

  • Windows 11에서 개발·검증했습니다. Windows 10은 검증하지 않았고, Linux와 macOS는 지원하지 않습니다.
  • Python은 3.11~3.12만 됩니다(3.13 불가).
  • 인식한 글자를 클립보드에 넣고 Ctrl+V를 보내는 방식입니다. 이전 클립보드 내용은 다시 돌려놓지만 텍스트만 복원되고, 이미지나 파일은 사라집니다.
  • 관리자 권한으로 띄운 창에는 붙여 넣지 못합니다. 앱도 관리자 권한으로 실행해야 합니다.
  • 키를 뗀 뒤 한꺼번에 인식하므로 말하는 동안 글자가 실시간으로 나오지는 않습니다. 한 번에 최대 90초까지 녹음합니다.
  • 언어는 한국어로 고정되어 있고, whisper.language로 바꿀 수 있습니다.
  • Ulanzi와 관계없는 개인 프로젝트입니다. 라이선스는 MIT이고, 쓰는 라이브러리와 모델의 라이선스는 THIRD_PARTY_NOTICES.md에 있습니다.

설치 과정과 문제 해결은 app/INSTALL.md에 정리해 두었습니다. 소스는 GitHub 저장소에서 볼 수 있습니다.

함께 읽으면 좋은 글