cjpais/Handy

A free, open source, and extensible speech-to-text application that works completely offline.

Handy – 오프라인, 개인정보 우선의 음성-텍스트 변환

무엇인가요 – Handy는 무료로 오픈소스인 데스크톱 앱으로, 클라우드에 음성을 전송하지 않고도 어떤 창에도 즉시 텍스트를 입력할 수 있습니다. Windows, macOS, Linux에서 로컬로 실행되며, 온디바이스 신경망 모델(OpenAI 스타일의 Whisper 또는 CPU 최적화된 Parakeet)을 사용하여 음성 인식을 수행합니다.

작동 방식

사용자 정의 가능한 글로벌 단축키(홀드로 녹음 또는 토글)를 누릅니다.
말하기 – 음성은 cpal을 통해 캡처되고 Silero VAD로 필터링됩니다.
단축키를 놓으면, 선택된 모델(Whisper Small/Medium/Turbo/Large 또는 Parakeet V3)에 음성이 전달됩니다.
결과 텍스트는 현재 포커스된 애플리케이션에 자동으로 붙여넣기됩니다.

모든 단계는 귀하의 기기에서 수행되며, 네트워크 트래픽이 필요하지 않습니다.

주요 기능

오프라인 추론 – Whisper GGML/GGUF 또는 Parakeet 모델과 호환; 사용 가능한 경우 GPU 가속이 활성화됩니다.
크로스플랫폼 – macOS(Intel 및 Apple Silicon), Windows x64, Linux x64용 네이티브 빌드 제공.
확장성 – Tauri(Rust 백엔드, React/TS 프론트엔드)로 구축되어 개발자가 플러그인이나 새로운 모델을 추가할 수 있습니다.
글로벌 단축키 – rdev를 통해 시스템 전체 단축키 제공; CLI 플래그로 실행 중 인스턴스 제어 가능(handy --toggle-transcription).
음성 활동 탐지 – Silero VAD로 무음 전에 필터링하여 불필요한 처리를 줄입니다.
Raycast 통합 – macOS 사용자는 Raycast 런처에서 Handy를 제어할 수 있습니다.
디버그 모드 및 CLI – 내장된 디버그 오버레이, 상세 로깅, 파워유저를 위한 다양한 시작 플래그 제공.

아키텍처 개요

계층	기술	역할
UI	React + TypeScript, Tailwind CSS	설정 창, 오버레이 UI
앱 쉘	Tauri (Rust)	크로스플랫폼 패키징, 시스템 통합
오디오 I/O	`cpal`	마이크 스트림 캡처
VAD	`vad-rs` (Silero)	음성과 무음 구분
단축키	`rdev`	글로벌 키보드 단축키
리샘플링	`rubato`	모델 요구 샘플 레이트로 변환
Whisper 추론	`transcribe-cpp` (GGML/GGUF)	GPU 또는 CPU용 Whisper 모델
Parakeet 추론	`transcribe-rs`	CPU 최적화된 Parakeet V3 모델

시작하기

설치 – GitHub 릴리스 페이지에서 바이너리를 다운로드하거나 패키지 매니저 사용:
- macOS: brew install --cask handy
- Windows: winget install cjpais.Handy
앱을 실행하고 마이크 및 접근성 권한을 허용한 후, 설정 → 키보드에서 단축키를 설정합니다.
단축키를 누르고 말한 후 놓으면, 전사된 텍스트가 커서 위치에 붙여넣어집니다.

고급 제어 – CLI 플래그를 사용해 녹음 토글, 숨은 상태로 시작, 트레이 아이콘 비활성화 등을 가능하게 합니다. 예시:

handy --start-hidden --no-tray &   # 조용히 시작
handy --toggle-transcription       # 사용자 정의 단축키나 스크립트에서 토글

알려진 제한 및 문제 해결

macOS 블루투스 마이크 – 재생 볼륨이 낮아질 수 있음; 최상의 결과를 위해 내장 마이크 또는 유선 마이크 사용 권장.
fn/Globe 키 단축키 – Apple 키보드에서만 작동(하드웨어 HID 제한으로 인해).
Whisper 모델 충돌 – 일부 Windows/Linux 환경에서 발생; 커뮤니티의 도움 요청.
Linux Wayland – 텍스트 삽입을 위해 wtype 또는 dotool 필요; 오버레이가 포커스를 가로챌 수 있으므로, 오버레이 위치를 "없음"으로 설정하는 것이 권장됨.
런타임 라이브러리 – Linux에서는 앱을 시작하려면 libgtk-layer-shell0 (또는 디스트리뷰션별 패키지)가 필요할 수 있음.

Handy 확장하기

백엔드가 Rust이고 UI가 표준 웹 스택이므로 기여자는 다음을 수행할 수 있습니다:

새로운 모델 로더 추가(예: 다른 GGUF/ONNX 모델).
OS 간 글로벌 단축키 처리 개선.
추가 통합 구축(예: VS Code 확장 또는 브라우저 플러그인).
설정 저장소 리팩터링 또는 사용자 정의 후처리용 플러그인 시스템 추가.

로드맵(README 기준)

파일에 대한 디버그 로깅.
macOS 단축키 개선(Globe 키, 글로벌 단축키 처리 재작성).
선택적 옵트인 분석(개인정보 우선).
설정 시스템 정리 및 Tauri 명령 리팩터링.

파워유저를 위한 빠른 점검

Handy는 릴리스 아티팩트를 Tauri의 업데이터 서명으로 서명합니다. 공개 키는 src-tauri/tauri.conf.json에 있으며, README에 설명된 대로 minisign으로 다운로드를 검증할 수 있습니다.

결론 – Handy는 개인정보를 존중하며, 세 가지 주요 데스크톱 OS에서 작동하고 오픈소스 음성 인식 라이브러리 기반의 완전히 오프라인의 간단한 음성 입력 워크플로우를 제공합니다. 수정 가능하고 확장 가능한 음성-텍스트 도구로서 훌륭한 기반을 제공합니다.