amicalhq/amical

Amical – 로컬 우선 AI 음성 녹음

무엇인가요 – Amical은 사용자의 컴퓨터에서 완전히 작동하는 오픈소스 데스크톱 앱입니다. AI를 활용해 텍스트를 음성 입력하고 메모를 작성할 수 있습니다. OpenAI의 Whisper를 음성-텍스트 변환에 사용하고, Ollama를 통해 로컬에서 실행되는 LLM(대규모 언어 모델)을 활용해 문맥을 이해하고 현재 사용 중인 앱(이메일, IDE, 채팅 등)에 맞는 형식으로 변환합니다. 인터넷 연결이 필요 없으며, 음성 데이터는 기기 외부로 나가지 않습니다.

주요 기능

• 빠르고 정확한 음성 입력 – Whisper는 로컬에서 실행되어 거의 실시간으로 변환됩니다.
• 문맥 인식 형식 – 활성 창을 감지해 출력 형식을 자동 조정(예: 이메일 형식, 코드 스니펫, 채팅 메시지).
• 확장 가능한 워크플로우 – 핫키, 음성 매크로, 사용자 정의 파이프라인을 추가할 수 있습니다.
• 개인정보 최우선 – 모든 모델은 로컬에 다운로드 및 실행되며, 음성 데이터는 클라우드로 전송되지 않습니다.
• 플로팅 위젯 – 작업 흐름을 방해하지 않고 시작/정지가 가능한 작은 화면 내 제어 요소.
• 계획 중 – 음성 메모 요약, 작업 추출, 회의 녹음, 앱 제어 통합 강화.

기술 스택

• 음성-텍스트 변환: Whisper (네이티브 애드온으로 컴파일됨)
• LLM 추론: Ollama (오픈소스 모델을 로컬에서 실행)
• 데스크톱 프레임워크: Electron + TypeScript
• UI: TailwindCSS + Shadcn UI 컴포넌트
• 인증 및 검증: Better-Auth, Zod
• 빌드 및 테스트: Turborepo, Vitest, TypeScript 7 (네이티브 컴파일러)

개발 시작 방법

1. 서브모듈 포함 복제 – git clone --recurse-submodules https://github.com/amicalhq/amical.git
2. 도구 설치 – Node 24, pnpm 10.15, CMake ≥ 3.20, macOS는 Xcode, Windows는 Visual Studio 2022.
3. Corepack 활성화 및 종속성 설치 – corepack enable && pnpm install --frozen-lockfile
4. Whisper가 사용하는 Node 바이너리 다운로드 – pnpm --filter @amical/desktop download-node
5. 앱 실행 – pnpm turbo run dev --filter=@amical/desktop
6. PR 제출 전 검사 실행 – pnpm type:check && pnpm test

엔드유저용 설치 방법

• macOS: brew install --cask amical 또는 최신 릴리스 다운로드.
• Windows: 릴리스 페이지에서 설치 프로그램 다운로드.
• Android: Google Play에서 이용 가능 (README 내 링크 참조).
• iOS: 베타 등록 링크 제공.

기여 방법 – PR 및 버그 리포트를 환영합니다. 논의 및 커뮤니티 지원은 Discord 서버에서 진행됩니다. PR을 열기 전에 타입 체크 및 테스트를 실행하는 기여 체크리스트를 따르세요.

라이선스 – MIT.