Galpi · 갈피

Mac(Apple Silicon)과 Windows x64에서 회의를 녹음하고, 화자를 구분해 전사하고,
필요한 경우 AI로 회의록까지 정리하는 로컬 우선 데스크톱 앱

한국어 · English

Important

Galpi 0.1.0은 macOS 14 이상 Apple Silicon(M1 이상) 과 Windows 10/11 x64 를 지원하는 개발 빌드입니다. 배포용 바이너리는 제공하지 않습니다. 사용할 컴퓨터에서 소스로 직접 빌드해 설치합니다(아래 '1. 설치'). Intel Mac과 Linux는 지원하지 않습니다.

한눈에 보기

Galpi는 회의 음성을 앱 안에서 녹음하거나 기존 파일로 가져와, 한국어 전사와 화자분리를 로컬에서 수행합니다. 전사 엔진은 설정의 전사 엔진에서 선택하며 기본값은 Qwen3(Qwen3-ASR-1.7B + Qwen3-ForcedAligner-0.6B)이고 이전 엔진 WhisperX(faster-whisper large-v3-turbo)를 그대로 고를 수 있습니다. 화자분리는 두 프리셋이 pyannote community-1을 공용합니다. 전사 결과는 사용자가 고른 폴더에 저장되며, 선택적으로 OpenAI 호환 API를 사용해 한국어 회의록 Markdown을 만들 수 있습니다.

기능	내용
바로 녹음	마이크 입력(CPAL: CoreAudio/WASAPI)을 16-bit PCM WAV로 저장
파일 가져오기	m4a, mp3, wav, mp4, mov, aac, flac, ogg
로컬 전사	Qwen3(기본) 또는 WhisperX 프리셋 한국어 ASR
화자분리	pyannote 기반 분리, 자동·정확히·최소/최대 화자 수 힌트
문장 정렬	한국어 문장 정렬과 장기 무음 환각 필터링
참석자 명부	이름·팀·역할·별칭·설명을 회의마다 재사용
단어집	고유명사와 전문 용어를 회의록 가공에 반영
AI 회의록	OpenAI 호환 API로 결정·담당·기한 중심 Markdown 생성
작업 제어	준비·전사 취소와 상세 로그, AI 증강·Drive 가져오기 진행률과 오류 표시

빠른 시작

1. 설치

Galpi는 사용할 컴퓨터에서 직접 빌드해 설치합니다. 같은 컴퓨터에서 만든 앱에는 인터넷에서 받은 파일이라는 표시(macOS 격리 속성, Windows Mark of the Web)가 붙지 않습니다. 그래서 서명되지 않은 빌드를 내려받았을 때 나오는 Gatekeeper 경고 없이 열리며(macOS 27에서 확인), Windows에서도 SmartScreen 경고가 보통 나오지 않습니다.

코딩 에이전트(Claude Code, Codex 등)에게 다음과 같이 요청하면 됩니다.

https://github.com/m16khb-org/galpi 저장소를 받아서, INSTALL.md를 따라 이 컴퓨터에 Galpi를 빌드하고 설치해 줘.

에이전트는 INSTALL.md에 따라 플랫폼을 확인하고, 빠진 도구(Xcode Command Line Tools 또는 Visual Studio Build Tools, Rust, Bun, Tauri CLI)를 설치해도 되는지 물은 뒤 빌드·설치합니다. 직접 진행할 때도 같은 문서를 따르면 됩니다. 업데이트도 같은 방법으로 다시 빌드합니다.

개발 모드로 실행하기

필수 환경:

• macOS 14 이상 Apple Silicon 또는 Windows 10/11 x64
• Windows: Microsoft Visual C++ 2015–2022 x64 재배포 패키지(앱에 포함되지 않음)
• Rust 1.88 이상
• Bun 1.3 이상
• Tauri CLI 2.11.4

cargo install tauri-cli --version 2.11.4 --locked
bun install
bun run dev

bun run dev는 해당 플랫폼의 검증된 uv, Python worker, 프론트엔드, Tauri 앱을 준비해 실행합니다. Python, ffmpeg, WhisperX를 전역으로 미리 설치할 필요는 없습니다. Windows에서도 PowerShell에서 같은 명령을 사용합니다.

Windows 참고

1. Microsoft Visual C++ 2015–2022 x64 재배포 패키지가 필요합니다. 앱에 포함되어 있지 않으며, INSTALL.md 절차가 함께 설치합니다.
2. 빌드한 NSIS 설치 프로그램(Galpi_<버전>_x64-setup.exe)은 현재 사용자용으로 설치되므로 관리자 권한이 필요 없습니다.
3. 아래 '최초 엔진 준비'를 진행합니다.

