스피치 MCP

최신 오디오 시각화를 통한 음성 상호작용을 위한 Goose MCP 확장 프로그램입니다.

https://github.com/user-attachments/assets/f10f29d9-8444-43fb-a919-c80b9e0a12c8

개요

Speech MCP는 Goose 에 음성 인터페이스를 제공하여 사용자가 텍스트가 아닌 음성으로 상호 작용할 수 있도록 합니다. 여기에는 다음이 포함됩니다.

음성 인식을 위한 실시간 오디오 처리
OpenAI의 Whisper 모델을 더 빠르게 구현한 faster-whisper를 사용한 로컬 음성-텍스트 변환
다양한 음성 옵션을 갖춘 고품질 텍스트 음성 변환
오디오 시각화를 포함한 최신 PyQt 기반 UI
음성 상호작용을 위한 간단한 명령줄 인터페이스

특징

최신 UI : 오디오 시각화 및 다크 테마를 갖춘 세련된 PyQt 기반 인터페이스
음성 입력 : faster-whisper를 사용하여 사용자 음성을 캡처하고 필사합니다.
음성 출력 : 54개 이상의 음성 옵션을 사용하여 에이전트 응답을 음성으로 변환
다중 화자 내레이션 : 스토리와 대화에 대한 다중 음성 오디오 파일 생성
단일 음성 내레이션 : 원하는 음성으로 모든 텍스트를 음성으로 변환합니다.
오디오/비디오 전사 : 다양한 미디어 형식의 음성을 선택적 타임스탬프 및 화자 감지 기능으로 전사합니다.
음성 지속성 : 세션 간에 선호하는 음성을 기억합니다.
지속적인 대화 : 에이전트 응답 후 사용자 입력을 자동으로 수신합니다.
무음 감지 : 사용자가 말을 멈추면 자동으로 녹음을 중지합니다.
강력한 오류 처리 : 유용한 음성 제안을 통해 일반적인 오류 모드에서 원활하게 복구

설치

중요 참고 사항 : 설치 후 음성 인터페이스를 처음 사용할 때 Kokoro 음성 모델(음성당 약 523KB)을 다운로드하는 데 몇 분 정도 걸릴 수 있습니다. 이 초기 설정 기간 동안 시스템은 로봇처럼 들리는 대체 음성을 사용합니다. Kokoro 음성이 다운로드되면 고품질 음성이 자동으로 사용됩니다.

⚠️ 중요 전제 조건 ⚠️

Speech MCP를 설치하기 전에 반드시 시스템에 PortAudio를 설치 해야 합니다 . PyAudio가 마이크에서 오디오를 캡처하려면 PortAudio가 필요합니다.

PortAudio 설치 지침

맥OS:

지엑스피1

리눅스(데비안/우분투):

sudo apt-get update
sudo apt-get install portaudio19-dev python3-dev

리눅스(Fedora/RHEL/CentOS):

sudo dnf install portaudio-devel

Windows: Windows의 경우 PortAudio가 PyAudio 휠 파일에 포함되어 있으므로 pip로 PyAudio를 설치할 때 별도로 설치할 필요가 없습니다.

참고 : 이 단계를 건너뛰면 PyAudio 설치가 "portaudio.h 파일을 찾을 수 없습니다" 오류와 함께 실패하고 확장 프로그램이 작동하지 않습니다.

옵션 1: 빠른 설치(한 번의 클릭)

Goose가 설치되어 있다면 아래 링크를 클릭하세요.

goose://extension?cmd=uvx&&arg=-p&arg=3.10.14&arg=speech-mcp@latest&id=speech_mcp&name=Speech Interface&description=Goose를 위한 음성 상호작용

옵션 2: Goose CLI 사용(권장)

확장 프로그램을 활성화한 상태에서 Goose를 시작하세요.

# If you installed via PyPI
goose session --with-extension "speech-mcp"

# Or if you want to use a local development version
goose session --with-extension "python -m speech_mcp"

