OHF-Voice/wyoming

Wyoming 프로토콜 – 음성 어시스턴트 구성 요소를 위한 경량 오픈소스 와이어 포맷

정의 – JSON-lines 제어 메시지와 원시 PCM 오디오를 함께 전송하는 작은 TCP 기반 프로토콜입니다. Home Assistant 서버가 마이크 입력, 웨이크워드 감지, 음성-텍스트 변환, 텍스트-음성 변환, 의도 파싱 등을 처리하는 별도의 프로그램과 통신할 수 있게 합니다.

중요성 – 메시지 레이아웃(한 줄의 JSON 헤더, 그 뒤에 선택적 UTF-8 데이터 및 이진 페이로드)을 표준화함으로써 통합 코드를 다시 작성하지 않고도 각 구성 요소를 교체할 수 있습니다. 이 프로토콜은 의도적으로 인증 및 암호화가 없으므로 신뢰할 수 있는 로컬 네트워크에서만 안전합니다. 이는 대부분의 스마트 홈 허브가 실행되는 환경과 정확히 일치합니다.

주요 개념

• 헤더 – type, 선택적 data, 길이 필드(data_length, payload_length).
• 페이로드 – 일반적으로 PCM 오디오이지만 모든 이진 데이터가 허용됩니다.
• 이벤트 흐름 – 클라이언트는 describe 요청을 보내고, 사용 가능한 서비스를 설명하는 info 응답을 받고, 선택적으로 select-program으로 프로그램을 선택한 다음, 도메인별 이벤트(transcribe, synthesize, detect 등)를 교환합니다.

주요 이벤트 패밀리

• 오디오 – audio-start/stop 및 audio-chunk로 원시 오디오를 스트리밍합니다.
• 음성-텍스트 변환 – transcribe → transcript(또는 스트리밍 transcript-start/chunk/stop).
• 텍스트-음성 변환 – synthesize → 오디오 스트림(또는 스트리밍 synthesize-start/chunk/stop).
• 웨이크워드 – detect → detection / not-detected.
• 의도 처리 – recognize → intent(또는 여러 의도에 대해 intents-start/stop) 및 실행 결과에 대한 handled/not-handled.
• 위성 제어 – 원격 음성 위성 장치용 이벤트(run-satellite, run-pipeline 등).

사용 방법 – Home Assistant에는 별도의 프로그램(예: ASR용 wyoming-faster-whisper, TTS용 wyoming-piper)과 통신하는 내장 통합(wyoming)이 포함되어 있습니다. 각 프로그램은 동일한 프로토콜을 구현하므로 모델과 백엔드를 쉽게 혼합하여 사용할 수 있습니다.

보안 참고 사항 – 암호화나 인증이 없습니다. LAN 내부 또는 컨테이너 네트워크 내에 유지하세요. 저장소에는 위협 모델을 설명하는 SECURITY.md에 대한 링크가 있습니다.

관련 프로젝트 – README에는 모두 Wyoming을 사용하는 동반 구현(마이크, VAD, Whisper, Piper 등)의 컬렉션이 나열되어 있습니다.

결론 – Wyoming은 Home Assistant 및 유사한 생태계에서 모듈식이고 교체 가능한 음성 어시스턴트 서비스를 가능하게 하는 오픈 표준, 저오버헤드 프로토콜입니다.