Windows에서는 전사 엔진으로 WhisperX만 선택할 수 있습니다(Qwen3/MLX는 Apple Silicon 전용). 기본은 CPU이며, 설정에서 CUDA를 고를 수 있습니다. CUDA는 PyTorch cu128 빌드를 추가로 약 3.5 GB 내려받고 NVIDIA 드라이버가 필요합니다. CUDA를 고르면 음성 인식(CTranslate2 float16)과 정렬·화자분리가 모두 GPU에서 돌고, GPU 음성 인식이 실패하면 CPU int8로 한 번 다시 시도합니다.

2. 최초 엔진 준비

1. 앱 우측 상단의 설정을 엽니다.
2. 새 컴퓨터에서 화자분리 모델을 처음 받는다면 Hugging Face 토큰을 저장합니다.
3. 로컬 엔진 준비를 누릅니다.
4. 선택한 엔진의 엔진, 전사 모델, ffmpeg가 모두 준비됨이 될 때까지 기다립니다. 전사 엔진 선택지 아래에는 각 프리셋의 준비 상태가 함께 표시됩니다.

최초 준비에서는 앱 전용 Python 3.12 환경과 수 GB의 모델을 내려받을 수 있습니다. 이후에는 같은 앱 데이터 폴더와 모델 캐시를 재사용합니다. 두 프리셋은 서로 다른 가상환경(engine/, engine/qwen3/)에 설치되므로 한쪽을 준비해도 다른쪽에 영향을 주지 않습니다.

3. Hugging Face 토큰

화자분리 모델을 처음 내려받을 때만 필요합니다.

1. pyannote/speaker-diarization-community-1의 이용 조건에 동의합니다.
2. Hugging Face Access Tokens에서 Fine-grained 토큰을 만듭니다.
3. 해당 저장소에 Read 권한만 허용합니다.
4. hf_로 시작하는 값을 Galpi 설정에 저장합니다.

쓰기 권한과 Inference Providers 권한은 필요하지 않습니다.

사용 흐름

회의 녹음 또는 파일 선택

앱에서 녹음

1. 출력 폴더를 확인합니다.
2. 녹음 소스를 고릅니다. 기본값 마이크만은 마이크 입력만, 마이크 + 회의 소리는 마이크와 컴퓨터에서 재생되는 소리(Slack 허들, Zoom, Google Meet 등 상대방 목소리)를 함께 녹음합니다. 선택은 바로 저장되며 녹음 중에는 바꿀 수 없습니다.
3. 바로 녹음을 누르고 마이크 권한을 허용합니다. Windows에서는 설정 → 개인 정보 → 마이크에서 마이크 접근과 '데스크톱 앱이 마이크에 액세스하도록 허용'이 켜져 있어야 합니다.
4. 회의가 끝나면 정지를 누릅니다. 마이크 + 회의 소리는 정지 뒤 두 트랙을 하나의 WAV로 합치는 시간이 조금 더 걸립니다.
5. 완성된 WAV가 자동으로 전사 입력에 선택됩니다.

녹음은 bounded queue와 전용 WAV writer를 사용해 점진적으로 저장합니다. 버리기를 선택하면 부분 파일을 제거합니다.

Note

마이크 + 회의 소리는 Windows에서 기본 출력 장치의 소리를 WASAPI 루프백으로, macOS 14.6 이상에서는 Core Audio 프로세스 탭으로 녹음합니다. macOS에서는 시스템 오디오 녹음 권한이 필요하며, 개발 PC에서는 macOS 동작을 검증하지 못했습니다. 스피커 대신 마이크가 없는 헤드폰을 쓰세요. 에코 제거가 없어 스피커로 나온 상대 목소리를 마이크가 다시 녹음하면 두 번 들어갑니다. macOS에서는 마이크가 달린 헤드셋이나 에어팟이 기본 출력이면 컴퓨터 소리를 따로 받을 수 없어 녹음이 시작되지 않습니다. 컴퓨터 소리는 기본 출력 장치에서만 가져옵니다. 앱별 녹음과 장치 선택은 지원하지 않으며, 회의 앱의 알림음 등 컴퓨터 소리도 함께 녹음됩니다.

기존 녹음 가져오기