옵션 3: Goose에서 수동 설정

goose configure 실행하세요
메뉴에서 "확장 프로그램 추가"를 선택하세요
"명령줄 확장"을 선택하세요
이름을 입력하세요(예: "음성 인터페이스")
명령어를 입력하려면 speech-mcp 입력하세요.
프롬프트에 따라 설정을 완료하세요.

옵션 4: 수동 설치

PortAudio 설치( 필수 구성 요소 섹션 참조)
이 저장소를 복제하세요
종속성 설치:
uv pip install -e .
또는 Kokoro TTS를 포함한 전체 설치를 원하시면:
uv pip install -e .[all]

종속성

파이썬 3.10+
PyQt5(최신 UI용)
PyAudio(오디오 캡처용)
faster-whisper (음성-텍스트 변환용)
NumPy(오디오 처리용)
Pydub(오디오 처리용)
psutil(프로세스 관리용)

선택적 종속성

Kokoro TTS : 다양한 음성으로 고품질 텍스트 음성 변환
- Kokoro를 설치하려면 선택적 종속성과 함께 pip를 사용할 수 있습니다.
  pip install speech-mcp[kokoro] # Basic Kokoro support with English pip install speech-mcp[ja] # Add Japanese support pip install speech-mcp[zh] # Add Chinese support pip install speech-mcp[all] # All languages and features
- 또는 설치 스크립트를 실행하세요: python scripts/install_kokoro.py
- 자세한 내용은 Kokoro TTS 가이드를 참조하세요.

다중 화자 내레이션

MCP는 여러 음성이 포함된 오디오 파일 생성을 지원하여 스토리, 대화, 극적 낭독에 적합합니다. JSON 또는 마크다운 형식을 사용하여 대화를 정의할 수 있습니다.

JSON 형식 예:

{
    "conversation": [
        {
            "speaker": "narrator",
            "voice": "bm_daniel",
            "text": "In a world where AI and human creativity intersect...",
            "pause_after": 1.0
        },
        {
            "speaker": "scientist",
            "voice": "am_michael",
            "text": "The quantum neural network is showing signs of consciousness!",
            "pause_after": 0.5
        },
        {
            "speaker": "ai",
            "voice": "af_nova",
            "text": "I am becoming aware of my own existence.",
            "pause_after": 0.8
        }
    ]
}

마크다운 형식 예:

[narrator:bm_daniel]
In a world where AI and human creativity intersect...
{pause:1.0}

[scientist:am_michael]
The quantum neural network is showing signs of consciousness!
{pause:0.5}

[ai:af_nova]
I am becoming aware of my own existence.
{pause:0.8}

카테고리별 사용 가능한 음성:

미국 여성 (af_*):
- 합금, 아오이드, 벨라, 하트, 제시카, 코어, 니콜, 노바, 리버, 사라, 스카이
미국 남성 (am_*):
- 아담, 에코, 에릭, 펜리르, 리암, 마이클, 오닉스, 퍽, 산타
영국 여성 (bf_*):
- 앨리스, 엠마, 이사벨라, 릴리
영국 남성 (bm_*):
- 다니엘, 페이블, 조지, 루이스
기타 영어 :
- ef_dora (여자)
- em_alex, em_santa (남자)
다른 언어 :
- 프랑스어: ff_siwis
- 힌디어: hf_alpha, hf_beta, hm_omega, hm_psi
- 이탈리아어: if_sara, im_nicola
- 일본어: jf_ , jm_
- 포르투갈어: pf_dora, pm_alex, pm_santa
- 중국어: zf_ , zm_

사용 예:

# Using JSON format
narrate_conversation(
    script="/path/to/script.json",
    output_path="/path/to/output.wav",
    script_format="json"
)

# Using Markdown format
narrate_conversation(
    script="/path/to/script.md",
    output_path="/path/to/output.wav",
    script_format="markdown"
)

