Desktop AI Pet

로컬 음성 인식 (Whisper) 설치

앱의 마이크 입력은 로컬 STT 서버(OpenAI 호환 transcription API)로만 전송됩니다. 클라우드 SpeechRecognition은 사용하지 않습니다. 서버는 반드시 http://127.0.0.1 (또는 [::1]) 에서 실행해야 합니다. Windows · macOS 모두 동일 설정입니다.

앱 설정 값 (공통)

endpoint: http://127.0.0.1:8080/v1/audio/transcriptions
model:    whisper
최대 녹음: 1~30초 (기본 30)

설정 → 음성 인식(STT) 탭
위 endpoint / model 입력 (서버가 다른 모델 이름을 쓰면 그 이름으로)
로컬 음성 인식 사용 켜고 저장
(선택) 설정 안 STT 테스트 버튼으로 연결 확인
대화 창 마이크 버튼으로 녹음 → 변환 확인

보안: endpoint는 loopback만 허용됩니다. 외부 IP · HTTPS · localhost 문자열 · proxy URL은 거부됩니다. 마이크 원본은 디스크에 저장하지 않습니다.

macOS — whisper.cpp 서버

도구 준비

xcode-select --install
brew install cmake

소스 받기 & 빌드

git clone https://github.com/ggml-org/whisper.cpp
cd whisper.cpp
cmake -B build
cmake --build build -j --config Release

모델 다운로드 (용량·품질 트레이드오프)

# 가벼운 시작: base / 한국어 품질↑: small
bash ./models/download-ggml-model.sh base
# 또는
bash ./models/download-ggml-model.sh small

서버 실행 (loopback only)
```
./build/bin/whisper-server \
  -m models/ggml-base.bin \
  --host 127.0.0.1 \
  --port 8080
```
바이너리 이름·경로는 버전에 따라 server / whisper-server, build/bin/ 위치가 다를 수 있습니다. --help 로 OpenAI 호환 경로(/v1/audio/transcriptions) 지원 여부를 확인하세요. 구버전은 다른 path를 쓸 수 있어, 그때는 앱 endpoint를 서버 문서에 맞게 맞춥니다.
마이크 권한: 시스템 설정 → 개인 정보 보호 및 보안 → 마이크 에서 Desktop AI Pet 허용

Windows — whisper.cpp 서버

CMake 와 Visual Studio Build Tools(C++ 워크로드) 또는 사용 가능한 C/C++ 툴체인 설치

PowerShell / “x64 Native Tools” 개발자 명령 프롬프트에서:

git clone https://github.com/ggml-org/whisper.cpp
cd whisper.cpp
cmake -B build
cmake --build build --config Release

모델 받기

# Git Bash 가 있으면:
bash ./models/download-ggml-model.sh base

# 또는 브라우저로 ggml-base.bin 을 받아 models\ 에 둡니다.
# https://huggingface.co/ggerganov/whisper.cpp

서버 실행

.\build\bin\Release\whisper-server.exe `
  -m models\ggml-base.bin `
  --host 127.0.0.1 `
  --port 8080

# 경로 예 (버전에 따라):
# .\build\bin\whisper-server.exe
# .\build\Release\whisper-server.exe

Windows 마이크 권한: 설정 → 개인 정보 및 보안 → 마이크 → Desktop AI Pet 허용
WebView2 녹음 MIME은 보통 audio/webm 또는 audio/mp4 입니다. 앱이 자동 협상합니다.

소스 빌드가 부담스러우면 OpenAI 호환 /v1/audio/transcriptions 를 127.0.0.1 에 제공하는 다른 로컬 Whisper 서버(예: Docker 기반)도 동일하게 연결할 수 있습니다. model 이름만 서버 설정과 맞추면 됩니다.

플랫폼 요약

항목	macOS	Windows
STT 엔진	로컬 Whisper 서버 (앱에 내장되지 않음)
권장 서버	whisper.cpp server (OpenAI-compatible)
앱 endpoint	`http://127.0.0.1:8080/v1/audio/transcriptions`
마이크 권한	시스템 설정 → 마이크	설정 → 마이크

동작 확인 · 장애

브라우저/curl 로 http://127.0.0.1:8080 이 떠 있는지 확인
앱 설정에서 STT 켠 뒤 대화 창 마이크 테스트
서버를 끄면 “변환 실패”류 오류가 나고, 펫 애니메이션은 계속되어야 함
권한 거부·장치 분리·타임아웃은 재시도 가능해야 하며 녹음 버퍼는 폐기됩니다

← 다운로드 페이지 · TTS 안내