1. 오디오 파일 선택에서 회의 파일을 고릅니다.
2. 결과를 저장할 출력 폴더를 확인합니다.
3. 화자 수를 모르면 자동, 정확히 알면 정확히, 범위만 알면 범위를 고릅니다. 이번 회의 참석자를 고르면 참석 인원 앞뒤로 한 명씩 범위가 자동으로 채워집니다. 말하지 않은 참석자가 있으면 정확히는 한 사람의 목소리를 둘로 나눌 수 있습니다.
4. 전사 시작을 누릅니다.

참석자와 단어집

설정에서 다음 정보를 저장해 여러 회의에 재사용할 수 있습니다.

• 참석자: 이름, 팀, 역할, 별칭, 설명
• 단어집: 용어와 선택적 설명
• 회의 배경: 목적, 맥락, 원하는 정리 방식

이 정보는 화자 이름과 용어 표기를 안정적으로 정리하는 데 사용됩니다.

AI 회의록 만들기

전사가 끝난 뒤 AI 증강 실행을 누르면 OpenAI 호환 API로 Markdown 회의록을 생성합니다. 새 녹음·전사 없이 이미 가지고 있는 전사문도 03 전사 결과 AI 증강 패널의 전사문 파일 가져오기로 바로 증강할 수 있습니다(txt·md). Google Drive를 연결했다면 같은 패널의 Drive에서 전사문 가져오기로 Drive에 있는 전사문(보통 Galpi가 올린 _화자별.txt)을 골라 증강할 수 있습니다.

• 기본 모델: glm-5.3-flash
• 기본 API: https://api.z.ai/api/coding/paas/v4
• 모델, Base URL, 추론 강도는 설정에서 변경 가능

준비 순서:

1. 설정의 AI 증강 섹션에 사용할 서비스의 API Key를 입력합니다. 저장한 키는 마스킹되어 다시 표시되지 않습니다. 키를 바꾸려면 AI 증강 API 키 지우기로 지운 뒤 새 키를 입력하세요.
2. z.ai가 아니라면 제공자의 모델 이름과 OpenAI 호환 Base URL을 입력합니다.
3. 필요한 참석자를 선택하고 단어집·사전 정보를 확인합니다.
4. 전사를 완료한 뒤 AI 증강 실행을 누릅니다.

ChatGPT로 로그인해 사용하기

API Key 대신 ChatGPT 계정으로 로그인해 회의록 정제 모델을 사용할 수 있습니다.

1. 설정 → AI 증강에서 ChatGPT를 선택하고 ChatGPT로 계속하기를 누릅니다.
2. 시스템 브라우저가 열리면 로그인 후 접근을 승인합니다. 승인이 끝나면 앱으로 돌아옵니다.
3. 모델은 로그인한 계정의 /v1/models 목록에서 고릅니다.
4. 추론 강도는 고른 모델이 지원하는 단계 중에서 고릅니다. 모델 기본값이면 모델이 정한 강도를 그대로 씁니다. 높을수록 오래 걸리고 요금제 사용량을 더 씁니다.

• 사용량 한도는 ChatGPT 요금제와 공유되며, 한도에 걸려도 앱은 요청을 자동으로 다시 보내지 않습니다.
• ChatGPT 대화 내용과 계정 정보에는 접근하지 않습니다.
• 로그아웃하면 서버에 토큰 폐기를 시도하고 로컬 토큰을 삭제합니다. ChatGPT 설정의 연결된 앱에서도 해제할 수 있습니다.
• 토큰은 현재 0600 권한의 settings.json에 저장됩니다(아래 "로컬 데이터와 개인정보" 참고). refresh token은 30일 유효하며 갱신 때마다 회전됩니다.

Warning

음성 녹음과 전사(Qwen3·WhisperX 모두)는 로컬에서 처리됩니다. AI 증강 실행을 누르면 전사문, 이번 회의에서 선택한 참석자, 단어집, 사전 정보가 설정한 외부 API(ChatGPT 로그인 사용 시 OpenAI API)로 전송됩니다. 민감한 회의에서는 사용 중인 API 제공자의 보안·보존 정책을 먼저 확인하세요.

Google Drive 연결

Drive에 올려 둔 녹음을 가져와 전사하고, 결과를 내 Drive의 Galpi 폴더에 자동으로 올릴 수 있습니다. Drive를 연결하지 않아도 다른 기능은 그대로 쓸 수 있습니다.

Galpi에는 Google OAuth 클라이언트가 들어 있지 않습니다. Drive는 내 Google Cloud 프로젝트에서 만든 클라이언트를 한 번 저장한 뒤에만 연결됩니다. 준비 절차는 이 절 끝의 Google Drive 사용 준비에 있으니 먼저 읽어 주세요.

