local-stt

맥북(Apple Silicon)에서 완전 로컬로 동작하는 한국어 음성 → 텍스트 변환(STT) 도구입니다.

인터넷 불필요 · 비용 0원 · 데이터 유출 없음

주요 기능

• 파일 변환: mp3, m4a, wav 등 음성 파일을 한국어 텍스트로 변환
• 실시간 녹음: 맥북 마이크로 녹음하고 바로 텍스트로 변환
• SRT 자막 생성: 타임스탬프 포함 자막 파일 자동 생성
• 커스텀 사전: 자주 오인식되는 단어를 자동 교정

기술 스택

구성 요소	설명
whisper.cpp	OpenAI Whisper의 C/C++ 포팅. Apple Metal GPU 가속 지원
Whisper large-v3-turbo	OpenAI의 최신 STT 모델. large-v3 대비 6배 빠른 추론
SoX	오디오 포맷 변환 및 마이크 녹음

요구 사항

• macOS (Apple Silicon M1 이상 권장)
• Homebrew
• 디스크 여유 공간 ~2GB (모델 파일)

설치

git clone https://github.com/Rich00lee/local-stt.git
cd local-stt
./install.sh

install.sh가 자동으로 처리하는 것:

1. whisper-cpp 설치 (Homebrew)
2. sox 설치 (Homebrew)
3. large-v3-turbo 모델 다운로드 (~1.5GB)
4. 커스텀 사전 초기 파일 생성

사용법

파일 변환

# 기본 변환 (터미널 출력)
./transcribe.sh ~/Downloads/meeting.mp3

# SRT 자막 파일도 함께 생성
./transcribe.sh ~/Downloads/meeting.mp3 --srt

실시간 녹음 → 변환

./record-and-transcribe.sh
# 마이크에 대고 말하기 → Ctrl+C로 종료 → 자동 변환

녹음 파일은 recordings/ 폴더에 자동 저장됩니다.

커스텀 사전

custom-dict.sed 파일에 자주 오인식되는 단어를 등록하면 자동 교정됩니다:

# 형식: s/잘못된표현/올바른표현/g
s/라이브 클라스/라이브클래스/g

성능

환경	10분 음성 변환 시간
M1 (8GB)	23분
M1 Pro/Max	12분
M2/M3/M4	~1분 이내

Metal GPU 가속이 자동 적용됩니다.

프로젝트 구조

local-stt/
├── install.sh                  # 설치 스크립트
├── transcribe.sh               # 파일 변환
├── record-and-transcribe.sh    # 실시간 녹음 → 변환
├── custom-dict.sed             # 커스텀 사전
├── models/                     # 모델 파일 (git 미포함)
│   └── ggml-large-v3-turbo.bin
└── recordings/                 # 녹음 파일 (git 미포함)

라이선스

MIT License

크레딧

• OpenAI Whisper — 원본 STT 모델
• whisper.cpp — C/C++ 포팅 및 Apple Silicon 최적화
• SoX — 오디오 처리