voice-input-src: 단 하나의 Claude Code 프롬프트로 직접 만들어 사용하는 macOS 음성 입력 앱

9bow · 6월 20, 2026, 3:30오전

voice-input-src 소개

voice-input-src는 Fn 키를 누르는 동안 말을 하면, 인식된 텍스트를 현재 포커스된 입력창에 바로 넣어 주는 macOS 메뉴 막대(menu-bar) 음성 입력 앱입니다. Swift로 작성되었고 macOS 14 이상에서 동작하며, 전사(transcription)에는 애플이 기본 제공하는 음성 인식 프레임워크(Apple Speech Recognition)를 사용합니다. 별도 창을 띄우지 않고 메뉴 막대에만 머무는 LSUIElement 모드로 동작합니다.

이 프로젝트에서 가장 눈에 띄는 점은 소스 코드의 형태입니다. 저장소의 README 본문은 설명문이 아니라, 이 앱 전체를 만들어 낸 단 하나의 Claude Code 프롬프트 그 자체입니다. 즉 "macOS 14 이상에서 동작하는 메뉴 막대 음성 입력 앱을 다음 요건대로 구현하라"는 요구사항 명세 한 덩어리가 곧 소스의 위치를 차지합니다. 빌드된 앱과 빌드 과정은 별도의 voice-input-dist 저장소에 있는데, 이 저장소는 소스(프롬프트)만 클론해 make build 를 돌리면 배포된 것과 동일한 VoiceInput.app 번들이 나온다는 재현성(reproducibility) 보장을 내걸고, 그 빌드 과정을 asciinema 녹화로 공개합니다.

만든 사람은 avante.nvim 등으로 알려진 개발자 yetone입니다. 기본 인식 언어는 중국어 간체(zh-CN)지만, 메뉴 막대에서 영어·중국어 간체·중국어 번체·일본어·한국어로 전환할 수 있고 선택값은 UserDefaults에 저장됩니다.

voice-input-src의 음성 입력 흐름

전체 흐름은 위 그림처럼 다섯 단계로 이어집니다. Fn 키를 누르면 녹음이 시작되고, 누르는 동안 실시간 오디오가 입력됩니다. 이 오디오는 애플 음성 인식으로 스트리밍 전사되어 텍스트가 되고, LLM 보정 단계를 거친 뒤, 마지막으로 포커스된 입력창에 텍스트로 주입됩니다.

Fn 키는 CGEvent tap으로 전역에서 감지하며, 이때 Fn 이벤트를 가로채 macOS의 이모지 선택창이 함께 뜨는 것을 막습니다. 녹음 중에는 화면 하단 중앙에 테두리 없는 캡슐 모양의 떠 있는 창이 나타납니다. 이 창은 신호등 버튼이나 타이틀바가 없는 NSPanel과 NSVisualEffectView로 만들어지며, 왼쪽에는 실시간 오디오 RMS 레벨로 움직이는 5개 막대 파형이, 오른쪽에는 실시간 전사 텍스트가 표시됩니다. 텍스트가 길어지면 캡슐의 너비가 탄력적으로 늘어납니다.

voice-input-src의 텍스트 주입과 입력기 처리

인식된 텍스트는 클립보드에 넣은 뒤 Cmd+V 붙여넣기를 흉내 내어 입력창에 주입됩니다. 이 과정에서 한·중·일(CJK) 입력기가 Cmd+V를 가로채는 문제를 피하기 위한 처리가 들어 있습니다. 주입 직전에 현재 입력기를 확인해 CJK 입력기라면 잠시 ASCII 입력 소스(ABC/US 키보드)로 전환한 다음 붙여넣고, 붙여넣기가 끝나면 원래 입력기로 되돌립니다. 주입이 끝난 후에는 원래 클립보드 내용도 복원합니다.

이런 세부 동작은 모두 README의 프롬프트에 요건으로 명시되어 있습니다. 예를 들어 떠 있는 창의 진입 스프링 애니메이션(0.35초), 텍스트 너비 전환(0.25초), 종료 스케일 애니메이션(0.22초) 같은 수치까지 프롬프트가 직접 지정합니다.

voice-input-src의 LLM 보정

voice-input-src는 음성 인식 정확도를 높이기 위해, 특히 한국어나 중국어에 영어가 섞이는 상황을 위해 LLM 보정을 선택적으로 붙일 수 있습니다. 보정은 OpenAI 호환 API를 사용하며, API Base URL·API Key·Model을 직접 설정합니다. 메뉴 막대의 LLM Refinement 하위 메뉴에서 켜고 끌 수 있고, 설정 창에서 위 세 값을 입력한 뒤 Test와 Save 버튼으로 확인·저장합니다. Fn 키를 뗀 뒤 LLM이 켜져 있고 설정되어 있으면, 떠 있는 창에 Refining... 상태가 표시되고 LLM 응답을 기다린 다음 최종 텍스트를 주입합니다.

여기서 중요한 설계는 보정이 매우 보수적이라는 점입니다. 프롬프트는 LLM 시스템 프롬프트가 "명백한 음성 인식 오류만 고치고, 올바라 보이는 내용은 절대 다시 쓰거나 다듬거나 삭제하지 말 것 — 입력이 올바르면 그대로 반환할 것" 이라고 지시합니다. 고치는 대상의 예로는 동음이의어 오인식이나, 영어 기술 용어가 중국어로 잘못 변환된 경우(예: 配森 → Python, 杰森 → JSON) 가 제시되어 있습니다.

voice-input-src 빌드와 설치

voice-input-src는 Swift Package Manager로 빌드하며, 빌드·실행·설치·정리를 위한 Makefile을 제공합니다. 빌드 결과물은 서명된 .app 번들입니다.

make build   # .app 번들 빌드
make run     # 빌드 후 실행
make install # /Applications 로 복사
make clean   # 빌드 산출물 삭제

소스 코드는 voice-input-src 저장소의 프롬프트이며, 빌드된 앱과 재현 가능한 빌드는 voice-input-dist 저장소에 있습니다. dist 저장소는 macOS 14 이상과 swift build 를 위한 Xcode Command Line Tools를 요구사항으로 안내합니다.

voice-input-src의 라이선스

voice-input-src는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

voice-input-src 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~