1. 앱을 열면 나타나는 Google Drive 연결 카드에서 Drive 연결을 누릅니다. 클라이언트를 저장하기 전에는 이 자리에 Google 클라이언트 설정 버튼이 보이며, 저장하면 Drive 연결로 바뀝니다. 카드를 닫았다면 설정의 Google Drive에서 연결합니다.
2. 시스템 브라우저에서 Drive 권한을 허용합니다. 연결이 끝나면 내 Drive에 Galpi 폴더가 생기고(이미 있으면 그 폴더를 씁니다), 상단에 연결한 계정이 표시됩니다.
3. Drive에서 가져오기를 누르면 브라우저에서 Google Picker가 열립니다. 녹음 파일을 하나 고르면 이 컴퓨터로 내려받고, 전사 시작으로 전사할 수 있습니다. 내려받는 동안에는 진행 카드에 받은 크기와 전체 크기, 진행률이 표시됩니다. Drive에 연결한 계정과 다른 계정에서 고른 파일은 가져오지 않습니다. AI 증강 패널의 Drive에서 전사문 가져오기도 같은 방식으로 Picker를 열며, txt·md 전사문 하나를 골라 이 컴퓨터로 내려받아 증강 대상으로 씁니다.
4. Drive가 연결되어 있으면 전사, 전사문 가져오기, AI 증강이 끝날 때마다 결과(.srt, _화자별.txt, _회의록.md)가 Galpi/<회의 이름> 폴더에 올라갑니다. 같은 회의를 다시 처리하면 새 파일을 만들지 않고 같은 파일을 갱신합니다. 회의 이름은 녹음 파일 이름이며, 새로운 노트_화자별.txt 같은 화자별 전사문은 _화자별을 뗀 새로운 노트가 회의 이름입니다(이 컴퓨터의 회의 폴더도 같습니다). Galpi가 올린 전사문을 Drive에서 골라 증강하면 회의록은 원래 그 회의의 Drive 폴더에 올라갑니다.
5. 설정 → Google Drive에서 녹음을 마치면 Drive에 바로 저장을 켜면, 마이크로 녹음한 파일을 정지하는 즉시 Galpi/<녹음 이름> 폴더에 올립니다. 올리는 동안에도 전사를 시작할 수 있고, 같은 녹음의 전사 결과는 같은 폴더에 올라갑니다. 이 스위치는 Drive에 연결해야 켤 수 있으며 연결을 해제하면 꺼집니다.

• 권한 범위는 drive.file 하나입니다. Galpi는 직접 만든 파일과 Picker에서 직접 고른 파일에만 접근하며, Drive의 다른 파일은 볼 수 없습니다.
• 마지막으로 올린 뒤 Drive에서 파일이 바뀌었으면 덮어쓰지 않고 충돌로 알립니다. 결과 영역의 Drive 버전 덮어쓰기를 눌러야 덮어씁니다.
• 업로드가 실패해도 로컬 결과는 그대로 남고, 실패는 결과 영역에 따로 표시됩니다. 앱은 실패한 업로드를 자동으로 다시 보내지 않습니다.
• 녹음 업로드가 실패하면 녹음 영역에 이유와 다시 올리기 버튼이 나타나며, 로컬 녹음 파일은 그대로 남습니다. 이미 올린 녹음은 다시 올리지 않고, 그 사이 Drive의 사본이 바뀌었으면 덮어쓰지 않습니다. 긴 녹음도 디스크에서 4MB씩 읽어 이어 올리므로 파일 전체를 메모리에 올리지 않습니다.
• Drive에서 고른 원본은 읽기만 하고 옮기거나 지우지 않습니다. 내려받은 사본은 앱 캐시의 drive-imports 폴더에 두며, 앱을 다시 실행하면 지웁니다.
• 설정 → Google Drive → 연결 해제를 누르면 Google에 토큰 폐기를 요청하고 로컬 연결 정보를 지웁니다. Drive에 올린 파일은 지우지 않습니다.
• 코드 교환과 토큰 갱신은 앱이 Google 토큰 엔드포인트(oauth2.googleapis.com)에 직접 보냅니다. 앱 소스에는 OAuth 클라이언트 ID도 보안 비밀번호도 들어 있지 않으며, 내가 저장한 클라이언트만 쓰고 인가 코드는 PKCE가 지킵니다.
• 개인정보처리방침: https://m16khb.dev/galpi/privacy/