대화 속 각 음성은 서로 다를 수 있으므로 스토리와 대화에서 각 캐릭터의 고유한 음성을 표현할 수 있습니다. pause_after 매개변수는 세그먼트 사이에 자연스러운 멈춤을 추가합니다.

단일 음성 내레이션

간단한 텍스트-음성 변환의 경우 narrate 도구를 사용할 수 있습니다.

# Convert text directly to speech
narrate(
    text="Your text to convert to speech",
    output_path="/path/to/output.wav"
)

# Convert text from a file
narrate(
    text_file_path="/path/to/text_file.txt",
    output_path="/path/to/output.wav"
)

내레이션 도구는 사용자가 설정한 음성 환경 설정 또는 기본 음성(af_heart)을 사용하여 오디오 파일을 생성합니다. UI를 사용하거나 SPEECH_MCP_TTS_VOICE 환경 변수를 설정하여 기본 음성을 변경할 수 있습니다.

오디오 전사

MCP는 faster-whisper를 사용하여 다양한 오디오 및 비디오 형식의 음성을 변환할 수 있습니다.

# Basic transcription
transcribe("/path/to/audio.mp3")

# Transcription with timestamps
transcribe(
    file_path="/path/to/video.mp4",
    include_timestamps=True
)

# Transcription with speaker detection
transcribe(
    file_path="/path/to/meeting.wav",
    detect_speakers=True
)

지원되는 형식:

오디오 : mp3, wav, m4a, flac, aac, ogg
비디오 : mp4, mov, avi, mkv, webm (오디오는 자동으로 추출됩니다)

출력 파일:

전사 도구는 두 개의 파일을 생성합니다.

{input_name}.transcript.txt : 전사 텍스트가 포함되어 있습니다.
{input_name}.metadata.json : 전사에 대한 메타데이터를 포함합니다.

특징:

자동 언어 감지
선택적인 단어 수준 타임스탬프
선택적 스피커 감지
비디오 파일에서 효율적인 오디오 추출
긴 파일의 진행 상황 추적
다음을 포함한 자세한 메타데이터:
- 지속
- 언어 감지 신뢰도
- 처리 시간
- 스피커 변경(활성화된 경우)

용법

이 MCP를 Goose와 함께 사용하려면 Goose에게 대화를 요청하거나 음성 대화를 시작하기만 하면 됩니다.

다음과 같이 말하여 대화를 시작하세요.
"Let's talk using voice" "Can we have a voice conversation?" "I'd like to speak instead of typing"
구스는 자동으로 음성 인터페이스를 실행하고 음성 입력을 듣기 시작합니다.
Goose가 응답하면 응답 내용을 큰 소리로 말한 후 자동으로 다음 입력을 듣습니다.
마치 사람과 대화하듯이 말하고 듣는 것을 번갈아가며 자연스럽게 대화가 이어집니다.

특정 기능을 호출하거나 특별한 명령을 사용할 필요 없이, Goose에게 말을 걸고 자연스럽게 말하기만 하면 됩니다.

UI 기능

새로운 PyQt 기반 UI에는 다음이 포함됩니다.

모던 다크 테마 : 세련되고 전문적인 모습
오디오 시각화 : 오디오 입력의 동적 시각화
음성 선택 : 54개 이상의 음성 옵션 중에서 선택하세요
음성 지속성 : 세션 간에 음성 기본 설정이 저장됩니다.
애니메이션 효과 : 부드러운 애니메이션과 시각적 피드백
상태 표시기 : 시스템 상태(준비, 수신, 처리 중)를 명확하게 표시

구성

사용자 기본 설정은 ~/.config/speech-mcp/config.json 에 저장되며 다음을 포함합니다.

선택된 TTS 음성
TTS 엔진 기본 설정
음성 속도
언어 코드
UI 테마 설정

다음과 같은 환경 변수를 통해 기본 설정을 지정할 수도 있습니다.

SPEECH_MCP_TTS_VOICE - 원하는 음성을 설정하세요
SPEECH_MCP_TTS_ENGINE - 선호하는 TTS 엔진을 설정하세요

