ffvoice-engine은(는) 무엇을 하나요?
AI 에이전트를 위한 오프라인 음성-텍스트 변환 및 화자 분리 — Whisper ASR + MCP 서버 + CLI + Python 바인딩, 완전 온디바이스, 클라우드 불필요
개요
chicogong/ffvoice-engine은 오프라인 환경에서 작동하는 음성 인식 및 화자 분리 엔진입니다. Whisper ASR 모델을 활용하여 고품질의 음성-텍스트 변환을 제공하며, MCP(Model Context Protocol) 서버를 통해 AI 에이전트와 쉽게 통합할 수 있습니다. CLI 도구와 Python 바인딩도 함께 제공되어 다양한 사용 사례에 유연하게 대응할 수 있습니다.
주요 기능
- 오프라인 음성 인식: 클라우드 API 없이 로컬에서 Whisper 모델을 실행하여 음성을 텍스트로 변환합니다.
- 화자 분리(Diarization): 여러 화자가 말한 오디오에서 각 화자를 구분하여 누가 언제 말했는지 식별합니다.
- MCP 서버: Model Context Protocol을 통해 AI 에이전트(예: Claude Code, Cursor)와 통합할 수 있는 서버를 제공합니다.
- CLI 도구: 명령줄에서 바로 사용할 수 있는 간편한 인터페이스를 제공합니다.
- Python 바인딩: Python 코드에서 직접 엔진을 호출하여 사용자 정의 워크플로우를 구축할 수 있습니다.
지원 플랫폼
- Linux, macOS, Windows
- Python 3.8+
- AI 에이전트: Claude Code, Cursor, Codex 등 MCP를 지원하는 모든 에이전트
설치 및 사용 방법
전제 조건
- Python 3.8 이상
pip패키지 관리자- (선택 사항) CUDA 지원 GPU
설치
pip install ffvoice-engine
CLI 사용 예시
# 오디오 파일을 텍스트로 변환
ffvoice transcribe audio.mp3
# 화자 분리 수행
ffvoice diarize meeting.wav
Python 바인딩 사용 예시
from ffvoice_engine import VoiceEngine
engine = VoiceEngine()
result = engine.transcribe("audio.mp3")
print(result["text"])
# 화자 분리
result = engine.diarize("meeting.wav")
for segment in result["segments"]:
print(f"화자 {segment['speaker']}: {segment['text']} ({segment['start']}s - {segment['end']}s)")
MCP 서버 시작
ffvoice mcp-server --port 8080
그런 다음 AI 에이전트 설정에서 MCP 서버 주소를 http://localhost:8080으로 지정하십시오.
환경 변수
FFVOICE_MODEL_PATH: Whisper 모델 파일의 커스텀 경로를 지정합니다.FFVOICE_DEVICE: 사용할 디바이스 (cpu또는cuda). 기본값은cpu입니다.FFVOICE_LANGUAGE: 인식할 언어 코드 (예:ko,en). 기본값은 자동 감지입니다.
리소스
라이선스
MIT License