Google Drive 사용 준비

Drive를 연결하려면 내 Google Cloud 프로젝트의 OAuth 클라이언트(클라이언트 ID와 보안 비밀번호)가 필요합니다. 아래 순서로 한 번만 만들어 저장하면 됩니다.

1. Google Cloud 콘솔에서 프로젝트를 만듭니다.
2. API 및 서비스에서 Google Drive API와 Google Picker API를 사용 설정합니다.
3. Google 인증 플랫폼에서 앱 정보와 대상(외부)을 설정합니다. 게시 상태가 테스트이면 Drive 연결이 7일 뒤 끊기므로, 앱을 프로덕션으로 게시합니다. drive.file은 민감하지 않은 범위입니다.
4. 클라이언트에서 애플리케이션 유형 데스크톱 앱으로 클라이언트를 만들고, 보안 비밀번호를 바로 복사합니다. 콘솔은 만든 직후에만 보여 줍니다.
5. 만든 클라이언트 ID와 보안 비밀번호를 설정 → Google Drive → Google 클라이언트에 붙여 넣고 저장합니다. Drive가 연결돼 있으면 먼저 연결 해제합니다.
6. Drive 연결을 눌러 동의합니다. 범위는 drive.file 하나입니다. 방금 만든 클라이언트는 Google에 반영되기까지 몇 분 걸릴 수 있고, 그 사이 동의 화면에서 400 오류가 나면 잠시 뒤 다시 시도합니다.
7. 저장한 클라이언트를 없애려면 클라이언트 삭제를 누릅니다(연결 해제 필요). 삭제하면 클라이언트를 다시 저장하기 전까지 Drive에 연결할 수 없습니다.

클라이언트를 바꾸면 Drive에 새 Galpi 폴더가 생깁니다. drive.file은 그 클라이언트(프로젝트)가 만들거나 연 파일에만 접근하므로, 이전 클라이언트로 올린 파일은 이어지지 않습니다. 회의 폴더와 녹음은 새 폴더에 다시 올라가고, 충돌과 최신 여부 판정도 새로 시작합니다. 이전 클라이언트로 올린 파일은 보이지 않을 뿐 Drive에서 지워지지는 않습니다.

• 클라이언트를 저장하거나 삭제하는 일은 Drive 연결을 해제한 상태에서만 할 수 있습니다. refresh token은 발급한 클라이언트에서만 갱신되기 때문입니다. 연결 해제는 저장한 클라이언트를 지우지 않습니다.
• 보안 비밀번호는 저장한 뒤 화면에 다시 보여 주지 않습니다. 저장된 동안에는 입력칸 대신 사용 중인 클라이언트 ID와 클라이언트 삭제만 보입니다.
• 클라이언트를 저장한 채 클라이언트 설정이 없는 이전 버전으로 되돌리면, 이전 버전은 저장한 클라이언트를 모르므로 토큰을 갱신하지 못하고 DRIVE_UNAVAILABLE로 실패합니다. 이때는 연결 해제한 뒤 다시 연결하세요.
• 이전 빌드는 앱에 들어 있던 클라이언트로 Drive에 연결했습니다. 그 클라이언트는 더 이상 없으므로, 이전 빌드에서 만든 Drive 연결은 갱신할 수 없습니다. 앱을 처음 실행하면 그 연결이 해제되며, 위 순서대로 내 클라이언트를 저장하고 Drive 연결을 다시 눌러야 합니다.

처리 단계와 사용 모델

녹음부터 전사까지는 모두 로컬에서 처리하고, AI 증강 실행을 눌렀을 때만 전사문을 외부 API로 보냅니다. 단계 순서는 OS와 관계없이 같으며, OS에 따라 달라지는 것은 음성 인식 엔진과 연산 장치입니다. Linux용 빌드는 제공하지 않습니다.

