🔊 Edge TTS 엣지드라이버 사용 설명서
SmartThings 루틴(자동화)에서 원하는 문구를 스피커로 읽어주는 커스텀 드라이버입니다. Microsoft Edge의 무료 TTS(Text-to-Speech) 엔진을 사용해 자연스러운 한국어 음성을 만들어 줍니다.
1. 이 드라이버가 하는 일
- 루틴이나 다른 기기가 “이 문구를 읽어줘”라고 요청을 보냅니다.
- 브리지 서버(같은 네트워크의 안드로이드 기기)가 Microsoft Edge TTS로 문구를 mp3 음성 파일로 변환합니다.
- 변환된 mp3를 지정한 스피커(구글홈, 등록된 SmartThings 스피커 기기 등)로 재생합니다.
- 혹시 변환이나 재생에 실패하면, 자동으로 스피커 자체의 기본 TTS(
speechSynthesis)로 대신 읽어줍니다. 이 경우 음질은 다소 기계적으로 들릴 수 있지만, 무음으로 끝나는 상황은 방지됩니다.
즉, 웬만하면 항상 “무언가는 재생되는” 구조로 만들어져 있습니다.
2. 준비물
| 구성 요소 | 설명 |
|---|---|
| 브리지 서버 앱 | 같은 Wi-Fi에 있는 안드로이드 기기에 설치되어 항상 켜져 있어야 합니다. Edge TTS 음성 합성과 파일 서빙을 담당합니다. |
| SmartThings 허브 | 이 드라이버(엣지드라이버)를 설치할 SmartThings 환경 |
| 재생할 스피커 | SmartThings에 이미 등록되어 있고, audioNotification(트랙 재생) 또는 speechSynthesis(음성 합성) 기능을 지원하는 기기 (예: 구글홈, 스마트 스피커 등) |
브리지 서버 앱이 꺼져 있거나 네트워크가 끊기면 음성 재생이 동작하지 않습니다. 가장 흔한 오류 원인이니 문제가 생기면 가장 먼저 브리지 서버 앱이 실행 중인지 확인하세요.
3. 기기 설정 (Preferences)
SmartThings 앱에서 Edge TTS 기기를 열고 설정(톱니바퀴)으로 들어가면 아래 항목들이 있습니다.
| 설정 항목 | 설명 | 예시 값 |
|---|---|---|
| Bridge Server | 브리지 서버 앱의 주소 (같은 네트워크 내 사설 IP) | http://192.168.0.10:8090 |
| 스피커 (nameSpeaker) | 음성을 재생할 SmartThings 기기 이름 또는 ID | 구글홈미니 서재 |
| 목소리 (ttsVoice) | 사용할 Edge TTS 목소리 이름 | ko-KR-SunHiNeural (기본값, 여성) |
| 말속도 (ttsRate) | 말하는 속도 조절 (+가 빠름, -가 느림) | +0% |
| 피치 (ttsPitch) | 음높이 조절 | +0Hz |
| 음량 (ttsVolume) | 음량 조절 | +0% |
| 자식 기기 생성 (createDev) | 켜면 스피커별로 독립된 자식 기기를 하나 더 만들어줍니다 | 끄기 → 켜기로 전환 시 생성 |
자주 쓰는 한국어 목소리 예시
| 목소리 이름 | 성별/느낌 |
|---|---|
ko-KR-SunHiNeural | 여성 (기본값) |
ko-KR-InJoonNeural | 남성 |
ko-KR-HyunsuMultilingualNeural | 남성, 다국어 지원 |
목소리 이름은 대소문자를 정확히 맞춰야 합니다.
4. 자식(하위) 기기 활용
자식 기기 생성 옵션을 켜면 원본(부모) 기기와 별도로 자식 기기가 하나 생성됩니다.
- 자식 기기는 부모 기기의 브리지 서버/목소리/속도 등 설정을 그대로 물려받습니다.
- 자식 기기에서 스피커(nameSpeaker) 값만 따로 지정하면, “같은 목소리로 다른 방 스피커에 알림 보내기” 같은 구성이 가능합니다.
- 예: 부모 기기 = 거실 스피커용, 자식 기기 = 서재 스피커용.
5. 루틴에서 사용하는 방법
- SmartThings 앱에서 루틴을 만들고, “그러면(Then)” 항목에서 Edge TTS 기기를 선택합니다.
- 사용 가능한 커스텀 명령 중 “음성 메시지 보내기(setSpeak)” 를 선택합니다.
- 읽어줄 문구를 입력합니다.
문구에 다른 기기 상태 끼워 넣기 (템플릿 기능)
문구 안에 {기기이름:속성} 형태를 넣으면, 실제 재생 시점의 기기 상태 값으로 자동 치환됩니다.
지금 거실 온도는 {거실 온도센서:temperature}도 입니다.
이렇게 등록하면 실제 재생될 때는:
지금 거실 온도는 24도 입니다.
처럼 자동으로 값이 채워집니다. 이 기능을 활용하면 “지금 실내 습도는 몇 %입니다”, “현관문이 열려있습니다” 같은 동적인 알림 문구를 만들 수 있습니다.
템플릿 문법에 대한 자세한 옵션(
{기기명:All}등)은 별도 문서(template.lua관련 안내)를 참고하세요.
6. 웹 에디터로 문구 입력하기
기기 상세 화면에 있는 “✏️ 메시지 입력” 링크를 누르면, 스마트폰이 아니라 PC/웹에서도 편하게 긴 문구를 작성하고 저장할 수 있는 웹 에디터가 열립니다. 문구를 저장하면 바로 그 내용을 스피커로 재생합니다.
7. 상태 화면 읽는 법
기기 상세 화면에는 두 개의 상태 표시 영역이 있습니다.
| 영역 | 의미 |
|---|---|
| 읽는 중인 문구 | 마지막으로 요청받은 원본 문구가 표시됩니다 (템플릿 치환 전) |
| 처리 결과 | ⏳ 처리 중 → ✅ 재생 완료 / ⚠️ 오류 메시지 순서로 갱신됩니다 |
✅ 재생 완료: <스피커 이름> 이 뜨면 정상적으로 처리된 것입니다.
✅ speechSynthesis 재생 완료가 뜨면 Edge TTS 합성엔 실패했지만 폴백으로 스피커 자체 음성으로 대신 읽어준 것입니다 (기능은 정상 작동, 음질만 기본 TTS 수준).
8. 자주 발생하는 문제
| 증상 | 원인 / 해결 |
|---|---|
| “Bridge Server가 설정되지 않았습니다” | 설정에서 Bridge Server 주소를 입력하세요. |
| “스피커가 설정되지 않았습니다” / “스피커를 찾지 못했습니다” | 설정의 스피커 이름 오타 여부 확인, 또는 새로고침(Refresh) 명령으로 기기 목록 캐시를 갱신해 보세요. |
항상 speechSynthesis 재생 완료만 뜨고 Edge TTS 음성이 안 나옴 | 브리지 서버 앱이 꺼져 있거나, 네트워크 문제, 또는 Microsoft 서버 쪽 일시적 차단일 수 있습니다. 잠시 후 다시 시도해보세요. |
| 새로 추가한 스피커가 목록에서 안 잡힘 | 기기 상세 화면에서 새로고침(Refresh) 명령을 실행해 기기 목록 캐시를 지워주세요. |
| 아무 소리도 안 남 | 브리지 서버 앱 실행 여부, 스피커 기기가 SmartThings 앱에서 정상 온라인 상태인지부터 확인하세요. |
9. 참고 사항
- Edge TTS는 Microsoft가 공식적으로 API 형태로 제공하는 서비스가 아니라, Edge 브라우저의 “소리 내어 읽기” 기능을 우회해서 쓰는 방식이라 가끔 일시적으로 응답이 느려지거나 실패할 수 있습니다. 이런 경우를 대비해 자동으로 최대 2회까지 재시도한 뒤, 그래도 안되면 스피커 자체 TTS로 자동 전환되도록 설계되어 있습니다.
- 완전히 무료로 동작하며 별도의 API 키나 결제 정보가 필요 없습니다.
- 음성 파일은 브리지 서버 기기에 임시로 저장되며, 일정 시간(10분)이 지나면 자동으로 정리됩니다.
