설치 및 권한

설치와 권한이 올바르게 끝나야 전역 단축키와 음성 입력이 안정적으로 동작합니다. 이 페이지는 실제 설치 순서대로 진행합니다. 아래 그림은 자동 생성 UI 미리보기(시스템 설정 / 설치 / 메뉴 바 HTML 재현 + Releases 실제 페이지 스크린샷)이며, 필요하면 public/screenshots/의 PNG를 실제 캡처로 바꿀 수 있습니다.

요구 사항

• macOS 14 이상
• Apple Silicon 또는 Intel
• 선택: ASR / LLM API 키 (BYOK)
• 실제 음성 입력에는 마이크 + 손쉬운 사용(Accessibility) 이 필요합니다

1. 설치 파일 다운로드

1. Releases 열기
   VoiceHotkey-releases · Latest로 이동합니다.

2. DMG 다운로드
   macOS용 .dmg 에셋을 선택합니다. 앱으로 Source code 아카이브를 사용하지 마세요.

3. 디스크 이미지 열기
   DMG를 더블 클릭하고 설치 창이 나타날 때까지 기다립니다.

그림 1 · Releases 페이지 (UI 미리보기 · install-01-releases.webp)

2. 안정적인 경로에 설치

1. Applications로 드래그
   VoiceHotkey.app을 Applications 또는 ~/Applications로 드래그합니다.

2. DMG 꺼내기 (선택)
   백업으로 DMG를 남겨 두어도 됩니다.

3. 경로 기억하기
   항상 같은 위치에서 실행하세요. 예:

   • /Applications/VoiceHotkey.app
   • 또는 ~/Applications/VoiceHotkey.app

그림 2 · DMG 설치 창 (UI 미리보기 · install-02-dmg.webp)

그림 3 · 앱 경로 확인 (UI 미리보기 · install-03-path.webp)

Downloads에서 장기간 실행하지 마세요

~/Downloads나 임시 폴더에서 실행하면 이동·재다운로드 후 macOS가 손쉬운 사용을 다른 앱으로 취급해 단축키가 “갑자기” 동작하지 않을 수 있습니다. 먼저 Applications에 설치한 뒤 권한을 부여하세요.

3. 첫 실행

1. 앱 열기
   Launchpad 또는 Finder에서 엽니다. Gatekeeper가 차단하면 개인정보 보호 및 보안에서 허용합니다(공증된 빌드가 더 원활합니다).

2. 메뉴 바 확인
   오른쪽에 마이크 스타일 아이콘이 나타나야 합니다. 없으면 메뉴 바 오버플로 또는 앱 실행 여부를 확인하세요.

3. 온보딩 완료
   첫 실행 시 빠른 설정(환영 → 권한 → 플랜 → 완료)이 표시됩니다. 여기서 권한을 부여하거나 나중에 시스템 설정에서 할 수 있습니다.

그림 4 · 메뉴 바 아이콘 (UI 미리보기 · install-07-menubar.webp)

그림 5 · 온보딩 권한 (UI 미리보기 · install-06-onboarding.webp)

4. 손쉬운 사용 권한 부여

전역 단축키, 캐럿에 텍스트 삽입, 키 입력 주입에 필요합니다. 없으면 단축키가 보통 아무 반응도 하지 않습니다.

1. 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용을 엽니다.
2. +(또는 잠금 해제)를 눌러 VoiceHotkey.app을 추가합니다.
3. 경로가 실제로 실행하는 앱과 일치하는지 확인합니다.
4. 스위치를 켬으로 둡니다.
5. “VoiceHotkey” 행이 여러 개면 이전 항목을 제거하고 현재 경로만 남긴 뒤 앱을 종료 후 다시 실행하세요.

그림 6 · 손쉬운 사용 (UI 미리보기 · install-04-accessibility.webp)

앱에서 바로 열기

설정 → 일반(또는 온보딩)에 손쉬운 사용으로 이동하는 버튼이 보통 있습니다. 권한 부여 후 메뉴 바의 “손쉬운 사용 필요” 경고가 사라져야 합니다.

5. 마이크 권한 부여

실제 음성 입력에 필요합니다. 데모 모드는 마이크를 건너뛸 수 있지만, 실제 사용에는 필수입니다.

1. 시스템 설정 → 개인정보 보호 및 보안 → 마이크를 엽니다.
2. VoiceHotkey를 켭니다.
3. 첫 녹음 시 시스템 프롬프트가 나오면 허용합니다.
4. 외장 마이크는 시스템 설정 → 사운드 → 입력을 확인하세요. 앱 일반에 마이크 선택기가 있으면 같은 장치를 사용합니다.

5b. 음성 인식 (Apple 엔진 전용)

Apple Speech / SpeechAnalyzer를 사용하면 시스템이 음성 인식 권한(SFSpeechRecognizer)을 추가로 요구합니다. 클라우드 엔진(Doubao, Whisper 등)은 대개 이 권한에 의존하지 않습니다.

1. 시스템 설정 → 개인정보 보호 및 보안 → 음성 인식을 엽니다.
2. VoiceHotkey를 허용합니다.
3. 특정 언어를 사용할 수 없다면 시스템 설정에서 해당 언어 팩을 다운로드하거나 엔진을 바꾸세요.

그림 7 · 마이크 (UI 미리보기 · install-05-microphone.webp)

6. 권한 체크리스트

확인 항목	기대 결과
메뉴 바 아이콘	보이고 메뉴가 열림
설정 → 일반 · 권한	손쉬운 사용 + 마이크 허용됨
단축키 입력	오버레이 / 상태 변화 (데모에서도)
설치 경로	손쉬운 사용 항목과 일치

여전히 안 되면 문제 해결을 참고하세요.

다음

첫 설정데모 모드, 엔진, 단축키, 실제 입력 테스트.

단축키 및 녹음탭 / 길게 누르기, Quick Send, 취소.