단계	macOS (Apple Silicon)	Windows 10/11 x64
1. 입력	마이크 녹음(WAV) 또는 오디오 파일 가져오기	같음
2. 디코딩	앱에 포함된 ffmpeg로 16 kHz 모노 WAV 변환	같음
3. 음성 인식	Qwen3(기본): Qwen/Qwen3-ASR-1.7B를 MLX 8비트 가중치로 변환해 Metal GPU에서 실행 WhisperX: faster-whisper-large-v3-turbo, CTranslate2 CPU int8	WhisperX만 제공: faster-whisper-large-v3-turbo, CTranslate2 CPU int8 또는 CUDA float16
4. 단어 시간 정렬	Qwen3: Qwen/Qwen3-ForcedAligner-0.6B(MLX, 음성 인식과 같은 단계에서 실행) WhisperX: kresnik/wav2vec2-large-xlsr-korean(MPS)	kresnik/wav2vec2-large-xlsr-korean(CPU 또는 CUDA)
5. 화자분리	pyannote/speaker-diarization-community-1(MPS)	pyannote/speaker-diarization-community-1(CPU 또는 CUDA)
6. 후처리	문장 병합과 환각 구간 제거(규칙 기반, 모델 없음)	같음
7. AI 증강	외부 LLM API(아래 설명 참고)	같음

• macOS에는 연산 장치 선택 메뉴가 없고, 설치된 PyTorch에서 MPS를 쓸 수 있으면 자동으로 사용합니다(CTranslate2에는 MPS가 없어 WhisperX 음성 인식은 CPU int8입니다). Windows에서 CUDA를 고르면 음성 인식·정렬·화자분리를 모두 가속합니다.
• WhisperX 프리셋은 MPS나 CUDA에서 정렬·화자분리가 실패하면 CPU로 한 번 다시 시도합니다.
• Qwen3 프리셋은 오디오를 무음 위치 기준으로 30초 이하 구간으로 나눠 인식합니다.
• 참석자 이름과 단어집은 음성 인식 단계에도 반영됩니다. WhisperX는 hotwords 옵션으로, Qwen3는 문맥 힌트로 넣습니다.
• AI 증강은 API 키 방식이면 OpenAI 호환 Chat Completions API(기본 모델 glm-5.3-flash)를, ChatGPT 로그인 방식이면 OpenAI Responses API와 계정 모델 목록에서 고른 모델을 사용합니다.
• 전사문이 48,000자를 넘으면 16,000자 단위 구간으로 나눠 구간별 핵심 사실을 먼저 추출하고(동시 요청 최대 3개), 이를 종합해 최종 회의록을 씁니다. 그 이하는 요청 한 번으로 회의록을 만듭니다.

산출물

기본 저장 위치는 ~/Documents/Galpi입니다(출력 폴더에서 변경할 수 있습니다). 회의 하나에 폴더 하나가 대응됩니다. 마이크 녹음은 시작 시각으로 폴더를 만들고(YYYY-MM-DD HHMMSS 녹음), 전사 결과는 오디오 파일 이름과 같은 폴더에 저장됩니다. 가져온 화자별 전사문은 녹음 이름의 폴더에 들어갑니다(새로운 노트_화자별.txt → 새로운 노트). 폴더 안의 모든 파일은 폴더와 같은 이름을 공유합니다.

~/Documents/Galpi/
├── 2026-08-24 143052 녹음/     # 마이크 녹음 (시작 시각으로 자동 이름)
│   ├── 2026-08-24 143052 녹음.wav
│   ├── 2026-08-24 143052 녹음.srt
│   ├── 2026-08-24 143052 녹음_화자별.txt
│   ├── 2026-08-24 143052 녹음.aligned.v2.json
│   └── 2026-08-24 143052 녹음_회의록.md   # AI 증강 실행 시
└── 팀미팅/                      # 가져온 오디오·전사문 (녹음 이름, `_화자별` 제외)
    ├── 팀미팅.srt
    ├── 팀미팅_화자별.txt
    ├── 팀미팅.aligned.v2.json
    └── 팀미팅_회의록.md

같은 이름의 회의가 이미 있으면 팀미팅 2처럼 번호를 붙입니다. 체크포인트(.aligned.v2.json)는 두 프리셋 모두 만들며, 같은 오디오를 다시 전사할 때 전사·정렬 단계를 건너뛰고 화자분리부터 다시 실행합니다. 체크포인트에는 만든 엔진이 기록되므로 다른 프리셋이 만든 체크포인트는 재사용하지 않습니다.

파일	용도
.srt	자막과 타임코드
_화자별.txt	화자 단위 읽기 쉬운 전사문
.aligned.v2.json	전사·정렬 체크포인트와 재처리 기반
_회의록.md	결정, 담당, 기한, 논의 내용을 정리한 문서

완료 화면에서 파일을 열거나 출력 폴더를 Finder(macOS) 또는 파일 탐색기(Windows)로 열 수 있습니다.

로컬 데이터와 개인정보