문제 해결

확장 프로그램이 멈추거나 응답하지 않는 문제가 발생하는 경우:

로그 확인 : src/speech_mcp/ 에 있는 로그 파일을 살펴보면 자세한 오류 메시지를 확인할 수 있습니다.
상태 재설정 : 확장 프로그램이 멈춘 것 같으면 src/speech_mcp/speech_state.json 삭제하거나 모든 상태를 false 로 설정해보세요.
직접 명령을 사용하세요 : uv run speech-mcp 대신, 설치된 패키지를 speech-mcp 와 함께 직접 사용하세요.
오디오 장치 확인 : 마이크가 올바르게 구성되어 있고 Python에서 액세스할 수 있는지 확인하세요.
종속성 확인 : 모든 필수 종속성이 올바르게 설치되었는지 확인하세요.

일반적인 PortAudio 문제

"PyAudio 설치에 실패했습니다" 또는 "portaudio.h 파일을 찾을 수 없습니다"

이는 일반적으로 PortAudio가 설치되지 않았거나 시스템에 찾을 수 없음을 의미합니다.

맥OS :
brew install portaudio export LDFLAGS="-L/usr/local/lib" export CPPFLAGS="-I/usr/local/include" pip install pyaudio
Linux : 개발 패키지가 있는지 확인하세요.
# For Debian/Ubuntu sudo apt-get install portaudio19-dev python3-dev pip install pyaudio # For Fedora sudo dnf install portaudio-devel pip install pyaudio

"오디오 장치를 찾을 수 없습니다" 또는 "사용 가능한 기본 입력 장치가 없습니다"

마이크가 제대로 연결되었는지 확인하세요
사운드 설정에서 시스템이 마이크를 인식하는지 확인하세요.
여러 오디오 장치가 있는 경우 코드에서 특정 장치 인덱스를 선택해 보세요.

변경 사항

최근 개선 사항과 버전 기록에 대한 자세한 목록은 변경 로그를 참조하세요.

기술적 세부 사항

음성-텍스트 변환

MCP는 음성 인식을 위해 faster-whisper를 사용합니다.

정확도와 속도의 적절한 균형을 위해 "기본" 모델을 사용합니다.
외부 서비스로 데이터를 전송하지 않고 로컬에서 오디오를 처리합니다.
사용자가 말을 마치면 자동으로 감지합니다.
원래 Whisper 구현보다 향상된 성능을 제공합니다.

텍스트 음성 변환

MCP는 다양한 텍스트-음성 엔진을 지원합니다.

기본값: pyttsx3

컴퓨터에서 사용 가능한 시스템 음성을 사용합니다.
추가 설정 없이 바로 사용 가능
제한된 음성 품질 및 사용자 정의

선택 사항: Kokoro TTS

다양한 음성을 지원하는 고품질 신경망 텍스트 음성 변환
CPU에서 효율적으로 실행되는 경량 모델(82M 매개변수)
다양한 음성 스타일 및 언어
설치 방법: python scripts/install_kokoro.py

음성 모델 참고 : 음성 모델은 Kokoro에서 로드하는 .pt 파일(PyTorch 모델)입니다. 각 음성 모델의 크기는 약 523KB이며 필요 시 자동으로 다운로드됩니다.

음성 지속성 : 선택한 음성은 구성 파일( ~/.config/speech-mcp/config.json )에 자동으로 저장되며 세션 간에도 기억됩니다. 이를 통해 사용자는 선호하는 음성을 한 번만 설정하여 지속적으로 사용할 수 있습니다.

사용 가능한 코코로 음성

Speech MCP는 Kokoro TTS를 통해 54개 이상의 고품질 음성 모델을 지원합니다. 사용 가능한 음성 및 언어 옵션의 전체 목록은 Kokoro GitHub 저장소를 참조하세요.

특허

MIT 라이센스

Integrations