역사 문서: 2026-07-26에 사용했던 Superwhisper 2.16.6과 Macrowhisper 2.1.1 구성의 기록이다. 두 도구의 실행 구성과 데이터는 제거됐으며, 현재 구조는 Whisper Voice와 Hammerspoon으로 로컬 음성 제어하기를 참조한다.
Superwhisper를 터미널의 AI 에이전트에게 자연어로 지시하는 용도로 사용하다 보니, 음성 입력의 범위를 운영체제 제어까지 넓히고 싶어졌다. 하지만 현재 입력란에 받아쓰기 결과를 붙여 넣는 방식으로는 매번 대상 창이나 입력란을 직접 활성화해야 한다. 이를 피하려면 음성을 텍스트 입력이 아니라 동작을 일으키는 이벤트로 다뤄야 한다.
이 목적을 위해 Superwhisper, Macrowhisper, Hammerspoon을 다음과 같이 연결했다.
음성
→ Superwhisper가 음성을 텍스트로 변환
→ Macrowhisper가 명령 실행 조건 판별
→ Hammerspoon URL 이벤트 호출
→ Hammerspoon이 macOS 동작 실행
역할을 나눈 이유
음성 인식, 명령 분기, 운영체제 제어를 한 도구에 모두 맡기지 않고 세 단계로 나눴다. Superwhisper가 현재 앱에 명령을 입력하고 다른 도구가 이를 다시 해석하게 만드는 대신, Macrowhisper가 Hammerspoon의 이벤트를 직접 호출한다. 그래서 명령을 실행하기 전에 터미널이나 특정 입력란을 활성화할 필요가 없다.
Hammerspoon은 음성 변환 결과를 임의의 셸 명령으로 실행하지 않는다. 미리 정의한 동작 이름만 허용 목록에서 찾아 실행한다. 자유로운 음성 입력과 실제 운영체제 제어 사이에 명확하고 예측 가능한 경계를 둔 셈이다.
도구별로 살펴보기
세 도구는 모두 자동화에 관여하지만 서로 대체할 수 있는 관계는 아니다. Superwhisper는 사람의 말을 텍스트로 바꾸고, Macrowhisper는 그 텍스트에 어떤 동작을 적용할지 결정하며, Hammerspoon은 macOS에서 실제 동작을 수행한다.
| 도구 | 핵심 역할 | 이 구성에서 하는 일 |
|---|---|---|
| Superwhisper | 음성 인식과 텍스트 가공 | 음성을 텍스트로 변환하고 녹음 메타데이터와 함께 저장한다. |
| Macrowhisper | Superwhisper 결과의 분기 | 일반 받아쓰기와 Action 명령을 구분한다. |
| Hammerspoon | macOS 자동화 실행 | 앱, 창, 디스플레이를 정해진 방식으로 제어한다. |
Superwhisper
Superwhisper는 macOS 어디에서나 사용할 수 있는 음성 입력 도구다. 단순히 소리를 받아 적는 데서 끝나지 않고, 모드별 프롬프트와 언어 모델을 이용해 말한 내용을 정리하거나 형식을 바꿀 수 있다.
주요 활용 범위는 다음과 같다.
- 어느 앱에서든 단축키를 이용한 받아쓰기
- 문장부호와 문체를 다듬은 텍스트 생성
- 번역, 요약, 이메일이나 문서 초안 작성
- 선택한 텍스트와 현재 앱의 맥락을 반영한 결과 생성
- 로컬 또는 클라우드 모델을 이용한 음성 변환과 후처리
- 녹음별 음성, 변환 결과, 메타데이터 보관
일반적인 사용에서는 처리한 텍스트를 현재 커서 위치에 바로 붙여 넣는다. 이 방식은 메신저, 이메일, 문서, 터미널의 AI 에이전트에게 긴 자연어를 입력할 때 유용하다. 반면 운영체제를 제어할 때는 커서 위치에 텍스트를 넣는 것보다 명령을 직접 실행하는 것이 중요하다. 특정 입력란을 먼저 선택해야 한다면 손을 쓰지 않는 제어라는 목적에도 맞지 않는다.
이 구성에서 Superwhisper는 음성 인식과 결과 생성까지만 담당한다. 자체 자동 붙여넣기를 끄고 녹음 결과를 남기면, 다음 단계인 Macrowhisper가 그 결과를 받아 일반 문장인지 제어 명령인지 판단한다. Superwhisper는 macOS 동작을 직접 실행하지 않는다.
Macrowhisper
Macrowhisper는 Superwhisper의 공식 내장 기능이 아니라, Superwhisper가 만든 녹음 폴더와 meta.json을 감시하는 독립적인 커뮤니티 프로젝트다. Superwhisper의 결과와 자동화 도구를 잇는 다리라고 볼 수 있다.
Macrowhisper는 음성 내용뿐 아니라 모드, 활성 앱, URL 같은 조건으로 동작을 선택할 수 있다. 조건에 따라 선택된 동작은 다음과 같은 방식으로 실행할 수 있다.
- 현재 입력란에 텍스트 삽입
- URL 열기
- 셸 스크립트 또는 AppleScript 실행
- macOS 단축어 실행
- 여러 동작 연결
- 처리한 녹음 이동 또는 삭제
이 도구가 유용한 이유는 받아쓰기와 명령 분기를 나눌 수 있기 때문이다. Superwhisper 설정을 복잡하게 바꾸지 않아도 특정 문구나 모드에만 자동화를 붙일 수 있고, 조건에 맞지 않는 텍스트는 평소처럼 입력할 수 있다.
이 구성에서는 Action으로 시작하는 음성 변환 결과만 Hammerspoon URL 이벤트로 보낸다. 그 외의 문장은 autoPaste 기본 동작으로 처리한다. 한글·영어 혼합 표기와 자동으로 삽입된 쉼표까지 실행 조건의 정규 표현식에서 받아들인다. URL은 백그라운드에서 열어 Hammerspoon 자체가 화면 앞쪽을 차지하지 않게 한다.
Macrowhisper는 명령의 의미를 이해하는 AI 에이전트가 아니다. 설정에 적힌 실행 조건과 동작을 그대로 평가하는 분기 도구다. 이 단순함 덕분에 어떤 음성이 어떤 동작을 실행하는지 예측하기 쉽다.
Hammerspoon
Hammerspoon은 Lua로 macOS를 자동화할 수 있는 상주형 실행 환경이다. 단축키 실행기처럼 사용할 수도 있지만, 실제 강점은 macOS의 여러 이벤트와 API를 작은 Lua 함수로 연결할 수 있다는 점이다.
대표적으로 다음 영역을 다룰 수 있다.
- 앱 실행, 활성화, 숨기기와 종료
- 창 위치, 크기, 활성 상태와 최소화 상태
- 여러 디스플레이 탐색과 창 이동
- 전역 단축키와 키보드·마우스 이벤트
- 앱, 창, 화면, Wi-Fi, USB, 잠자기 상태 감시
- 클립보드, 메뉴 막대, 알림과 타이머
- 셸 프로세스, AppleScript, URL 이벤트와 IPC 연동
단축어나 일반 실행기로도 앱을 열 수 있지만, Hammerspoon은 조건과 상태를 코드로 표현할 수 있다는 점이 다르다. 예를 들어 현재 창의 위치와 크기를 저장한 뒤 다른 디스플레이로 옮기거나, 직전 앱을 기억했다가 다시 활성화하는 동작을 하나의 실행 환경 안에서 구현할 수 있다.
이 구성에서 Hammerspoon은 실제 macOS 제어와 상태 관리를 맡는다. Macrowhisper가 전달한 동작 이름을 허용 목록에서 찾고 다음 작업을 수행한다.
- Chrome을 지정한 프로필로 실행하고 URL 열기
- WezTerm과 Apple Notes 활성화
- 창을 화면의 절반이나 전체 영역에 배치
- 창을 다른 디스플레이로 이동하거나 최소화
- 최근 앱 또는 창 상태를 한 단계 저장하고
Action Back으로 복구
Hammerspoon에는 자연어 해석을 맡기지 않는다. focusTerminal, windowRight, display2처럼 제한된 동작만 실행한다. 따라서 음성 인식 결과가 예상과 조금 달라도 Macrowhisper의 실행 조건을 통과한 정해진 동작만 수행한다.
과거 설치와 설정 위치
사용한 버전은 다음과 같다.
- Superwhisper 2.16.6
- Hammerspoon 1.1.1
- Macrowhisper 2.1.1
Hammerspoon과 Macrowhisper는 Homebrew로 설치했다.
brew install --cask hammerspoon
brew install ognistik/formulae/macrowhisper
설정은 dotfiles에서 관리하고 홈 디렉터리에 심볼릭 링크로 연결한다.
~/dotfiles/.hammerspoon/init.lua
→ ~/.hammerspoon/init.lua
~/dotfiles/.config/macrowhisper/macrowhisper.json
→ ~/.config/macrowhisper/macrowhisper.json
Hammerspoon은 로그인할 때 자동으로 실행하고, Macrowhisper는 백그라운드 서비스로 실행한다.
macrowhisper --start-service
macrowhisper --service-status
Hammerspoon의 창 제어에는 macOS 손쉬운 사용 권한이 필요하다.
일반 받아쓰기와 명령 분리
Superwhisper 자체의 자동 붙여넣기는 끄고 Macrowhisper의 autoPaste를 기본 동작으로 사용한다. 명령 실행 조건에 맞지 않는 일반 문장은 기존처럼 현재 입력란에 들어간다.
Superwhisper의 주요 설정은 다음과 같다.
- Recording Window(녹음 창): ON
- Paste Result Text(결과 텍스트 붙여넣기): OFF
- Restore Clipboard After Paste(붙여넣은 뒤 클립보드 복원): OFF
- Simulate Key Presses(키 입력 흉내 내기): OFF
명령에는 Action이라는 예약 접두사를 붙인다. 크롬, 백, 돌아가 같은 일반 단어만으로 동작을 실행하지 않기 때문에 받아쓰기 중 오작동할 가능성이 줄어든다.
음성 인식 결과는 한글, 영어, 혼합 표기가 될 수 있다. Superwhisper가 문장부호를 넣는 경우도 있으므로 다음 표현을 같은 명령으로 취급한다.
Action Window Right
액션 Window 라이트
액션, 윈도우 라이트.
앱과 검색
당시 등록했던 앱 명령은 다음과 같다.
| 명령 | 동작 |
|---|---|
Action Browser | Chrome의 master 프로필 열기 |
Action Terminal | WezTerm 활성화 |
Action Memo | Apple Notes 활성화 |
Action YouTube | YouTube 전용 Chrome 프로필에서 YouTube 열기 |
Action Netflix | master 프로필에서 Netflix 열기 |
Action Search <검색어> | master 프로필에서 Google 검색 |
Chrome의 표시 이름이 아니라 내부 프로필 디렉터리를 사용한다.
master → Profile 2
youtube → Profile 8
예를 들어 Action Search Hammerspoon tutorials라고 말하면 검색어를 URL 인코딩해 Google 검색 주소를 만든 뒤 Profile 2에서 연다. 이때 검색어를 셸 문자열로 평가하지 않고, 완성된 검색 주소를 /usr/bin/open의 프로세스 인자로 전달한다.
창 배치
현재 활성화된 실제 앱의 활성 창을 기준으로 동작한다. Superwhisper와 Hammerspoon 자체는 앱 전환 기록에서 제외한다.
| 명령 | 동작 |
|---|---|
Action Window Left | 왼쪽 절반 |
Action Window Right | 오른쪽 절반 |
Action Window Up | 위쪽 절반 |
Action Window Down | 아래쪽 절반 |
Action Window Full | 사용 가능한 화면 전체 크기 |
Action Window Minimize | 현재 창 최소화 |
Window Full은 macOS의 전체 화면 모드가 아니다. 메뉴 막대와 Dock을 제외한 화면 영역에 창을 맞춘다.
방향 이름도 한글 음차를 허용한다.
Left → 레프트
Right → 라이트
Up → 업
Down → 다운
Full → 풀, 맥시마이즈
Minimize → 미니마이즈
디스플레이 이동
두 디스플레이는 연결 순서나 이름 검색에 의존하지 않도록 UUID로 식별한다.
| 명령 | 대상 |
|---|---|
Action Display 1 | LG ULTRAFINE |
Action Display 2 | Studio Display |
1·2, One·Two, 원·투를 모두 허용하며 디스플레이 2는 이로 인식된 경우도 처리한다. 창을 옮길 때는 대상 디스플레이에 대한 상대 위치와 크기를 유지한다.
디스플레이 UUID는 해당 Mac의 하드웨어 구성에 종속된다. 모니터를 교체하면 Hammerspoon 설정의 UUID 연결 정보도 갱신해야 한다.
Action Back으로 되돌리기
Action Back은 최근의 의미 있는 동작 하나를 복구한다.
액션 돌아가
액션 고 백
액션 고백
액션 백
액션백
Action Go Back
Action Back
ActionBack
복구 대상은 두 종류다.
- 앱을 전환했다면 이전 애플리케이션을 다시 활성화한다.
- 창 또는 디스플레이를 조작했다면 이전 창 상태를 복원한다.
창 관련 동작을 실행하기 전에는 다음 정보만 Lua 메모리에 저장한다.
창 ID
앱 번들 ID
디스플레이 UUID
디스플레이 기준 상대 위치와 크기
최소화 여부
복원 직전의 상태를 다시 저장하기 때문에 Action Back을 연속으로 실행하면 두 상태를 왕복할 수 있다.
창 최소화
→ Action Back: 창 복원
→ Action Back: 다시 최소화
디스플레이 1로 이동
→ Action Back: 원래 디스플레이로 복귀
→ Action Back: 다시 디스플레이 1로 이동
Chrome 탭이나 같은 앱 내부의 창 전환은 앱 전환 기록으로 남기지 않는다. 애플리케이션 번들 단위의 전환만 추적한다.
상태는 한 단계만 저장하므로 메모리 사용량이 계속 늘어나지 않는다. Hammerspoon 설정을 다시 불러오거나 앱을 종료하고 다시 실행하면 메모리는 초기화된다. Mac이 잠자기에 들어갔다가 깨어나는 동안에는 Hammerspoon 프로세스가 유지되므로 상태도 남는다.
복원할 때는 창 ID와 소유 앱을 다시 확인한다. 창이 닫혔거나 디스플레이가 연결되어 있지 않다면 오래된 상태를 적용하지 않는다. 디스플레이의 배치나 해상도가 달라져도 상대 위치와 크기를 이용해 새 좌표를 계산한다.
과거 확인 방법
다음 명령은 당시 구성에서 사용했다. Macrowhisper가 제거된 현재 환경에서는 실행되지 않는다.
Macrowhisper 설정과 서비스 상태는 다음 명령으로 확인한다.
macrowhisper --validate-config
macrowhisper --service-status
Hammerspoon 설정을 수정한 뒤에는 다시 불러온다.
hs -c 'hs.reload()'
설정을 다시 불러온 직후 hs 명령줄 도구에서 메시지 포트 관련 오류가 출력될 수 있다. Hammerspoon이 기존 IPC 연결을 끊고 Lua 상태를 다시 만드는 과정에서 발생하는 정상적인 전송 오류다.
정리
이 구성의 핵심은 음성 받아쓰기를 운영체제 동작과 직접 연결하되, 음성 변환 결과 자체에는 실행 권한을 주지 않는 데 있다. Superwhisper는 음성을 인식하고, Macrowhisper는 일반 받아쓰기와 명령 사이에 경계를 만들며, Hammerspoon은 제한된 동작만 실행한다.
처음에는 앱 활성화 기능 하나로 시작했지만 같은 구조 안에서 검색, Chrome 프로필, 창 배치, 디스플레이 이동, 한 단계 복구까지 확장할 수 있었다. 새 기능을 추가할 때도 Action 예약 접두사와 허용 목록을 유지하면 일반 받아쓰기와 충돌하지 않으면서 점진적으로 넓혀 갈 수 있다.
출처와 참고 자료
Superwhisper
- Superwhisper 공식 문서
- 사용자 정의 모드와 맥락 인식
- 고급 설정: 녹음 창, 저장 폴더, 텍스트 입력
- 단축키 설정
- 커뮤니티 프로젝트: Macrowhisper 소개
- Superwhisper 공식 내려받기 저장소
Macrowhisper
- Macrowhisper 저장소와 빠른 시작 안내
- Macrowhisper 전체 문서
- 설정과 동작 참고 문서 원문
- 녹음 감시와 동작 처리 흐름
- Macrowhisper 코드 구성도
- 설정 스키마
Hammerspoon
- Hammerspoon 공식 문서
- 핵심 API와 설정 다시 불러오기
- 앱 실행과 활성화
- 앱 상태 감시
- 창 이동, 크기 조절과 최소화
- 디스플레이 탐색과 UUID
- URL 이벤트
- 명령줄 IPC
- 외부 프로세스 실행
- 타이머와 지연 실행