• 음성과 전사 산출물은 사용자가 선택한 로컬 폴더에 저장됩니다.
• 전사·정렬·화자분리 모델(Qwen3, WhisperX, pyannote)은 Galpi의 앱 전용 Hugging Face 캐시에 저장됩니다.
• Hugging Face 토큰, AI 증강 API 키, ChatGPT 로그인 토큰은 플랫폼에 따라 다르게 저장됩니다. Windows에서는 Windows Credential Manager의 com.m16khb.galpi:hugging-face-token, com.m16khb.galpi:assistant-api-key, com.m16khb.galpi:chatgpt-tokens 항목에 저장되며, 긴 값은 여러 항목에 나누어 저장됩니다. macOS에서는 Application Support 아래 설정 파일(settings.json)에 0600 권한으로 저장됩니다. ChatGPT 토큰(access·refresh)도 이 파일에 평문으로 들어가므로, 파일이 유출되면 계정의 API 접근이 노출될 수 있습니다.
• 이전 버전이 남긴 Credential Manager의 로그인 세션 항목 com.m16khb.galpi:gateway-session과 설정 파일의 gateway* 키는 더 쓰지 않으며 지워도 됩니다.
• Google Drive 토큰도 같은 경로로 저장됩니다. Windows에서는 com.m16khb.galpi:drive-session 항목에, macOS에서는 settings.json에 평문으로 저장됩니다. 연결한 Drive 계정의 이메일과 Galpi 폴더 ID는 두 플랫폼 모두 settings.json에 저장됩니다. 녹음을 마치면 Drive에 바로 저장하는 선택(driveSaveRecordings)도 settings.json에 있으며, 연결을 해제하면 꺼집니다.
• 내 Google 클라이언트의 보안 비밀번호는 Windows에서 com.m16khb.galpi:drive-client-secret 항목에, macOS에서는 settings.json에 평문으로 저장됩니다. 클라이언트 ID(driveClientId)는 두 플랫폼 모두 settings.json에 있으며, Drive 연결을 해제해도 남습니다. 클라이언트 삭제를 누르면 둘 다 지웁니다.
• macOS에서는 자격 증명을 아직 Keychain으로 암호화하지 않습니다. Keychain은 항목 접근 권한을 앱의 코드 서명에 묶는데, 현재 빌드는 ad-hoc 서명이라 빌드마다 서명이 달라져 사용자가 업데이트할 때마다 접근 허용 창을 다시 보게 됩니다. macOS의 Keychain 전환은 Developer ID 서명과 함께 적용할 예정입니다.
• AI 회의록을 실행하지 않으면 전사문은 외부 LLM API로 전송되지 않습니다.
• worker는 고정된 프로그램과 argv로 실행되며 셸 문자열을 실행하지 않습니다.

아키텍처

TypeScript UI
    │ Tauri IPC + validated events
    ▼
Rust application
    │ ports
    ├── 마이크 녹음기 (CPAL: CoreAudio/WASAPI)
    ├── filesystem / opener
    └── supervised Python worker
            │ versioned JSONL
            ▼
       Qwen3·WhisperX / pyannote / assistant

경로	역할
src/	도메인 계약(작업·화자·백엔드 포트)과 검증, 상태 머신, Zod 경계, DOM UI
src-tauri/	Tauri 명령, Rust use case·도메인 값 객체, 녹음·프로세스 어댑터
worker/	Qwen3·WhisperX 프리셋 전사, 정렬, 화자분리, 회의록 가공
scripts/	아키텍처 검사, sidecar staging, DMG 패키징
DESIGN.md	UI, 접근성, 컴포넌트 상태의 규범
docs/ARCHITECTURE.md	레이어 구조와 포트 소유권의 규범
docs/ROADMAP.md	현재 상태와 다음 제품 단계

개발 명령

빠른 검증

bun run check
bun test

전체 검증

Python 검증에는 uv/uvx가 PATH에 있어야 합니다. Homebrew를 사용한다면 brew install uv로 설치할 수 있습니다. <WhisperX Python 경로>에는 WhisperX가 설치된 Python 실행 파일의 절대 경로를 넣습니다.

cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --all-targets
uvx ruff check worker
uvx ruff format --check worker
uvx basedpyright --pythonpath <WhisperX Python 경로>
PYTHONPATH=. python3 -m unittest discover -s worker/tests -t . -v   # macOS
# Windows PowerShell
$env:PYTHONPATH='.'; python3 -m unittest discover -s worker/tests -t . -v

프로덕션 빌드

bun run build

결과:

