이 글은 Home Assistant 2025.12.x 버전 기능을 기반으로 한 자세한 초보자 튜토리얼입니다.
2024~2025년의 발전 과정에서 Home Assistant (HA)의 TTS(텍스트 음성 변환) 로직은 매우 표준화되었습니다. 구버전의 플랫폼 전용 서비스(예: tts.google_translate_say) 대신 범용 tts.speak 서비스를 사용하는 것을 권장합니다. 이렇게 하면 나중에 음성 엔진을 교체해도 자동화 스크립트를 수정할 필요가 없습니다.
핵심 원리
- TTS 통합: 텍스트를 오디오 스트림으로 변환합니다(Google Translate, Edge TTS, Piper 등).
- 미디어 플레이어: 오디오를 재생하는 장치(샤오아이, HomePod, 브라우저, 블루투스 스피커 등).
- Jinja2 템플릿: 센서 데이터를 가져와 텍스트에 삽입합니다.
준비 작업
- Home Assistant: 버전 2025.12.2(또는 유사 버전).
- 재생 장치: HA에 연동된 미디어 플레이어(엔터티 ID 예: media_player.living_room_speaker).
- 센서: 연동된 PM2.5 센서(엔터티 ID 예: sensor.living_room_pm25).
1단계: TTS 서비스 (Text-to-Speech) 설정
초보자에게 가장 간단하고 추가 하드웨어가 필요 없는 방법은 내장 Google Translate TTS(네트워크 환경 지원 필요)를 사용하거나 HACS를 통해 Edge TTS를 설치하는 것입니다(더 자연스러워 권장). 여기서는 공식 내장 흐름을 설명합니다.
- HA 왼쪽 메뉴 설정 (Settings) -> 장치 및 서비스 (Devices & Services)를 엽니다.
- 오른쪽 아래의 통합 추가 (Add Integration)를 클릭합니다.
- Google Translate text-to-speech를 검색하고 추가를 클릭합니다.
- 언어 코드를 설정합니다. 중국어는 zh-cn 입력을 권장하며, 제출을 클릭합니다.
- 시스템이 자동으로 엔터티를 생성합니다. 보통 tts.google_zh_cn입니다.
주의
: 오프라인 동작이나 더 나은 중국어 품질을 원한다면 “Piper”(공식 로컬 애드온) 또는 “Edge TTS”(HACS) 검색 및 설치를 권장합니다. 설정 후 로직은 아래와 완전히 동일합니다.
2단계: TTS가 소리를 낼 수 있는지 검증
자동화를 작성하기 전에 먼저 소리가 재생되는지 확인합니다.
- 왼쪽 메뉴 개발자 도구 (Developer Tools) -> 서비스 (Services/Actions)를 엽니다.
- 동작 검색란에 tts.speak를 입력합니다(이것이 현대 HA의 표준 발화 동작입니다).
- 대상 (Target): 방금 추가한 TTS 엔터티(예: tts.google_zh_cn)를 선택합니다.
- 미디어 플레이어 엔터티 (Media Player Entity): 사용자의 스피커(예: media_player.browser 또는 스마트 스피커)를 선택합니다.
- 메시지 (Message): “안녕하세요, 이것은 테스트입니다”를 입력합니다.
- 동작 실행 (Perform Action)을 클릭합니다.
스피커에서 소리가 나면 다음 단계로 진행할 수 있습니다. 나지 않으면 네트워크나 스피커 볼륨을 확인하세요.
3단계: 안내 방송 자동화 작성 (UI 비주얼 모드)
구현할 내용: 매일 아침 8시에 현재 PM2.5 수치를 알려주고 창문을 열지 조언합니다.
- 설정 -> 자동화 및 장면 -> 자동화 만들기 -> 새 자동화 만들기를 엽니다.
1. 트리거 조건 (Triggers) 설정
- 트리거 추가 -> 시간 (Time) 선택을 클릭합니다.
- 고정 시간을 설정합니다. 예: 08:00:00.
2. 동작 (Actions) 설정 – 핵심 부분
- 동작 추가 -> TTS: Speak(또는 “텍스트를 음성으로 전송”으로 표시)를 검색해 선택을 클릭합니다.
- TTS 엔터티: tts.google_zh_cn을 선택합니다.
- 미디어 플레이어 엔터티: 사용자의 스피커를 선택합니다.
- 메시지 (Message): 가장 중요한 단계로, 템플릿 (Template)을 사용해 변수를 삽입해야 합니다. 다음 코드를 메시지 상자에 복사하세요:
codeJinja2
좋은 아침입니다. 현재 거실 PM2.5 지수는 {{ states(‘sensor.living_room_pm25’) }} 마이크로그램/세제곱미터입니다.{% set pm = states(‘sensor.living_room_pm25’) | float(0) %}조언:{% if pm
- 초보자를 위한 코드 해설:
- {{ states(‘…’) }}: 센서 값을 추출하는 정형 표현입니다. sensor.living_room_pm25를 반드시 자신의 시스템 센서 ID로 교체하세요.
- {% set pm = … %}: pm이라는 변수를 정의해 이후 판단에 사용합니다. float(0)은 센서를 사용할 수 없을 때 오류가 나는 것을 방지하기 위한 것으로 기본값은 0입니다.
- {% if … %}: 논리 판단으로, 값에 따라 스피커가 다른 내용을 말하게 합니다. 언어 (Language): 비워 두거나 zh-cn을 입력합니다.
3. 자동화 저장
- 오른쪽 아래의 저장을 클릭하고 “매일 공기질 안내”로 이름을 지정합니다.
4단계: 고급 팁 (YAML 모드)
YAML 코드로 직접 설정하거나 다른 사람에게 공유하고 싶다면, 자동화 편집기 오른쪽 위의 점 세 개를 클릭하고 “YAML에서 편집”을 선택합니다.
다음은 완전하고 표준화된 자동화 YAML 설정입니다(HA 2025 표준 기반):
alias: 每日空气质量播报description: "通过TTS播报PM2.5及建议"trigger:
- platform: time
at: "08:00:00"condition: action:
- action: tts.speak
target:
entity_id: tts.google_zh_cn
# 你的TTS实体
data:
media_player_entity_id: media_player.living_room_speaker
# 你的音箱实体
message: >- 现在是 {{ now().strftime('%H点%M分') }}。 当前 PM2.5 数值为 {{ states('sensor.living_room_pm25') }}。 {% set pm = states('sensor.living_room_pm25') | float(0) %} {% if pm > 75 %} 空气不好，我已经为您自动开启了净化器。 {% else %} 空气清新，祝您心情愉快。 {% endif %}mode: single자주 발생하는 문제와 해결 가이드
- 수치가 “Unknown” 또는 “Unavailable”로 읽힘:
- 원인: 당시 센서가 오프라인이었거나 ID를 잘못 입력했습니다.
- 해결: “개발자 도구 -> 상태”에서 sensor ID가 올바른지, 구체적인 값이 있는지 확인하세요.
Google TTS 소리가 나지 않음:
- 원인: 사용자의 네트워크 환경에서 Google 서비스에 연결할 수 없을 수 있습니다.
- 해결:
- 방안 A: 네트워크 환경을 설정합니다(라우터 계층).
- 방안 B(권장): HACS에서 Edge TTS 통합을 다운로드합니다. Microsoft Edge 브라우저의 인터페이스를 이용하므로 중국 내 연결 속도가 매우 빠르고 음성도 자연스럽습니다. 설정 방법은 위 단계와 완전히 동일하며, action의 엔터티를 tts.edge_tts로 바꾸기만 하면 됩니다.
수치를 반올림하려면?
- “PM2.5는 25.3421…”을 듣고 싶지 않다면 템플릿에 round를 추가할 수 있습니다:
- {{ states(‘sensor.living_room_pm25’) | float(0) | round(0) }}
플레이어가 지원되지 않음:
- Sonoff 같은 단순 부저 게이트웨이를 사용한다면 TTS를 지원하지 않습니다. 실제 미디어 플레이어(HomePod, Sonos, Google Nest 또는 DLNA로 연결된 스피커 등)가 필요합니다.
위 단계를 통해 Home Assistant 2025에서 스마트한 음성 안내를 구현할 수 있습니다. 먼저 간단한 “안녕하세요”를 성공시킨 후 점차 센서 데이터를 추가하는 것을 권장합니다.
