open-typeless

open-typeless란?

open-typeless는 Trellis 프레임워크의 쇼케이스로 제작된 macOS 데스크톱 애플리케이션입니다. 마이크에서 음성을 녹음하는 푸시투토크 워크플로를 제공하며, Volcano Engine의 ASR 서비스를 사용해 스트리밍 음성-텍스트 변환을 수행하고, 현재 포커스된 텍스트 커서에 인식된 텍스트를 삽입합니다.

이 프로젝트는 창 전환 없이 어떤 앱에든 음성 입력을 원하는 사용자들을 위해 제작되었습니다. 또한 핫키를 누르고 있는 동안 현재 청취 상태와 실시간 전사를 보여주는 유리모양(glassmorphism) 스타일의 플로팅 오버레이를 포함합니다.

주요 기능

• 푸시투토크 핫키(누르고 있음): 오른쪽 Option 키를 누르고 있으면 녹음 시작; 키를 놓으면 녹음 종료 후 자동 삽입.
• 실시간 스트리밍 전사: Volcano Engine ASR을 사용해 부분 결과를 스트리밍하며, 인식 진행에 따라 오버레이가 업데이트됩니다.
• 상태 및 전사 표시 플로팅 오버레이: "청취 중…" 상태와 전사된 텍스트를 유리결빙(frosted-glass) 모양으로 표시.
• 창 전환 없이 커서 삽입: 현재 커서 위치에 인식 텍스트를 자동 삽입해 사용 중인 앱에서 타이핑을 계속할 수 있습니다.
• 포커스 뺏지 않음: 플로팅 창은 현재 애플리케이션에서 사용자 워크플로를 방해하지 않도록 설계되었습니다.

open-typeless 사용 방법

1. 의존성 설치: pnpm install 실행.
2. 환경 변수 설정: .env.example을 .env로 복사한 후 Volcano Engine 자격 증명을 입력.
   • VOLCENGINE_APP_ID
   • VOLCENGINE_ACCESS_TOKEN
   • VOLCENGINE_RESOURCE_ID (리포지토리 예시: 모델 1.0은 volc.bigasr.sauc, 모델 2.0은 volc.seedasr.sauc(권장))
3. 앱 시작: pnpm start 실행.
4. 첫 실행 시 macOS 권한 승인:
   • 마이크 권한 (녹음용)
   • 접근성(보조 기능) 권한 (글로벌 핫키 처리 및 텍스트 삽입용) 권한 부여 후 앱을 백그라운드에서 실행 상태로 유지.
5. 음성 입력: 텍스트 필드가 있는 어떤 앱에서든 오른쪽 Option을 누르고 말한 후 놓기. 앱이 커서에 인식 텍스트를 삽입합니다.

사용 사례

• 어떤 에디터든 메시지 음성 입력: 채팅, 이메일 에디터, 문서 필드에 오른쪽 Option을 누르고 음성 입력; 인식 텍스트가 수동 붙여넣기 없이 커서에 나타남.
• 실시간 피드백 폼 작성: 말하는 동안 시스템 인식을 플로팅 오버레이로 모니터링한 후 놓아 텍스트 확정.
• 앱 간 빠른 메모: 누르고 놓는 키로 음성 시작/중지, 활성 창 포커스 유지.
• 핫키/텍스트 삽입 문제 해결: 핫키가 작동하지 않거나 텍스트가 삽입되지 않으면 앱에 접근성 권한이 활성화되어 있는지, 커서가 입력 영역에 있는지 확인.

자주 묻는 질문

• 핫키가 작동하지 않는 이유는? 시스템 환경설정 → 개인 정보 보호 및 보안 → 접근성에서 앱에 접근성(보조 기능) 권한이 부여되어 있고, 허용 앱 목록에 추가되어 있는지 확인.

• 앱이 텍스트를 삽입하지 못하는 이유는? 대상 애플리케이션이 텍스트 입력을 지원해야 하며, 커서가 텍스트 입력 영역에 있어야 합니다. 또한 접근성 권한이 올바르게 승인되었는지 확인.

• 음성 인식 시작 지연이 있나요? Volcano Engine 서비스에 첫 연결 시 WebSocket 연결이 설정되며 1–2초 정도 걸릴 수 있습니다; 이후 사용은 더 빠를 수 있습니다.

• 핫키를 변경할 수 있나요? 리포지토리에 따르면 핫키는 현재 오른쪽 Option 키로 고정되어 있으며, 변경하려면 src/main/services/keyboard/keyboard.service.ts의 triggerKey를 수정해야 합니다.

대안

• macOS 내장 음성 입력 / 음성 입력: 외부 ASR 제공자 자격 증명 설정 없이 시스템 수준 음성-텍스트를 선호할 때 유용. 워크플로가 다르며, 통합 및 삽입 동작은 macOS에서 처리.
• 수동 복사/붙여넣기 음성-텍스트 도구: 전사를 제공하지만 일반적으로 결과를 대상 앱에 붙여넣어야 하며, 이 프로젝트의 커서 삽입 방식과 다름.
• 텍스트 확장 및 핫키 음성 입력 앱: 단축키로 텍스트 삽입 도움; 일부는 스트리밍 ASR, 유리 오버레이, 푸시투토크 대신 편집 매크로나 전사 파이프라인에 초점.
• 개발자 중심 다른 음성-텍스트 통합: 자체 워크플로 제작 시 ASR API와 글로벌 핫키/클립보드 또는 접근성 API 사용 가능; 이 앱처럼 즉시 사용 대신 구현 필요.