src-tauri/target/release/bundle/macos/Galpi.app
src-tauri/target/release/bundle/dmg/Galpi_0.1.0_aarch64.dmg

macOS에서는 위 두 파일을, Windows x64에서는 NSIS 설치 프로그램을 만듭니다.

src-tauri/target/release/bundle/nsis/*.exe

macOS 빌드는 .app을 만든 뒤 hdiutil로 DMG를 생성합니다. Windows 빌드는 서명되지 않은 NSIS .exe를 만듭니다. CI는 두 플랫폼을 모두 검증합니다.

다른 사람에게 배포할 때

지금은 바이너리를 배포하지 않고 각자 INSTALL.md로 빌드합니다. 이 절은 나중에 바이너리를 배포할 때를 위한 것입니다. 서명·공증되지 않은 DMG를 받은 Mac은 Gatekeeper가 실행을 막으므로, 배포 전에 Apple Developer 인증서로 서명하고 공증하세요.

서명이 붙으면 자격 증명도 Keychain으로 옮길 수 있습니다. macOS는 Keychain 항목의 접근 권한을 앱의 코드 서명에 묶어 두므로, 서명이 고정되기 전에는 사용자가 업데이트할 때마다 접근 허용 창을 보게 됩니다.

.github/workflows/release.yml이 v* 태그나 수동 실행에서 DMG와 Windows 설치 프로그램을 만들어 워크플로 아티팩트로 올립니다. 아래 저장소 시크릿이 설정되어 있으면 서명·공증까지 수행한 뒤 codesign/spctl로 검증합니다.

시크릿	내용
APPLE_CERTIFICATE	Developer ID Application 인증서(.p12)의 base64
APPLE_CERTIFICATE_PASSWORD	해당 .p12의 비밀번호
APPLE_SIGNING_IDENTITY	예: Developer ID Application: 이름 (TEAMID)
APPLE_ID / APPLE_PASSWORD / APPLE_TEAM_ID	공증용 Apple ID와 앱 암호, 팀 ID

시크릿이 없으면 워크플로는 기존처럼 ad-hoc 서명 DMG를 만들며, 이는 내부 테스트용입니다.

Hardened Runtime에 필요한 entitlement는 src-tauri/Entitlements.plist에 이미 선언되어 있습니다. Galpi는 첫 실행에서 자체 Python 환경을 설치하고 그 안의 PyTorch·MLX를 불러오므로 라이브러리 검증 비활성화와 실행 가능 메모리 허용이 필요합니다. 아직 서명된 빌드를 만들어 검증한 적은 없으므로, 첫 공증 시 이 부분을 반드시 확인하세요.

문제 해결

증상	확인할 내용
cargo tauri 명령을 찾을 수 없음	cargo install tauri-cli --version 2.11.4 --locked
로컬 엔진 준비가 중간에 실패함	같은 버튼을 다시 누르면 이어서 재시도합니다(실패한 부분 설치는 자동으로 정리됩니다). 네트워크 상태도 확인하세요
Qwen3 준비 시 내려받을 파일이 큼	Qwen3 프리셋은 전사·정렬 모델 합계 약 6.6GB를 내려받습니다
모델 다운로드가 401/403으로 실패	모델 이용 조건 동의와 Fine-grained Read 토큰 확인
마이크 녹음이 시작되지 않음	시스템 설정에서 Galpi 마이크 권한 확인
상대방 음성이 녹음되지 않음	현재 시스템 오디오 캡처는 지원하지 않음
AI 회의록이 실패함	API Key, Base URL, 모델 이름, 제공자 사용량 한도 확인
다른 Mac에서 앱을 열 수 없음	내려받은 미서명·미공증 빌드는 Gatekeeper가 막습니다. 그 Mac에서 INSTALL.md로 직접 빌드하세요
앱 업데이트 후 엔진이 다시 대기로 표시됨	엔진 준비 마커가 의존성 잠금 파일의 해시를 따릅니다. 잠금이 바뀌면 로컬 엔진 준비를 한 번 더 눌러 환경을 맞춥니다(모델은 다시 받지 않습니다)

현재 상태

Galpi는 활발히 개발 중인 0.1.0 프로젝트입니다. 배포 자동 업데이트, 서명·공증, 시스템 오디오 캡처, 회의 라이브러리는 이후 단계로 계획되어 있습니다. 자세한 계획은 docs/ROADMAP.md를 참고하세요.

라이선스

GPL-3.0-or-later. 전문은 LICENSE를 참고합니다.

Copyright (C) 2026 m16khb

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.